Skip to content

Design Tokens ​

The single source of visual truth. Every colour, size, radius, shadow, and duration in AdminVora originates here.

Tokens are generated. tools/build-tokens.mjs holds the ramp tables, tools/presets.mjs every preset definition and tools/styles.mjs every UI style's tokens; npm run tokens writes src/css/tokens.css, one custom property per line, in three tiers.


The three tiers ​

┌─ TIER 1 · PRIMITIVES ────────────────────────────────────────────────┐
│  Raw values. No meaning. Never used directly in component CSS.        │
│  --av-blue-600: oklch(55% .19 258)                                    │
│  --av-space-4:  1rem                                                  │
└──────────────────────────────┬────────────────────────────────────────┘
                               │ referenced by
┌──────────────────────────────▼────────────────────────────────────────┐
│  TIER 2 · SEMANTIC                                                    │
│  Purpose, not appearance. THIS is what flips in dark mode.            │
│  --av-color-primary:  var(--av-blue-600)                              │
│  --av-surface-raised: var(--av-white)                                 │
│  --av-text-muted:     var(--av-neutral-600)                           │
└──────────────────────────────┬────────────────────────────────────────┘
                               │ referenced by
┌──────────────────────────────▼────────────────────────────────────────┐
│  TIER 3 · COMPONENT                                                   │
│  Local, overridable customisation surface for one component.          │
│  --av-card-bg:      var(--av-surface-raised)                          │
│  --av-card-padding: var(--av-space-5)                                 │
└───────────────────────────────────────────────────────────────────────┘

Why three tiers and not one ​

One tier (raw values everywhere) makes rebranding a find-and-replace nightmare and makes dark mode a second stylesheet.

Two tiers works until someone needs "cards in this section have tighter padding" and reaches for !important or a specificity war.

Three tiers means:

scss
/* Change the whole brand */
:root { --av-blue-600: oklch(52% .21 340); }

/* Change how one role looks */
:root { --av-surface-raised: var(--av-neutral-100); }

/* Change one component, in one context, safely */
.dashboard .av-card { --av-card-padding: var(--av-space-4); }

Each is a one-line change at the right level of abstraction.


Tier 1 — Primitive reference ​

Colour ramps ​

14 hues × 11 steps. Full detail in Color System.

neutral  0  50 100 200 300 400 500 600 700 800 900 950
blue     50 100 200 300 400 500 600 700 800 900 950
indigo   violet  purple  fuchsia  pink  rose  red
orange   amber   yellow  lime     green teal  cyan  sky

Naming: --av-<hue>-<step>, e.g. --av-emerald-500.

Spacing — 4pt grid ​

TokenrempxTypical use
--av-space-000Reset
--av-space-px0.06251Hairlines
--av-space-0-50.1252Icon nudges
--av-space-10.254Icon–label gap
--av-space-1-50.3756Badge padding
--av-space-20.58Tight stacks
--av-space-2-50.62510Small input padding
--av-space-30.7512Button padding-x
--av-space-4116Default gap
--av-space-51.2520Card padding
--av-space-61.524Section gap
--av-space-8232Block separation
--av-space-102.540Page padding
--av-space-12348Major sections
--av-space-16464Hero padding
--av-space-20580
--av-space-24696
--av-space-328128

Important — space tokens are multiplied by the density scale. Under data-av-density="compact", --av-space-4 resolves to 0.8rem, not 1rem. Never bypass the tokens with a raw rem, or the density modes will not apply to your component.

Radius ​

TokenValueUse
--av-radius-none0Flush edges
--av-radius-xs0.25remBadges, chips
--av-radius-sm0.375remSmall buttons, inputs
--av-radius-md0.5remDefault — buttons, inputs
--av-radius-lg0.75remCards, panels
--av-radius-xl1remModals, large cards
--av-radius-2xl1.5remHero surfaces
--av-radius-3xl2remFeature panels
--av-radius-full9999pxPills, avatars

All are multiplied by --av-radius-scale, driven by data-av-radius:

data-av-radiusScale
sharp0
subtle0.5
rounded1 (default)
pill1.6

Typography primitives ​

TokenValue
--av-font-sans'InterVariable', system-ui, -apple-system, 'Segoe UI', sans-serif
--av-font-display'PlusJakartaSansVariable', var(--av-font-sans)
--av-font-mono'JetBrainsMonoVariable', ui-monospace, 'SF Mono', monospace
--av-font-size-2xs … --av-font-size-7xl0.625rem → 4.5rem (see Typography)
--av-font-weight-light … --av-font-weight-black300 → 900
--av-line-height-none … --av-line-height-loose1 → 2
--av-tracking-tighter … --av-tracking-widest−0.05em → 0.1em

Shadow ​

TokenDefinition
--av-shadow-xs0 1px 2px 0 oklch(var(--av-shadow-color) / .05)
--av-shadow-sm0 1px 2px -1px … / .06, 0 1px 3px 0 … / .10
--av-shadow-md0 2px 4px -2px … / .06, 0 4px 12px -2px … / .10
--av-shadow-lg0 4px 6px -4px … / .05, 0 10px 24px -4px … / .12
--av-shadow-xl0 8px 10px -6px … / .05, 0 20px 40px -8px … / .14
--av-shadow-2xl0 32px 64px -12px … / .22
--av-shadow-innerinset 0 2px 4px 0 … / .05
--av-shadow-focus0 0 0 var(--av-focus-width) var(--av-focus-color)

--av-shadow-color is a hue-tinted near-black per theme, not pure black. See Elevation.

Overlay ​

TokenDefinition
--av-overlay-alpha.55
--av-overlayoklch(var(--av-shadow-color) / var(--av-overlay-alpha))

The scrim behind anything modal: dialog, drawer, command palette, the off-canvas sidebar's backdrop, a lightbox. Built on the shadow triplet rather than its own colour, because the scrim and the shadow are the same absence of light and a theme that warms one should warm the other. Override --av-overlay-alpha on a component to go lighter or heavier without restating the colour.

This existed as a literal at five sites before it was a token, and had already drifted into three different values — .55 in the dialog and drawer, .5 in the command palette, and 0% 0 0 / .45 behind the off-canvas sidebar, which had lost the blue tint altogether. Nothing caught it: lint:css required a token for background-color and not for the background shorthand, which is how all five were written. A rule that covers the longhand and not the shorthand covers the spelling nobody uses. The linter checks both now.

Motion ​

TokenValue
--av-duration-instant0ms
--av-duration-fastest80ms
--av-duration-fast140ms
--av-duration-normal220ms
--av-duration-slow320ms
--av-duration-slower480ms
--av-ease-linearlinear
--av-ease-standardcubic-bezier(.2, 0, 0, 1)
--av-ease-deceleratecubic-bezier(0, 0, 0, 1)
--av-ease-acceleratecubic-bezier(.3, 0, 1, 1)
--av-ease-emphasizedcubic-bezier(.2, 0, 0, 1)
--av-ease-springlinear(0, .68 28%, 1.03 46%, .995 70%, 1)

Z-index ​

Every layered element is registered. Never invent a z-index.

TokenValueLayer
--av-z-below−1Decorative backgrounds
--av-z-base0Normal flow
--av-z-raised10Hovered cards
--av-z-sticky100Sticky table headers
--av-z-topbar1020Topbar
--av-z-sidebar1030Sidebar
--av-z-backdrop1040Modal/offcanvas backdrop
--av-z-drawer1045Utility drawer
--av-z-modal1055Modal
--av-z-popover1070Popovers, dropdowns
--av-z-tooltip1080Tooltips
--av-z-toast1090Toasts
--av-z-palette1100Command palette
--av-z-max2147483647Debug overlays only

Tier 2 — Semantic reference ​

Surfaces ​

TokenLightDarkUse
--av-surface-baseneutral-50neutral-950Page background
--av-surface-raisedwhiteneutral-900Cards, panels
--av-surface-overlaywhiteneutral-850Dropdowns, modals
--av-surface-sunkenneutral-100neutral-925Wells, code blocks
--av-surface-inverseneutral-900neutral-50Tooltips
--av-surface-accent-subtleprimary-50primary-950Selected rows, highlights
--av-surface-disabledneutral-100neutral-850Disabled controls

Text ​

TokenLightDarkMin contrast
--av-text-primaryneutral-900neutral-5015:1
--av-text-secondaryneutral-700neutral-3008:1
--av-text-mutedneutral-600neutral-4004.6:1
--av-text-subtleneutral-500neutral-5003.1:1 (large/decorative only)
--av-text-disabledneutral-400neutral-600n/a
--av-text-inversewhiteneutral-950—
--av-text-on-primarycomputedcomputed≥ 4.5:1
--av-text-linkprimary-600primary-4004.5:1

Borders ​

TokenLightDark
--av-border-subtleneutral-200neutral-800
--av-border-defaultneutral-300neutral-750
--av-border-strongneutral-400neutral-600
--av-border-inverseneutral-700neutral-300
--av-border-focusprimary-500primary-400

Status ​

Each status role has five variants:

VariantPurpose
--av-color-<status>Solid fill
--av-color-<status>-hoverHover fill
--av-color-<status>-subtleSoft background (badges, alerts)
--av-color-<status>-borderBorder for the soft variant
--av-color-<status>-textReadable text on the soft variant

Statuses: primary, secondary, success, warning, danger, info, neutral.

scss
.av-badge--success-soft {
  background: var(--av-color-success-subtle);
  border: 1px solid var(--av-color-success-border);
  color: var(--av-color-success-text);
}

Focus ​

TokenValue
--av-focus-colorvar(--av-color-primary)
--av-focus-width2px
--av-focus-offset2px
--av-focus-ring0 0 0 var(--av-focus-width) var(--av-focus-color)

Applied once, globally:

scss
// src/scss/base/_focus.scss
:where(a, button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])):focus-visible {
  outline: var(--av-focus-width) solid var(--av-focus-color);
  outline-offset: var(--av-focus-offset);
  border-radius: var(--av-radius-sm);
}

// On dark or coloured surfaces, invert so the ring never disappears
.av-surface-inverse :focus-visible,
[data-av-on-brand] :focus-visible {
  --av-focus-color: var(--av-neutral-0);
}

:where() gives zero specificity, so a component can always override the ring shape without an !important.


Tier 3 — Component tokens ​

Declared at the top of each component's SCSS block. This is the documented customisation surface.

scss
.av-table {
  --av-table-cell-padding-x: var(--av-space-4);
  --av-table-cell-padding-y: var(--av-space-3);
  --av-table-header-bg:      var(--av-surface-sunken);
  --av-table-header-color:   var(--av-text-muted);
  --av-table-border-color:   var(--av-border-subtle);
  --av-table-row-hover-bg:   var(--av-surface-sunken);
  --av-table-row-selected-bg:var(--av-surface-accent-subtle);
  --av-table-stripe-bg:      var(--av-surface-sunken);
}

Consumers override contextually, with no specificity cost:

html
<div class="av-table" style="--av-table-cell-padding-y: var(--av-space-2)">
scss
.reports-page .av-table {
  --av-table-cell-padding-y: var(--av-space-2);
  --av-table-header-bg: transparent;
}

Customising tokens ​

Three tiers, cheapest first. Each reaches the whole product rather than the components you remembered, because everything paints through the tokens.

1. Pick a preset — no code ​

html
<html data-av-preset="pine" data-bs-theme="dark" data-av-radius="sharp">

Theme Presets lists every preset. The customizer writes this attribute and the inline boot script restores it before first paint.

2. Override the custom properties — a stylesheet, no rebuild ​

css
/* your own sheet, loaded after tokens.css */
:root {
  --av-primary-500: oklch(62% 0.20 340);
  --av-primary-600: oklch(54% 0.21 340);
  --av-primary-700: oklch(46% 0.19 340);
  --av-radius-scale: 1.25;              /* the whole radius ladder is a calc() off this */
  --av-font-sans: 'AcmeSans', system-ui, sans-serif;
}

Or one value at a time, at runtime:

js
document.documentElement.style.setProperty('--av-color-primary', 'oklch(58% .21 300)');

tokens.css puts everything in @layer tokens, which is the lowest layer in the cascade, so an unlayered rule of your own wins without needing specificity.

3. Regenerate the ramp — for a full rebrand ​

tools/build-tokens.mjs holds the lightness and chroma tables and the ramp() function; tools/presets.mjs holds every preset. A brand palette is a change to the preset file followed by npm run tokens. It is a script rather than a configuration file, which is blunter than a JSON token source and is what this build has.

There is no SCSS configuration surface behind any of this: no @use 'adminvora' with (…), and no $av-… variables at all — npm run check:scss-api fails the build on any this documentation names. See How the stylesheet is configured.


Token linting ​

npm run lint:tokens enforces exactly one rule, and it is a sharper one than it sounds:

RuleCheck
Every reference resolvesA var(--av-…) with no definition and no fallback fails the build

A custom property that resolves to nothing is not "no value" — it is invalid at computed-value time, which takes the entire declaration with it and leaves the property at its initial value. Nothing warns, in any browser. Two of these shipped: --av-space-7 zeroed the padding on two auth cards and --av-space-14 zeroed the inline padding on the auth brand panel, which is what put the wordmark hard against the diagonal. A reference written with a fallback is deliberate and exempt.

Contrast is a separate gate, because it has to be measured in a browser rather than read off a file:

bash
npm run check:tokens    # every var(--av-…) resolves
npm run test:contrast   # every preset × 2 modes, 4.5:1, from getComputedStyle

test:contrast reads the computed colour out of a real page rather than recomputing it, because the generator's OKLCH maths clamps out-of-gamut values instead of gamut-mapping them and can disagree with the browser about what was actually painted.


Using the palette in Figma ​

Read the OKLCH values out of src/css/tokens.css — a generated file with one custom property per line. There is no Figma export.

Read next: Color System.

Documentation for @creativeigniter/adminvora