Foundations / Tokens

Tokens

The four scales that govern every spatial, surface, and stacking decision in the system.

Section: Foundations

Every --ds-* token below is loaded globally via src/styles/global.css. The CSS file under src/styles/tokens/ is the source of truth; this page reads each var() live, so any drift is immediately visible.

Spacing

4pt grid. Use the numeric tokens for layout, semantic aliases for common patterns.

--ds-space-0 0
--ds-space-0_5 2px
--ds-space-1 4px
--ds-space-2 8px
--ds-space-3 12px
--ds-space-4 16px
--ds-space-5 20px
--ds-space-6 24px
--ds-space-8 32px
--ds-space-10 40px
--ds-space-12 48px
--ds-space-16 64px
--ds-space-20 80px
--ds-space-24 96px
--ds-space-32 128px
spacing.css | css 
/* 4pt grid — every layout decision picks from this scale. */
.card {
  padding: var(--ds-space-6);            /* 24px */
  gap: var(--ds-space-4);                /* 16px */
  margin-bottom: var(--ds-space-8);      /* 32px */
}

.tight-cluster { gap: var(--ds-space-2); } /* 8px between chips */
.section-break { margin-top: var(--ds-space-16); } /* 64px */

Radius

One canonical scale. Legacy --radius-* from three competing systems is being migrated out.

--ds-radius-xs 2px
--ds-radius-sm 4px
--ds-radius-md 8px
--ds-radius-lg 12px
--ds-radius-xl 16px
--ds-radius-2xl 24px
--ds-radius-pill 9999px
--ds-radius-full 50%
radius.css | css 
.chip   { border-radius: var(--ds-radius-pill); }   /* 9999px */
.button { border-radius: var(--ds-radius-md); }     /* 8px */
.card   { border-radius: var(--ds-radius-lg); }     /* 12px */
.modal  { border-radius: var(--ds-radius-xl); }     /* 16px */
.avatar { border-radius: var(--ds-radius-full); }   /* perfect circle */

Elevation

5 neutral steps. Shadows convey depth, never brand. The focus-ring lives here for accessibility, not as an elevation step.

--ds-shadow-1
Subtle hairline (default card resting)
--ds-shadow-2
Raised card (hover, active toolbar)
--ds-shadow-3
Floating card (dropdown closed)
--ds-shadow-4
Popover, tooltip, dropdown menu
--ds-shadow-5
Modal dialog, command palette
--ds-shadow-focus-ring
Focus ring (accessibility — not elevation)
elevation.css | css 
/* Five steps, neutral colour. Shadows convey depth, never brand. */
.card           { box-shadow: var(--ds-shadow-1); }   /* hairline */
.card:hover     { box-shadow: var(--ds-shadow-2); }   /* lifted */
.dropdown       { box-shadow: var(--ds-shadow-3); }   /* floating */
.popover        { box-shadow: var(--ds-shadow-4); }   /* overlay */
.modal          { box-shadow: var(--ds-shadow-5); }   /* dialog */

button:focus-visible { box-shadow: var(--ds-shadow-focus-ring); } /* a11y */

Z-index

8-layer ladder. Every z-index in source must reference one of these names. Magic integers are bugs.

--ds-z-below -1 Below — beneath the page baseline
--ds-z-base 0 Base — default flow
--ds-z-raised 1 Raised — minor elevation
--ds-z-sticky 100 Sticky — pinned headers, in-flow chrome
--ds-z-overlay 200 Overlay — backdrops, scrims
--ds-z-modal 300 Modal — focus-trapping dialogs
--ds-z-toast 400 Toast — transient notifications
--ds-z-debug 500 Debug — dev-only overlays
z-index.css | css 
/* Every z-index in the codebase must reference one of these. */
.site-header   { z-index: var(--ds-z-sticky);  } /* 100 */
.backdrop      { z-index: var(--ds-z-overlay); } /* 200 */
.modal         { z-index: var(--ds-z-modal);   } /* 300 */
.toast-region  { z-index: var(--ds-z-toast);   } /* 400 */

Color

Semantic color tokens introduced in v0.1.5 (Week 3). The legacy --color-* and --ypai-* layers are still loaded but no longer extended. Every token below is a live var() reference, so the sample row picks up any change to the underlying CSS file immediately.

Surface

--ds-color-bg-void #030308 Deepest layer
--ds-color-bg-base #0a0a0e Page default
--ds-color-bg-raised #0b0d12 Card resting
--ds-color-bg-overlay #11141a Popover/dropdown
--ds-color-bg-modal #14171f Modal dialog
--ds-color-bg-inset rgba(0,0,0,0.4) Inset/well

Text

--ds-color-text-primary rgba(255,255,255,0.95) The quick brown fox jumps over the lazy dog
--ds-color-text-secondary rgba(255,255,255,0.75) The quick brown fox jumps over the lazy dog
--ds-color-text-muted rgba(255,255,255,0.55) The quick brown fox jumps over the lazy dog
--ds-color-text-disabled rgba(255,255,255,0.35) The quick brown fox jumps over the lazy dog
--ds-color-text-inverse rgba(10,10,14,0.95) The quick brown fox jumps over the lazy dog

Border

--ds-color-border-subtle rgba(255,255,255,0.06)
--ds-color-border-default rgba(255,255,255,0.12)
--ds-color-border-strong rgba(255,255,255,0.20)
--ds-color-border-focus rgba(139,92,246,0.55)

Status (text + background pairs)

Info --ds-color-status-info #60A5FA
Success --ds-color-status-success #10B981
Warning --ds-color-status-warn #F59E0B
Danger --ds-color-status-danger #F87171
color.css | css 
/* Surface — pick the matching layer for your context. */
.page  { background: var(--ds-color-bg-base);    }
.card  { background: var(--ds-color-bg-raised);  }
.modal { background: var(--ds-color-bg-modal);   }

/* Text — five tiers of emphasis. */
.title    { color: var(--ds-color-text-primary);   }
.body     { color: var(--ds-color-text-secondary); }
.caption  { color: var(--ds-color-text-muted);     }
.disabled { color: var(--ds-color-text-disabled);  }

/* Status — pair text + background tokens for badges and alerts. */
.alert--error {
  background: var(--ds-color-status-danger-bg);
  color:      var(--ds-color-status-danger);
  border:     1px solid var(--ds-color-status-danger);
}

Accent (passthrough)

--ds-color-accent reads from --hub-accent when a hub is set on a parent element, otherwise falls back to brand violet (#A855F7). This is why a single component can render purple on a marketing page and amber on the LLMOps hub without changing a line of its CSS.

--ds-color-accent Resolves through --hub-accent; brand violet otherwise
--ds-color-accent-soft Soft alpha tint for backgrounds
--ds-color-accent-strong High-emphasis variant (CTA, focus)

OKLCH ramps (raw, 6 hues x 11 steps)

Six hue ramps drive the entire v1.1 palette. Components should not reference these tokens directly — use the semantic aliases below. Values match Tailwind v4 for cross-system parity.

Violet (brand)
50 oklch(0.969 0.016 293.756)
100 oklch(0.943 0.029 294.588)
200 oklch(0.894 0.057 293.283)
300 oklch(0.811 0.111 293.571)
400 oklch(0.702 0.183 293.541)
500 oklch(0.606 0.250 292.717)
600 oklch(0.541 0.281 293.009)
700 oklch(0.491 0.270 292.581)
800 oklch(0.432 0.232 292.759)
900 oklch(0.380 0.189 293.745)
950 oklch(0.283 0.141 291.089)
a10 oklch(0.606 0.250 292.717 / 0.10)
a20 oklch(0.606 0.250 292.717 / 0.20)
a30 oklch(0.606 0.250 292.717 / 0.30)
Slate (neutral)
50 oklch(0.984 0.003 247.858)
100 oklch(0.968 0.007 247.896)
200 oklch(0.929 0.013 255.508)
300 oklch(0.869 0.022 252.894)
400 oklch(0.704 0.040 256.788)
500 oklch(0.554 0.046 257.417)
600 oklch(0.446 0.043 257.281)
700 oklch(0.372 0.044 257.287)
800 oklch(0.279 0.041 260.031)
900 oklch(0.208 0.042 265.755)
950 oklch(0.129 0.042 264.695)
Teal (data accent)
50 oklch(0.984 0.014 180.720)
100 oklch(0.953 0.051 180.801)
200 oklch(0.910 0.096 180.426)
300 oklch(0.855 0.138 181.071)
400 oklch(0.777 0.152 181.912)
500 oklch(0.704 0.140 182.503)
600 oklch(0.600 0.118 184.704)
700 oklch(0.511 0.096 186.391)
800 oklch(0.437 0.078 188.216)
900 oklch(0.386 0.063 188.416)
950 oklch(0.277 0.046 192.524)
a10 oklch(0.704 0.140 182.503 / 0.10)
a20 oklch(0.704 0.140 182.503 / 0.20)
Sky (info)
50 oklch(0.977 0.013 236.824)
100 oklch(0.951 0.026 236.824)
200 oklch(0.901 0.058 230.902)
300 oklch(0.828 0.111 230.318)
400 oklch(0.746 0.160 232.661)
500 oklch(0.685 0.169 237.323)
600 oklch(0.588 0.158 241.966)
700 oklch(0.500 0.134 242.749)
800 oklch(0.443 0.110 240.790)
900 oklch(0.391 0.090 240.876)
950 oklch(0.293 0.066 243.157)
Amber (warning)
50 oklch(0.987 0.022 95.277)
100 oklch(0.962 0.059 95.617)
200 oklch(0.924 0.120 95.746)
300 oklch(0.879 0.169 91.605)
400 oklch(0.828 0.189 84.429)
500 oklch(0.769 0.188 70.080)
600 oklch(0.666 0.179 58.318)
700 oklch(0.555 0.163 48.998)
800 oklch(0.473 0.137 46.201)
900 oklch(0.414 0.112 45.904)
950 oklch(0.279 0.077 45.635)
Red (danger)
50 oklch(0.971 0.013 17.380)
100 oklch(0.936 0.032 17.717)
200 oklch(0.885 0.062 18.334)
300 oklch(0.808 0.114 19.571)
400 oklch(0.704 0.191 22.216)
500 oklch(0.637 0.237 25.331)
600 oklch(0.577 0.245 27.325)
700 oklch(0.505 0.213 27.518)
800 oklch(0.444 0.177 26.899)
900 oklch(0.396 0.141 25.723)
950 oklch(0.258 0.092 26.042)

v1.1 semantic tokens (alias chain)

Each new semantic token resolves through one alias to a raw ramp step. Change a ramp and every downstream token updates. The chip on the left is a live var() reference so any drift between this page and the CSS file is visible immediately.

Token Alias Resolved OKLCH
--ds-color-accent-subtle --ds-color-violet-100 oklch(0.943 0.029 294.588)
--ds-color-accent-muted --ds-color-violet-300 oklch(0.811 0.111 293.571)
--ds-color-accent-default --ds-color-violet-500 oklch(0.606 0.250 292.717)
--ds-color-accent-strong --ds-color-violet-600 oklch(0.541 0.281 293.009)
--ds-color-accent-emphasis --ds-color-violet-700 oklch(0.491 0.270 292.581)
--ds-color-accent-text --ds-color-violet-200 oklch(0.894 0.057 293.283)
--ds-color-info-subtle --ds-color-sky-100 oklch(0.951 0.026 236.824)
--ds-color-info-muted --ds-color-sky-300 oklch(0.828 0.111 230.318)
--ds-color-info-default --ds-color-sky-500 oklch(0.685 0.169 237.323)
--ds-color-info-strong --ds-color-sky-600 oklch(0.588 0.158 241.966)
--ds-color-info-emphasis --ds-color-sky-700 oklch(0.500 0.134 242.749)
--ds-color-info-text --ds-color-sky-200 oklch(0.901 0.058 230.902)
--ds-color-success-subtle --ds-color-teal-100 oklch(0.953 0.051 180.801)
--ds-color-success-muted --ds-color-teal-300 oklch(0.855 0.138 181.071)
--ds-color-success-default --ds-color-teal-500 oklch(0.704 0.140 182.503)
--ds-color-success-strong --ds-color-teal-600 oklch(0.600 0.118 184.704)
--ds-color-success-emphasis --ds-color-teal-700 oklch(0.511 0.096 186.391)
--ds-color-success-text --ds-color-teal-200 oklch(0.910 0.096 180.426)
--ds-color-warn-subtle --ds-color-amber-100 oklch(0.962 0.059 95.617)
--ds-color-warn-muted --ds-color-amber-300 oklch(0.879 0.169 91.605)
--ds-color-warn-default --ds-color-amber-500 oklch(0.769 0.188 70.080)
--ds-color-warn-strong --ds-color-amber-600 oklch(0.666 0.179 58.318)
--ds-color-warn-emphasis --ds-color-amber-700 oklch(0.555 0.163 48.998)
--ds-color-warn-text --ds-color-amber-200 oklch(0.924 0.120 95.746)
--ds-color-danger-subtle --ds-color-red-100 oklch(0.936 0.032 17.717)
--ds-color-danger-muted --ds-color-red-300 oklch(0.808 0.114 19.571)
--ds-color-danger-default --ds-color-red-500 oklch(0.637 0.237 25.331)
--ds-color-danger-strong --ds-color-red-600 oklch(0.577 0.245 27.325)
--ds-color-danger-emphasis --ds-color-red-700 oklch(0.505 0.213 27.518)
--ds-color-danger-text --ds-color-red-200 oklch(0.885 0.062 18.334)
--ds-color-data-positive --ds-color-teal-400 oklch(0.777 0.152 181.912)
--ds-color-data-negative --ds-color-red-400 oklch(0.704 0.191 22.216)
--ds-color-data-neutral --ds-color-slate-400 oklch(0.704 0.040 256.788)
--ds-color-data-primary --ds-color-violet-400 oklch(0.702 0.183 293.541)
--ds-color-data-secondary --ds-color-teal-400 oklch(0.777 0.152 181.912)
--ds-color-data-tertiary --ds-color-sky-400 oklch(0.746 0.160 232.661)
--ds-color-data-quaternary --ds-color-amber-400 oklch(0.828 0.189 84.429)
--ds-color-link-default --ds-color-violet-300 oklch(0.811 0.111 293.571)
--ds-color-link-hover --ds-color-violet-200 oklch(0.894 0.057 293.283)
--ds-color-link-visited --ds-color-violet-400 oklch(0.702 0.183 293.541)
--ds-color-link-active --ds-color-violet-100 oklch(0.943 0.029 294.588)
--ds-color-surface-sunken --ds-color-slate-950 oklch(0.129 0.042 264.695)
--ds-color-surface-overlay slate-800 @ 85% oklch(0.279 0.041 260.031 / 0.85)
--ds-color-surface-scrim slate-950 @ 65% oklch(0.129 0.042 264.695 / 0.65)

Density

The data-density attribute (set on :root) switches every density-aware control between comfortable (default, 40px control height) and compact (75% padding, 34px control height). The toggle in the top-right of every /design page persists your choice in localStorage. Below: the same three controls in both modes, side by side.

comfortable
compact

The two columns above force their density locally. Use the toolbar toggle (top-right) to switch the whole document.

density.html | html 
<!-- Set on <html> to switch the whole document. -->
<html data-density="compact">…</html>

<!-- Or scope to a single surface (e.g. a sidebar). -->
<aside data-density="compact">
  <Button size="sm">Filter</Button>
</aside>
density.css | css 
/* Density-aware controls read these tokens. */
.button {
  height:  var(--ds-density-control-h-md);
  padding: 0 calc(var(--ds-space-4) * var(--ds-density-pad-multiplier, 1));
}

Motion

Duration and easing tokens live in /design/motion. They pair with the data-motion contract so reduced-motion is honored globally.