@mcp-b/design-tokens 0.20.5 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-b/design-tokens",
-  "version": "0.20.5",
+  "version": "0.22.0",
   "description": "Shared design tokens for MCP-B React applications.",
   "homepage": "https://mcp-b-design-system-storybook.alexmnahas.workers.dev",
   "bugs": {
@@ -24,6 +24,8 @@
     "./index.css": "./src/index.css",
     "./borders": "./src/borders.css",
     "./borders.css": "./src/borders.css",
+    "./elevation": "./src/elevation.css",
+    "./elevation.css": "./src/elevation.css",
     "./focus": "./src/focus.css",
     "./focus.css": "./src/focus.css",
     "./motion": "./src/motion.css",

package/src/borders.css

@@ -1,15 +1,58 @@
 /*
  * Border Tokens
+ *
+ * Radii are a base scale multiplied by --sigvelo-radius-scale, so a product,
+ * a theme, or one subtree can go rounder or squarer by setting a single
+ * variable instead of overriding every radius. Set it on :root for a global
+ * change, or on any element to rescale that subtree.
+ *
+ * --sigvelo-radius-full and --sigvelo-radius-circle stay unscaled: a pill and
+ * a circle are shapes, not sizes.
  */
 
 :root {
   --sigvelo-border-style: solid;
   --sigvelo-border-width: 1px;
-  --sigvelo-radius-xs: 0.1875rem; /* 3px */
-  --sigvelo-radius-sm: 0.25rem; /* 4px */
-  --sigvelo-radius-md: 0.5rem; /* 8px */
-  --sigvelo-radius-lg: 0.75rem; /* 12px */
-  --sigvelo-radius-xl: 1rem; /* 16px */
+
+  /* Hairline rules and rings. Sub-pixel on 1x, crisp on 2x. */
+  --sigvelo-border-width-hairline: 0.5px;
+
+  --sigvelo-radius-scale: 1;
+
+  --sigvelo-radius-xs-base: 0.1875rem; /* 3px */
+  --sigvelo-radius-sm-base: 0.25rem; /* 4px */
+  --sigvelo-radius-md-base: 0.5rem; /* 8px */
+  --sigvelo-radius-lg-base: 0.75rem; /* 12px */
+  --sigvelo-radius-xl-base: 1rem; /* 16px */
+  --sigvelo-radius-2xl-base: 1.25rem; /* 20px */
+  --sigvelo-radius-3xl-base: 1.5rem; /* 24px */
+
+  --sigvelo-radius-xs: calc(var(--sigvelo-radius-xs-base) * var(--sigvelo-radius-scale));
+  --sigvelo-radius-sm: calc(var(--sigvelo-radius-sm-base) * var(--sigvelo-radius-scale));
+  --sigvelo-radius-md: calc(var(--sigvelo-radius-md-base) * var(--sigvelo-radius-scale));
+  --sigvelo-radius-lg: calc(var(--sigvelo-radius-lg-base) * var(--sigvelo-radius-scale));
+  --sigvelo-radius-xl: calc(var(--sigvelo-radius-xl-base) * var(--sigvelo-radius-scale));
+  --sigvelo-radius-2xl: calc(var(--sigvelo-radius-2xl-base) * var(--sigvelo-radius-scale));
+  --sigvelo-radius-3xl: calc(var(--sigvelo-radius-3xl-base) * var(--sigvelo-radius-scale));
+
   --sigvelo-radius-full: 9999px;
   --sigvelo-radius-circle: 50%;
+
+  /* Applied by the shared surface, row, control, and button recipes. Only
+     rounded rectangles opt in — pills and circles keep a true arc. */
+  --sigvelo-corner-shape: round;
+}
+
+/*
+ * Squircle corners where the browser can draw them. A superellipse cuts less
+ * material out of the corner than a circular arc, so the same radius reads
+ * tighter; the scale opens up to compensate and the two changes ship together.
+ * Browsers without corner-shape keep round corners at the unscaled radii and
+ * look exactly as they did before.
+ */
+@supports (corner-shape: superellipse(1.5)) {
+  :root {
+    --sigvelo-corner-shape: superellipse(1.5);
+    --sigvelo-radius-scale: 1.25;
+  }
 }

package/src/contrast.css

@@ -0,0 +1,50 @@
+/*
+ * Increased contrast.
+ *
+ * A request for more contrast is about the faint end of each ramp — quiet text
+ * and hairline edges — not about the whole palette. Brand hues, surfaces, and
+ * every on-color pairing stay exactly as authored, so no component opts in and
+ * no contrast pair that already passed gets re-tuned.
+ *
+ * Every declaration here reads a token this block does not itself reassign.
+ * Custom properties resolve to the winning value, so a chain of promotions
+ * inside one block (subtle -> muted -> base) would collapse all three onto the
+ * base and flatten the hierarchy instead of raising it. Borders deliberately do
+ * collapse — a divider that cannot be seen has no hierarchy to preserve — while
+ * text keeps three distinguishable steps, measured against the canvas.
+ *
+ * Remapping the resolved aliases rather than the -light/-dark inputs means one
+ * block covers system dark mode, both data-theme choices, and the light-dark()
+ * path together.
+ */
+@media (prefers-contrast: more) {
+  :root {
+    /* Secondary text is the first thing to go. Muted reaches full foreground;
+       the two steps below it stay apart by mixing toward the canvas rather
+       than by referencing each other. */
+    --sigvelo-color-text-muted: var(--sigvelo-color-text);
+    --sigvelo-color-text-subtle: color-mix(
+      in oklab,
+      var(--sigvelo-color-text),
+      var(--sigvelo-color-canvas) 20%
+    );
+    --sigvelo-color-text-faint: color-mix(
+      in oklab,
+      var(--sigvelo-color-text),
+      var(--sigvelo-color-canvas) 35%
+    );
+
+    /* Hairlines at the subtle and muted steps round to nothing at this
+       contrast level, so both take the solid border for their hue. */
+    --sigvelo-color-neutral-border-subtle: var(--sigvelo-color-neutral-border);
+    --sigvelo-color-neutral-border-muted: var(--sigvelo-color-neutral-border);
+    --sigvelo-color-primary-border-subtle: var(--sigvelo-color-primary-border);
+    --sigvelo-color-primary-border-muted: var(--sigvelo-color-primary-border);
+    --sigvelo-color-success-border-subtle: var(--sigvelo-color-success-border);
+    --sigvelo-color-success-border-muted: var(--sigvelo-color-success-border);
+    --sigvelo-color-warning-border-subtle: var(--sigvelo-color-warning-border);
+    --sigvelo-color-warning-border-muted: var(--sigvelo-color-warning-border);
+    --sigvelo-color-danger-border-subtle: var(--sigvelo-color-danger-border);
+    --sigvelo-color-danger-border-muted: var(--sigvelo-color-danger-border);
+  }
+}

package/src/elevation.css

@@ -0,0 +1,28 @@
+/*
+ * Elevation Materials
+ *
+ * The geometry half of elevation: the composed filters that turn a
+ * translucent surface into frosted chrome. The color half — the layered
+ * shadows themselves — is theme-specific and lives in semantic-colors.css as
+ * the --sigvelo-elevation-* family.
+ *
+ * Elevation here is a stack, not a single shadow: a hairline ring that reads
+ * as an edge at any zoom, then a tight contact shadow, then a wide ambient
+ * one. That layering is what keeps a raised surface legible on both a white
+ * canvas and a near-black one.
+ */
+
+:root {
+  /*
+   * Frosted chrome over scrolling content.
+   *
+   * Held to a single 1px radius, which separates modal chrome without making
+   * the page behind it look frosted. A backdrop filter repaints the whole
+   * area behind the element every frame, so a wider radius or a second pass
+   * such as saturate() on a full-viewport scrim costs frames on every dialog
+   * open — measurably, not theoretically: at blur(24px) saturate(180%) the
+   * Storybook suite dropped roughly a third of its runs to timing failures in
+   * stories that had nothing to do with dialogs.
+   */
+  --sigvelo-glass-filter: blur(1px);
+}

package/src/focus.css

@@ -5,7 +5,6 @@
 :root {
   --sigvelo-focus-width: 3px;
   --sigvelo-focus-offset: 1px;
-  --sigvelo-backdrop-filter: blur(6px);
   /* Focus ring used in forced-colors mode, where the box-shadow ring is dropped. */
   --sigvelo-focus-ring-forced: 2px solid Highlight;
 }

package/src/index.css

@@ -5,5 +5,8 @@
 @import "./focus.css";
 @import "./spacing.css";
 @import "./motion.css";
+@import "./layers.css";
+@import "./elevation.css";
 @import "./semantic-colors.css";
 @import "./themes.css";
+@import "./contrast.css";

package/src/layers.css

@@ -0,0 +1,44 @@
+/*
+ * Stacking layers.
+ *
+ * Only the bands that components have to agree on live here. Ordering *inside*
+ * a component — a gradient behind its own text, a badge over its own avatar —
+ * stays a plain 0/1/2 in that component's stylesheet, because naming a token
+ * for it would imply a cross-component contract that does not exist.
+ *
+ * The gaps between bands are deliberate. A component that needs to sit just
+ * above its band says so with calc() against the band it belongs to, which
+ * keeps the relationship legible instead of encoding it as a bare 23.
+ */
+
+:root {
+  /* Sticky application chrome: app bars, pinned rows, and hover cards that
+     float within a scroll region but below anything modal. */
+  --sigvelo-z-chrome: 20;
+
+  /* Drag affordances — resize handles, splitters — which have to stay grabbable
+     above the chrome they resize. */
+  --sigvelo-z-panel: 25;
+
+  /* Base UI popups: dialog, alert dialog, popover, menu, tooltip, preview card.
+     One band for all of them, because the library already resolves their order
+     among themselves by mount order. */
+  --sigvelo-z-overlay: 50;
+
+  /* Toasts outrank overlays: a toast reporting the result of a dialog action
+     has to be readable while that dialog is still closing. */
+  --sigvelo-z-toast: 100;
+
+  /*
+   * Overlays drawn on top of a host page this design system does not control —
+   * a browser control surface injected into someone else's document. Max int is
+   * not a layer, it is a concession that we cannot see the other stylesheet.
+   * Nothing that renders inside our own tree may use it.
+   *
+   * Recorded here so the value has one documented home, but such a surface
+   * cannot actually reference it: it mounts in a closed shadow root where this
+   * sheet does not exist, so var() would resolve to nothing and z-index would
+   * silently fall back to auto. Those stylesheets inline the number instead.
+   */
+  --sigvelo-z-host-overlay: 2147483647;
+}

package/src/motion.css

@@ -7,6 +7,24 @@
   --sigvelo-ease-standard: cubic-bezier(0.2, 0, 0, 1);
   --sigvelo-ease-emphasized: cubic-bezier(0.16, 1, 0.3, 1);
   --sigvelo-ease-accelerate: cubic-bezier(0.4, 0, 1, 1);
+  /* Nearly all of the distance in the first third, then a long settle. Reads
+     as responsive on entrances that also move a long way. */
+  --sigvelo-ease-snappy: cubic-bezier(0.23, 1, 0.32, 1);
+  /* Press and release. A damped spring settling in three shrinking bounces —
+     a cubic-bezier can only overshoot once, which reads as a wobble rather
+     than a physical button. Keep it on transform; on color it just looks slow. */
+  --sigvelo-ease-press: linear(
+    0,
+    0.3505,
+    0.7432,
+    0.9336,
+    0.9951,
+    1.0062,
+    1.0045,
+    1.0019,
+    1.0005,
+    1
+  );
 
   /* Semantic motion roles keep component families on one quiet rhythm. */
   --sigvelo-motion-duration-interaction: var(--sigvelo-duration-fast);
@@ -16,11 +34,25 @@
   /* Looping "busy/streaming" text shimmer sweep. Not reduced with the
      interaction scale — reduced motion turns the shimmer off entirely. */
   --sigvelo-motion-duration-shimmer: 2400ms;
+  /* Breathing rate of a live-state indicator. Slower than a heartbeat on
+     purpose: fast enough to read as ongoing, slow enough to sit at the edge of
+     vision for minutes without demanding attention. Like the shimmer, reduced
+     motion switches it off rather than shortening it. */
+  --sigvelo-motion-duration-pulse: 1400ms;
+  /* One full turn of a spinner. A loop rate, not a transition duration: the
+     transition scale tops out at 360ms, which as a rotation period is a blur —
+     which is why every surface that wanted a spinner used to write its own
+     literal instead of the shared class. */
+  --sigvelo-motion-duration-spin: 900ms;
 
   --sigvelo-motion-ease-enter: var(--sigvelo-ease-emphasized);
   --sigvelo-motion-ease-exit: var(--sigvelo-ease-accelerate);
   --sigvelo-motion-ease-change: var(--sigvelo-ease-standard);
 
+  /* Delay between neighbours in a revealed list, so a group of rows arrives
+     as a sequence instead of a single block. Keep the total under ~200ms. */
+  --sigvelo-motion-stagger-step: 35ms;
+
   --sigvelo-motion-distance-xs: 1px;
   --sigvelo-motion-distance-sm: 4px;
   --sigvelo-motion-distance-md: 8px;

package/src/semantic-colors.css

@@ -6,159 +6,142 @@
  */
 
 :root {
-  --sigvelo-color-canvas-light: white;
-  --sigvelo-color-canvas-dark: var(--sigvelo-color-neutral-950);
-  --sigvelo-color-surface-light: white;
-  --sigvelo-color-surface-dark: color-mix(in oklab, var(--sigvelo-color-neutral-950), white 2.5%);
-  --sigvelo-color-text-light: var(--sigvelo-color-neutral-900);
-  --sigvelo-color-text-dark: var(--sigvelo-color-neutral-200);
-  --sigvelo-color-text-muted-light: var(--sigvelo-color-neutral-700);
-  --sigvelo-color-text-muted-dark: var(--sigvelo-color-neutral-500);
+  --sigvelo-color-canvas-light: #fff;
+  --sigvelo-color-canvas-dark: #212121;
+  /* The quiet window stage visible around bounded application surfaces. It is
+     not a control fill: canvas remains the neutral base for embedded fields. */
+  --sigvelo-color-surface-under-light: #f9f9f9;
+  --sigvelo-color-surface-under-dark: #000;
+  --sigvelo-color-surface-light: #fff;
+  --sigvelo-color-surface-dark: #181818;
+  --sigvelo-color-text-light: #0d0d0d;
+  --sigvelo-color-text-dark: #ececec;
+  --sigvelo-color-text-muted-light: #5d5d5d;
+  --sigvelo-color-text-muted-dark: #b4b4b4;
+  /* Two quieter rungs below muted, measured against the owning surface rather
+     than picked off the legacy neutral ramp.
+     subtle: de-emphasized label text, still holds ~4.5:1 against its surface.
+     faint: icons and resting affordances only — it clears the 3:1 needed for
+     a graphic, not the 4.5:1 needed for body copy. */
+  --sigvelo-color-text-subtle-light: #737373;
+  --sigvelo-color-text-subtle-dark: #a6a6a6;
+  --sigvelo-color-text-faint-light: #8f8f8f;
+  --sigvelo-color-text-faint-dark: #8f8f8f;
+  /* Surfaces that sit above the page. In light mode a raised card is the
+     same white as the surface and is separated by shadow alone; in dark mode
+     shadow does almost nothing, so the card lifts by getting lighter. */
+  --sigvelo-color-surface-raised-light: #fff;
+  --sigvelo-color-surface-raised-dark: #282828;
+  --sigvelo-color-surface-sunken-light: #f9f9f9;
+  --sigvelo-color-surface-sunken-dark: #171717;
+  /* Translucent counterpart of surface-raised, for panels that blur what is
+     scrolling underneath. Pair with --sigvelo-glass-filter, and fall back to
+     surface-raised where backdrop-filter is unavailable. */
+  --sigvelo-color-surface-glass-light: color-mix(
+    in oklab,
+    var(--sigvelo-color-surface-raised-light),
+    transparent 20%
+  );
+  --sigvelo-color-surface-glass-dark: color-mix(
+    in oklab,
+    var(--sigvelo-color-surface-raised-dark),
+    transparent 20%
+  );
   --sigvelo-color-focus-light: var(--sigvelo-color-primary-bg-light);
   --sigvelo-color-focus-dark: var(--sigvelo-color-primary-bg-dark);
   --sigvelo-focus-ring-light: var(--sigvelo-border-style) var(--sigvelo-focus-width)
     var(--sigvelo-color-focus-light);
   --sigvelo-focus-ring-dark: var(--sigvelo-border-style) var(--sigvelo-focus-width)
     var(--sigvelo-color-focus-dark);
-  --sigvelo-color-backdrop-light: rgb(0 0 0 / 0.5);
-  --sigvelo-color-backdrop-dark: rgb(0 0 0 / 0.5);
+  /* Paired with --sigvelo-glass-filter on dialog scrims. A pale tint and 1px
+     blur recede the page without turning it into a dark or frosted sheet. */
+  --sigvelo-color-backdrop-light: rgb(238 238 238 / 50%);
+  --sigvelo-color-backdrop-dark: rgb(0 0 0 / 50%);
   --sigvelo-color-selection-bg-light: var(--sigvelo-color-primary-300);
   --sigvelo-color-selection-bg-dark: var(--sigvelo-color-primary-700);
   --sigvelo-color-selection-text-light: var(--sigvelo-color-text-light);
   --sigvelo-color-selection-text-dark: var(--sigvelo-color-text-dark);
-  --sigvelo-color-shadow-light: black;
-  --sigvelo-color-shadow-dark: black;
-  --sigvelo-shadow-xs-light: 0 0.0625rem 0.0625rem
-    color-mix(in oklab, transparent, var(--sigvelo-color-shadow-light) 4%);
-  --sigvelo-shadow-xs-dark: 0 1px 2px
-    color-mix(in oklab, transparent, var(--sigvelo-color-shadow-dark) 8%);
-  --sigvelo-shadow-sm-light: 0 0.125rem 0.1875rem
-    color-mix(in oklab, transparent, var(--sigvelo-color-shadow-light) 8%);
-  --sigvelo-shadow-sm-dark: 0 2px 4px
-    color-mix(in oklab, transparent, var(--sigvelo-color-shadow-dark) 12%);
-  --sigvelo-shadow-md-light: 0 0.1875rem 0.375rem
-    color-mix(in oklab, transparent, var(--sigvelo-color-shadow-light) 10%);
-  --sigvelo-shadow-md-dark: 0 4px 8px
-    color-mix(in oklab, transparent, var(--sigvelo-color-shadow-dark) 16%);
-  --sigvelo-shadow-lg-light: 0 0.375rem 0.75rem
-    color-mix(in oklab, transparent, var(--sigvelo-color-shadow-light) 12%);
-  --sigvelo-shadow-lg-dark: 0 8px 16px
-    color-mix(in oklab, transparent, var(--sigvelo-color-shadow-dark) 20%);
-  --sigvelo-shadow-xl-light: 0 0.5rem 1rem
-    color-mix(in oklab, transparent, var(--sigvelo-color-shadow-light) 14%);
-  --sigvelo-shadow-xl-dark: 0 12px 20px
-    color-mix(in oklab, transparent, var(--sigvelo-color-shadow-dark) 24%);
-  --sigvelo-inset-shadow-xs-light: inset 0 0.125rem 0.125rem -0.125rem
-    color-mix(in oklab, black, transparent 94%);
-  --sigvelo-inset-shadow-xs-dark: var(--sigvelo-inset-shadow-xs-light);
-  --sigvelo-inset-shadow-sm-light: inset 0 0.25rem 0.25rem -0.25rem
-    color-mix(in oklab, black, transparent 90%);
-  --sigvelo-inset-shadow-sm-dark: var(--sigvelo-inset-shadow-sm-light);
-  --sigvelo-inset-shadow-md-light: inset 0 0.5rem 0.5rem -0.5rem
-    color-mix(in oklab, black, transparent 88%);
-  --sigvelo-inset-shadow-md-dark: var(--sigvelo-inset-shadow-md-light);
-  --sigvelo-inset-shadow-lg-light: inset 0 1rem 1rem -1rem
-    color-mix(in oklab, black, transparent 85%);
-  --sigvelo-inset-shadow-lg-dark: var(--sigvelo-inset-shadow-lg-light);
-  --sigvelo-inset-shadow-xl-light: inset 0 1.5rem 1.5rem -1.5rem
-    color-mix(in oklab, black, transparent 82%);
-  --sigvelo-inset-shadow-xl-dark: var(--sigvelo-inset-shadow-xl-light);
-  --sigvelo-color-primary-bg-subtle-light: var(--sigvelo-color-primary-100);
-  --sigvelo-color-primary-bg-subtle-dark: color-mix(
-    in oklab,
-    var(--sigvelo-color-primary-900),
-    white 1%
-  );
-  --sigvelo-color-primary-bg-muted-light: var(--sigvelo-color-primary-200);
-  --sigvelo-color-primary-bg-muted-dark: var(--sigvelo-color-primary-800);
-  --sigvelo-color-primary-bg-light: color-mix(
-    in oklab,
-    var(--sigvelo-color-primary-600),
-    black 2.5%
-  );
-  --sigvelo-color-primary-bg-dark: color-mix(
-    in oklab,
-    var(--sigvelo-color-primary-600),
-    black 7.5%
-  );
-  --sigvelo-color-primary-bg-strong-light: var(--sigvelo-color-primary-800);
-  --sigvelo-color-primary-bg-strong-dark: var(--sigvelo-color-primary-200);
-  --sigvelo-color-primary-bg-stronger-light: var(--sigvelo-color-primary-900);
-  --sigvelo-color-primary-bg-stronger-dark: var(--sigvelo-color-primary-100);
-  --sigvelo-color-primary-text-on-subtle-light: var(--sigvelo-color-primary-900);
-  --sigvelo-color-primary-text-on-subtle-dark: var(--sigvelo-color-primary-100);
-  --sigvelo-color-primary-text-on-bg-light: white;
-  --sigvelo-color-primary-text-on-bg-dark: white;
-  --sigvelo-color-primary-text-on-strong-light: white;
-  --sigvelo-color-primary-text-on-strong-dark: black;
-  --sigvelo-color-primary-text-light: color-mix(
-    in oklab,
-    var(--sigvelo-color-primary-600),
-    black 12.5%
-  );
-  --sigvelo-color-primary-text-dark: var(--sigvelo-color-primary-500);
-  --sigvelo-color-primary-border-subtle-light: color-mix(
-    in oklab,
-    var(--sigvelo-color-primary-100),
-    black 3%
-  );
-  --sigvelo-color-primary-border-subtle-dark: color-mix(
-    in oklab,
-    var(--sigvelo-color-primary-900),
-    white 7.5%
-  );
-  --sigvelo-color-primary-border-muted-light: var(--sigvelo-color-primary-300);
-  --sigvelo-color-primary-border-muted-dark: var(--sigvelo-color-primary-800);
-  --sigvelo-color-primary-border-light: var(--sigvelo-color-primary-500);
-  --sigvelo-color-primary-border-dark: var(--sigvelo-color-primary-600);
-  --sigvelo-color-neutral-bg-subtle-light: var(--sigvelo-color-neutral-100);
-  --sigvelo-color-neutral-bg-subtle-dark: color-mix(
-    in oklab,
-    var(--sigvelo-color-neutral-900),
-    white 1%
-  );
-  --sigvelo-color-neutral-bg-muted-light: var(--sigvelo-color-neutral-200);
-  --sigvelo-color-neutral-bg-muted-dark: var(--sigvelo-color-neutral-800);
-  --sigvelo-color-neutral-bg-light: color-mix(
-    in oklab,
-    var(--sigvelo-color-neutral-600),
-    black 2.5%
-  );
-  --sigvelo-color-neutral-bg-dark: color-mix(
-    in oklab,
-    var(--sigvelo-color-neutral-600),
-    black 7.5%
-  );
-  --sigvelo-color-neutral-bg-strong-light: var(--sigvelo-color-neutral-800);
-  --sigvelo-color-neutral-bg-strong-dark: var(--sigvelo-color-neutral-200);
-  --sigvelo-color-neutral-bg-stronger-light: var(--sigvelo-color-neutral-900);
-  --sigvelo-color-neutral-bg-stronger-dark: var(--sigvelo-color-neutral-100);
-  --sigvelo-color-neutral-text-on-subtle-light: var(--sigvelo-color-neutral-900);
-  --sigvelo-color-neutral-text-on-subtle-dark: var(--sigvelo-color-neutral-100);
-  --sigvelo-color-neutral-text-on-bg-light: white;
-  --sigvelo-color-neutral-text-on-bg-dark: white;
-  --sigvelo-color-neutral-text-on-strong-light: white;
-  --sigvelo-color-neutral-text-on-strong-dark: black;
-  --sigvelo-color-neutral-text-light: color-mix(
-    in oklab,
-    var(--sigvelo-color-neutral-600),
-    black 12.5%
-  );
-  --sigvelo-color-neutral-text-dark: var(--sigvelo-color-neutral-500);
-  --sigvelo-color-neutral-border-subtle-light: color-mix(
-    in oklab,
-    var(--sigvelo-color-neutral-200),
-    transparent 40%
-  );
-  --sigvelo-color-neutral-border-subtle-dark: color-mix(
-    in oklab,
-    var(--sigvelo-color-neutral-900),
-    white 4%
-  );
-  --sigvelo-color-neutral-border-muted-light: var(--sigvelo-color-neutral-300);
-  --sigvelo-color-neutral-border-muted-dark: var(--sigvelo-color-neutral-800);
-  --sigvelo-color-neutral-border-light: var(--sigvelo-color-neutral-500);
-  --sigvelo-color-neutral-border-dark: var(--sigvelo-color-neutral-600);
+  /* One color for both themes. What differs between light and dark is how much
+     of it each stack mixes in, and that lives in the stacks below. */
+  --sigvelo-color-shadow: black;
+
+  /* Elevation stacks. Each begins with the hairline ring below — a sub-pixel
+     edge that survives zoom and keeps a shadowed surface from dissolving into
+     the canvas when the shadow itself is nearly invisible. */
+  --sigvelo-elevation-hairline-light: 0 0 0 var(--sigvelo-border-width-hairline)
+    color-mix(in oklab, transparent, var(--sigvelo-color-shadow) 5%);
+  --sigvelo-elevation-hairline-dark: 0 0 0 var(--sigvelo-border-width-hairline)
+    color-mix(in oklab, transparent, white 10%);
+  /* raised: rows, cards, anything one step off the page. A broad, low-alpha
+     shadow separates the surface without drawing a dark line beneath it. */
+  --sigvelo-elevation-raised-light:
+    var(--sigvelo-elevation-hairline-light),
+    0 0 15px color-mix(in oklab, transparent, var(--sigvelo-color-shadow) 3%);
+  --sigvelo-elevation-raised-dark:
+    var(--sigvelo-elevation-hairline-dark),
+    0 0 15px color-mix(in oklab, transparent, var(--sigvelo-color-shadow) 3%);
+  /* floating: composers and toolbars that hover over scrolling content. The
+     wide spread-free ambient layer is what reads as "off the page" rather
+     than "outlined". */
+  --sigvelo-elevation-floating-light:
+    var(--sigvelo-elevation-hairline-light),
+    0 3px 7.5px color-mix(in oklab, transparent, var(--sigvelo-color-shadow) 4%),
+    0 0 20px color-mix(in oklab, transparent, var(--sigvelo-color-shadow) 5%);
+  --sigvelo-elevation-floating-dark:
+    var(--sigvelo-elevation-hairline-dark),
+    0 3px 7.5px color-mix(in oklab, transparent, var(--sigvelo-color-shadow) 32%),
+    0 0 20px color-mix(in oklab, transparent, var(--sigvelo-color-shadow) 28%);
+  /* overlay: popovers, menus, dialogs — detached from the page entirely. */
+  --sigvelo-elevation-overlay-light: 0 0 1px rgb(0 0 0 / 62%), 0 8px 12px rgb(0 0 0 / 8%);
+  --sigvelo-elevation-overlay-dark: 0 0 1px rgb(255 255 255 / 14%), 0 8px 16px rgb(0 0 0 / 35%);
+  --sigvelo-color-primary-bg-subtle-light: #f9f9f9;
+  --sigvelo-color-primary-bg-subtle-dark: #2f2f2f;
+  --sigvelo-color-primary-bg-muted-light: #ececec;
+  --sigvelo-color-primary-bg-muted-dark: #424242;
+  --sigvelo-color-primary-bg-light: #0d0d0d;
+  --sigvelo-color-primary-bg-dark: #fff;
+  --sigvelo-color-primary-bg-strong-light: #000;
+  --sigvelo-color-primary-bg-strong-dark: #fff;
+  --sigvelo-color-primary-bg-stronger-light: #000;
+  --sigvelo-color-primary-bg-stronger-dark: #fff;
+  --sigvelo-color-primary-text-on-subtle-light: #0d0d0d;
+  --sigvelo-color-primary-text-on-subtle-dark: #ececec;
+  --sigvelo-color-primary-text-on-bg-light: #fff;
+  --sigvelo-color-primary-text-on-bg-dark: #0d0d0d;
+  --sigvelo-color-primary-text-on-strong-light: #fff;
+  --sigvelo-color-primary-text-on-strong-dark: #0d0d0d;
+  --sigvelo-color-primary-text-light: #0d0d0d;
+  --sigvelo-color-primary-text-dark: #ececec;
+  --sigvelo-color-primary-border-subtle-light: rgb(0 0 0 / 5%);
+  --sigvelo-color-primary-border-subtle-dark: rgb(255 255 255 / 10%);
+  --sigvelo-color-primary-border-muted-light: rgb(0 0 0 / 10%);
+  --sigvelo-color-primary-border-muted-dark: rgb(255 255 255 / 15%);
+  --sigvelo-color-primary-border-light: #0d0d0d;
+  --sigvelo-color-primary-border-dark: #ececec;
+  --sigvelo-color-neutral-bg-subtle-light: rgb(0 0 0 / 5%);
+  --sigvelo-color-neutral-bg-subtle-dark: rgb(255 255 255 / 8%);
+  --sigvelo-color-neutral-bg-muted-light: #ececec;
+  --sigvelo-color-neutral-bg-muted-dark: #424242;
+  --sigvelo-color-neutral-bg-light: #5d5d5d;
+  --sigvelo-color-neutral-bg-dark: #b4b4b4;
+  --sigvelo-color-neutral-bg-strong-light: #333;
+  --sigvelo-color-neutral-bg-strong-dark: #ececec;
+  --sigvelo-color-neutral-bg-stronger-light: #0d0d0d;
+  --sigvelo-color-neutral-bg-stronger-dark: #fff;
+  --sigvelo-color-neutral-text-on-subtle-light: #0d0d0d;
+  --sigvelo-color-neutral-text-on-subtle-dark: #ececec;
+  --sigvelo-color-neutral-text-on-bg-light: #fff;
+  --sigvelo-color-neutral-text-on-bg-dark: #0d0d0d;
+  --sigvelo-color-neutral-text-on-strong-light: #fff;
+  --sigvelo-color-neutral-text-on-strong-dark: #0d0d0d;
+  --sigvelo-color-neutral-text-light: #5d5d5d;
+  --sigvelo-color-neutral-text-dark: #b4b4b4;
+  --sigvelo-color-neutral-border-subtle-light: rgb(0 0 0 / 5%);
+  --sigvelo-color-neutral-border-subtle-dark: rgb(255 255 255 / 10%);
+  --sigvelo-color-neutral-border-muted-light: rgb(0 0 0 / 10%);
+  --sigvelo-color-neutral-border-muted-dark: rgb(255 255 255 / 15%);
+  --sigvelo-color-neutral-border-light: #5d5d5d;
+  --sigvelo-color-neutral-border-dark: #b4b4b4;
   --sigvelo-color-success-bg-subtle-light: var(--sigvelo-color-success-100);
   --sigvelo-color-success-bg-subtle-dark: color-mix(
     in oklab,

package/src/spacing.css

@@ -1,65 +1,94 @@
 /*
  * Spacing & Form Control Tokens
+ *
+ * One 4px grid, named by quarter-rem step: --sigvelo-spacing-3 is 3 × 0.25rem
+ * = 12px. The scale is dense through the range components actually lay out in
+ * and thins out above 48px, where sizing becomes layout rather than spacing.
+ *
+ * Every control height and gap in this file resolves to a step on that grid.
+ * If a value you need is not on the scale, that is the signal to reconsider the
+ * value rather than to write the number: audit:css-recipes rejects off-grid
+ * lengths in component spacing.
  */
 
 :root {
   /* Spacing scale */
-  --sigvelo-spacing-0-5: 0.125rem;
-  --sigvelo-spacing-1: 0.25rem;
-  --sigvelo-spacing-1-5: 0.375rem;
-  --sigvelo-spacing-2: 0.5rem;
-  --sigvelo-spacing-2-5: 0.625rem;
-  --sigvelo-spacing-3: 0.75rem;
-  --sigvelo-spacing-4: 1rem;
-  --sigvelo-spacing-5: 1.25rem;
-  --sigvelo-spacing-6: 1.5rem;
-  --sigvelo-spacing-8: 2rem;
-  --sigvelo-spacing-12: 3rem;
+  --sigvelo-spacing-0-5: 0.125rem; /* 2px */
+  --sigvelo-spacing-1: 0.25rem; /* 4px */
+  --sigvelo-spacing-1-5: 0.375rem; /* 6px */
+  --sigvelo-spacing-2: 0.5rem; /* 8px */
+  --sigvelo-spacing-2-5: 0.625rem; /* 10px */
+  --sigvelo-spacing-3: 0.75rem; /* 12px */
+  --sigvelo-spacing-3-5: 0.875rem; /* 14px */
+  --sigvelo-spacing-4: 1rem; /* 16px */
+  --sigvelo-spacing-5: 1.25rem; /* 20px */
+  --sigvelo-spacing-6: 1.5rem; /* 24px */
+  --sigvelo-spacing-7: 1.75rem; /* 28px */
+  --sigvelo-spacing-8: 2rem; /* 32px */
+  --sigvelo-spacing-9: 2.25rem; /* 36px */
+  --sigvelo-spacing-10: 2.5rem; /* 40px */
+  --sigvelo-spacing-11: 2.75rem; /* 44px */
+  --sigvelo-spacing-12: 3rem; /* 48px */
+  --sigvelo-spacing-14: 3.5rem; /* 56px */
+  --sigvelo-spacing-16: 4rem; /* 64px */
+  --sigvelo-spacing-20: 5rem; /* 80px */
+  --sigvelo-spacing-24: 6rem; /* 96px */
 
-  --sigvelo-spacing-content: 1.75rem;
-
-  /* Form control heights per size */
-  --sigvelo-control-height-xs: 1.75rem;
-  --sigvelo-control-height-sm: 2rem;
-  --sigvelo-control-height-md: 2.25rem;
-  --sigvelo-control-height-lg: 2.5rem;
-  --sigvelo-control-height-xl: 2.75rem;
+  /* Form control heights per size. Expressed on the spacing scale so a panel,
+     a gap, or a reserved gutter can line up with a control by name. */
+  --sigvelo-control-height-xs: var(--sigvelo-spacing-7); /* 28px */
+  --sigvelo-control-height-sm: var(--sigvelo-spacing-8); /* 32px */
+  --sigvelo-control-height-md: var(--sigvelo-spacing-9); /* 36px */
+  --sigvelo-control-height-lg: var(--sigvelo-spacing-10); /* 40px */
+  --sigvelo-control-height-xl: var(--sigvelo-spacing-11); /* 44px */
 
   /* Form control font sizes per size */
   --sigvelo-control-text-xs: 0.75rem;
   --sigvelo-control-text-sm: 0.8125rem;
   --sigvelo-control-text-md: 0.875rem;
-  --sigvelo-control-text-lg: 1rem;
-  --sigvelo-control-text-xl: 1.125rem;
+  --sigvelo-control-text-lg: 0.875rem;
+  --sigvelo-control-text-xl: 0.875rem;
+
+  /* The leading that belongs to each of those sizes, from the type ramp's
+     whole-pixel partners. A ratio applied to a size that is itself a variable
+     lands on fractions — 13px at 1.25 is 16.25px — and a stack of rows then
+     drifts off the 4px grid a quarter pixel at a time. Every one of these fits
+     inside the matching control height with room to spare, so a control keeps
+     its box and gains a predictable baseline. */
+  --sigvelo-control-line-height-xs: var(--sigvelo-text-xs-leading); /* 16px */
+  --sigvelo-control-line-height-sm: var(--sigvelo-text-compact-leading); /* 18px */
+  --sigvelo-control-line-height-md: var(--sigvelo-text-sm-leading); /* 20px */
+  --sigvelo-control-line-height-lg: var(--sigvelo-text-sm-leading); /* 20px */
+  --sigvelo-control-line-height-xl: var(--sigvelo-text-sm-leading); /* 20px */
 
   /* Canonical control geometry derived from the public size scale. */
   --sigvelo-control-padding-inline-xs: var(--sigvelo-spacing-2);
   --sigvelo-control-padding-inline-sm: var(--sigvelo-spacing-2-5);
   --sigvelo-control-padding-inline-md: var(--sigvelo-spacing-3);
   --sigvelo-control-padding-inline-lg: var(--sigvelo-spacing-4);
-  --sigvelo-control-padding-inline-xl: var(--sigvelo-spacing-5);
-  --sigvelo-control-icon-size-xs: 0.75rem;
-  --sigvelo-control-icon-size-sm: 0.875rem;
-  --sigvelo-control-icon-size-md: 1rem;
-  --sigvelo-control-icon-size-lg: 1.125rem;
-  --sigvelo-control-icon-size-xl: 1.25rem;
+  --sigvelo-control-padding-inline-xl: var(--sigvelo-spacing-4);
+
+  /* Icons ride the type ramp rather than a scale of their own: a glyph beside
+     a label should be the size of the label, not a nearby round number. */
+  --sigvelo-control-icon-size-xs: var(--sigvelo-text-xs); /* 12px */
+  --sigvelo-control-icon-size-sm: var(--sigvelo-text-sm); /* 14px */
+  --sigvelo-control-icon-size-md: var(--sigvelo-text-base); /* 16px */
+  --sigvelo-control-icon-size-lg: var(--sigvelo-text-lg); /* 18px */
+  --sigvelo-control-icon-size-xl: var(--sigvelo-text-xl); /* 20px */
 
   /* Compact application density. Product chrome and shared recipes resolve
      through these aliases so density can be tuned in one place. */
   --sigvelo-density-compact-control-height: var(--sigvelo-control-height-sm);
   --sigvelo-density-compact-control-padding-inline: var(--sigvelo-control-padding-inline-sm);
   --sigvelo-density-compact-control-font-size: var(--sigvelo-control-text-sm);
+  --sigvelo-density-compact-control-line-height: var(--sigvelo-control-line-height-sm);
   --sigvelo-density-compact-control-icon-size: var(--sigvelo-control-icon-size-sm);
   --sigvelo-density-compact-control-gap: var(--sigvelo-spacing-1-5);
 
   /* Form control misc */
-  --sigvelo-control-required-content: "*";
   --sigvelo-control-placeholder-color: color-mix(
     in oklab,
     var(--sigvelo-color-text-muted),
     transparent 25%
   );
-
-  /* Button */
-  --sigvelo-button-active-offset: 1.5px;
 }

package/src/themes.css

@@ -8,25 +8,24 @@
 :root {
   color-scheme: light dark;
   --sigvelo-color-canvas: var(--sigvelo-color-canvas-light);
+  --sigvelo-color-surface-under: var(--sigvelo-color-surface-under-light);
   --sigvelo-color-surface: var(--sigvelo-color-surface-light);
+  --sigvelo-color-surface-raised: var(--sigvelo-color-surface-raised-light);
+  --sigvelo-color-surface-sunken: var(--sigvelo-color-surface-sunken-light);
+  --sigvelo-color-surface-glass: var(--sigvelo-color-surface-glass-light);
   --sigvelo-color-text: var(--sigvelo-color-text-light);
   --sigvelo-color-text-muted: var(--sigvelo-color-text-muted-light);
+  --sigvelo-color-text-subtle: var(--sigvelo-color-text-subtle-light);
+  --sigvelo-color-text-faint: var(--sigvelo-color-text-faint-light);
   --sigvelo-color-focus: var(--sigvelo-color-focus-light);
   --sigvelo-focus-ring: var(--sigvelo-focus-ring-light);
   --sigvelo-color-backdrop: var(--sigvelo-color-backdrop-light);
   --sigvelo-color-selection-bg: var(--sigvelo-color-selection-bg-light);
   --sigvelo-color-selection-text: var(--sigvelo-color-selection-text-light);
-  --sigvelo-color-shadow: var(--sigvelo-color-shadow-light);
-  --sigvelo-shadow-xs: var(--sigvelo-shadow-xs-light);
-  --sigvelo-shadow-sm: var(--sigvelo-shadow-sm-light);
-  --sigvelo-shadow-md: var(--sigvelo-shadow-md-light);
-  --sigvelo-shadow-lg: var(--sigvelo-shadow-lg-light);
-  --sigvelo-shadow-xl: var(--sigvelo-shadow-xl-light);
-  --sigvelo-inset-shadow-xs: var(--sigvelo-inset-shadow-xs-light);
-  --sigvelo-inset-shadow-sm: var(--sigvelo-inset-shadow-sm-light);
-  --sigvelo-inset-shadow-md: var(--sigvelo-inset-shadow-md-light);
-  --sigvelo-inset-shadow-lg: var(--sigvelo-inset-shadow-lg-light);
-  --sigvelo-inset-shadow-xl: var(--sigvelo-inset-shadow-xl-light);
+  --sigvelo-elevation-hairline: var(--sigvelo-elevation-hairline-light);
+  --sigvelo-elevation-raised: var(--sigvelo-elevation-raised-light);
+  --sigvelo-elevation-floating: var(--sigvelo-elevation-floating-light);
+  --sigvelo-elevation-overlay: var(--sigvelo-elevation-overlay-light);
   --sigvelo-color-primary-bg-subtle: var(--sigvelo-color-primary-bg-subtle-light);
   --sigvelo-color-primary-bg-muted: var(--sigvelo-color-primary-bg-muted-light);
   --sigvelo-color-primary-bg: var(--sigvelo-color-primary-bg-light);
@@ -94,25 +93,24 @@
 @media (prefers-color-scheme: dark) {
   :root {
     --sigvelo-color-canvas: var(--sigvelo-color-canvas-dark);
+    --sigvelo-color-surface-under: var(--sigvelo-color-surface-under-dark);
     --sigvelo-color-surface: var(--sigvelo-color-surface-dark);
+    --sigvelo-color-surface-raised: var(--sigvelo-color-surface-raised-dark);
+    --sigvelo-color-surface-sunken: var(--sigvelo-color-surface-sunken-dark);
+    --sigvelo-color-surface-glass: var(--sigvelo-color-surface-glass-dark);
     --sigvelo-color-text: var(--sigvelo-color-text-dark);
     --sigvelo-color-text-muted: var(--sigvelo-color-text-muted-dark);
+    --sigvelo-color-text-subtle: var(--sigvelo-color-text-subtle-dark);
+    --sigvelo-color-text-faint: var(--sigvelo-color-text-faint-dark);
     --sigvelo-color-focus: var(--sigvelo-color-focus-dark);
     --sigvelo-focus-ring: var(--sigvelo-focus-ring-dark);
     --sigvelo-color-backdrop: var(--sigvelo-color-backdrop-dark);
     --sigvelo-color-selection-bg: var(--sigvelo-color-selection-bg-dark);
     --sigvelo-color-selection-text: var(--sigvelo-color-selection-text-dark);
-    --sigvelo-color-shadow: var(--sigvelo-color-shadow-dark);
-    --sigvelo-shadow-xs: var(--sigvelo-shadow-xs-dark);
-    --sigvelo-shadow-sm: var(--sigvelo-shadow-sm-dark);
-    --sigvelo-shadow-md: var(--sigvelo-shadow-md-dark);
-    --sigvelo-shadow-lg: var(--sigvelo-shadow-lg-dark);
-    --sigvelo-shadow-xl: var(--sigvelo-shadow-xl-dark);
-    --sigvelo-inset-shadow-xs: var(--sigvelo-inset-shadow-xs-dark);
-    --sigvelo-inset-shadow-sm: var(--sigvelo-inset-shadow-sm-dark);
-    --sigvelo-inset-shadow-md: var(--sigvelo-inset-shadow-md-dark);
-    --sigvelo-inset-shadow-lg: var(--sigvelo-inset-shadow-lg-dark);
-    --sigvelo-inset-shadow-xl: var(--sigvelo-inset-shadow-xl-dark);
+    --sigvelo-elevation-hairline: var(--sigvelo-elevation-hairline-dark);
+    --sigvelo-elevation-raised: var(--sigvelo-elevation-raised-dark);
+    --sigvelo-elevation-floating: var(--sigvelo-elevation-floating-dark);
+    --sigvelo-elevation-overlay: var(--sigvelo-elevation-overlay-dark);
     --sigvelo-color-primary-bg-subtle: var(--sigvelo-color-primary-bg-subtle-dark);
     --sigvelo-color-primary-bg-muted: var(--sigvelo-color-primary-bg-muted-dark);
     --sigvelo-color-primary-bg: var(--sigvelo-color-primary-bg-dark);
@@ -179,25 +177,24 @@
 [data-theme="light"] {
   color-scheme: light;
   --sigvelo-color-canvas: var(--sigvelo-color-canvas-light);
+  --sigvelo-color-surface-under: var(--sigvelo-color-surface-under-light);
   --sigvelo-color-surface: var(--sigvelo-color-surface-light);
+  --sigvelo-color-surface-raised: var(--sigvelo-color-surface-raised-light);
+  --sigvelo-color-surface-sunken: var(--sigvelo-color-surface-sunken-light);
+  --sigvelo-color-surface-glass: var(--sigvelo-color-surface-glass-light);
   --sigvelo-color-text: var(--sigvelo-color-text-light);
   --sigvelo-color-text-muted: var(--sigvelo-color-text-muted-light);
+  --sigvelo-color-text-subtle: var(--sigvelo-color-text-subtle-light);
+  --sigvelo-color-text-faint: var(--sigvelo-color-text-faint-light);
   --sigvelo-color-focus: var(--sigvelo-color-focus-light);
   --sigvelo-focus-ring: var(--sigvelo-focus-ring-light);
   --sigvelo-color-backdrop: var(--sigvelo-color-backdrop-light);
   --sigvelo-color-selection-bg: var(--sigvelo-color-selection-bg-light);
   --sigvelo-color-selection-text: var(--sigvelo-color-selection-text-light);
-  --sigvelo-color-shadow: var(--sigvelo-color-shadow-light);
-  --sigvelo-shadow-xs: var(--sigvelo-shadow-xs-light);
-  --sigvelo-shadow-sm: var(--sigvelo-shadow-sm-light);
-  --sigvelo-shadow-md: var(--sigvelo-shadow-md-light);
-  --sigvelo-shadow-lg: var(--sigvelo-shadow-lg-light);
-  --sigvelo-shadow-xl: var(--sigvelo-shadow-xl-light);
-  --sigvelo-inset-shadow-xs: var(--sigvelo-inset-shadow-xs-light);
-  --sigvelo-inset-shadow-sm: var(--sigvelo-inset-shadow-sm-light);
-  --sigvelo-inset-shadow-md: var(--sigvelo-inset-shadow-md-light);
-  --sigvelo-inset-shadow-lg: var(--sigvelo-inset-shadow-lg-light);
-  --sigvelo-inset-shadow-xl: var(--sigvelo-inset-shadow-xl-light);
+  --sigvelo-elevation-hairline: var(--sigvelo-elevation-hairline-light);
+  --sigvelo-elevation-raised: var(--sigvelo-elevation-raised-light);
+  --sigvelo-elevation-floating: var(--sigvelo-elevation-floating-light);
+  --sigvelo-elevation-overlay: var(--sigvelo-elevation-overlay-light);
   --sigvelo-color-primary-bg-subtle: var(--sigvelo-color-primary-bg-subtle-light);
   --sigvelo-color-primary-bg-muted: var(--sigvelo-color-primary-bg-muted-light);
   --sigvelo-color-primary-bg: var(--sigvelo-color-primary-bg-light);
@@ -264,25 +261,24 @@
 [data-theme="dark"] {
   color-scheme: dark;
   --sigvelo-color-canvas: var(--sigvelo-color-canvas-dark);
+  --sigvelo-color-surface-under: var(--sigvelo-color-surface-under-dark);
   --sigvelo-color-surface: var(--sigvelo-color-surface-dark);
+  --sigvelo-color-surface-raised: var(--sigvelo-color-surface-raised-dark);
+  --sigvelo-color-surface-sunken: var(--sigvelo-color-surface-sunken-dark);
+  --sigvelo-color-surface-glass: var(--sigvelo-color-surface-glass-dark);
   --sigvelo-color-text: var(--sigvelo-color-text-dark);
   --sigvelo-color-text-muted: var(--sigvelo-color-text-muted-dark);
+  --sigvelo-color-text-subtle: var(--sigvelo-color-text-subtle-dark);
+  --sigvelo-color-text-faint: var(--sigvelo-color-text-faint-dark);
   --sigvelo-color-focus: var(--sigvelo-color-focus-dark);
   --sigvelo-focus-ring: var(--sigvelo-focus-ring-dark);
   --sigvelo-color-backdrop: var(--sigvelo-color-backdrop-dark);
   --sigvelo-color-selection-bg: var(--sigvelo-color-selection-bg-dark);
   --sigvelo-color-selection-text: var(--sigvelo-color-selection-text-dark);
-  --sigvelo-color-shadow: var(--sigvelo-color-shadow-dark);
-  --sigvelo-shadow-xs: var(--sigvelo-shadow-xs-dark);
-  --sigvelo-shadow-sm: var(--sigvelo-shadow-sm-dark);
-  --sigvelo-shadow-md: var(--sigvelo-shadow-md-dark);
-  --sigvelo-shadow-lg: var(--sigvelo-shadow-lg-dark);
-  --sigvelo-shadow-xl: var(--sigvelo-shadow-xl-dark);
-  --sigvelo-inset-shadow-xs: var(--sigvelo-inset-shadow-xs-dark);
-  --sigvelo-inset-shadow-sm: var(--sigvelo-inset-shadow-sm-dark);
-  --sigvelo-inset-shadow-md: var(--sigvelo-inset-shadow-md-dark);
-  --sigvelo-inset-shadow-lg: var(--sigvelo-inset-shadow-lg-dark);
-  --sigvelo-inset-shadow-xl: var(--sigvelo-inset-shadow-xl-dark);
+  --sigvelo-elevation-hairline: var(--sigvelo-elevation-hairline-dark);
+  --sigvelo-elevation-raised: var(--sigvelo-elevation-raised-dark);
+  --sigvelo-elevation-floating: var(--sigvelo-elevation-floating-dark);
+  --sigvelo-elevation-overlay: var(--sigvelo-elevation-overlay-dark);
   --sigvelo-color-primary-bg-subtle: var(--sigvelo-color-primary-bg-subtle-dark);
   --sigvelo-color-primary-bg-muted: var(--sigvelo-color-primary-bg-muted-dark);
   --sigvelo-color-primary-bg: var(--sigvelo-color-primary-bg-dark);
@@ -355,10 +351,26 @@
       var(--sigvelo-color-canvas-light),
       var(--sigvelo-color-canvas-dark)
     );
+    --sigvelo-color-surface-under: light-dark(
+      var(--sigvelo-color-surface-under-light),
+      var(--sigvelo-color-surface-under-dark)
+    );
     --sigvelo-color-surface: light-dark(
       var(--sigvelo-color-surface-light),
       var(--sigvelo-color-surface-dark)
     );
+    --sigvelo-color-surface-raised: light-dark(
+      var(--sigvelo-color-surface-raised-light),
+      var(--sigvelo-color-surface-raised-dark)
+    );
+    --sigvelo-color-surface-sunken: light-dark(
+      var(--sigvelo-color-surface-sunken-light),
+      var(--sigvelo-color-surface-sunken-dark)
+    );
+    --sigvelo-color-surface-glass: light-dark(
+      var(--sigvelo-color-surface-glass-light),
+      var(--sigvelo-color-surface-glass-dark)
+    );
     --sigvelo-color-text: light-dark(
       var(--sigvelo-color-text-light),
       var(--sigvelo-color-text-dark)
@@ -367,6 +379,14 @@
       var(--sigvelo-color-text-muted-light),
       var(--sigvelo-color-text-muted-dark)
     );
+    --sigvelo-color-text-subtle: light-dark(
+      var(--sigvelo-color-text-subtle-light),
+      var(--sigvelo-color-text-subtle-dark)
+    );
+    --sigvelo-color-text-faint: light-dark(
+      var(--sigvelo-color-text-faint-light),
+      var(--sigvelo-color-text-faint-dark)
+    );
     --sigvelo-color-focus: light-dark(
       var(--sigvelo-color-focus-light),
       var(--sigvelo-color-focus-dark)
@@ -383,10 +403,6 @@
       var(--sigvelo-color-selection-text-light),
       var(--sigvelo-color-selection-text-dark)
     );
-    --sigvelo-color-shadow: light-dark(
-      var(--sigvelo-color-shadow-light),
-      var(--sigvelo-color-shadow-dark)
-    );
     --sigvelo-color-primary-bg-subtle: light-dark(
       var(--sigvelo-color-primary-bg-subtle-light),
       var(--sigvelo-color-primary-bg-subtle-dark)

package/src/typography.css

@@ -3,12 +3,30 @@
  */
 
 :root {
-  --sigvelo-font-sans: system-ui, sans-serif;
+  --sigvelo-font-sans:
+    -apple-system-body, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica,
+    Arial, sans-serif;
   --sigvelo-font-heading: var(--sigvelo-font-sans);
   --sigvelo-font-mono:
     SFMono-Regular, Consolas, Menlo, Monaco, "liberation mono", "Courier New", monospace;
   --sigvelo-text-root: 16px;
 
+  /*
+   * Reading roles. Interface chrome, the assistant's prose, and the user's own
+   * words are three different reading tasks, and products routinely want them
+   * set differently — a serif response against a sans UI is the common one.
+   * All three resolve to the sans face until a consumer says otherwise, so
+   * nothing changes by default.
+   */
+  --sigvelo-font-ui: var(--sigvelo-font-sans);
+  --sigvelo-font-response: var(--sigvelo-font-sans);
+  --sigvelo-font-user-message: var(--sigvelo-font-sans);
+
+  /* Named so [data-font="dyslexic"] has something to point at. The face is not
+     bundled; a consumer that wants it self-hosts OpenDyslexic and the stack
+     falls through to a wide-spaced serif everywhere else. */
+  --sigvelo-font-dyslexic: "OpenDyslexic", "Comic Sans MS", Georgia, serif;
+
   /* Type scale */
   --sigvelo-text-3xs: 0.625rem;
   --sigvelo-text-2xs: 0.6875rem;
@@ -19,7 +37,7 @@
   --sigvelo-text-lg: 1.125rem;
   --sigvelo-text-xl: 1.25rem;
   --sigvelo-text-2xl: 1.5rem;
-  --sigvelo-text-3xl: 1.875rem;
+  --sigvelo-text-3xl: 1.75rem;
   --sigvelo-text-4xl: 2.25rem;
   --sigvelo-text-5xl: 3rem;
 
@@ -35,8 +53,15 @@
   --sigvelo-font-weight-semibold: 500;
   --sigvelo-font-weight-bold: 700;
 
-  /* Line heights */
-  --sigvelo-leading-body: 1.6;
+  /*
+   * Line heights.
+   *
+   * The ratio scale below is for prose, where leading should grow with the
+   * reader's font size. For interface text, prefer the paired absolutes
+   * further down: they are quantized to whole pixels, so a stack of labels,
+   * rows, and icons lands on the same rhythm the spacing scale uses instead of
+   * accumulating fractional drift.
+   */
   --sigvelo-leading-none: 1;
   --sigvelo-leading-tight: 1.2;
   --sigvelo-leading-compact: 1.25;
@@ -45,8 +70,62 @@
   --sigvelo-leading-relaxed: 1.625;
   --sigvelo-leading-loose: 2;
 
-  /* Letter spacing */
+  /*
+   * One leading per type step. Setting a size and its partner keeps every
+   * label of that size on the same baseline rhythm without anyone choosing a
+   * ratio by eye. Small text takes a proportionally tighter measure and large
+   * text a looser one, which is why these are not one multiplier.
+   */
+  --sigvelo-text-3xs-leading: 0.875rem; /* 14px */
+  --sigvelo-text-2xs-leading: 1rem; /* 16px */
+  --sigvelo-text-xs-leading: 1rem; /* 16px */
+  --sigvelo-text-compact-leading: 1.125rem; /* 18px */
+  --sigvelo-text-sm-leading: 1.25rem; /* 20px */
+  --sigvelo-text-base-leading: 1.5rem; /* 24px */
+  --sigvelo-text-lg-leading: 1.75rem; /* 28px */
+  --sigvelo-text-xl-leading: 1.75rem; /* 28px */
+  --sigvelo-text-2xl-leading: 2rem; /* 32px */
+  --sigvelo-text-3xl-leading: 2.25rem; /* 36px */
+  --sigvelo-text-4xl-leading: 2.5rem; /* 40px */
+  --sigvelo-text-5xl-leading: 3rem; /* 48px */
+
+  /* Letter spacing. Large type set at the default tracking looks loose, so
+     display headings tighten as they grow. */
+  --sigvelo-tracking-tighter: -0.03em;
+  --sigvelo-tracking-tight: -0.015em;
   --sigvelo-tracking-normal: 0;
   --sigvelo-tracking-wide: 0.025em;
   --sigvelo-tracking-wider: 0.05em;
+
+  /*
+   * Measure. Line length is the readability control with the most evidence
+   * behind it and the one nothing in the system could express, so long-form
+   * agent output ran the full width of whatever panel it landed in. Character
+   * units, not rem: the comfortable measure is a count of characters, and it
+   * should follow the reader's font size rather than fight it.
+   */
+  --sigvelo-measure-prose: 68ch;
+  /* Code, tables, and diagrams read worse when wrapped than when wide. */
+  --sigvelo-measure-wide-block: 100ch;
+
+  /*
+   * Reader text scale. Applied by .sigvelo-reader-text to prose only, never to
+   * chrome: a reader who wants larger message text is not asking for taller
+   * toolbars, and scaling both is how a side panel runs out of room. Controls
+   * keep resolving through the rem type ramp.
+   */
+  --sigvelo-chat-font-scale: 1;
+}
+
+/*
+ * Opt-in dyslexia-friendly face. Set on :root for the whole document or on any
+ * subtree. Only the reading roles change — mono stays mono, because a
+ * proportional face makes code worse for everyone.
+ */
+:root[data-font="dyslexic"],
+[data-font="dyslexic"] {
+  --sigvelo-font-ui: var(--sigvelo-font-dyslexic);
+  --sigvelo-font-response: var(--sigvelo-font-dyslexic);
+  --sigvelo-font-user-message: var(--sigvelo-font-dyslexic);
+  --sigvelo-font-heading: var(--sigvelo-font-dyslexic);
 }