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 |
|---|---|
--color-light-background |
Light mode root page background seed (white). |
--color-light-foreground |
Light mode root text foreground seed (#262626). Derives dark mode seeds and the full 10-hue chromatic wheel. |
--tooltip-background |
Default tooltip container background (var(--color-dark, #1a1a1a)). |
--tooltip-text |
Default tooltip text color (var(--color-light, #ffffff)). |
Base Measurements & Vertical Rhythm
Core measurements governing typography and vertical cadence. Includes fluid viewport scaling and baseline rhythm anchoring.
| Name | Description |
|---|---|
--optical-ratio |
Modular scale ratio. Resolves theme hook --font-ratio with fallback to --ratio-silver. |
--physics-slope |
Ratio growth physics slope derived from optical ratio (max(calc(var(--optical-ratio) - 1), 0.15)). |
--fluid-growth |
Viewport-responsive growth increment (calc(var(--physics-slope) * 1.2vw)). |
--base-size |
Root font size base (defaults to --font-text-size or 1.0625rem). |
--font-size |
Clamped fluid font size that scales smoothly between mobile and wide displays. |
--density-base |
Reading density base resolving from --font-density or --optical-ratio. |
--line-height |
Clamped fluid unitless line height (1.35 to 1.75). |
--baseline |
Official rhythm unit (1rlh). Drives vertical spacing across all components. |
--trim |
Half-leading trim applied to typography box edges (calc(var(--leading) / 2)). |
--leading |
Space between font cap-height and the next baseline (calc((var(--line-height) - 1) * var(--font-size))). |
--nl |
Newline unit representing a full vertical rhythm step (calc(var(--leading) * var(--line-height))). |
Rhythm & Gaps
Spacing intervals between major layout blocks, page sections, headers, and footers.
| Name | Description |
|---|---|
--gap |
Dynamic gap between rhythm blocks (calc(var(--space) * var(--optical-ratio))). |
--gap-body |
Standard gutter for body content containers (var(--space-2)). |
--gap-header |
Top margin gutter above page headers (var(--space-8)). |
--gap-footer |
Bottom margin gutter above page footers (calc(var(--gap-body) * 1.5)). |
--gap-grid-img |
Micro-gap separating adjacent images in rhythm grids (var(--space-d4)). |
--gap-multiplicator |
Gutter multiplier factor (2). |
Breakpoints
Viewport boundaries for responsive layout adaptations across mobile, tablet, and desktop displays.
| Name | Description |
|---|---|
--breakpoint-mobile |
Mobile viewport breakpoint boundary (#{$mobile}). |
--breakpoint-sm |
Small tablet and compact screen breakpoint boundary (#{$small}). |
--breakpoint-lg |
Large desktop screen breakpoint boundary (#{$large}). |
--breakpoint-wide |
Ultra-wide display breakpoint boundary (#{$wide}). |
Content Breakout Widths
Grid breakout track sizes allowing editorial content, features, and media to extend past the reading measure.
| Name | Description |
|---|---|
--content-width-sm |
Small layout breakout track width (max(calc(var(--space-2) - var(--space)), var(--space))). |
--content-width-editorial |
Editorial column breakout track width (minmax(0, var(--space-2))). |
--content-width-feature |
Feature callout breakout track width (minmax(0, var(--space-4))). |
--content-width-hero |
Full-bleed hero breakout track width (minmax(0, 1fr)). |
Stroke, Radius & Filters
Hairline strokes, corner curvature, and glassmorphic backdrop filters.
| Name | Description |
|---|---|
--stroke-width |
Hairline border stroke width (max(1px, 0.06rem)). |
--stroke-width-lg |
Heavy border stroke width (calc(var(--stroke-width) * 2)). |
--radius |
Border radius proportional to leading. Resolves theme hook --corner or derives proportionally from --leading. |
--radius-sm |
Small border radius for badges, inputs, and buttons (min(8px, var(--radius))). |
--filter-blur |
Standard blur filter (blur(8px)). |
--filter-glass |
Deep glassmorphic blur filter for overlays and floating panels (blur(20px)). |
Shadows & Elevation
Multi-layered elevation scale and presets driven by semantic color seeds.
| Name | Description |
|---|---|
--shadow-ambient |
Subtle ambient contact shadow. |
--shadow-lift |
Medium elevation shadow with directional lift. |
--shadow-glow |
Atmospheric ambient glow shadow. |
--shadow-inset |
Inset bevel shadow. |
--shadow-ring |
Fine border ring inset shadow. |
--shadow-raised |
Layered raised preset with top highlight, hairline border, and ambient shadow. |
--shadow |
Default elevation shadow. |
--shadow-lg |
Large floating dialog/card shadow. |
--shadow-xl |
Maximum elevation hero shadow. |
Mathematical Ratios
Proportional ratios driving modular scales, typographic scaling, and harmonic layout proportions.
| Name | Description |
|---|---|
--ratio-golden |
Golden ratio (φ ≈ 1.618). Used for golden spiral proportions and dramatic growth slopes. |
--ratio-silver |
Silver ratio (√2 ≈ 1.414). Default modular scale factor for typography and optical steps. |
--ratio-halfstep |
Half-step ratio (1.272). Moderate progression for subtle hierarchy. |
--ratio-quarterstep |
Quarter-step ratio (1.128). Tighter step progression for compact interfaces. |
--ratio-eighthstep |
Eighth-step ratio (1.062). Minimal step increment for dense data displays. |
Layout & Reading Widths
Column constraints for prose reading measure and outer page boundaries.
| Name | Description |
|---|---|
--body-max-width |
Maximum width of the entire page shell (900px). Constrains headers, prose, and footers. |
--line-width-xs |
Extra-small reading width (24rem). Ideal for cards, sidebars, and captions. |
--line-width-sm |
Small reading width (32rem). |
--line-width-md |
Medium reading width (42rem). Optimal reading line length (approx. 65-75 characters). |
--line-width-lg |
Large reading width (50rem). |
--line-width-xl |
Extra-large reading width (60rem). |
--line-width-full |
Full viewport width minus gutters (calc(100vw - (var(--space) * 2))). |
--line-width |
Active reading column measure. Resolves --font-line-width, --measure, or --line-width-md. |
--content-width |
Effective content width constrained to container (min(var(--line-width), 100%)). |
Line Heights & Letter Spacing
Tracking adjustments and proportional line height variants.
| Name | Description |
|---|---|
--line-height-compact |
Compact line height (calc(1 + (var(--line-height) - 1) / 2)). Used for titles and tight headings. |
--line-height-relaxed |
Relaxed line height (calc(1 + (var(--line-height) - 1) * 1.5)). Used for loose longform prose. |
--tracking-tight |
Tight letter-spacing (-0.01em). Applied to large display headings. |
--tracking-neutral |
Normal letter-spacing (0em). Default for body text. |
--tracking-open |
Open letter-spacing (0.01em). Applied to uppercase labels and small caps. |
Spacing Scale
Complete vertical rhythm scale derived from --baseline (1rlh). Division steps (--space-d*) subdivide the baseline; multiplication steps (--space-*) expand it.
| Name | Description |
|---|---|
--space |
Base rhythm spacing unit (var(--baseline), 1rlh). |
--space-half |
Half-space rhythm unit (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 |
|---|---|
--scale-d5 |
Sub-base optical step -5 (max(calc(var(--font-size) / (var(--optical-ratio) * var(--optical-ratio))), 11px)). |
--scale-d4 |
Sub-base optical step -4 (max(calc(var(--font-size) / (var(--optical-ratio) * 1.25)), 11px)). |
--scale-d3 |
Sub-base optical step -3 (max(calc(var(--font-size) / var(--optical-ratio)), 11px)). |
--scale-d2 |
Sub-base optical step -2 (max(calc(var(--font-size) / (1 + (var(--optical-ratio) - 1) * 0.5)), 11px)). |
--scale |
Base optical scale step (var(--font-size)). |
--scale-2 |
Super-base optical step 2 (calc(var(--font-size) * var(--optical-ratio))). |
--scale-3 |
Super-base optical step 3 (calc(var(--scale-2) * var(--optical-ratio))). |
--scale-4 |
Super-base optical step 4 (calc(var(--scale-3) * var(--optical-ratio))). |
--scale-5 |
Super-base optical step 5 (calc(var(--scale-4) * var(--optical-ratio))). |
--scale-6 |
Super-base optical step 6 (calc(var(--scale-5) * var(--optical-ratio))). |
--scale-7 |
Super-base optical step 7 (calc(var(--scale-6) * var(--optical-ratio))). |
--scale-8 |
Super-base optical step 8 (calc(var(--scale-7) * var(--optical-ratio))). |
--size-3xs |
T-shirt size alias for --scale-d5. Used for micro-badges and metadata captions. |
--size-2xs |
T-shirt size alias for --scale-d4. Used for tooltips, footnotes, and tags. |
--size-xs |
T-shirt size alias for --scale-d3. Used for secondary labels and table metadata. |
--size-sm |
T-shirt size alias for --scale-d2. Used for UI controls, inputs, and captions. |
--size-base |
T-shirt size alias for --scale. Base body text size (1rem). |
--size-lg |
T-shirt size alias for --scale-2. Subheadings and lead paragraphs. |
--size-xl |
T-shirt size alias for --scale-3. Section headers (h3). |
--size-2xl |
T-shirt size alias for --scale-4. Major headings (h2). |
--size-3xl |
T-shirt size alias for --scale-5. Page titles (h1). |
--size-4xl |
T-shirt size alias for --scale-6. Hero display headings. |
--size-5xl |
T-shirt size alias for --scale-7. Large hero numbers and display text. |
--size-6xl |
T-shirt size alias for --scale-8. Maximum display typography scale. |
Mobile Settings
Responsive overrides applied on mobile screen sizes.
| Name | Description |
|---|---|
--font-size-mobile |
Base font size override on mobile viewports (1.125rem). |
--gap-body-mobile |
Body gutter override on mobile viewports (var(--space)). |
--gap-mobile |
General layout gap override on mobile viewports (var(--space)). |
--gap-header-mobile |
Header gutter override on mobile viewports (var(--space-4)). |
Z-Index Scale
Consistent stacking order hierarchy preventing z-index collisions.
| Name | Description |
|---|---|
--z-base |
Base stacking layer above standard document flow (1). |
--z-header |
Sticky page header layer (900). |
--z-launcher |
Command launcher and quick-search palette (1000). |
--z-dropdown |
Dropdowns, popovers, and context menus (1100). |
--z-modal |
Modal dialogs and backdrop scrims (1200). |
--z-toast |
Toast notifications and system alerts (2000). |
--z-image-zoom |
Fullscreen lightbox image zoom overlay (9999). |
Animation, Timing & Curves
Cubic bezier easing curves, transition durations, and physics-driven motion presets.
| Name | Description |
|---|---|
--ease-snappy |
Fast response curve for small icons and toggles (cubic-bezier(0.2, 0, 0, 1)). |
--ease-standard |
Standard curve for general UI transitions (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)). |
--ease-emphasis |
Weighted curve with anticipation and subtle overshoot (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)). |
--ease-stnd |
Standard signature ease curve (cubic-bezier(0, 0.3, 0, 1)). |
--ease-stnd-heavy |
Heavy standard signature ease curve (cubic-bezier(0.5, 0, 0, 1)). |
--ease-invisibolt |
Sudden bolt curve (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)). |
--duration-instant |
Instant duration for micro-interactions (100ms). |
--duration-fast |
Fast duration for button hover, active states, and menus (350ms). |
--duration-standard |
Standard duration for UI component state transitions (500ms). |
--duration-slow |
Slow duration for large panels, dialogs, and navigation sheets (1000ms). |
--transition-fast |
Fast transition shorthand (0.5s var(--ease-friction)). |
--transition |
Standard transition shorthand (1s var(--ease-friction)). |
--transition-slow |
Slow transition shorthand (2s var(--ease-friction)). |
--ease-shape-snappy |
Snappy shape alias curve (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)). |
--ease-shape-soft |
Soft shape alias curve (cubic-bezier(0.16, 1, 0.3, 1)). |
--ease-interaction |
Preset transition for interactive controls (var(--duration-fast) var(--ease-shape-snappy)). |
--ease-feedback |
Preset transition for validation and feedback states (var(--duration-standard) var(--ease-shape-bounce)). |
--ease-surface |
Preset transition for large panels and sidebars (var(--duration-slow) var(--ease-shape-soft)). |
--ease-enter |
Preset transition for entering elements (var(--duration-fast) ease-out). |
--ease-exit |
Preset transition for exiting elements (var(--duration-standard) ease-in). |
Theme Authoring Hooks
Documented custom property hooks intended for themes (packages/themes/*) and document frontmatter overrides.
| Name | Description |
|---|---|
--font-ratio |
Theme-authoring hook to override the optical modular scale factor (e.g. 1.414). |
--font-density |
Theme-authoring hook to override base line height density. |
--font-line-width |
Theme-authoring hook to override default reading column measure. |
--measure |
Editor and writer component hook to override active text measure. |
--corner |
Theme-authoring hook to override base border radius. |