Skip to main content

Design Tokens

Semantic CSS variables, color contrast roles, border radius multipliers, and z-index scales.

View as Markdown

Use semantic CSS variables to customize colors, typography, spacing, border radii, and shadows. A variable applies to the components within its CSS scope.

CSS Variables#

With UnoCSS, presetMoraine() supplies a neutral light and dark palette and accepts named override entries. Use presetMoraine({ wind3: true }) with Wind3. When defining the palette in CSS, set themeDefaults: false and supply the colors and semantic shadows yourself. Tailwind users also define these values in CSS.

Define the base color variables listed below for both the light and the dark theme, along with --radius, --spacing, and --font-size; the -hover, -active, and status -foreground variables are optional. The status colors --info, --success, --warning, and --danger use Moraine’s tuned status palette, where warning is amber/orange rather than bright yellow. Add the semantic shadows and font families described below when using an external theme. Set color-scheme: light or color-scheme: dark in each theme scope so native browser controls follow the theme.

Color Tokens#

Each color token maps to a CSS variable and a utility of the same name. Surfaces and tones expand into -hover and -active variants. Tones also provide -ink for readable text, -soft for translucent washes, and -border for subtle boundaries. The swatches below use the live token values, so they follow the docs site’s light or dark theme:

PreviewTokenCSS variableLight defaultDark default
background--backgroundrgb(255, 255, 255)rgb(10, 10, 10)
background-hover--background-hoverauto (color-mix, 6%)auto (color-mix, 6%)
background-active--background-activeauto (color-mix, 10%)auto (color-mix, 10%)
foreground--foregroundrgb(10, 10, 10)rgb(250, 250, 250)
primary--primaryrgb(23, 23, 23)rgb(229, 229, 229)
primary-foreground--primary-foregroundrgb(250, 250, 250)rgb(23, 23, 23)
primary-hover--primary-hoverauto (color-mix, 6%)auto (color-mix, 6%)
primary-active--primary-activeauto (color-mix, 10%)auto (color-mix, 10%)
primary-ink--primary-inkauto (color-mix, 25%)auto (color-mix, 25%)
primary-soft--primary-softauto (color-mix, 12%)auto (color-mix, 12%)
primary-border--primary-borderauto (color-mix, 20%)auto (color-mix, 20%)
secondary--secondaryrgb(51, 65, 85)rgb(203, 213, 225)
secondary-foreground--secondary-foregroundrgb(248, 250, 252)rgb(15, 23, 42)
secondary-hover--secondary-hoverauto (color-mix, 6%)auto (color-mix, 6%)
secondary-active--secondary-activeauto (color-mix, 10%)auto (color-mix, 10%)
secondary-ink--secondary-inkauto (color-mix, 25%)auto (color-mix, 25%)
secondary-soft--secondary-softauto (color-mix, 12%)auto (color-mix, 12%)
secondary-border--secondary-borderauto (color-mix, 20%)auto (color-mix, 20%)
neutral--neutralrgb(23, 23, 23)rgb(250, 250, 250)
neutral-foreground--neutral-foregroundrgb(250, 250, 250)rgb(23, 23, 23)
neutral-hover--neutral-hoverauto (color-mix, 6%)auto (color-mix, 6%)
neutral-active--neutral-activeauto (color-mix, 10%)auto (color-mix, 10%)
neutral-ink--neutral-inkauto (color-mix, 25%)auto (color-mix, 25%)
neutral-soft--neutral-softauto (color-mix, 12%)auto (color-mix, 12%)
neutral-border--neutral-borderauto (color-mix, 20%)auto (color-mix, 20%)
card--cardrgb(255, 255, 255)rgb(23, 23, 23)
card-foreground--card-foregroundrgb(10, 10, 10)rgb(250, 250, 250)
card-hover--card-hoverauto (color-mix, 6%)auto (color-mix, 6%)
card-active--card-activeauto (color-mix, 10%)auto (color-mix, 10%)
popover--popoverrgb(255, 255, 255)rgb(23, 23, 23)
popover-foreground--popover-foregroundrgb(10, 10, 10)rgb(250, 250, 250)
popover-hover--popover-hoverauto (color-mix, 6%)auto (color-mix, 6%)
popover-active--popover-activeauto (color-mix, 10%)auto (color-mix, 10%)
muted--mutedrgb(245, 245, 245)rgb(32, 32, 32)
muted-foreground--muted-foregroundrgb(115, 115, 115)rgb(161, 161, 161)
muted-hover--muted-hoverauto (color-mix, 6%)auto (color-mix, 6%)
muted-active--muted-activeauto (color-mix, 10%)auto (color-mix, 10%)
accent--accentrgb(235, 235, 235)rgb(46, 46, 46)
accent-foreground--accent-foregroundrgb(23, 23, 23)rgb(250, 250, 250)
accent-hover--accent-hoverauto (color-mix, 6%)auto (color-mix, 6%)
accent-active--accent-activeauto (color-mix, 10%)auto (color-mix, 10%)
danger--dangerrgb(197, 60, 32)rgb(209, 115, 97)
danger-foreground--danger-foregroundfalls back to --backgroundfalls back to --background
danger-hover--danger-hoverauto (color-mix, 6%)auto (color-mix, 6%)
danger-active--danger-activeauto (color-mix, 10%)auto (color-mix, 10%)
danger-ink--danger-inkauto (color-mix, 25%)auto (color-mix, 25%)
danger-soft--danger-softauto (color-mix, 12%)auto (color-mix, 12%)
danger-border--danger-borderauto (color-mix, 20%)auto (color-mix, 20%)
info--inforgb(37, 119, 211)rgb(99, 161, 233)
info-foreground--info-foregroundfalls back to --backgroundfalls back to --background
info-hover--info-hoverauto (color-mix, 6%)auto (color-mix, 6%)
info-active--info-activeauto (color-mix, 10%)auto (color-mix, 10%)
info-ink--info-inkauto (color-mix, 25%)auto (color-mix, 25%)
info-soft--info-softauto (color-mix, 12%)auto (color-mix, 12%)
info-border--info-borderauto (color-mix, 20%)auto (color-mix, 20%)
success--successrgb(51, 134, 68)rgb(81, 169, 114)
success-foreground--success-foregroundfalls back to --backgroundfalls back to --background
success-hover--success-hoverauto (color-mix, 6%)auto (color-mix, 6%)
success-active--success-activeauto (color-mix, 10%)auto (color-mix, 10%)
success-ink--success-inkauto (color-mix, 25%)auto (color-mix, 25%)
success-soft--success-softauto (color-mix, 12%)auto (color-mix, 12%)
success-border--success-borderauto (color-mix, 20%)auto (color-mix, 20%)
warning--warningrgb(171, 102, 24)rgb(198, 158, 57)
warning-foreground--warning-foregroundfalls back to --backgroundfalls back to --background
warning-hover--warning-hoverauto (color-mix, 6%)auto (color-mix, 6%)
warning-active--warning-activeauto (color-mix, 10%)auto (color-mix, 10%)
warning-ink--warning-inkauto (color-mix, 25%)auto (color-mix, 25%)
warning-soft--warning-softauto (color-mix, 12%)auto (color-mix, 12%)
warning-border--warning-borderauto (color-mix, 20%)auto (color-mix, 20%)
border--borderrgb(229, 229, 229)rgb(35, 35, 35)
input--inputrgb(229, 229, 229)rgb(47, 47, 47)
control--controlrgb(255, 255, 255)rgb(23, 23, 23)
backdrop--backdroprgba(0, 0, 0, 0.32)rgba(0, 0, 0, 0.32)
ring--ringrgb(161, 161, 161)rgb(115, 115, 115)

Moraine-specific Variables#

A shadcn/ui palette supplies the shared color roles and --radius. Also configure these variables when adapting an external theme for Moraine:

Variable Purpose Default or fallback
--control Surface for outline fields, unchecked choices, and upload controls; independent of --input boundaries. UnoCSS: white in light mode, rgb(23, 23, 23) in dark mode. No utility fallback; external themes must define it.
--backdrop Scrim behind modal overlays, used by bg-backdrop. Black at 32% opacity.
--shadow-surface, --shadow-overlay, --shadow-input Elevation by component role, used by shadow-surface, shadow-overlay, and shadow-input. UnoCSS: Tailwind sm, md, and xs, respectively. External themes must define them; none removes a role’s shadow.
--<surface>-hover, --<surface>-active Surface interaction colors for accent, muted, card, popover, and background. Generated state color mixing surface base with foreground.
--<tone>-hover, --<tone>-active Tone interaction colors for primary, secondary, neutral, danger, info, success, warning. Generated state color mixing tone base with tone foreground.
--<tone>-ink Accessible text/indicator color for tones (primary, secondary, neutral, etc.). Explicit override, then auto-mixed ink, then base fallback.
--<tone>-soft Translucent wash for tones (primary, secondary, neutral, etc.). Explicit override, then auto-mixed with transparent, then transparent.
--<tone>-border Opaque subtle boundary for tones. Explicit override, then auto-mixed with --border, then --border.
--danger-foreground Text and icon color for danger surfaces. --background.
--info-foreground, --success-foreground, --warning-foreground Text and icon color for status surfaces. --background.
--font-size Local base for Moraine’s text-xs through text-9xl scale in Tailwind 4 and Wind4. 1rem.
--sidebar-width Desktop sidebar width; also used by w-sidebar. No variable value is set by default; the width falls back to clamp(14rem, 25%, 20rem).
--mo-anim-duration Overrides all Moraine CSS animation durations in its scope. Type-specific durations when unset.
--mo-anim-duration-enter, --mo-anim-duration-exit, --mo-anim-duration-loop, --mo-anim-duration-spin Duration per animation family when the global duration is unset. 250ms, 150ms, 2s, and 1s, respectively.
--mo-anim-ease Overrides the easing of animate-mo-enter and animate-mo-exit in its scope. Direction-specific easing when unset.
--mo-anim-ease-enter, --mo-anim-ease-exit Easing for entrance and exit when the shared easing is unset. cubic-bezier(0.16, 1, 0.3, 1) and cubic-bezier(0.7, 0, 0.84, 0), respectively.

UnoCSS emits default control, backdrop, and semantic shadows only when themeDefaults is enabled or the values are explicitly configured. The backdrop utility retains its fallback when the variable is absent. --font-size, --spacing, and --radius keep their root defaults when themeDefaults: false. Animation duration variables use CSS fallbacks unless configured. The preset emits --sidebar-width only when configured; Sidebar uses clamp(14rem, 25%, 20rem) when unset. With Tailwind, supply the palette and shadow values in your stylesheet.

Use override.<theme>.colors for control, backdrop, and explicit interaction colors; use override.<theme>.shadows for semantic shadows. The preset also accepts fontSize, spacing, radius, and sidebarWidth at the top level or inside a theme override. Set animation controls directly in CSS. For example, customize a container using Wind4 or Tailwind v4:

.workspace {
  --font-size: 0.875rem;
  --spacing: 0.2rem;
  --sidebar-width: 18rem;
  --mo-anim-duration-enter: 180ms;
  --mo-anim-duration-exit: 120ms;
}

Variables inherit through DOM ancestors. Portaled overlays need these values on an ancestor of the portal container, such as the document root, or a portal mounted inside the themed container.

Use the Animations guide to customize entrance and exit motion.

Surface Colors and Tones#

Moraine distinguishes surfaces (containers and canvas) from tones (semantic intents and indicators).

Surfaces#

Role Surface token Foreground token Primary use
Control --control --foreground Default outline fields, unchecked choices, upload controls.
Page --background --foreground Default viewport canvas and readable body text.
Card --card --card-foreground Cards and grouped surfaces.
Popover --popover --popover-foreground Floating overlays, menus, tooltips, dialogs.
Muted --muted --muted-foreground Subtle backgrounds, secondary descriptions, disabled state.
Accent --accent --accent-foreground Hover states, tab indicators, highlighted list items.

Tones#

Role Base token Foreground token Ink token Primary use
Primary --primary --primary-foreground --primary-ink High-emphasis brand actions and active selections.
Secondary --secondary --secondary-foreground --secondary-ink Co-equal brand anchor actions (slate default).
Neutral --neutral --neutral-foreground --neutral-ink Monochrome anchor actions and neutral soft badges.
Danger --danger --danger-foreground --danger-ink Destructive actions, errors, and failure feedback.
Info --info --info-foreground --info-ink Informational status and callouts.
Success --success --success-foreground --success-ink Confirmed completion and positive status.
Warning --warning --warning-foreground --warning-ink Caution that needs attention.

Form surface migration#

Define --control in both light and dark external themes. It controls outline fields, unchecked choices, and upload surfaces independently of --input boundaries. Subtle fields use --muted; field text uses --foreground and placeholders use --muted-foreground.

Use the UnoCSS defaults listed under Moraine-specific Variables as a starting point, or supply your own CSS colors or variable references. bg-control/50 supports a translucent control surface. Check text and boundary contrast against the resulting background. control has no dedicated foreground, hover, or active tokens.

State Colors and Tone Ink Derivation#

Moraine generates interaction tokens and tone ink inside an @supports (color: color-mix(in oklch, black, white)) stylesheet block:

  1. Surfaces: --<surface>-hover and --<surface>-active are emitted for accent, muted, card, popover, and background. They mix the surface base with its foreground using the configured mix.hover (default 6%) and mix.active (default 10%) percentages.
  2. Tones: --<tone>-hover and --<tone>-active are emitted for all 7 tones (primary, secondary, neutral, danger, info, success, warning), mixing each tone’s base with its tone foreground using mix.hover and mix.active. Tones also derive --<tone>-ink for readable text on washes, --<tone>-soft for the wash itself, and --<tone>-border for an opaque subtle boundary. State, ink, soft, and border variables follow a 3-tier precedence:
    • Tier 1 (Explicit): User-provided colors.<tone>.hover, .active, .ink, .soft, or .border override.
    • Tier 2 (Auto-mixed): Auto-mixed via color-mix(in oklch, var(--<tone>), var(--<tone>-foreground) <mix>%) (for hover/active), with var(--foreground) (for ink, default 25% foreground), with transparent (for soft, default 12% tone, so the wash composites on the local surface), or with var(--border) (for border, default 20% tone + 80% border).
    • Tier 3 (Fallback): var(--<tone>) for hover/active/ink, transparent for soft, or var(--border) for border.

Inside component recipes like Button and Badge, components bind to the universal --mo-tone channel (bg-tone, border-tone, border-tone-border, bg-tone-soft, hover:bg-tone-soft-hover, active:bg-tone-soft-active, hover:bg-tone-hover, and active:bg-tone-active) to keep recipes free of compound variants, while application code and custom styles can consume --<tone>-hover, --<tone>-active, and utilities like hover:bg-primary-hover directly.

See the UnoCSS guide for configuring mix percentages.

Border Radius Scale#

Set --radius on a container to scale its default named radius utilities. Explicit CSS engine theme overrides can replace these values. The pixel examples below assume 1rem = 16px:

Utility Formula Computed value (with --radius: 0.625rem)
rounded-xs calc(var(--radius) * 0.5) 0.3125rem (5px)
rounded-sm calc(var(--radius) * 0.6) 0.375rem (6px)
rounded-md calc(var(--radius) * 0.8) 0.5rem (8px)
rounded-lg var(--radius) 0.625rem (10px)
rounded-xl calc(var(--radius) * 1.4) 0.875rem (14px)
rounded-2xl calc(var(--radius) * 1.8) 1.125rem (18px)
rounded-3xl calc(var(--radius) * 2.2) 1.375rem (22px)
rounded-4xl calc(var(--radius) * 2.6) 1.625rem (26px)

Backdrop and Semantic Shadows#

Use these tokens to customize component elevation by role. --backdrop controls the overlay behind modals, dialogs, and sheets. Backdrop blur remains a separate class on the overlay slot.

Utility Token UnoCSS default Component use
bg-backdrop --backdrop Black at 32% Modal backdrops
shadow-surface --shadow-surface Tailwind sm Cards, floating sidebar surfaces, badges, indicators
shadow-overlay --shadow-overlay Tailwind md Menus, selection panels, popovers, dialogs, sheets, tooltips, command palettes
shadow-input --shadow-input Tailwind xs Outline and subtle fields, checkbox controls, switch tracks and thumbs, slider thumbs, upload controls

Set a shadow token to none to remove elevation for that role. UnoCSS emits default values for the three semantic shadows, matching Tailwind’s sm, md, and xs values used by shadcn/ui’s neutral theme. With Tailwind or themeDefaults: false, define the semantic shadows in your stylesheet or explicit overrides. Changing a role token leaves explicit size utilities such as shadow-lg unchanged.

src/theme.css
:root {
  --shadow-surface: 0 1px 3px rgb(0 0 0 / 0.05);
  --shadow-overlay: 0 8px 24px rgb(0 0 0 / 0.12);
  --shadow-input: none;
}

.dark {
  --backdrop: rgb(0 0 0 / 0.4);
  --shadow-surface: none;
  --shadow-overlay: 0 8px 24px rgb(0 0 0 / 0.3);
}

These variables can be scoped to a container. Portaled overlays need the variables on an ancestor of their portal container. UnoCSS accepts colors.backdrop and shadows.surface, shadows.overlay, and shadows.input in each named override entry; Tailwind reads the same CSS variables directly.

CSS Engine Shadows#

Size utilities such as shadow-xs, shadow-md, and shadow-lg use the CSS engine’s native shadow scale. Moraine does not register or configure these sizes. Use UnoCSS’s theme options or Tailwind’s @theme to customize them separately from Moraine’s semantic shadows.

Typography and Spacing#

Token Description Fallback
--font-sans Primary UI typeface None in Moraine
--font-mono Code, numbers, and Kbd None in Moraine
--font-serif Editorial serif typeface None in Moraine
--font-size Base for text-xs–text-9xl in Tailwind 4 and Wind4 1rem
--spacing Base spacing unit 0.25rem

With Wind4 and Tailwind v4, set --font-size on a container to scale the default text-xs through text-9xl utilities. Wind3 uses its configured font sizes and does not scale them through --font-size. Explicit CSS engine typography overrides follow the values you configure.

Moraine’s default font-sans, font-mono, and font-serif utilities use the corresponding CSS variables, but Moraine does not supply family values. With UnoCSS, configure theme.font (Wind4) or theme.fontFamily (Wind3) to use literal families or your own variable references; see Font families. To use the default variable mapping, define the families in your stylesheet:

src/theme.css
:root {
  --font-sans: Inter, system-ui, sans-serif;
  --font-mono: 'Maple Mono', ui-monospace, monospace;
  --font-serif: Georgia, serif;
}

Default numeric spacing utilities use the local --spacing in Tailwind v4 and Wind4. For example, p-4 is 2rem under --spacing: 0.5rem. Wind3 keeps its native numeric spacing and size values, including explicit theme overrides, even with wind3: true. Use p-[var(--app-padding)] for variable-based padding in Wind3.

Use leading-* to customize line height. With Wind3, configure typography through UnoCSS’s theme.fontSize and theme.lineHeight.

Semantic Z-Index Utilities#

Moraine avoids magic numeric z-indices in favor of a 7-tier semantic scale:

Utility Value Scope
z-base 1 Base elevated content
z-raised 2 Raised content and ranges
z-control 3 Controls above local ranges
z-sticky 10 Sticky headers and rails
z-resize 20 Splitter and resize handles
z-overlay 40 Backdrop masks and overlay scrims
z-floating 50 Dialogs, popovers, menus, tooltips