Design Tokens
Foundation
Primitive design tokens forming the foundation of the design system. Includes mathematical ratios, modular scales, spacing system, layout widths, z-index hierarchy, animation curves, and seed colors.
Color Seeds & Tooltips
Primary background and foreground seeds from which the OKLCH relative color engine derives full palettes, plus tooltip defaults.
| Name | Description | Value |
|---|---|---|
--color-light-background |
Light mode root page background seed (#faf8f2). Warm archival stock — felt rather than perceived, never clinical pure white. |
#faf8f2 |
--color-light-foreground |
Light mode root text foreground seed (#221f1c). Warm carbon printer’s ink — never pure black. Derives dark mode seeds and the full 10-hue chromatic wheel. |
#221f1c |
Base Measurements & Vertical Rhythm
Core measurements governing typography and vertical cadence. Includes fluid viewport scaling and baseline rhythm anchoring.
| Name | Description | Value |
|---|---|---|
--optical-ratio |
Modular scale ratio. Resolves theme hook --ratio with fallback to --ratio-silver. |
var(--ratio, var(--ratio-silver)) |
--ratio-mobile |
Theme-authoring hook to override the optical modular scale factor on mobile viewports (var(--ratio-halfstep)). |
var(--ratio-halfstep) |
--physics-slope |
Ratio growth physics slope derived from optical ratio (max(calc(var(--optical-ratio) - 1), 0.15)). |
max(calc(var(--optical-ratio) - 1), 0.15) |
--fluid-growth |
Viewport-responsive growth increment beyond wide screens (0px). |
0px |
--base-size |
Root font size base (defaults to --font-text-size or 1rem) (var(--font-text-size, 1rem)). |
var(--font-text-size, 1rem) |
Aa--font-size |
Base font size, scaling fluidly on displays wider than wide breakpoint (var(--base-size)). |
var(--base-size) |
--density-base |
Reading density base resolving from --density or --optical-ratio. |
var(--density, var(--optical-ratio)) |
--line-height |
Clamped fluid unitless line height (1.35 to 1.75). | clamp(1.35, var(--density-base), 1.75) |
--baseline |
Official rhythm unit (1rlh). Drives vertical spacing across all components. |
1rlh |
--trim |
Half-leading trim applied to typography box edges (calc(var(--leading) / 2)). |
calc(var(--leading) / 2) |
--leading |
Space between font cap-height and the next baseline (calc((var(--line-height) - 1) * var(--font-size))). |
calc((var(--line-height) - 1) * var(--font-size)) |
--nl |
Newline unit representing a full vertical rhythm step (calc(var(--leading) * var(--line-height))). |
calc(var(--leading) * var(--line-height)) |
Rhythm & Page Padding
Spacing intervals between major layout blocks, page sections, and screen edges.
| Name | Description | Value |
|---|---|---|
--gap |
Dynamic gap between rhythm blocks (calc(var(--space))). |
calc(var(--space)) |
--gap-compact |
Compact micro-gap for inline groups, metadata, breadcrumbs (var(--trim)). |
var(--trim) |
--page-padding |
Fluid outer margin/padding preventing content from touching device bezels. | clamp(var(--space-6), 15vw, var(--space-10)) |
--page-padding-small |
Compact page margin for small viewports (var(--space-d2)). |
var(--space-d2) |
--rhythm-block-scale |
Ratio multiplier factor for non-text blocks (2). |
2 |
Breakpoints
Viewport boundaries for responsive layout adaptations across mobile, tablet, and desktop displays.
| Name | Description | Value |
|---|---|---|
--breakpoint-mobile |
Mobile viewport breakpoint boundary (#{$mobile}). |
#{$mobile |
--breakpoint-sm |
Small tablet and compact screen breakpoint boundary (#{$small}). |
#{$small |
--breakpoint-lg |
Large desktop screen breakpoint boundary (#{$large}). |
#{$large |
--breakpoint-wide |
Ultra-wide display breakpoint boundary (#{$wide}). |
#{$wide |
Prose Breakout Tracks & Insets
Grid breakout track sizes allowing wide content and full-width elements to extend past the reading measure, plus narrow element insets.
| Name | Description | Value |
|---|---|---|
--prose-inset |
Narrow layout inset margin (max(calc(var(--space-2) - var(--space)), var(--space))). |
max(calc(var(--space-2) - var(--space)), var(--space)) |
--prose-wide |
Wide column breakout track width (minmax(0, var(--space-2))). |
minmax(0, var(--space-2)) |
--prose-full |
Full-width page breakout track (minmax(0, 1fr)). |
minmax(0, 1fr) |
Stroke, Radius & Filters
Hairline strokes, corner curvature, and glassmorphic backdrop filters.
| Name | Description | Value |
|---|---|---|
--stroke-width |
Hairline border stroke width (max(1px, 0.06rem)). |
max(1px, 0.06rem) |
--stroke-width-lg |
Heavy border stroke width (calc(var(--stroke-width) * 2)). |
calc(var(--stroke-width) * 2) |
--opacity-disabled |
How much of a control is left when it cannot act (0.4). Every disabled control, fieldset:disabled zone and [inert] zone reads it, so they all dim alike. |
0.4 |
--opacity-subdued |
A little less than full: secondary content, an inactive neighbour. | 0.85 |
--opacity-faint |
Half: placeholders, decoration and quiet states (a control that cannot act is --opacity-disabled). |
0.5 |
--radius |
Macro border radius for cards, dialogs, and large containers. | var(--trim) |
--radius-sm |
Micro border radius for tags, badges, buttons, and inputs. | max(calc(var(--radius) / 2), 4px) |
--radius-lg |
Large border radius, for modals and hero panels. | min(calc(var(--radius) * 2), var(--space)) |
--radius-full |
Fully rounded corners: pills, badges, avatars and progress tracks. | 9999px |
--filter-blur |
Standard blur filter (blur(8px)). |
blur(8px) |
--filter-glass |
Deep glassmorphic blur filter for overlays and floating panels (blur(20px)). |
blur(20px) |
--filter-blur-sm |
A light blur, for a hint of depth behind a small floating element. | blur(4px) |
Shadows & Elevation
Multi-layered elevation scale and presets driven by semantic color seeds. Composable shadow primitives: combine them freely with comma-separated values, for example box-shadow: var(--shadow-ring), var(--shadow-lift).
| Name | Description | Value |
|---|---|---|
--shadow-ambient |
Subtle ambient contact shadow. | 0 1px 1px var(--color-shadow) |
--shadow-lift |
Medium elevation shadow with directional lift. | 0 4px 6px -1px var(--color-shadow), 0 2px 4px -2px var(--color-shadow) |
--shadow-glow |
Atmospheric ambient glow shadow. | 0 4px var(--space) rgb(from var(--color-shadow) r g b / 0.15) |
--shadow-inset |
Inset bevel shadow. | inset 0 1px 3px var(--color-shadow), inset 0 -1px 0 0 var(--color-highlight) |
--shadow-ring |
Fine border ring inset shadow. | inset 0px 1px 1px var(--color-border), inset 1px 0px 1px var(--color-border), in… |
--shadow-focus |
The keyboard focus ring as a shadow: --color-ring around the element, two strokes wide. For a control that cannot take an outline. |
0 0 0 var(--stroke-width-lg) var(--color-ring) |
--shadow-border |
A one-stroke border drawn as an inset shadow: it looks like border: var(--border) but takes no layout space, so nothing shifts when it appears, disappears or changes colour. Paints under the element’s content (use ::after over a canvas or image). |
inset 0 0 0 var(--stroke-width) var(--color-border) |
--shadow-border-top |
Same, one side only (a divider): -top, -bottom, -left, -right. |
inset 0 var(--stroke-width) 0 0 var(--color-border) |
--shadow-border-bottom |
Same as --shadow-border, bottom side only. |
inset 0 calc(var(--stroke-width) * -1) 0 0 var(--color-border) |
--shadow-border-left |
Same as --shadow-border, left side only. |
inset var(--stroke-width) 0 0 0 var(--color-border) |
--shadow-border-right |
Same as --shadow-border, right side only. |
inset calc(var(--stroke-width) * -1) 0 0 0 var(--color-border) |
--shadow-raised |
Layered raised preset with top highlight, hairline border, and ambient shadow. | inset 0 1px 0 0 var(--color-highlight), var(--shadow-ambient) |
--shadow |
Default elevation shadow. | var(--shadow-raised) |
--shadow-hover |
Raised shadow plus a large lift, for an element under the pointer. | var(--shadow-raised), var(--shadow-lg) |
--shadow-xl-tone |
Colour of the --shadow-xl layers: the shadow colour in a light scheme, transparent in a dark one, where the surface steps carry the elevation. |
light-dark(var(--color-shadow), transparent) |
--shadow-xs |
Extra-small subtle contact shadow. | var(--shadow-ambient) |
--shadow-sm |
Small card/well shadow. | 0 1px 2px 0 var(--color-shadow), 0 1px 1px -1px var(--color-shadow) |
--shadow-md |
Medium elevation shadow. | var(--shadow-lift) |
--shadow-lg |
Large floating dialog/card shadow. | var(--shadow-ambient), var(--shadow-lift) |
--shadow-overlay |
The shadow that pairs with --color-surface-overlay (alias of --shadow-lg). --shadow-raised pairs with --color-surface-raised, --shadow-inset with --color-surface-sunken. |
var(--shadow-lg) |
--shadow-xl |
Maximum elevation hero shadow. | 0 1px 1px var(--shadow-xl-tone), 0 4px 6px -1px var(--shadow-xl-tone), 0 2px 4px… |
Mathematical Ratios
Proportional ratios driving modular scales, typographic scaling, and harmonic layout proportions.
| Name | Description | Value |
|---|---|---|
--ratio-golden |
Golden ratio (φ ≈ 1.618). Used for golden spiral proportions and dramatic growth slopes. | 1.618 |
--ratio-silver |
Silver ratio (√2 ≈ 1.414). Default modular scale factor for typography and optical steps. | 1.414 |
--ratio-halfstep |
Half-step ratio (1.272). Moderate progression for subtle hierarchy. | 1.272 |
--ratio-quarterstep |
Quarter-step ratio (1.128). Tighter step progression for compact interfaces. | 1.128 |
--ratio-eighthstep |
Eighth-step ratio (1.062). Minimal step increment for dense data displays. | 1.062 |
Layout & Reading Widths
Column constraints for prose reading measure and outer page boundaries. A two-tier containment model: --page-max-width is the outer boundary of the page shell, header and footer, while --prose-width is the optimal reading measure (60 to 75 characters). Breakout tracks extend outwards from --prose-width in rhythm steps towards --page-max-width.
| Name | Description | Value |
|---|---|---|
--page-max-width |
Maximum width of the entire page shell (1400px). |
1400px |
--prose-width |
Optimal reading line length (approx. 65 characters / 42rem). |
var(--reading-width, 42rem) |
Control Sizes & Containers
How big a control is, and how wide a container may be. Control heights are the Primer scale (28, 32, 40) plus the minimum touch target (44, the size Apple asks for). Container widths are Tailwind’s named scale, in rem: a popover, a drawer, a dialog or a form column takes one instead of a number.
| Name | Description | Value |
|---|---|---|
--control-height-sm |
A small control: 28px. | 28px |
--control-height-md |
The standard control: 32px. | 32px |
--control-height-lg |
A large control: 40px. | 40px |
--hit-target |
The smallest touch target: 44px. An icon button that is drawn smaller is still this big to a finger. | 44px |
--container-xs |
Extra-small container: 20rem. | 20rem |
--container-sm |
Small container: 24rem. | 24rem |
--container-md |
Medium container: 28rem. | 28rem |
--container-lg |
Large container: 32rem. | 32rem |
--container-xl |
Extra-large container: 36rem. | 36rem |
--container-2xl |
42rem, the reading measure. | 42rem |
--container-3xl |
48rem. | 48rem |
--container-4xl |
56rem. | 56rem |
--container-5xl |
64rem. | 64rem |
Line Heights & Letter Spacing
Tracking adjustments and proportional line height variants.
| Name | Description | Value |
|---|---|---|
--line-height-none |
A line height of 1, for numerals, icons and labels set on one line (Tailwind’s leading-none). |
1 |
--line-height-compact |
Compact line height (calc(1 + (var(--line-height) - 1) / 2)). Used for titles and tight headings. |
calc(1 + (var(--line-height) - 1) / 2) |
--line-height-relaxed |
Relaxed line height (calc(1 + (var(--line-height) - 1) * 1.5)). Used for loose longform prose. |
calc(1 + (var(--line-height) - 1) * 1.5) |
Abc--tracking-tight |
Tight letter-spacing (-0.01em). Applied to large display headings. |
-0.01em |
Abc--tracking-neutral |
Normal letter-spacing (0em). Default for body text. |
0em |
Abc--tracking-open |
Open letter-spacing (0.01em). Applied to uppercase labels and small caps. |
0.01em |
Abc--tracking-wide |
Wide letter-spacing, for small uppercase labels and captions (Tailwind’s tracking-wide). |
0.05em |
Abc--tracking-wider |
Wider letter-spacing, for the smallest uppercase labels (Tailwind’s tracking-wider). |
0.1em |
Spacing Scale
Complete vertical rhythm scale derived from --baseline (1rlh). Division steps (--space-d*) subdivide the baseline; multiplication steps (--space-*) expand it.
| Name | Description | Value |
|---|---|---|
--space |
Base rhythm spacing unit (var(--baseline), 1rlh). |
var(--baseline) |
--space-half |
Half-space rhythm unit (calc(var(--baseline) / 2)). |
calc(var(--baseline)/2) |
--space-d1 |
Division step 1 (calc(var(--space) / 1)). |
|
--space-d2 |
Division step 2 (calc(var(--space) / 2)). Half-step spacing for compact padding and gaps. |
|
--space-d3 |
Division step 3 (calc(var(--space) / 3)). One-third baseline spacing. |
|
--space-d4 |
Division step 4 (calc(var(--space) / 4)). Quarter baseline spacing for micro-gaps and badge padding. |
|
--space-d5 |
Division step 5 (calc(var(--space) / 5)). |
|
--space-d6 |
Division step 6 (calc(var(--space) / 6)). |
|
--space-d7 |
Division step 7 (calc(var(--space) / 7)). |
|
--space-d8 |
Division step 8 (calc(var(--space) / 8)). Micro-hairline spacing for dense lists and borders. |
|
--space-d9 |
Division step 9 (calc(var(--space) / 9)). |
|
--space-d10 |
Division step 10 (calc(var(--space) / 10)). |
|
--space-d11 |
Division step 11 (calc(var(--space) / 11)). |
|
--space-d12 |
Division step 12 (calc(var(--space) / 12)). Smallest fractional spacing step. |
|
--space-1 |
Multiplication step 1 (calc(var(--space) * 1)). Equals base --space. |
|
--space-2 |
Multiplication step 2 (calc(var(--space) * 2)). Standard body gutter and section spacing. |
|
--space-3 |
Multiplication step 3 (calc(var(--space) * 3)). Intermediate container margin. |
|
--space-4 |
Multiplication step 4 (calc(var(--space) * 4)). Feature breakout margin and block rhythm. |
|
--space-5 |
Multiplication step 5 (calc(var(--space) * 5)). |
|
--space-6 |
Multiplication step 6 (calc(var(--space) * 6)). Large section gap. |
|
--space-7 |
Multiplication step 7 (calc(var(--space) * 7)). |
|
--space-8 |
Multiplication step 8 (calc(var(--space) * 8)). Page header gap and macro layout spacing. |
|
--space-9 |
Multiplication step 9 (calc(var(--space) * 9)). |
|
--space-10 |
Multiplication step 10 (calc(var(--space) * 10)). |
|
--space-11 |
Multiplication step 11 (calc(var(--space) * 11)). |
|
--space-12 |
Multiplication step 12 (calc(var(--space) * 12)). Maximum rhythm spacing step. |
Optical Harmony Scale & Sizes
Modular geometric scale driven by --optical-ratio for typography and sizing. Sub-base steps (d5..d2) use a flattened divisor and floor at 11px to protect legibility.
| Name | Description | Value |
|---|---|---|
Aa--scale-d5 |
Sub-base optical step -5. | max(calc(var(--font-size) * pow(var(--optical-ratio), -4)), 9px) |
Aa--scale-d4 |
Sub-base optical step -4. | max(calc(var(--font-size) * pow(var(--optical-ratio), -3)), 9px) |
Aa--scale-d3 |
Sub-base optical step -3. | max(calc(var(--font-size) * pow(var(--optical-ratio), -2)), 9px) |
Aa--scale-d2 |
Sub-base optical step -2. | max(calc(var(--font-size) * pow(var(--optical-ratio), -1)), 9px) |
Aa--scale |
Base optical scale step (var(--font-size)). |
var(--font-size) |
Aa--scale-2 |
Super-base optical step 2. | min(calc(var(--font-size) * pow(var(--optical-ratio), 1)), 96px) |
Aa--scale-3 |
Super-base optical step 3. | min(calc(var(--font-size) * pow(var(--optical-ratio), 2)), 96px) |
Aa--scale-4 |
Super-base optical step 4. | min(calc(var(--font-size) * pow(var(--optical-ratio), 3)), 96px) |
Aa--scale-5 |
Super-base optical step 5. | min(calc(var(--font-size) * pow(var(--optical-ratio), 4)), 96px) |
Aa--scale-6 |
Super-base optical step 6. | min(calc(var(--font-size) * pow(var(--optical-ratio), 5)), 96px) |
Aa--scale-7 |
Super-base optical step 7. | min(calc(var(--font-size) * pow(var(--optical-ratio), 6)), 96px) |
Aa--scale-8 |
Super-base optical step 8. | min(calc(var(--font-size) * pow(var(--optical-ratio), 7)), 96px) |
Mobile Settings
Responsive overrides applied on mobile screen sizes.
| Name | Description | Value |
|---|---|---|
Aa--font-size-mobile |
Base font size override on mobile viewports (1.125rem). |
1.125rem |
Z-Index Scale
Consistent stacking order hierarchy preventing z-index collisions.
| Name | Description | Value |
|---|---|---|
--z-base |
Base stacking layer above standard document flow (1). |
1 |
--z-header |
Sticky page header layer (900). |
900 |
--z-palette |
Command palette and quick-search overlay (1000). |
1000 |
--z-dropdown |
Dropdowns, popovers, and context menus (1100). |
1100 |
--z-modal |
Modal dialogs and backdrop scrims (1200). |
1200 |
--z-toast |
Toast notifications and system alerts (2000). |
2000 |
--z-image-zoom |
Fullscreen lightbox image zoom overlay (9999). |
9999 |
Animation, Timing & Curves
Cubic bezier easing curves, transition durations, and physics-driven motion presets.
| Name | Description | Value |
|---|---|---|
--ease-snappy |
Fast response curve for small icons and toggles (cubic-bezier(0.2, 0, 0, 1)). |
cubic-bezier(0.2, 0, 0, 1) |
--ease-standard |
Standard curve for general UI transitions (cubic-bezier(0.4, 0, 0.2, 1)). |
cubic-bezier(0.4, 0, 0.2, 1) |
--ease-soft |
Gentle curve for large modals, overlays, and drawer panels (cubic-bezier(0.16, 1, 0.3, 1)). |
cubic-bezier(0.16, 1, 0.3, 1) |
--ease-emphasis |
Weighted curve with anticipation and subtle overshoot (cubic-bezier(0.34, 1.56, 0.64, 1)). |
cubic-bezier(0.34, 1.56, 0.64, 1) |
--ease-aggressive |
Rapid acceleration curve for urgent transitions (cubic-bezier(0.7, 0, 0.3, 1)). |
cubic-bezier(0.7, 0, 0.3, 1) |
--ease-stnd |
Standard signature ease curve (cubic-bezier(0, 0.3, 0, 1)). |
cubic-bezier(0, 0.3, 0, 1) |
--ease-stnd-heavy |
Heavy standard signature ease curve (cubic-bezier(0.5, 0, 0, 1)). |
cubic-bezier(0.5, 0, 0, 1) |
--ease-invisibolt |
Sudden bolt curve (cubic-bezier(1, 0, 0, 1)). |
cubic-bezier(1, 0, 0, 1) |
--ease-friction |
Analog physical friction curve with swift attack and long taper (cubic-bezier(0.22, 1, 0.36, 1)). |
cubic-bezier(0.22, 1, 0.36, 1) |
--duration-instant |
Instant duration for micro-interactions (100ms). |
100ms |
--duration-fast |
Fast duration for button hover, active states, and menus (350ms). |
350ms |
--duration-standard |
Standard duration for UI component state transitions (500ms). |
500ms |
--duration-slow |
Slow duration for large panels, dialogs, and navigation sheets (1000ms). |
1000ms |
--transition-fast |
Fast transition shorthand (0.5s var(--ease-friction)). |
0.5s var(--ease-friction) |
--transition |
Standard transition shorthand (1s var(--ease-friction)). |
1s var(--ease-friction) |
--transition-slow |
Slow transition shorthand (2s var(--ease-friction)). |
2s var(--ease-friction) |
--ease-shape-snappy |
Snappy shape alias curve (cubic-bezier(0.2, 0, 0, 1)). |
cubic-bezier(0.2, 0, 0, 1) |
--ease-shape-bounce |
Bouncy shape alias curve with overshoot (cubic-bezier(0.34, 1.56, 0.64, 1)). |
cubic-bezier(0.34, 1.56, 0.64, 1) |
--ease-shape-soft |
Soft shape alias curve (cubic-bezier(0.16, 1, 0.3, 1)). |
cubic-bezier(0.16, 1, 0.3, 1) |
--ease-interaction |
Preset transition for interactive controls (var(--duration-fast) var(--ease-shape-snappy)). |
var(--duration-fast) var(--ease-shape-snappy) |
--ease-feedback |
Preset transition for validation and feedback states (var(--duration-standard) var(--ease-shape-bounce)). |
var(--duration-standard) var(--ease-shape-bounce) |
--ease-surface |
Preset transition for large panels and sidebars (var(--duration-slow) var(--ease-shape-soft)). |
var(--duration-slow) var(--ease-shape-soft) |
--ease-enter |
Preset transition for entering elements (var(--duration-fast) ease-out). |
var(--duration-fast) ease-out |
--ease-exit |
Preset transition for exiting elements (var(--duration-standard) ease-in). |
var(--duration-standard) ease-in |
Theme Authoring Hooks
Documented custom property hooks intended for themes (packages/themes/*) and document frontmatter overrides.
| Name | Description | Value |
|---|---|---|
--ratio |
Theme-authoring hook to override the optical modular scale factor (e.g. 1.414). |
|
--ratio-mobile |
Theme-authoring hook to override the optical modular scale factor on mobile viewports (var(--ratio-halfstep)). |
var(--ratio-halfstep) |
--density |
Theme-authoring hook to override base line height density. | |
--font-text-size |
Theme-authoring hook to override base text size (drives --base-size). |
|
--reading-width |
Theme-authoring hook to override the default reading column measure: --prose-width reads it. |
|
--font-header-weight |
Theme-authoring hook to override the heading weight anchor: --font-weight-header reads it. |
|
--radius |
Theme-authoring hook to override base border radius. | var(--trim) |