Appearance
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 skyNaming: --av-<hue>-<step>, e.g. --av-emerald-500.
Spacing — 4pt grid
| Token | rem | px | Typical use |
|---|---|---|---|
--av-space-0 | 0 | 0 | Reset |
--av-space-px | 0.0625 | 1 | Hairlines |
--av-space-0-5 | 0.125 | 2 | Icon nudges |
--av-space-1 | 0.25 | 4 | Icon–label gap |
--av-space-1-5 | 0.375 | 6 | Badge padding |
--av-space-2 | 0.5 | 8 | Tight stacks |
--av-space-2-5 | 0.625 | 10 | Small input padding |
--av-space-3 | 0.75 | 12 | Button padding-x |
--av-space-4 | 1 | 16 | Default gap |
--av-space-5 | 1.25 | 20 | Card padding |
--av-space-6 | 1.5 | 24 | Section gap |
--av-space-8 | 2 | 32 | Block separation |
--av-space-10 | 2.5 | 40 | Page padding |
--av-space-12 | 3 | 48 | Major sections |
--av-space-16 | 4 | 64 | Hero padding |
--av-space-20 | 5 | 80 | |
--av-space-24 | 6 | 96 | |
--av-space-32 | 8 | 128 |
Important — space tokens are multiplied by the density scale. Under
data-av-density="compact",--av-space-4resolves to0.8rem, not1rem. Never bypass the tokens with a rawrem, or the density modes will not apply to your component.
Radius
| Token | Value | Use |
|---|---|---|
--av-radius-none | 0 | Flush edges |
--av-radius-xs | 0.25rem | Badges, chips |
--av-radius-sm | 0.375rem | Small buttons, inputs |
--av-radius-md | 0.5rem | Default — buttons, inputs |
--av-radius-lg | 0.75rem | Cards, panels |
--av-radius-xl | 1rem | Modals, large cards |
--av-radius-2xl | 1.5rem | Hero surfaces |
--av-radius-3xl | 2rem | Feature panels |
--av-radius-full | 9999px | Pills, avatars |
All are multiplied by --av-radius-scale, driven by data-av-radius:
data-av-radius | Scale |
|---|---|
sharp | 0 |
subtle | 0.5 |
rounded | 1 (default) |
pill | 1.6 |
Typography primitives
| Token | Value |
|---|---|
--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-7xl | 0.625rem → 4.5rem (see Typography) |
--av-font-weight-light … --av-font-weight-black | 300 → 900 |
--av-line-height-none … --av-line-height-loose | 1 → 2 |
--av-tracking-tighter … --av-tracking-widest | −0.05em → 0.1em |
Shadow
| Token | Definition |
|---|---|
--av-shadow-xs | 0 1px 2px 0 oklch(var(--av-shadow-color) / .05) |
--av-shadow-sm | 0 1px 2px -1px … / .06, 0 1px 3px 0 … / .10 |
--av-shadow-md | 0 2px 4px -2px … / .06, 0 4px 12px -2px … / .10 |
--av-shadow-lg | 0 4px 6px -4px … / .05, 0 10px 24px -4px … / .12 |
--av-shadow-xl | 0 8px 10px -6px … / .05, 0 20px 40px -8px … / .14 |
--av-shadow-2xl | 0 32px 64px -12px … / .22 |
--av-shadow-inner | inset 0 2px 4px 0 … / .05 |
--av-shadow-focus | 0 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
| Token | Definition |
|---|---|
--av-overlay-alpha | .55 |
--av-overlay | oklch(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 —
.55in the dialog and drawer,.5in the command palette, and0% 0 0 / .45behind the off-canvas sidebar, which had lost the blue tint altogether. Nothing caught it:lint:cssrequired a token forbackground-colorand not for thebackgroundshorthand, 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
| Token | Value |
|---|---|
--av-duration-instant | 0ms |
--av-duration-fastest | 80ms |
--av-duration-fast | 140ms |
--av-duration-normal | 220ms |
--av-duration-slow | 320ms |
--av-duration-slower | 480ms |
--av-ease-linear | linear |
--av-ease-standard | cubic-bezier(.2, 0, 0, 1) |
--av-ease-decelerate | cubic-bezier(0, 0, 0, 1) |
--av-ease-accelerate | cubic-bezier(.3, 0, 1, 1) |
--av-ease-emphasized | cubic-bezier(.2, 0, 0, 1) |
--av-ease-spring | linear(0, .68 28%, 1.03 46%, .995 70%, 1) |
Z-index
Every layered element is registered. Never invent a z-index.
| Token | Value | Layer |
|---|---|---|
--av-z-below | −1 | Decorative backgrounds |
--av-z-base | 0 | Normal flow |
--av-z-raised | 10 | Hovered cards |
--av-z-sticky | 100 | Sticky table headers |
--av-z-topbar | 1020 | Topbar |
--av-z-sidebar | 1030 | Sidebar |
--av-z-backdrop | 1040 | Modal/offcanvas backdrop |
--av-z-drawer | 1045 | Utility drawer |
--av-z-modal | 1055 | Modal |
--av-z-popover | 1070 | Popovers, dropdowns |
--av-z-tooltip | 1080 | Tooltips |
--av-z-toast | 1090 | Toasts |
--av-z-palette | 1100 | Command palette |
--av-z-max | 2147483647 | Debug overlays only |
Tier 2 — Semantic reference
Surfaces
| Token | Light | Dark | Use |
|---|---|---|---|
--av-surface-base | neutral-50 | neutral-950 | Page background |
--av-surface-raised | white | neutral-900 | Cards, panels |
--av-surface-overlay | white | neutral-850 | Dropdowns, modals |
--av-surface-sunken | neutral-100 | neutral-925 | Wells, code blocks |
--av-surface-inverse | neutral-900 | neutral-50 | Tooltips |
--av-surface-accent-subtle | primary-50 | primary-950 | Selected rows, highlights |
--av-surface-disabled | neutral-100 | neutral-850 | Disabled controls |
Text
| Token | Light | Dark | Min contrast |
|---|---|---|---|
--av-text-primary | neutral-900 | neutral-50 | 15:1 |
--av-text-secondary | neutral-700 | neutral-300 | 8:1 |
--av-text-muted | neutral-600 | neutral-400 | 4.6:1 |
--av-text-subtle | neutral-500 | neutral-500 | 3.1:1 (large/decorative only) |
--av-text-disabled | neutral-400 | neutral-600 | n/a |
--av-text-inverse | white | neutral-950 | — |
--av-text-on-primary | computed | computed | ≥ 4.5:1 |
--av-text-link | primary-600 | primary-400 | 4.5:1 |
Borders
| Token | Light | Dark |
|---|---|---|
--av-border-subtle | neutral-200 | neutral-800 |
--av-border-default | neutral-300 | neutral-750 |
--av-border-strong | neutral-400 | neutral-600 |
--av-border-inverse | neutral-700 | neutral-300 |
--av-border-focus | primary-500 | primary-400 |
Status
Each status role has five variants:
| Variant | Purpose |
|---|---|
--av-color-<status> | Solid fill |
--av-color-<status>-hover | Hover fill |
--av-color-<status>-subtle | Soft background (badges, alerts) |
--av-color-<status>-border | Border for the soft variant |
--av-color-<status>-text | Readable 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
| Token | Value |
|---|---|
--av-focus-color | var(--av-color-primary) |
--av-focus-width | 2px |
--av-focus-offset | 2px |
--av-focus-ring | 0 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:
| Rule | Check |
|---|---|
| Every reference resolves | A 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 getComputedStyletest: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.