Colors

Color Step Ranges (12-Step Framework)

Steps 1–2

Backgrounds

App background and subtle component fills.

Steps 3–5

Interactive components

Normal / hover / active backgrounds for interactive elements.

Steps 6–8

Borders and separators

Subtle to pronounced borders, from a hairline to a focus outline.

Steps 9–10

Solid colors

The color's "brand" moment — solid buttons, badges, indicators.

Steps 11–12

Accessible text

Low- and high-contrast text on the app background.

Gray families — real values (this package's actual --n-* scale per family)

These don't change with the Appearance toggle, on purpose: this package's foundation scale is theme-independent (see design-system/AGENTS.md) — light/dark differs in which semantic ROLE picks which step (e.g. bg-canvas = step 50 in light, step 1000/black in dark), not in the swatch values themselves.

Backgrounds

Interactive components

Borders and separators

Solid colors

Accessible text

Zinc

Slate

Gray

Neutral

Stone

Accent colors — generated illustration, light mode

Unlike the grays above, this package only stores ONE hex per accent (see the Configurator's swatch grid) — not a real 12-step scale per theme the way Radix's own colors ship. These rows are generated from that single hue via HSL lightness interpolation (a different curve per theme, which IS how Radix's real scales work) to show what applying the same framework would look like; they're illustrative, not perceptually tuned. Toggle Appearance in the Configurator to see it flip.

Backgrounds

Interactive components

Borders and separators

Solid colors

Accessible text

Monochrome

Tomato

Red

Ruby

Crimson

Pink

Plum

Purple

Violet

Iris

Indigo

Blue

Cyan

Teal

Jade

Green

Grass

Lime

Mint

Sky

Amber

Gold

Bronze

Brown

Semantic tokens — what components actually consume

Backgrounds

Canvas

--bg-canvas

Surface

--bg-surface

Surface hover

--bg-surface-hover

Elevated

--bg-elevated

Borders

Hairline

--hairline

Hairline strong

--hairline-strong

Text

Foreground

--fg

Foreground muted

--fg-muted

Foreground subtle

--fg-subtle

Link

--link

Accent

--accent

Accent hover

--accent-hover

Accent foreground

--accent-fg

Accent contrast

--accent-contrast

Accent text (alias)

--accent-text

Accent subtle bg

--accent-subtle

Accent subtle hover

--accent-subtle-hover

Status

Success

--success

Warning

--warning

Danger

--danger

Shadows, highlights, and overlays

Black overlay scale (0%–100% opacity)

White overlay scale (0%–100% opacity)

Smart Accent Semantics & Dynamic Luminance Engine

In traditional component libraries, switching an accent color to a high-luminance hue (like Lime, Mint, Amber, or Sky) severely breaks text readability on light surfaces, while selecting dark monochrome colors causes text to vanish in dark mode. @shavin/ui solves this with an integrated, mathematical Dynamic Luminance Engine that guarantees WCAG 2.1 AAA contrast compliance across all 24 presets in both themes.

1. Mathematical Luminance

Evaluates exact linear RGB coefficients per WCAG spec:
L = 0.2126R + 0.7152G + 0.0722B

2. Adaptive Contrast Text

Accents with L > 0.35 in light mode are dynamically darkened for --accent-contrast text, while dark accents in dark mode are complemented to ensure crisp ≥ 4.5:1 text contrast.

3. Achromatic Inversion

Monochrome black (0 0 0) seamlessly inverts to pure white (255 255 255) in dark mode, maintaining pristine brand contrast without manual theme configuration.

Complete Accent Semantic Hierarchy

--accentSolid brand fill for primary buttons, active toggles, and key accents.

--accent-fgContrast-safe foreground (black or white) rendered on top of solid accent fills.

--accent-contrastLuminance-corrected accent tone for text, icons, and glyphs on canvas/surface.

--accent-subtle12% translucent background tint for soft-variant buttons and tags.

Live Component Preview

Updates live with active accent

Accent Badge--accent-contrast sample

Brand Color Tokens

Alongside the DS semantic tokens, Shavin supports custom brand color tokens — supporting colors that brands use for assets, highlights, and different sections. These sit alongside the design system tokens and follow the same two-tier architecture: you enter raw hex values, and the system auto-computes a full cluster of WCAG-accessible derived tokens using the same luminance engine that powers --accent.

Auto-scaffoldedby npx @shavin/cli init

When you run npx @shavin/cli init, the CLI automatically scaffolds brand-tokens.css alongside your global CSS, generates the initial brand-preset.mjs, imports it in your CSS, merges the preset into your Tailwind config, and wires these scripts into package.json:

"scripts": {
  "brand:gen": "npx @shavin/cli brand",       // regenerate derived tokens
  "brand:check": "npx @shavin/cli brand --check",  // CI check (exit 1 if stale)
  "predev": "npm run brand:gen",              // auto-fires before npm run dev
  "prebuild": "npm run brand:gen"             // auto-fires before npm run build
}

You never need to run brand:gen manually — it fires automatically before every npm run dev and npm run build. The only time you interact with the file is to add hex values to the INPUT section.

How it works

1. Declare hex values — Add lines like --brand-coral: #FF6B6B; to the INPUT section of brand-tokens.css.
2. Auto-compute — The predev and prebuild hooks fire brand:gen automatically before every dev server start and production build. No manual step needed.
3. Use in components — Tailwind utilities like bg-brand-coral, text-brand-coral-contrast, bg-brand-coral-subtle become available.

Derived tokens per brand color

Every hex-based brand color gets 7 derived tokens — the same cluster as --accent:

--brand-{name}Base color (resolved triplet)

--brand-{name}-fgForeground on solid fills

--brand-{name}-hover±12% mix for hover states

--brand-{name}-contrastWCAG-safe text color

--brand-{name}-textAlias of contrast

--brand-{name}-subtle12% translucent background

--brand-{name}-subtle-hover18% translucent hover bg

brand-tokens.css — INPUT section

The file ships with --brand-primary: var(--accent); as a default alias. Uncomment or add new lines with hex values:

/* ─── INPUT ─── */
--brand-primary: var(--accent);
--brand-coral: #FF6B6B;
--brand-teal: #14B8A6;
/* --brand-gold: #F59E0B; */