Theming & Customization
Refine exposes its entire visual system as CSS custom properties. Every color, spacing value, shadow, and transition is a variable you can override. Nothing requires !important.
New to Refine?
Read the Usage Guide first. This page covers customization only.
Quick Start
Change the primary color, and secondary adapts automatically:
:root {
--color-primary-hue: 220deg; /* e.g. 160deg → teal, 35deg → amber, 0deg → red */
}That single variable shifts every primary token (base, focus, backdrop, border, lighter, light, dark, darker…) and simultaneously derives the secondary family as a near-black / near-white tone with a matching hue tint. No other overrides are needed for a full rebrand.
Need finer control? Override --color-primary itself after setting the hue: every other primary sub-token is computed from --color-primary with OKLCH relative color syntax (oklch(from var(--color-primary) ...)), so one override cascades everywhere it's used:
:root {
--color-primary-hue: 220deg;
/* Overriding the base is usually enough: focus/border/backdrop/lighter/light/dark/darker all derive from it */
--color-primary: light-dark(oklch(52% 0.2 var(--color-primary-hue)), oklch(65% 0.18 var(--color-primary-hue)));
}Toggle dark mode:
document.documentElement.classList.add('dark'); // force dark
document.documentElement.classList.remove('dark'); // force light (falls back to OS)
document.documentElement.classList.toggle('dark'); // toggleDark mode works automatically from the OS preference. The .dark class overrides it. No @media (prefers-color-scheme) blocks needed: every color token uses light-dark() and resolves based on the active color-scheme.
For an instant palette change without staggered component color transitions, use createThemeController:
import { createThemeController } from '@vielzeug/refine/theme';
const theme = createThemeController();
theme.setPreference('dark');
// Dispose when the application owner unmounts.
theme.dispose();The controller handles open shadow trees as well as light DOM. Direct class toggles do not suppress transitions.
How Overrides Work
All Refine tokens live inside @layer refine.tokens { … }. Any unlayered :root rule in your stylesheet takes precedence automatically:
/* This wins over refine.tokens without !important */
:root {
--color-primary: light-dark(oklch(55% 0.18 220deg), oklch(62% 0.18 220deg));
--rounded-md: 0.5rem;
}If you need to scope overrides to a subtree, put them on a class instead of :root:
.my-section {
--color-primary: light-dark(oklch(60% 0.2 35deg), oklch(66% 0.2 35deg));
}Semantic Colors
Each semantic color ships with one authored base plus 10 derived sub-tokens: 11 total. Only --color-{name} (and, for content/contrast, two small ink pairs) is ever hand-authored; every other sub-token is computed from the base with OKLCH relative color syntax (oklch(from var(--color-{name}) ...)). Override the base and the rest follows automatically: see Overriding the Neutral Palette below for a concrete example.
| Sub-token | Purpose |
|---|---|
--color-{name} | Base interactive color (buttons, links, highlights): the only hand-authored value |
--color-{name}-lighter | Tint step, brighter than base: decorative fills, subtle badges |
--color-{name}-light | Tint step, moderately brighter than base |
--color-{name}-dark | Shade step, moderately darker than base |
--color-{name}-darker | Shade step, darker than base, hue nudged slightly cooler |
--color-{name}-focus | Hover and active state |
--color-{name}-backdrop | Tinted surface behind a colored element |
--color-{name}-content | Foreground text/icon on a translucent or tinted fill of --color-{name} (e.g. the frost variant) |
--color-{name}-contrast | Foreground text/icon on a fully opaque fill of --color-{name} (solid buttons, badges, chips, hover/active states) |
--color-{name}-border | Border at reduced opacity |
--color-{name}-focus-shadow | Focus ring box-shadow |
Available families: neutral, primary, secondary, info, success, warning, error.
Secondary is auto-derived
secondary tokens are computed from --color-primary-hue: you never need to define them manually. Changing --color-primary-hue updates both the primary and secondary families at once. Override individual --color-secondary-* tokens only when you need the secondary color to diverge from the primary hue.
Retuning the ramp itself
lighter/light/dark/darker share one derivation recipe (lightness/chroma deltas, defined as --shade-* custom properties) across all 7 families. Override e.g. --shade-lighter-l once to make every family's "lighter" step lighter: you don't need to touch each family individually.
Overriding the Neutral Palette
Uncolored components (buttons, inputs, chips without a color attribute) use the neutral family. Because every other neutral sub-token derives from --color-neutral, overriding the base is usually all you need:
:root {
--color-neutral: light-dark(oklch(50% 0.01 240deg), oklch(68% 0.01 240deg));
}--color-neutral-focus, -backdrop, -border, -lighter, -light, -dark, and -darker all recompute from that one value. Override --color-neutral-content/-contrast too only if the default ink stops reading clearly against your new base:
:root {
--color-neutral: light-dark(oklch(50% 0.01 240deg), oklch(68% 0.01 240deg));
--color-neutral-content: light-dark(oklch(98% 0.01 240deg), oklch(15% 0.01 240deg));
--color-neutral-contrast: light-dark(oklch(99% 0.01 240deg), oklch(13% 0.01 240deg));
}This affects every component that defaults to neutral: without needing color="primary" on each element.
Dark Mode
Every color token uses the CSS light-dark() function. Refine sets color-scheme: light dark on :root, so the OS preference applies automatically from day one.
Two rules on <html> let you override the OS:
html.dark {
color-scheme: dark;
}
html:not(.dark) {
color-scheme: light;
}This is Refine's own dark-mode contract: not specific to any particular framework or app shell. Toggle .dark on <html> from any app (VitePress does this automatically for these docs) and every light-dark() token in the package resolves accordingly. Refine deliberately doesn't couple this behavior to a specific delivery mechanism (a router, a state library, a meta-framework convention): a plain class toggle keeps it usable anywhere.
Keeping Overrides Mode-Aware
A flat color override is always light (or always dark). Use light-dark() to keep it adaptive:
:root {
/* ✓ Adapts to light and dark */
--color-primary: light-dark(oklch(55% 0.18 220deg), oklch(62% 0.18 220deg));
/* ⚠ Static: same in both modes */
--color-primary: oklch(58% 0.18 220deg);
}OKLCH is recommended for custom colors: lightness steps are perceptually uniform, contrast ratios stay consistent across the ramp, and the wide gamut covers P3 displays.
Increased Contrast
A third appearance context sits alongside light and dark. The OS "increase contrast" setting is honored automatically, and an explicit html.contrast-more class gives an app the same path without an OS setting:
@media (prefers-contrast: more) {
/* applied automatically */
}
html.contrast-more {
/* manual opt-in, same effect */
}Both push the neutral ramp toward the extremes, thicken separators, and widen every focus ring (via --focus-ring-width), so a reader who cannot parse the default ramp has a verified higher-contrast path.
Surfaces
Components pick a background by role, never by a raw contrast-ramp step, so depth stays correct in both appearances:
| Token | Role |
|---|---|
--surface-base | default page-level surface |
--surface-sunken | recessed wells, inset fields |
--surface-raised | cards and panels resting on the base |
--surface-overlay | floating layers (dialog, popover, menu, drawer, command palette) |
--surface-inset | deepest inset fill |
--surface-overlay reads as a foreground surface in both schemes; in dark mode it steps one ramp level brighter (html.dark re-declares it) so a dialog separates from the page behind it.
Custom Themes
Scoped Theme Class
Create a theme with a single hue variable: primary and secondary both adapt:
.theme-ocean {
--color-primary-hue: 220deg;
}
.theme-sunset {
--color-primary-hue: 35deg;
}
.theme-forest {
--color-primary-hue: 160deg;
}
.theme-rose {
--color-primary-hue: 0deg;
}Apply it anywhere in the DOM:
<div class="theme-ocean">
<ore-button color="primary">Save</ore-button>
<ore-button color="secondary">Cancel</ore-button>
</div>Need to override more than just the hue? Add sub-token overrides after --color-primary-hue:
.theme-ocean {
--color-primary-hue: 220deg;
--color-primary: light-dark(oklch(52% 0.2 var(--color-primary-hue)), oklch(65% 0.18 var(--color-primary-hue)));
}Dynamic Theme Switching
Because the entire palette derives from a single hue, switching themes at runtime is a one-liner:
const THEMES = {
ocean: { '--color-primary-hue': '220deg' },
sunset: { '--color-primary-hue': '35deg' },
forest: { '--color-primary-hue': '160deg' },
rose: { '--color-primary-hue': '0deg' },
} as const;
function applyTheme(name: keyof typeof THEMES) {
const root = document.documentElement;
Object.entries(THEMES[name]).forEach(([prop, value]) => {
root.style.setProperty(prop, value);
});
}The browser recomputes every var(--color-primary-hue) reference: including the derived secondary tokens: in a single style recalc.
Shape and Rounded Corners
Choose corner shapes by the control's role and its relationship to nearby surfaces, not by whether its fill is solid, flat, or translucent. Refine keeps its existing radius scale; a primary action does not automatically become pill-shaped.
Choosing a Shape
- Keep related standalone controls consistent. Buttons, input fields, textareas, OTP cells, file dropzones, attached button-group exteriors, calendars, and select and date/time picker panels use
--radiusby default, which resolves to--rounded-lg(8px at a 16px root). Comboboxes, number inputs, and query bars inherit the input default. Enclosed variants share this shape; the underline-styletextinput retains square edges. Density does not select a different radius. - Keep the radius scale stable:
--rounded-lgremains 8px and--rounded-xlremains 12px at a 16px root. Set--radius: var(--rounded-xl)to restore the previous control shape across a theme, or userounded="xl"where supported for one control. This does not change cards, tabs, accordions, small affordances, or branded app-store badges. - Choose container radii for the surrounding composition. A larger surface may use a larger radius, but size alone does not require it.
- Use
rounded="full"on components that support it when a capsule is intentional, such as a filter or a prominent standalone action. Use--rounded-fullfor CSS customizations. Equal width and height produce a circle; non-square controls produce a capsule. - Keep joined edges square. Round only the exposed outside corners of a segmented control or a grouped accordion. Respect writing direction when identifying the outside edges.
- Preserve the same corner geometry across hover, selection, press, and keyboard focus. A focus outline may extend beyond the control, but should follow its shape and remain visible.
- Do not rely on roundness alone to communicate interactivity, selection, or danger. Keep labels, contrast, focus indicators, and accessible names.
On components that expose rounded, the attribute selects a theme token through shared rounding styles. Component-specific radius properties provide finer control where documented:
<ore-button rounded="lg">Save changes</ore-button>
<ore-button rounded="full">Start a project</ore-button>
<ore-copy-command rounded="lg" style="--copy-command-radius: var(--rounded-xl)" value="bun install"></ore-copy-command>Changing the scale changes every component that uses those tokens. Override --radius on :root or a shared ancestor to change the control family without changing the scale. Prefer a component-specific property when only one control needs a different shape.
Nested and Joined Surfaces
When an inner surface follows the same rounded perimeter as its container, derive its radius from the actual edge-to-edge inset. For symmetric borders and padding use:
inner radius = max(0, outer radius - border width - padding)For example, a 12px outer radius, 1px border, and 8px padding produce a 3px inner radius. Borderless surfaces with the same radius and padding produce a 4px inner radius.
This rule describes concentric surfaces, not every descendant. An independent button well inside a card retains its own shape. With asymmetric insets, calculate each corner's horizontal and vertical radii separately; do not subtract a multi-value padding shorthand in a scalar CSS calculation.
Grouped accordions, tab indicators and hover fills, and copy-command focus surfaces apply these rules to their own perimeter. When overriding their borders or padding through CSS parts or document styles, keep the radius calculation consistent with the new rendered inset.
Component-Level Overrides
Each component exposes CSS custom properties for fine-tuned control. Set them inline or in a stylesheet:
<ore-button style="
--button-bg: linear-gradient(135deg, #667eea, #764ba2);
--button-radius: 20px;
--button-padding: 0.75rem 2rem;
">
Gradient Button
</ore-button>Common component variables:
/* ore-button */
--button-bg
--button-color
--button-border
--button-radius
--button-padding
/* ore-input */
--input-bg
--input-color
--input-border-color
--input-placeholder-color
--input-radius
/* ore-text */
--text-size
--text-weight
--text-color
--text-line-height
--text-letter-spacingRefer to each component's documentation for its full variable list.
Token Reference
Color Palette
Brand Colors
Semantic Colors
Shade Colors
Contrast Scale
Adaptive gray scale: surfaces (50–400) and text (500–900). Automatically inverts in dark mode.
Contrast Scale
Refine uses an 11-step contrast scale driven by light-dark(). Values flip automatically between light and dark poles: no @media query needed.
Background range (50–400): surfaces, borders, UI structure:
| Token | Light | Dark | Usage |
|---|---|---|---|
--color-contrast-50 | oklch(99% 0.001 264deg) | oklch(17% 0.001 250deg) | Canvas, page background |
--color-contrast-100 | oklch(97% 0.001 264deg) | oklch(21% 0.001 250deg) | Cards, elevated surfaces |
--color-contrast-150 | oklch(95.5% 0.001 264deg) | oklch(23.5% 0.001 250deg) | Midpoint: chip base, subtle fills |
--color-contrast-200 | oklch(94% 0.001 264deg) | oklch(26% 0.001 250deg) | Nested cards, hover states |
--color-contrast-300 | oklch(89% 0.002 264deg) | oklch(32% 0.001 250deg) | Borders, dividers |
--color-contrast-400 | oklch(81% 0.002 264deg) | oklch(40% 0.001 250deg) | Disabled backgrounds, subtle UI |
Text range (500–900): readability and WCAG compliance:
| Token | Light | Dark | WCAG | Usage |
|---|---|---|---|---|
--color-contrast-500 | oklch(49% 0.002 264deg) | oklch(58% 0.001 250deg) | AA (large text) | Tertiary text, placeholders |
--color-contrast-600 | oklch(40% 0.002 264deg) | oklch(68% 0.001 250deg) | AA | Secondary / muted text |
--color-contrast-700 | oklch(32% 0.002 264deg) | oklch(78% 0.001 250deg) | AAA | Supplemental body text |
--color-contrast-800 | oklch(22% 0.002 264deg) | oklch(88% 0.001 250deg) | AAA | Default body text |
--color-contrast-900 | oklch(12% 0.002 264deg) | oklch(95% 0.001 250deg) | AAA | Headings, highest contrast |
Aliases:
| Token | Value | Usage |
|---|---|---|
--color-canvas | color-mix(in oklch, var(--color-contrast-50) 85%, transparent) | Default page/component background |
--color-divider | color-mix(in oklch, var(--color-contrast-300) 85%, transparent) | Separator lines and borders |
--color-contrast | color-mix(in oklch, var(--color-contrast-900) 85%, transparent) | Maximum-contrast text/icon color |
--color-scrim | light-dark(rgb(0 0 0 / 55%), rgb(0 0 0 / 72%)) | Overlay dim veil (never inverts) |
--overlay-veil | color-mix(in oklch, var(--color-scrim) 70%, transparent) | The dimming backdrop behind every overlay (dialog, drawer, command palette, tour, and the sidebar drawer in its backdrop="opaque"/"blur" modes) |
Semantic Text Colors
| Token | Contrast step | Use |
|---|---|---|
--text-color-heading | --color-contrast-900 | Headings: AAA |
--text-color-body | --color-contrast-800 | Default body text: AAA |
--text-color-secondary | --color-contrast-600 | Secondary / muted text: AA |
--text-color-tertiary | --color-contrast-500 | Placeholder, hint text: AA large |
--text-color-disabled | --color-contrast-400 | Disabled state: decorative only |
--text-color-contrast | --color-contrast-100 | Text on dark/colored backgrounds |
Prefer semantic tokens over raw contrast values: they stay meaningful in both modes:
/* ✓ Semantic: adapts automatically */
color: var(--text-color-body);
/* ✗ Avoid: raw value is less expressive */
color: var(--color-contrast-800);Z-Index Scale
One shared, monotonic stacking scale for an entire page: sticky headers, dropdowns, overlays, modals, popovers, tooltips, toasts. Reach for these instead of ad-hoc z-index literals in app code, the same way you'd reach for --size-* instead of a random margin value:
| Token | Value | Use |
|---|---|---|
--z-base | 0 | Default stacking, no explicit layer |
--z-sticky | 40 | Sticky headers/sidebars within the flow |
--z-dropdown | 100 | Inline dropdowns (select, combobox) |
--z-fixed | 300 | Fixed-position chrome |
--z-overlay | 500 | Backdrop behind a dialog/drawer |
--z-modal | 600 | Dialogs, drawers |
--z-popover | 1000 | Floating menus, popovers |
--z-tooltip | 1100 | Tooltips: always above popovers |
--z-toast | 9999 | Toasts: always on top |
.app-header {
position: sticky;
top: 0;
z-index: var(--z-sticky);
}Border Radius
The scale is rem-based except for the full-round sentinel. Pixel equivalents assume a 16px root font size; they scale with the user's root font size.
| Token | Value | Equivalent |
|---|---|---|
--rounded-none | 0 | 0px |
--rounded-xs | 0.125rem | 2px |
--rounded-sm | 0.25rem | 4px |
--rounded | 0.25rem | 4px (same default as --rounded-sm) |
--rounded-md | 0.375rem | 6px |
--rounded-lg | 0.5rem | 8px |
--rounded-xl | 0.75rem | 12px |
--rounded-2xl | 1rem | 16px |
--rounded-3xl | 1.5rem | 24px |
--rounded-full | 9999px | Pill or circle |
--radius | var(--rounded-lg) | 8px control default |
--rounded is a legacy alias by value, not a live reference: overriding --rounded-sm does not change it. --rounded-xs is available as a CSS token, but is not a shared rounded attribute value. Check each component's reference for its supported attributes.
Typography
Body scale (--text-*):
| Token | Value |
|---|---|
--text-2xs | 0.6875rem (11px) |
--text-xs | 0.75rem (12px) |
--text-sm | 0.875rem (14px) |
--text-base | 1rem (16px) |
--text-lg | 1.125rem (18px) |
--text-xl | 1.25rem (20px) |
--text-2xl | 1.5rem (24px) |
--text-3xl | 1.875rem (30px) |
--text-2xs (11px) is the legibility floor: component text never ships smaller. --text-3xl is reserved for display values (e.g. a circular-progress label), not running text.
Heading scale (--heading-*): used by <ore-text variant="heading">:
| Token | Value |
|---|---|
--heading-xs | 0.875rem (14px) |
--heading-sm | 1rem (16px) |
--heading-md | 1.5rem (24px) |
--heading-lg | 2rem (32px) |
--heading-xl | 3rem (48px) |
--heading-2xl | 4rem (64px) |
Font weights:
| Token | Value | Note |
|---|---|---|
--font-thin | 100 | |
--font-extralight | 200 | |
--font-light | 300 | |
--font-normal | 400 | Minimum for body text |
--font-medium | 500 | |
--font-semibold | 600 | |
--font-bold | 700 | |
--font-extrabold | 800 | |
--font-black | 900 |
Letter spacing:
| Token | Value | Use |
|---|---|---|
--tracking-tighter | -0.05em | Tightest display headings |
--tracking-tight | -0.025em | Standard headers, display text |
--tracking-header | -0.05em | Default for heading variant |
--tracking-normal | 0em | Default body tracking |
--tracking-wide | 0.05em | Labels, badges, uppercase caps |
Line heights:
| Token | Value | Use |
|---|---|---|
--leading-none | 1 | |
--leading-tight | 1.15 | Headings |
--leading-snug | 1.375 | |
--leading-normal | 1.5 | Body text (WCAG recommended) |
--leading-relaxed | 1.625 | |
--leading-loose | 2 | |
--leading-3 | 0.75rem (12px) | |
--leading-4 | 1rem (16px) | |
--leading-5 | 1.25rem (20px) | |
--leading-6 | 1.5rem (24px) | |
--leading-7 | 1.75rem (28px) | |
--leading-8 | 2rem (32px) | |
--leading-9 | 2.25rem (36px) | |
--leading-10 | 2.5rem (40px) |
Transitions & Animation
Duration, easing, pre-built transitions, named animations, and Motion Mode moved to their own page: see Animation & Motion.
All Token Categories
| Category | Prefix | Description |
|---|---|---|
| Spacing Scale | --size-{n} | 4px-increment spacing (0 → 96) |
| Container Sizes | --size-{2xs–7xl} | Named width breakpoints (256px → 1280px) |
| Special Sizes | --size-{full,fit,min,max,auto,none,prose} | Keyword size utilities |
| Viewport & Breakpoints | --size-screen-* | Viewport units + breakpoint values |
| Z-Index Scale | --z-* | Shared page-wide stacking scale (sticky → toast) |
| Aspect Ratios | --aspect-* | Common aspect ratios (square, video, wide…) |
| 3D Perspective | --perspective-* | Transform perspective distances |
| Grid Templates | --grid-{1–12} | CSS Grid column repeat helpers |
| Grid Auto-fit Floor | --grid-min-item-width | Minimum auto-fit column width (250px) |
| Surfaces | --surface-{base,sunken,raised,overlay,inset} | Role-named backgrounds, appearance-aware |
| Target Spacing | --target-gap-{bezel,open} | Minimum gap between controls (bezeled / borderless) |
| Safe-area Insets | --safe-area-inset-block/inline-* | Notch/home-indicator clearance (0 off-device) |
| Focus Ring | --focus-ring{,-width,-color,-offset} | Keyboard focus indicator primitives |
| Border Widths | --border-* | Stroke widths (0, 1px, 2px, 4px, 8px) |
| Ring Utilities | --ring-* | Focus ring box-shadow helpers |
| Border Radius | --rounded-* | Corner rounding scale |
| Blur Effects | --blur-* | Blur filter scale |
| Box Shadows | --shadow-* | Elevation shadows (light-dark aware) |
| Inset Shadows | --inset-shadow-* | Inner shadow scale |
| Drop Shadows | --drop-shadow-* | CSS filter drop-shadows |
| Text Shadows | --text-shadow-* | Typographic text shadows |
| Halo Shadows | --halo-shadow-* | Branded glow per semantic color |
| Font Families | --font-{sans,serif,mono} | System font stacks |
| Semantic Colors | --color-{name}-* | 1 authored base + 10 derived sub-tokens per family |
| Shade Ramp | --shade-* | Shared lighter/light/dark/darker derivation recipe |
| Contrast Scale | --color-contrast-{50–900} | 11-step light/dark adaptive palette |
| Section Spacing | --section-spacing | Default block section gap (2rem) |
| Named Animations | --animate-* | Keyframe + house timing as one token (see Animation & Motion) |
| Overlay Enter | --overlay-enter-* | Shared enter displacement/scale for overlays |
View theme.css
@layer refine.tokens {
:root {
/* ========================================
Spacing Scale
Based on 0.25rem (4px) increments
======================================== */
--size-0: 0;
--size-px: 1px;
--size-0-5: 0.125rem; /* 2px */
--size-1: 0.25rem; /* 4px */
--size-1-5: 0.375rem; /* 6px */
--size-2: 0.5rem; /* 8px */
--size-2-5: 0.625rem; /* 10px */
--size-3: 0.75rem; /* 12px */
--size-3-5: 0.875rem; /* 14px */
--size-4: 1rem; /* 16px */
--size-5: 1.25rem; /* 20px */
--size-6: 1.5rem; /* 24px */
--size-7: 1.75rem; /* 28px */
--size-8: 2rem; /* 32px */
--size-9: 2.25rem; /* 36px */
--size-10: 2.5rem; /* 40px */
--size-11: 2.75rem; /* 44px */
--size-12: 3rem; /* 48px */
--size-14: 3.5rem; /* 56px */
--size-16: 4rem; /* 64px */
--size-20: 5rem; /* 80px */
--size-24: 6rem; /* 96px */
--size-28: 7rem; /* 112px */
--size-32: 8rem; /* 128px */
--size-36: 9rem; /* 144px */
--size-40: 10rem; /* 160px */
--size-44: 11rem; /* 176px */
--size-48: 12rem; /* 192px */
--size-52: 13rem; /* 208px */
--size-56: 14rem; /* 224px */
--size-60: 15rem; /* 240px */
--size-64: 16rem; /* 256px */
--size-72: 18rem; /* 288px */
--size-80: 20rem; /* 320px */
--size-96: 24rem; /* 384px */
/* Section Spacing */
--section-spacing: 2rem; /* 32px */
/* Container Sizes */
--size-2xs: 16rem; /* 256px */
--size-xs: 20rem; /* 320px */
--size-sm: 24rem; /* 384px */
--size-md: 28rem; /* 448px */
--size-lg: 32rem; /* 512px */
--size-xl: 36rem; /* 576px */
--size-2xl: 42rem; /* 672px */
--size-3xl: 48rem; /* 768px */
--size-4xl: 56rem; /* 896px */
--size-5xl: 64rem; /* 1024px */
--size-6xl: 72rem; /* 1152px */
--size-7xl: 80rem; /* 1280px */
/* Special Sizes */
--size-full: 100%;
--size-fit: fit-content;
--size-min: min-content;
--size-max: max-content;
--size-auto: auto;
--size-none: none;
--size-prose: 65ch; /* Optimal reading width */
/* Viewport Units */
--size-screen-width: 100dvw;
--size-screen-height: 100dvh;
/* Breakpoints */
--size-screen-xs: 480px;
--size-screen-sm: 640px;
--size-screen-md: 768px;
--size-screen-lg: 1024px;
--size-screen-xl: 1280px;
--size-screen-2xl: 1536px;
/* ========================================
3D Perspective (for transforms)
======================================== */
--perspective-dramatic: 100px;
--perspective-near: 300px;
--perspective-normal: 500px;
--perspective-midrange: 800px;
--perspective-distant: 1200px;
/* ========================================
Aspect Ratios
======================================== */
--aspect-square: 1 / 1;
--aspect-video: 16 / 9;
--aspect-wide: 21 / 9;
--aspect-ultrawide: 32 / 9;
--aspect-portrait: 3 / 4;
--aspect-photo: 4 / 3;
/* ========================================
Grid Template Columns
======================================== */
--grid-1: repeat(1, minmax(0, 1fr));
--grid-2: repeat(2, minmax(0, 1fr));
--grid-3: repeat(3, minmax(0, 1fr));
--grid-4: repeat(4, minmax(0, 1fr));
--grid-5: repeat(5, minmax(0, 1fr));
--grid-6: repeat(6, minmax(0, 1fr));
--grid-7: repeat(7, minmax(0, 1fr));
--grid-8: repeat(8, minmax(0, 1fr));
--grid-9: repeat(9, minmax(0, 1fr));
--grid-10: repeat(10, minmax(0, 1fr));
--grid-11: repeat(11, minmax(0, 1fr));
--grid-12: repeat(12, minmax(0, 1fr));
/* Smallest column a responsive (auto-fit) grid may shrink a track to. */
--grid-min-item-width: 15.625rem; /* 250px */
/* ========================================
Z-Index Scale
A page only has one stacking context to reason about: every layer
(sticky headers, dropdowns, overlays, modals, popovers, tooltips,
toasts) needs one shared, monotonic scale, not ad-hoc literals
scattered across components and page code alike.
======================================== */
--z-base: 0;
--z-sticky: 40;
--z-dropdown: 100;
--z-fixed: 300;
--z-overlay: 500;
--z-modal: 600;
--z-popover: 1000;
--z-tooltip: 1100;
--z-toast: 9999;
/* ========================================
Border Widths
======================================== */
--border-0: 0;
--border: 1px;
--border-2: 2px;
--border-4: 4px;
--border-8: 8px;
/* Ring Utilities (for focus states) */
--ring-0: 0 0 0 0;
--ring: 0 0 0 var(--border);
--ring-2: 0 0 0 var(--border-2);
--ring-4: 0 0 0 var(--border-4);
--ring-8: 0 0 0 var(--border-8);
/* ========================================
Border Radius
======================================== */
--rounded-none: 0;
--rounded-xs: 0.125rem; /* 2px - minimal */
--rounded-sm: 0.25rem; /* 4px - small */
--rounded: 0.25rem; /* 4px - alias of the default --rounded-sm value */
--rounded-md: 0.375rem; /* 6px - medium */
--rounded-lg: 0.5rem; /* 8px - large */
--rounded-xl: 0.75rem; /* 12px - extra large */
--rounded-2xl: 1rem; /* 16px - 2x extra large */
--rounded-3xl: 1.5rem; /* 24px - 3x extra large */
--rounded-full: 9999px; /* Full circle/pill */
--radius: var(--rounded-lg); /* Default control radius */
/* ========================================
Blur Effects
======================================== */
--blur-none: 0;
--blur-xs: 4px;
--blur-sm: 8px;
--blur-md: 12px;
--blur-lg: 16px;
--blur-xl: 24px;
--blur-2xl: 40px;
--blur-3xl: 64px;
/* ========================================
Box Shadows
All shadows use light-dark() to remain visible in dark mode.
======================================== */
--shadow-none: 0 0 transparent;
/* light-dark() only accepts <color> arguments (spec: CSS Color 5): these used
to wrap the *entire* shadow (offset + blur + color), which is invalid CSS.
Custom properties store any token soup, so the declaration itself never
errored, but every consumer substituting it into an actual `box-shadow`
got an unparseable value and silently computed to `none` in spec-compliant
browsers. Fixed by keeping offset/blur outside and wrapping only the color.
Offset and blur are identical between light and dark here; only the
alpha differs. */
--shadow-2xs: 0 1px 2px light-dark(rgb(0 0 0 / 3%), rgb(0 0 0 / 20%));
--shadow-xs: 0 2px 4px light-dark(rgb(0 0 0 / 3%), rgb(0 0 0 / 22%));
--shadow-sm: 0 4px 10px -1px light-dark(rgb(0 0 0 / 5%), rgb(0 0 0 / 28%));
--shadow: 0 8px 16px -2px light-dark(rgb(0 0 0 / 6%), rgb(0 0 0 / 32%));
--shadow-md: 0 12px 24px -4px light-dark(rgb(0 0 0 / 6%), rgb(0 0 0 / 34%));
--shadow-lg: 0 24px 32px -8px light-dark(rgb(0 0 0 / 8%), rgb(0 0 0 / 38%));
--shadow-xl: 0 32px 64px -16px light-dark(rgb(0 0 0 / 12%), rgb(0 0 0 / 44%));
--shadow-2xl: 0 48px 80px -20px light-dark(rgb(0 0 0 / 20%), rgb(0 0 0 / 52%));
/* Inset Shadows: same light-dark()-color-only fix as above. */
--inset-shadow-none: inset 0 0 transparent;
--inset-shadow-2xs: inset 0 1px light-dark(rgb(0 0 0 / 5%), rgb(255 255 255 / 4%));
--inset-shadow-xs: inset 0 1px 1px light-dark(rgb(0 0 0 / 5%), rgb(255 255 255 / 4%));
--inset-shadow-sm: inset 0 2px 4px light-dark(rgb(0 0 0 / 5%), rgb(0 0 0 / 25%));
--inset-shadow: inset 0 2px 4px light-dark(rgb(0 0 0 / 6%), rgb(0 0 0 / 28%));
/* Drop Shadows (for filters) */
--drop-shadow-none: 0 0 transparent;
--drop-shadow-xs: 0 1px 1px rgb(0 0 0 / 5%);
--drop-shadow-sm: 0 1px 2px rgb(0 0 0 / 15%);
--drop-shadow: 0 1px 2px rgb(0 0 0 / 10%), 0 1px 1px rgb(0 0 0 / 6%);
--drop-shadow-md: 0 3px 3px rgb(0 0 0 / 12%);
--drop-shadow-lg: 0 4px 4px rgb(0 0 0 / 15%);
--drop-shadow-xl: 0 9px 7px rgb(0 0 0 / 10%);
--drop-shadow-2xl: 0 25px 25px rgb(0 0 0 / 15%);
/* Text Shadows (for readability) */
--text-shadow-none: 0 0 transparent;
--text-shadow-2xs: 0 1px 0 rgb(0 0 0 / 15%);
--text-shadow-xs: 0 1px 1px rgb(0 0 0 / 20%);
--text-shadow-sm: 0 1px 0 rgb(0 0 0 / 7.5%), 0 1px 1px rgb(0 0 0 / 7.5%), 0 2px 2px rgb(0 0 0 / 7.5%);
--text-shadow: 0 1px 1px rgb(0 0 0 / 10%), 0 2px 2px rgb(0 0 0 / 10%);
--text-shadow-md: 0 1px 1px rgb(0 0 0 / 10%), 0 1px 2px rgb(0 0 0 / 10%), 0 2px 4px rgb(0 0 0 / 10%);
--text-shadow-lg: 0 1px 2px rgb(0 0 0 / 10%), 0 3px 2px rgb(0 0 0 / 10%), 0 4px 8px rgb(0 0 0 / 10%);
/* ========================================
Typography
Optimized for WCAG AAA readability
======================================== */
/* Font Family */
--font-sans:
'Inter Variable', 'Plus Jakarta Sans Variable', system-ui, -apple-system, blinkmacsystemfont, 'Segoe UI', roboto,
sans-serif;
--font-serif: ui-serif, georgia, cambria, 'Times New Roman', times, serif;
--font-mono: ui-monospace, 'Cascadia Code', 'Source Code Pro', menlo, consolas, 'Liberation Mono', monospace;
/* Font Weights (Accessibility: minimum 400 for body text) */
--font-thin: 100;
--font-extralight: 200;
--font-light: 300;
--font-normal: 400; /* Minimum for body text */
--font-medium: 500;
--font-semibold: 600;
--font-bold: 700;
--font-extrabold: 800;
--font-black: 900;
/* Letter Spacing */
--tracking-tighter: -0.05em;
--tracking-tight: -0.025em; /* -2.5%: headers, display text */
--tracking-header: var(--tracking-tighter);
--tracking-normal: 0em; /* default body tracking */
--tracking-wide: 0.05em; /* labels, badges, uppercase caps */
/* Line Heights (Optimized for readability - WCAG recommends 1.5 for body text) */
--leading-none: 1;
--leading-tight: 1.15; /* 115% for headers */
--leading-snug: 1.375;
--leading-normal: 1.5; /* Optimal for body text (WCAG) */
--leading-relaxed: 1.625;
--leading-loose: 2;
/* Absolute Line Heights */
--leading-3: 0.75rem; /* 12px */
--leading-4: 1rem; /* 16px */
--leading-5: 1.25rem; /* 20px */
--leading-6: 1.5rem; /* 24px */
--leading-7: 1.75rem; /* 28px */
--leading-8: 2rem; /* 32px */
--leading-9: 2.25rem; /* 36px */
--leading-10: 2.5rem; /* 40px */
/* Component UI Font Sizes (7 steps: used inside components) */
/* Floor: 11px is the smallest size kept legible (HIG minimum micro label);
never ship component text below --text-2xs. */
--text-2xs: 0.6875rem; /* 11px - micro labels, dot-only badges */
--text-xs: 0.75rem; /* 12px - small labels only */
--text-sm: 0.875rem; /* 14px - secondary text */
--text-base: 1rem; /* 16px - body text (minimum) */
--text-lg: 1.125rem; /* 18px - large UI / headings */
--text-xl: 1.25rem; /* 20px - subheadings */
--text-2xl: 1.5rem; /* 24px - major headings */
--text-3xl: 1.875rem; /* 30px - display / circular progress label */
/* Document Heading Sizes (h1–h6: use outside components, in page/doc context) */
--heading-xs: 0.875rem;
--heading-sm: 1rem;
--heading-md: 1.5rem;
--heading-lg: 2rem;
--heading-xl: 3rem;
--heading-2xl: 4rem;
/* Semantic Text Colors (for accessibility)
These adapt to light/dark mode automatically */
--text-color-heading: var(--color-contrast-900);
--text-color-body: var(--color-contrast-800);
--text-color-secondary: var(--color-contrast-600);
--text-color-tertiary: var(--color-contrast-500);
--text-color-disabled: var(--color-contrast-400);
--text-color-contrast: var(--color-contrast-100);
/* ========================================
Transitions & Animations
Optimized for smooth, accessible motion
======================================== */
/* Easing Functions */
--ease-linear: linear;
--ease-in: cubic-bezier(0.4, 0, 1, 1);
--ease-out: cubic-bezier(0, 0, 0.2, 1);
--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
--ease-spring: cubic-bezier(0.22, 1, 0.36, 1); /* Fast start, soft landing: no overshoot */
--ease-move: cubic-bezier(0.25, 1, 0.5, 1); /* Spatial slides: drawers, panels, carousels */
--ease-overshoot: cubic-bezier(0.34, 1.1, 0.64, 1); /* Subtle spring overshoot: toasts, popups */
/* Duration (respects prefers-reduced-motion) */
--duration-75: 75ms;
--duration-100: 100ms;
--duration-150: 150ms;
--duration-200: 200ms;
--duration-250: 250ms;
--duration-300: 300ms;
--duration-350: 350ms;
--duration-500: 500ms;
--duration-600: 600ms;
--duration-700: 700ms;
--duration-1000: 1000ms;
--duration-1200: 1200ms; /* Looping indicator cycle */
--duration-1400: 1400ms; /* Looping indicator cycle */
--duration-1500: 1500ms; /* Looping indicator cycle */
/* Combined Transitions (most commonly used) */
--transition-none: none;
--transition-fast: 150ms var(--ease-in-out);
--transition-normal: 200ms var(--ease-in-out);
--transition-slow: 300ms var(--ease-in-out);
--transition-slower: 500ms var(--ease-in-out);
--transition-spring: 300ms var(--ease-spring);
--transition-exit: 300ms var(--ease-out); /* Exit animations: overlay dismiss, alert collapse */
--transition-loader: 600ms linear; /* Spinner: constant rotation */
/* Overlay entrance defaults: shared by @starting-style blocks */
--overlay-enter-translate-y: -4px; /* dropdown slides down from */
--overlay-enter-translate-y-up: 4px; /* bottom-anchored overlays slide up from */
--overlay-enter-scale: 0.97; /* slight scale-in for menus / panels */
--overlay-enter-scale-dialog: 0.96; /* slightly more pronounced for dialogs */
/* ========================================
Named Animations
Keyframe + house timing as one unit, composed from the duration/easing
tokens above so the Reduced Motion block below governs every one of
them. Consume as `animation: var(--animate-fade-in)`; inside a
component, wrap with the escape hatch —
`animation: var(--_motion-animation, var(--animate-fade-in))` — so the
reducedMotionMixin can switch it off. Keyframes ship in animation.css.
======================================== */
--animate-fade-in: fade-in var(--duration-150) var(--ease-out) both;
--animate-fade-out: fade-out var(--duration-150) var(--ease-in) both;
--animate-fade-in-up: fade-in-up var(--duration-300) var(--ease-move) both;
--animate-scale-in: scale-in var(--duration-200) var(--ease-overshoot) both;
--animate-slide-in-from-top: slide-in-from-top var(--duration-300) var(--ease-move) both;
--animate-slide-in-from-bottom: slide-in-from-bottom var(--duration-300) var(--ease-move) both;
--animate-slide-in-from-left: slide-in-from-left var(--duration-300) var(--ease-move) both;
--animate-slide-in-from-right: slide-in-from-right var(--duration-300) var(--ease-move) both;
--animate-spin: spin var(--transition-loader) infinite;
--animate-ping: ping var(--duration-1000) var(--ease-out) infinite;
--animate-pulse: pulse var(--duration-1000) var(--ease-in-out) infinite;
--animate-bounce: bounce var(--duration-1000) var(--ease-in-out) infinite;
--animate-progress-bar: progress-bar var(--duration-1400) var(--ease-in-out) infinite;
/* ========================================
Focus Ring
One set of primitives for every keyboard focus indicator in the
library. `--focus-ring` stays the convenience shorthand for the common
case (`outline: var(--focus-ring)`); a rule that needs a different ink
(an error-coloured field) or an inward ring (a stepper button inside a
bordered field) composes the same width/offset primitives instead of
re-typing a literal, so ring weight and offset can never drift.
======================================== */
--focus-ring-width: var(--border-2);
--focus-ring-offset: 2px;
--focus-ring-color: var(--color-primary);
--focus-ring: var(--focus-ring-width) solid var(--focus-ring-color);
/* ========================================
Surfaces
Purpose-named backgrounds, derived from the neutral contrast ramp below.
A component picks a ROLE, never a ramp step, so depth is automatic in
both appearances: `--surface-overlay` reads as a foreground surface in
both schemes, so a dialog or popover separates from the page behind it
without each component re-picking a ramp step.
======================================== */
--surface-base: var(--color-contrast-50);
--surface-sunken: var(--color-contrast-100);
--surface-raised: var(--color-contrast-100);
--surface-overlay: var(--color-contrast-100);
--surface-inset: var(--color-contrast-150);
/* ========================================
Target Spacing
Space between interactive controls matters as much as their size: too
little and a mis-tap hits the neighbour. Bezeled controls already read
as separate boxes, so they need less; borderless or icon-only controls
have no visible edge to aim at and need more.
======================================== */
--target-gap-bezel: var(--size-3); /* 12px between bordered controls */
--target-gap-open: var(--size-6); /* 24px around borderless/icon-only controls */
/* ========================================
Safe-area Insets
Edge-docked chrome (docked dialogs, drawers, bottom nav, command
palettes, toasts) must clear notches and home indicators. Defaults to 0
off-device, so `max()` against a spacing token keeps the design intact.
======================================== */
--safe-area-inset-block-start: env(safe-area-inset-top, 0px);
--safe-area-inset-block-end: env(safe-area-inset-bottom, 0px);
--safe-area-inset-inline-start: env(safe-area-inset-left, 0px);
--safe-area-inset-inline-end: env(safe-area-inset-right, 0px);
/* ========================================
Star Gold
The rating control's default fill. Lives here (a hand-authored singleton,
not one of the generated families) so `light-dark()` resolves once at the
themed root: per-component copies of the function get lowered against a
stylesheet that lacks the scheme switches.
======================================== */
--color-star: light-dark(oklch(76% 0.16 76deg), oklch(81% 0.15 76deg));
/* ── theme-tokens:generated:begin: run `bun run sync:theme`, do not hand-edit ── */
/* ── Contrast scale: Neutral OKLCH with a lifted, non-pure-black Dark Mode baseline ── */
--color-contrast-50: light-dark(oklch(99% 0.001 70deg), oklch(17% 0.0005 70deg)); /* Canvas, page background */
--color-contrast-100: light-dark(oklch(97% 0.001 70deg), oklch(21% 0.0005 70deg)); /* Cards, elevated surfaces */
--color-contrast-150: light-dark(
oklch(95.5% 0.001 70deg),
oklch(23.5% 0.0005 70deg)
); /* Midpoint: chip base, subtle fills */
--color-contrast-200: light-dark(oklch(94% 0.001 70deg), oklch(26% 0.0005 70deg)); /* Nested cards, hover states */
--color-contrast-300: light-dark(oklch(89% 0.002 70deg), oklch(32% 0.0005 70deg)); /* Borders, dividers */
--color-contrast-400: light-dark(
oklch(81% 0.002 70deg),
oklch(40% 0.0005 70deg)
); /* Disabled backgrounds, subtle UI */
--color-contrast-500: light-dark(
oklch(49% 0.002 70deg),
oklch(62% 0.001 70deg)
); /* Tertiary text - AA compliant (4.5:1 on canvas/card/sunken) */
--color-contrast-600: light-dark(
oklch(40% 0.002 70deg),
oklch(68% 0.001 70deg)
); /* Secondary text - AA compliant */
--color-contrast-700: light-dark(oklch(32% 0.002 70deg), oklch(78% 0.001 70deg)); /* Body text - AAA compliant */
--color-contrast-800: light-dark(oklch(22% 0.002 70deg), oklch(88% 0.001 70deg)); /* Headings - AAA compliant */
--color-contrast-900: light-dark(
oklch(12% 0.002 70deg),
oklch(95% 0.001 70deg)
); /* High contrast text - AAA compliant */
--color-canvas: color-mix(in oklch, var(--color-contrast-50) 85%, transparent);
--color-divider: color-mix(in oklch, var(--color-contrast-300) 85%, transparent);
--color-contrast: color-mix(in oklch, var(--color-contrast-900) 85%, transparent);
/* Scrim: the dimming veil behind overlays. A veil always darkens, so it */
/* must not invert with the contrast ramp (near-white in dark mode would */
/* brighten the page); plain black alpha, heavier in dark mode. */
--color-scrim: light-dark(rgb(0 0 0 / 55%), rgb(0 0 0 / 72%));
/* Overlay veil: the single dimming recipe behind every overlay backdrop */
/* (dialog, drawer, command palette, tour, sidebar drawer). */
--overlay-veil: color-mix(in oklch, var(--color-scrim) 70%, transparent);
/* ── Shade ramp: shared derivation recipe for every color family below ──── */
/* Every family only authors a `base` (+ content/contrast ink pair); every */
/* other sub-token is `oklch(from var(--color-x) ...)`, derived from that */
/* single base using the deltas below. Tune a family by editing its base; */
/* tune the ramp shape itself (e.g. how much lighter "-lighter" is) here, */
/* once, for all 7 families at once. */
--shade-lighter-l: 0.3;
--shade-lighter-c: 0.35;
--shade-light-l: 0.14;
--shade-light-c: 0.8;
--shade-dark-l: -0.14;
--shade-darker-l: -0.26;
--shade-darker-c: 0.85;
--shade-darker-h: -12;
--shade-focus-l: 0.06;
--shade-border-alpha: 60%;
--shade-focus-ring-strength: 40%;
--shade-backdrop-l-light: 93%;
--shade-backdrop-l-dark: 24%;
--shade-backdrop-c-light: 0.3;
--shade-backdrop-c-dark: 0.5;
--shade-backdrop-alpha-light: 83%;
--shade-backdrop-alpha-dark: 50%;
--shade-halo-glow: 15%;
--shade-halo-glow-soft: 8%;
/* ── Halo shadows: branded glow per color family ───────────────────────── */
--halo-shadow-neutral:
inset 0 1px 1px light-dark(rgb(0 0 0 / 5%), transparent),
0 0 var(--size-1) light-dark(rgb(255 255 255 / 10%), transparent) inset,
0 var(--size-2) var(--size-6) color-mix(in oklch, var(--color-neutral) var(--shade-halo-glow), transparent),
0 var(--size-1) var(--size-3) color-mix(in oklch, var(--color-neutral) var(--shade-halo-glow-soft), transparent);
--halo-shadow-primary:
inset 0 1px 1px light-dark(rgb(0 0 0 / 5%), rgb(255 255 255 / 3%)),
0 0 var(--size-1) light-dark(rgb(255 255 255 / 10%), rgb(255 255 255 / 12%)) inset,
0 var(--size-2) var(--size-6) color-mix(in oklch, var(--color-primary) var(--shade-halo-glow), transparent),
0 var(--size-1) var(--size-3) color-mix(in oklch, var(--color-primary) var(--shade-halo-glow-soft), transparent);
--halo-shadow-secondary:
inset 0 1px 1px light-dark(rgb(0 0 0 / 5%), rgb(255 255 255 / 3%)),
0 0 var(--size-1) light-dark(rgb(255 255 255 / 10%), rgb(255 255 255 / 12%)) inset,
0 var(--size-2) var(--size-6) color-mix(in oklch, var(--color-secondary) var(--shade-halo-glow), transparent),
0 var(--size-1) var(--size-3) color-mix(in oklch, var(--color-secondary) var(--shade-halo-glow-soft), transparent);
--halo-shadow-info:
inset 0 1px 1px light-dark(rgb(0 0 0 / 5%), rgb(255 255 255 / 3%)),
0 0 var(--size-1) light-dark(rgb(255 255 255 / 10%), rgb(255 255 255 / 12%)) inset,
0 var(--size-2) var(--size-6) color-mix(in oklch, var(--color-info) var(--shade-halo-glow), transparent),
0 var(--size-1) var(--size-3) color-mix(in oklch, var(--color-info) var(--shade-halo-glow-soft), transparent);
--halo-shadow-success:
inset 0 1px 1px light-dark(rgb(0 0 0 / 5%), rgb(255 255 255 / 3%)),
0 0 var(--size-1) light-dark(rgb(255 255 255 / 10%), rgb(255 255 255 / 12%)) inset,
0 var(--size-2) var(--size-6) color-mix(in oklch, var(--color-success) var(--shade-halo-glow), transparent),
0 var(--size-1) var(--size-3) color-mix(in oklch, var(--color-success) var(--shade-halo-glow-soft), transparent);
--halo-shadow-warning:
inset 0 1px 1px light-dark(rgb(0 0 0 / 5%), rgb(255 255 255 / 3%)),
0 0 var(--size-1) light-dark(rgb(255 255 255 / 10%), rgb(255 255 255 / 12%)) inset,
0 var(--size-2) var(--size-6) color-mix(in oklch, var(--color-warning) var(--shade-halo-glow), transparent),
0 var(--size-1) var(--size-3) color-mix(in oklch, var(--color-warning) var(--shade-halo-glow-soft), transparent);
--halo-shadow-error:
inset 0 1px 1px light-dark(rgb(0 0 0 / 5%), rgb(255 255 255 / 3%)),
0 0 var(--size-1) light-dark(rgb(255 255 255 / 10%), rgb(255 255 255 / 12%)) inset,
0 var(--size-2) var(--size-6) color-mix(in oklch, var(--color-error) var(--shade-halo-glow), transparent),
0 var(--size-1) var(--size-3) color-mix(in oklch, var(--color-error) var(--shade-halo-glow-soft), transparent);
/* ── Neutral: Warm gray: neutral UI surfaces ── */
--color-neutral: light-dark(oklch(52% 0.004 70deg), oklch(72% 0.004 70deg));
--color-neutral-backdrop: light-dark(
oklch(
from var(--color-neutral) var(--shade-backdrop-l-light) calc(c * var(--shade-backdrop-c-light)) h /
var(--shade-backdrop-alpha-light)
),
oklch(
from var(--color-neutral) var(--shade-backdrop-l-dark) calc(c * var(--shade-backdrop-c-dark)) h /
var(--shade-backdrop-alpha-dark)
)
);
--color-neutral-content: light-dark(
oklch(from var(--color-neutral) 99% calc(c * 0) h),
oklch(from var(--color-neutral) 22% calc(c * 0) h)
);
--color-neutral-contrast: light-dark(
oklch(from var(--color-neutral) 99% calc(c * 0) h),
oklch(from var(--color-neutral) 13% calc(c * 0) h)
);
--color-neutral-lighter: oklch(
from var(--color-neutral) clamp(0, calc(l + var(--shade-lighter-l)), 1) calc(c * var(--shade-lighter-c)) h
);
--color-neutral-light: oklch(
from var(--color-neutral) clamp(0, calc(l + var(--shade-light-l)), 1) calc(c * var(--shade-light-c)) h
);
--color-neutral-dark: oklch(from var(--color-neutral) clamp(0, calc(l + var(--shade-dark-l)), 1) c h);
--color-neutral-darker: oklch(
from var(--color-neutral) clamp(0, calc(l + var(--shade-darker-l)), 1) calc(c * var(--shade-darker-c))
calc(h + var(--shade-darker-h))
);
--color-neutral-focus: oklch(from var(--color-neutral) clamp(0, calc(l + var(--shade-focus-l)), 1) c h);
--color-neutral-border: oklch(from var(--color-neutral) l c h / var(--shade-border-alpha));
--color-neutral-focus-shadow:
0 0 0 4px color-mix(in oklch, var(--color-neutral) var(--shade-focus-ring-strength), transparent),
var(--shadow-sm);
/* ── Primary: Violet: primary brand color ── */
--color-primary-hue: 300deg;
--color-primary: light-dark(oklch(38% 0.14 var(--color-primary-hue)), oklch(63% 0.17 var(--color-primary-hue)));
--color-primary-backdrop: light-dark(
oklch(
from var(--color-primary) var(--shade-backdrop-l-light) calc(c * var(--shade-backdrop-c-light)) h /
var(--shade-backdrop-alpha-light)
),
oklch(
from var(--color-primary) var(--shade-backdrop-l-dark) calc(c * var(--shade-backdrop-c-dark)) h /
var(--shade-backdrop-alpha-dark)
)
);
--color-primary-content: light-dark(
oklch(from var(--color-primary) 97% calc(c * 0.05) h),
oklch(from var(--color-primary) 22% calc(c * 0.3) h)
);
--color-primary-contrast: light-dark(
oklch(from var(--color-primary) 98% calc(c * 0.045) h),
oklch(from var(--color-primary) 14% calc(c * 0.3) h)
);
--color-primary-lighter: oklch(
from var(--color-primary) clamp(0, calc(l + var(--shade-lighter-l)), 1) calc(c * var(--shade-lighter-c)) h
);
--color-primary-light: oklch(
from var(--color-primary) clamp(0, calc(l + var(--shade-light-l)), 1) calc(c * var(--shade-light-c)) h
);
--color-primary-dark: oklch(from var(--color-primary) clamp(0, calc(l + var(--shade-dark-l)), 1) c h);
--color-primary-darker: oklch(
from var(--color-primary) clamp(0, calc(l + var(--shade-darker-l)), 1) calc(c * var(--shade-darker-c))
calc(h + var(--shade-darker-h))
);
--color-primary-focus: oklch(from var(--color-primary) clamp(0, calc(l + var(--shade-focus-l)), 1) c h);
--color-primary-border: oklch(from var(--color-primary) l c h / var(--shade-border-alpha));
--color-primary-focus-shadow:
0 0 0 4px color-mix(in oklch, var(--color-primary) var(--shade-focus-ring-strength), transparent),
var(--shadow-sm);
/* ── Secondary: Ink/charcoal (light) · silver (dark): auto-derived from --color-primary-hue ── */
--color-secondary: light-dark(
color-mix(in oklch, oklch(20% 0 none) 86%, var(--color-primary)),
color-mix(in oklch, oklch(83% 0 none) 86%, var(--color-primary))
);
--color-secondary-backdrop: light-dark(
oklch(
from var(--color-secondary) var(--shade-backdrop-l-light) calc(c * var(--shade-backdrop-c-light)) h /
var(--shade-backdrop-alpha-light)
),
oklch(
from var(--color-secondary) var(--shade-backdrop-l-dark) calc(c * var(--shade-backdrop-c-dark)) h /
var(--shade-backdrop-alpha-dark)
)
);
--color-secondary-content: light-dark(
oklch(from var(--color-secondary) 97% 0.0015 h),
oklch(from var(--color-secondary) 22% 0.002 h)
);
--color-secondary-contrast: light-dark(
oklch(from var(--color-secondary) 98% 0.002 h),
oklch(from var(--color-secondary) 13% 0.003 h)
);
--color-secondary-lighter: oklch(
from var(--color-secondary) clamp(0, calc(l + var(--shade-lighter-l)), 1) calc(c * var(--shade-lighter-c)) h
);
--color-secondary-light: oklch(
from var(--color-secondary) clamp(0, calc(l + var(--shade-light-l)), 1) calc(c * var(--shade-light-c)) h
);
--color-secondary-dark: oklch(from var(--color-secondary) clamp(0, calc(l + var(--shade-dark-l)), 1) c h);
--color-secondary-darker: oklch(
from var(--color-secondary) clamp(0, calc(l + var(--shade-darker-l)), 1) calc(c * var(--shade-darker-c))
calc(h + var(--shade-darker-h))
);
--color-secondary-focus: oklch(from var(--color-secondary) clamp(0, calc(l + var(--shade-focus-l)), 1) c h);
--color-secondary-border: oklch(from var(--color-secondary) l c h / var(--shade-border-alpha));
--color-secondary-focus-shadow:
0 0 0 4px color-mix(in oklch, var(--color-secondary) var(--shade-focus-ring-strength), transparent),
var(--shadow-sm);
/* ── Info: Blue: informational messages ── */
--color-info: light-dark(oklch(53% 0.118 244deg), oklch(78% 0.109 244deg));
--color-info-backdrop: light-dark(
oklch(
from var(--color-info) var(--shade-backdrop-l-light) calc(c * var(--shade-backdrop-c-light)) h /
var(--shade-backdrop-alpha-light)
),
oklch(
from var(--color-info) var(--shade-backdrop-l-dark) calc(c * var(--shade-backdrop-c-dark)) h /
var(--shade-backdrop-alpha-dark)
)
);
--color-info-content: light-dark(
oklch(from var(--color-info) 97% 0.004 h),
oklch(from var(--color-info) 15% 0.004 h)
);
--color-info-contrast: light-dark(
oklch(from var(--color-info) 98% 0.004 h),
oklch(from var(--color-info) 12% 0.004 h)
);
--color-info-lighter: oklch(
from var(--color-info) clamp(0, calc(l + var(--shade-lighter-l)), 1) calc(c * var(--shade-lighter-c)) h
);
--color-info-light: oklch(
from var(--color-info) clamp(0, calc(l + var(--shade-light-l)), 1) calc(c * var(--shade-light-c)) h
);
--color-info-dark: oklch(from var(--color-info) clamp(0, calc(l + var(--shade-dark-l)), 1) c h);
--color-info-darker: oklch(
from var(--color-info) clamp(0, calc(l + var(--shade-darker-l)), 1) calc(c * var(--shade-darker-c))
calc(h + var(--shade-darker-h))
);
--color-info-focus: oklch(from var(--color-info) clamp(0, calc(l + var(--shade-focus-l)), 1) c h);
--color-info-border: oklch(from var(--color-info) l c h / var(--shade-border-alpha));
--color-info-focus-shadow:
0 0 0 4px color-mix(in oklch, var(--color-info) var(--shade-focus-ring-strength), transparent), var(--shadow-sm);
/* ── Success: Bluish green: positive outcomes & confirmations ── */
--color-success: light-dark(oklch(53% 0.1 165deg), oklch(78% 0.148 165deg));
--color-success-backdrop: light-dark(
oklch(
from var(--color-success) var(--shade-backdrop-l-light) calc(c * var(--shade-backdrop-c-light)) h /
var(--shade-backdrop-alpha-light)
),
oklch(
from var(--color-success) var(--shade-backdrop-l-dark) calc(c * var(--shade-backdrop-c-dark)) h /
var(--shade-backdrop-alpha-dark)
)
);
--color-success-content: light-dark(
oklch(from var(--color-success) 97% 0.004 h),
oklch(from var(--color-success) 15% 0.004 h)
);
--color-success-contrast: light-dark(
oklch(from var(--color-success) 98% 0.004 h),
oklch(from var(--color-success) 12% 0.004 h)
);
--color-success-lighter: oklch(
from var(--color-success) clamp(0, calc(l + var(--shade-lighter-l)), 1) calc(c * var(--shade-lighter-c)) h
);
--color-success-light: oklch(
from var(--color-success) clamp(0, calc(l + var(--shade-light-l)), 1) calc(c * var(--shade-light-c)) h
);
--color-success-dark: oklch(from var(--color-success) clamp(0, calc(l + var(--shade-dark-l)), 1) c h);
--color-success-darker: oklch(
from var(--color-success) clamp(0, calc(l + var(--shade-darker-l)), 1) calc(c * var(--shade-darker-c))
calc(h + var(--shade-darker-h))
);
--color-success-focus: oklch(from var(--color-success) clamp(0, calc(l + var(--shade-focus-l)), 1) c h);
--color-success-border: oklch(from var(--color-success) l c h / var(--shade-border-alpha));
--color-success-focus-shadow:
0 0 0 4px color-mix(in oklch, var(--color-success) var(--shade-focus-ring-strength), transparent),
var(--shadow-sm);
/* ── Warning: Amber: cautionary states & alerts ── */
--color-warning: light-dark(oklch(54% 0.105 70deg), oklch(78% 0.147 70deg));
--color-warning-backdrop: light-dark(
oklch(
from var(--color-warning) var(--shade-backdrop-l-light) calc(c * var(--shade-backdrop-c-light)) h /
var(--shade-backdrop-alpha-light)
),
oklch(
from var(--color-warning) var(--shade-backdrop-l-dark) calc(c * var(--shade-backdrop-c-dark)) h /
var(--shade-backdrop-alpha-dark)
)
);
--color-warning-content: light-dark(
oklch(from var(--color-warning) 97% 0.004 h),
oklch(from var(--color-warning) 15% 0.004 h)
);
--color-warning-contrast: light-dark(
oklch(from var(--color-warning) 98% 0.004 h),
oklch(from var(--color-warning) 12% 0.004 h)
);
--color-warning-lighter: oklch(
from var(--color-warning) clamp(0, calc(l + var(--shade-lighter-l)), 1) calc(c * var(--shade-lighter-c)) h
);
--color-warning-light: oklch(
from var(--color-warning) clamp(0, calc(l + var(--shade-light-l)), 1) calc(c * var(--shade-light-c)) h
);
--color-warning-dark: oklch(from var(--color-warning) clamp(0, calc(l + var(--shade-dark-l)), 1) c h);
--color-warning-darker: oklch(
from var(--color-warning) clamp(0, calc(l + var(--shade-darker-l)), 1) calc(c * var(--shade-darker-c))
calc(h + var(--shade-darker-h))
);
--color-warning-focus: oklch(from var(--color-warning) clamp(0, calc(l + var(--shade-focus-l)), 1) c h);
--color-warning-border: oklch(from var(--color-warning) l c h / var(--shade-border-alpha));
--color-warning-focus-shadow:
0 0 0 4px color-mix(in oklch, var(--color-warning) var(--shade-focus-ring-strength), transparent),
var(--shadow-sm);
/* ── Error: Red: destructive actions & errors ── */
--color-error: light-dark(oklch(38% 0.141 29deg), oklch(63% 0.178 29deg));
--color-error-backdrop: light-dark(
oklch(
from var(--color-error) var(--shade-backdrop-l-light) calc(c * var(--shade-backdrop-c-light)) h /
var(--shade-backdrop-alpha-light)
),
oklch(
from var(--color-error) var(--shade-backdrop-l-dark) calc(c * var(--shade-backdrop-c-dark)) h /
var(--shade-backdrop-alpha-dark)
)
);
--color-error-content: light-dark(
oklch(from var(--color-error) 97% 0.004 h),
oklch(from var(--color-error) 15% 0.004 h)
);
--color-error-contrast: light-dark(
oklch(from var(--color-error) 98% 0.004 h),
oklch(from var(--color-error) 12% 0.004 h)
);
--color-error-lighter: oklch(
from var(--color-error) clamp(0, calc(l + var(--shade-lighter-l)), 1) calc(c * var(--shade-lighter-c)) h
);
--color-error-light: oklch(
from var(--color-error) clamp(0, calc(l + var(--shade-light-l)), 1) calc(c * var(--shade-light-c)) h
);
--color-error-dark: oklch(from var(--color-error) clamp(0, calc(l + var(--shade-dark-l)), 1) c h);
--color-error-darker: oklch(
from var(--color-error) clamp(0, calc(l + var(--shade-darker-l)), 1) calc(c * var(--shade-darker-c))
calc(h + var(--shade-darker-h))
);
--color-error-focus: oklch(from var(--color-error) clamp(0, calc(l + var(--shade-focus-l)), 1) c h);
--color-error-border: oklch(from var(--color-error) l c h / var(--shade-border-alpha));
--color-error-focus-shadow:
0 0 0 4px color-mix(in oklch, var(--color-error) var(--shade-focus-ring-strength), transparent), var(--shadow-sm);
/* ── theme-tokens:generated:end ── */
}
/* ========================================
Reduced Motion
======================================== */
/* Three-state motion mode, mirroring necromancer's MotionMode:
- OS preference (default): reduced when the OS says so.
- data-motion='reduced': the app forces reduction.
- data-motion='full': the app opts back in despite the OS.
Set the attribute with setMotionMode() ('@vielzeug/refine'); 'system'
removes it. The declaration list is duplicated across the two blocks
because CSS has no shared declaration list across a media query and a
plain selector; keep the two in sync.
The --_motion-* pair is the component-level escape hatch (53 consumers
write `animation: var(--_motion-animation, ...)`). It lives here on
:root rather than in a per-component mixin because custom properties
inherit through shadow boundaries, so one root declaration reaches every
component, and unlike a media-query-only mixin it can honor the
data-motion='full' opt-out. */
@media (prefers-reduced-motion: reduce) {
:root:not([data-motion='full']) {
--duration-75: 0ms;
--duration-100: 0ms;
--duration-150: 0ms;
--duration-200: 0ms;
--duration-250: 0ms;
--duration-300: 0ms;
--duration-350: 0ms;
--duration-500: 0ms;
--duration-600: 0ms;
--duration-700: 0ms;
--duration-1000: 0ms;
--duration-1200: 0ms;
--duration-1400: 0ms;
--duration-1500: 0ms;
--transition-fast: none;
--transition-normal: none;
--transition-slow: none;
--transition-slower: none;
--transition-spring: none;
--transition-exit: none;
--transition-loader: none;
--_motion-transition: none;
--_motion-animation: none;
}
}
:root[data-motion='reduced'] {
--duration-75: 0ms;
--duration-100: 0ms;
--duration-150: 0ms;
--duration-200: 0ms;
--duration-250: 0ms;
--duration-300: 0ms;
--duration-350: 0ms;
--duration-500: 0ms;
--duration-600: 0ms;
--duration-700: 0ms;
--duration-1000: 0ms;
--duration-1200: 0ms;
--duration-1400: 0ms;
--duration-1500: 0ms;
--transition-fast: none;
--transition-normal: none;
--transition-slow: none;
--transition-slower: none;
--transition-spring: none;
--transition-exit: none;
--transition-loader: none;
--_motion-transition: none;
--_motion-animation: none;
}
/* Refine's dark-mode contract: toggle `classList.add/remove('dark')` on */
/* `<html>`, nothing else. Forcing `color-scheme` here (rather than only */
/* relying on `prefers-color-scheme`) is what makes every `light-dark()` */
/* token in this file resolve to the right branch once `.dark` is present, */
/* overriding the OS preference. See docs/refine/theming.md "Toggle dark */
/* mode": any consumer, not just this repo's own docs site, can rely on */
/* this class toggle. */
html.dark {
--surface-overlay: var(--color-contrast-200);
color-scheme: dark;
}
html:not(.dark) {
color-scheme: light;
}
/* ========================================
Increased Contrast
A third appearance context alongside light and dark. The OS "increase
contrast" setting and an explicit `html.contrast-more` class both push the
neutral ramp toward the extremes, thicken separators, and strengthen focus
rings, so a consumer that cannot read the default ramp has a verified
higher-contrast path instead of no path at all.
======================================== */
@media (prefers-contrast: more) {
:root {
--color-contrast-500: light-dark(oklch(43% 0.002 70deg), oklch(72% 0.001 70deg));
--color-contrast-600: light-dark(oklch(34% 0.002 70deg), oklch(80% 0.001 70deg));
--color-contrast-300: light-dark(oklch(74% 0.002 70deg), oklch(46% 0.001 70deg));
--color-divider: var(--color-contrast-300);
--focus-ring-width: var(--border-4);
}
}
html.contrast-more {
--color-contrast-500: light-dark(oklch(43% 0.002 70deg), oklch(72% 0.001 70deg));
--color-contrast-600: light-dark(oklch(34% 0.002 70deg), oklch(80% 0.001 70deg));
--color-contrast-300: light-dark(oklch(74% 0.002 70deg), oklch(46% 0.001 70deg));
--color-divider: var(--color-contrast-300);
--focus-ring-width: var(--border-4);
}
}Token Architecture (for contributors)
The color section of theme.css (contrast scale, the 7 semantic families, halo shadows) is generated, not hand-typed: see packages/refine/scripts/theme-tokens.mjs. Each family authors one base color (plus two small ink pairs for content/contrast); every other sub-token: backdrop, lighter, light, dark, darker, focus, border, focus-shadow, halo-shadow: is mechanically derived from that base with OKLCH relative color syntax. This is why overriding just --color-{name} (as shown throughout this page) is enough for most rebrands: the derived tokens read the override live, at the CSS level, with no rebuild.
Two rules keep this maintainable and stay out of your way as a consumer:
- Tokens are delivery-mechanism-agnostic. The
.darkclass toggle (see Dark Mode) is Refine's own contract, not tied to VitePress, a router, or any specific app shell: theme tokens never assume a particular framework is present. - The generated block is verified, not trusted.
bun run --filter @vielzeug/refine check:themefails the build iftheme.css's generated block andtheme-tokens.mjsdrift apart, the same guaranteecheck:manifestgives the package's export map.