@nebutra/design-tokens 0.1.2 → 2.0.0

package/README.md

@@ -127,7 +127,7 @@ The 70% parity floor is enforced; below it, the script exits non-zero.
 1. **Display-P3 wide-gamut overrides** — the legacy SSOT defines `--nebutra-brand-blue` / `--nebutra-brand-cyan` aliases inside `@supports (color: color(display-p3 ...))`. Those are not yet modeled in DTCG; today the generated values are the sRGB hex fallback. Next step: add a P3 wide-gamut variant in `core.json` and emit it under a SD `mediaQuery` wrapper.
 2. **`oklch()` overrides for `--ds-gray-*`** — the legacy file ships sRGB `hsla()` baseline values and overrides them under `@supports (color: oklch(...))`. The generated CSS currently keeps only the sRGB fallback. Next step: add a separate `themes/ds-gray-oklch.json` and a SD format that wraps it in the `@supports` block.
 3. **Compound shorthand tokens not yet emitted**:
-   - `--transition` (combines `--transition-duration` + `--transition-easing`)
+   - `--transition` (emitted today as a hardcoded `150ms ease-out` literal in `buildExtras()`; the `--transition-duration` / `--transition-easing` component tokens were removed from `semantic.json` — they had zero consumers)
    - `--focus-ring` (compound box-shadow recipe)
    These can be modeled as DTCG `composite` tokens; deferred to follow-up.
 4. **`--brand-primary` / `--brand-accent` in `.dark` mode** — the legacy SSOT keeps these mapped to the sRGB primitives, but in dark mode the visual brand is `var(--blue-9)` which itself maps to `--nebutra-blue-400`. Today the DTCG model resolves to the *core* primitive (always blue-500/cyan-500). Next step: add per-mode brand alias overrides in the dark theme file.

package/build/css/dark.css

@@ -52,23 +52,24 @@
   --breakpoint-tight: 67.5rem; /** 1080px — dense dashboard header horizontal */
   --breakpoint-shell: 73.75rem; /** 1180px — three-pane shell threshold */
   --breakpoint-3xl: 112.5rem; /** 1800px — 4K / Studio Display friendliness */
-  --radius-none: 0;
-  --radius-sm: 0.25rem;
-  --radius-md: 0.375rem;
-  --radius-lg: 0.5rem;
-  --radius-xl: 0.75rem;
-  --radius-2xl: 1rem;
-  --radius-3xl: 1.5rem;
-  --radius-full: 9999px;
-  --radius-button: 0.5rem; /** 2026 button radius — Vercel/Linear/Cursor consensus */
-  --radius-card: 0.75rem; /** 2026 card radius */
-  --radius-panel: 1rem; /** 2026 bento/hero panel radius */
+  --radius-none: 0; /** Job: flush. Edge-to-edge surfaces — a full-bleed table row, a segment welded to its neighbour, an inset that must not round twice. */
+  --radius-xs: 0.125rem; /** Job: swatch. The smallest corner that still reads as intentional at 8-12px: chart legend keys, mark highlights, progress and sparkline bar caps. Added because 18 call sites had hand-written 1px, 2px and 3px corners with no step to reach for. Matches the bottom of the Tailwind scale, so rounded-xs and var(--radius-xs) agree. */
+  --radius-sm: 0.25rem; /** Job: inner. The corner of something nested inside a control — a thumbnail inside a chip, a swatch inside a tile, a code span inside a paragraph. One step inside md. */
+  --radius-md: 0.375rem; /** Job: control. The default for anything you can click or type into at text height: input, select trigger, small button, menu item, badge with square corners. The most-used step on the ladder. */
+  --radius-lg: 0.5rem; /** Job: container. Things that hold controls rather than being one: popover, dropdown surface, tooltip, toolbar, inline code block. Aliased as radius-button. */
+  --radius-xl: 0.75rem; /** Job: card. A discrete surface in a list or grid that carries its own padding and elevation. Aliased as radius-card. */
+  --radius-2xl: 1rem; /** Job: panel. A region that holds cards — bento cell, dialog, sheet, dashboard section. Aliased as radius-panel. */
+  --radius-3xl: 1.5rem; /** Job: frame. The outermost shell of a marketing or docs composition — mockup window, hero frame, screenshot chrome. The top of the ladder. */
+  --radius-full: 9999px; /** Job: pill. Fully round by intent, not by size: avatar, dot, toggle track, tag. Kept as one step, not a pair, so there is exactly one way to say round. */
+  --radius-button: 0.5rem; /** Intent alias for the container step. Reach for this in product code instead of lg so the shape can be re-tuned in one place. */
+  --radius-card: 0.75rem; /** Intent alias for the card step. Reach for this in product code instead of xl. */
+  --radius-panel: 1rem; /** Intent alias for the panel step. Reach for this in product code instead of 2xl. */
   --duration-micro: 100ms; /** Micro-feedback: hover, focus, toggle, button press */
   --duration-flow: 200ms; /** State flow: modal open, dropdown reveal, tab switch, default page transition */
   --duration-reveal: 300ms; /** Content unveil: slide-in, expand, accordion, drawer */
   --duration-cinematic: 500ms; /** Hero-grade entrance: landing reveal, large delight moments */
   --ease-in: cubic-bezier(0.4, 0, 1, 1);
-  --ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
   --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
   --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
   --tracking-display: -0.04em; /** Hero H1 */
@@ -78,15 +79,13 @@
   --leading-heading: 1.15;
   --ring-hairline: inset 0 0 0 1px rgb(255 255 255 / 0.06); /** Hairline override — more visible on dark background */
   --overlay-faint: rgb(255 255 255 / 0.06); /** Dark-mode faint overlay (6% white) — inverted from light */
-  --font-sans: var(--font-geist-sans), "Geist", "Noto Sans SC", "PingFang SC", "Microsoft YaHei", -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
-  --font-cn: "Noto Sans SC", "PingFang SC", "Microsoft YaHei", "vivo Sans", sans-serif;
-  --font-display: var(--font-geist-sans), "Geist", "Noto Sans SC", sans-serif;
-  --font-heading: var(--font-geist-sans), "Geist", "Noto Sans SC", sans-serif;
+  --font-sans: var(--font-geist-sans), "Geist", var(--font-noto-sans-sc, "Noto Sans SC"), "PingFang SC", "Microsoft YaHei", -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+  --font-cn: var(--font-geist-sans), "Geist", var(--font-noto-sans-sc, "Noto Sans SC"), "PingFang SC", "Microsoft YaHei", sans-serif; /** CJK-locale stack — same order as sans, minus the Latin-only system faces */
+  --font-display: var(--font-geist-sans), "Geist", var(--font-noto-sans-sc, "Noto Sans SC"), sans-serif;
+  --font-heading: var(--font-geist-sans), "Geist", var(--font-noto-sans-sc, "Noto Sans SC"), sans-serif;
   --font-mono: var(--font-geist-mono), "Geist Mono", ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
-  --transition-duration: 200ms; /** Default transition duration — 200ms flow rail. */
-  --transition-easing: ease-out; /** ease-out keyword form (CSS-friendly). Equivalent to cubic-bezier(0,0,0.2,1). */
-  --brand-primary: #5c7cfa; /** Dark-mode brand primary — visible against dark surfaces (uses --blue-9 = nebutra-blue-400). */
-  --brand-accent: #1af7c8; /** Dark-mode brand accent — visible against dark surfaces (uses --cyan-9 = nebutra-cyan-400). */
+  --brand-primary: #5c7cfa; /** Dark-mode brand primary — the identity blue lifted to nebutra-blue-400 so it stays visible on dark surfaces. This is the identity alias, not the functional fill: the dark solid fill is --blue-9 (#396ae2, white label 4.85:1). The two are deliberately separate now that the VI hex is no longer pinned into ramp slot 9. */
+  --brand-accent: #1af7c8; /** Dark-mode brand accent — nebutra-cyan-400 (L* 87.1). The functional bright fill is --cyan-9 (#0bf1c3, L* 85.41), the same hex in both modes; dark ink for it is --cyan-contrast at 10.35:1. */
   --brand-tertiary: #8b5cf6;
   --brand-gradient-start: hsl(var(--primary)); /** Legacy alias of --primary (shadcn product blue). Prefer bg-primary / Button default. */
   --brand-gradient-end: hsl(var(--primary)); /** Legacy alias of --primary. Prefer hover:bg-primary/90. */
@@ -114,45 +113,47 @@
   --neutral-3: #1e293b;
   --neutral-4: #334155;
   --neutral-5: #475569;
-  --neutral-6: #171717;
-  --neutral-7: #262626;
-  --neutral-8: #404040;
+  --neutral-6: #666666; /** subtle border — DERIVED: OKLab lerp step5 → step9 at t=0.25, chroma forced to 0. The achromatic result is deliberate and preserves the documented intent of color.nebutra-gray ('used where blue undertone clashes — primarily dark-mode borders, dividers, elevation hairlines'). What was broken was the LIGHTNESS: gray-900/800/700 are darker than the slate background tier they sit above, so the border read as a hole rather than a hairline. */
+  --neutral-7: #7a7a7a; /** default border — DERIVED: OKLab lerp step5 → step9 at t=0.50, chroma 0. */
+  --neutral-8: #8d8d8d; /** hovered border — DERIVED: OKLab lerp step5 → step9 at t=0.75, chroma 0. */
   --neutral-9: #94a3b8;
   --neutral-10: #cbd5e1;
   --neutral-11: #e2e8f0;
   --neutral-12: #f8fafc;
-  --blue-1: #000830;
-  --blue-2: #000f59;
-  --blue-3: #001882;
-  --blue-4: #0021ab;
-  --blue-5: #002ad4;
-  --blue-6: #001882;
-  --blue-7: #0021ab;
-  --blue-8: #002ad4;
-  --blue-9: #5c7cfa;
-  --blue-10: #91a7ff;
-  --blue-11: #bac8ff;
-  --blue-12: #dbe4ff;
-  --cyan-1: #012923;
-  --cyan-2: #035143;
-  --cyan-3: #057963;
-  --cyan-4: #07a183;
-  --cyan-5: #09c9a3;
-  --cyan-6: #057963;
-  --cyan-7: #07a183;
-  --cyan-8: #09c9a3;
-  --cyan-9: #1af7c8;
-  --cyan-10: #4dfcd4;
-  --cyan-11: #80ffe0;
-  --cyan-12: #b3ffec;
+  --blue-1: #030815; /** app tint — L* 13.59, C 0.031, hue 264. */
+  --blue-2: #060f25; /** subtle background — L* 17.43, C 0.048. */
+  --blue-3: #09183b; /** component background default — L* 22.04, C 0.071. */
+  --blue-4: #0d2254; /** component background hover — L* 26.99, C 0.095. */
+  --blue-5: #132e6f; /** component background active — L* 32.46, C 0.118. Anchor for the derived border tier. */
+  --blue-6: #1c3c8a; /** subtle border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step9 (deep scale, span 23.5 L*) at t=0.25. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 38.25, C 0.136. */
+  --blue-7: #254ba7; /** default border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step9 (deep scale, span 23.5 L*) at t=0.50. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 44.21, C 0.155. */
+  --blue-8: #2f5ac4; /** hovered border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step9 (deep scale, span 23.5 L*) at t=0.75. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 50.01, C 0.173. */
+  --blue-9: #396ae2; /** solid fill — L* 55.92, C 0.191, hue 264.3. White label 4.85:1. Same value as the dark shadcn --primary, so light and dark both take their deep fill from one source. Chroma ceiling for dark is 0.190; this is 0.191. */
+  --blue-10: #3f70e3; /** solid fill hover — L* 57.44, C 0.183. White label 4.53:1. The hover has to move UP in a dark ramp, which costs contrast, so the step is deliberately small (1.52 L*) to keep white above 4.5:1. */
+  --blue-11: #89aaee; /** secondary text — L* 74.01, C 0.106. 8.62:1 on step 1. */
+  --blue-12: #d2e0fd; /** primary text — L* 90.52, C 0.043. 15.08:1 on step 1. */
+  --blue-contrast: #ffffff; /** Label ink for the solid fill tier. Absolute value, identical in both modes. 4.85:1 on step 9, 4.53:1 on step 10. */
+  --cyan-1: #04100c; /** app tint — L* 15.90, C 0.021, hue 172. */
+  --cyan-2: #091e18; /** subtle background — L* 21.54, C 0.030. */
+  --cyan-3: #0f2e25; /** component background default — L* 27.46, C 0.041. */
+  --cyan-4: #1c4035; /** component background hover — L* 34.10, C 0.046. */
+  --cyan-5: #2b5347; /** component background active — L* 40.88, C 0.050. Anchor for the derived border tier. */
+  --cyan-6: #307864; /** subtle border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step9 (span 44.5 L*) at t=0.25. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 52.12, C 0.079. */
+  --cyan-7: #309e82; /** default border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step9 (span 44.5 L*) at t=0.50. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 63.04, C 0.107. */
+  --cyan-8: #28c7a2; /** hovered border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step9 (span 44.5 L*) at t=0.75. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 74.30, C 0.136. */
+  --cyan-9: #0bf1c3; /** solid fill — same bright value as light mode, the way Radix ships one hex for mint-9 in both modes: L* 85.41, C 0.164. Ink 10.35:1 against --cyan-contrast. */
+  --cyan-10: #5af8ce; /** solid fill hover — L* 88.53, C 0.145, 3.12 L* above step 9 (Radix mint dark moves up 4.60 L*). Ink 11.34:1. */
+  --cyan-11: #90fbdb; /** secondary text — L* 91.46, C 0.110. 15.68:1 on step 1. */
+  --cyan-12: #bdfde8; /** primary text — L* 94.54, C 0.070. 16.95:1 on step 1. */
+  --cyan-contrast: #0d2b25; /** Label ink for the bright fill tier. Absolute near-black, identical in both modes. 10.35:1 on step 9, 11.34:1 on step 10. */
   --background: 222 14% 9%;
   --foreground: 210 18% 96%;
   --card: 222 12% 13%;
   --card-foreground: 210 18% 96%;
   --popover: 222 12% 13%;
   --popover-foreground: 210 18% 96%;
-  --primary: 228 90% 72%;
-  --primary-foreground: 222 14% 9%;
+  --primary: 222.6 74.4% 55.5%; /** Dark-mode action blue, paired with the near-black --primary-foreground, not white. #396ae2 keeps the VI hue and sits at L*55.9 C0.191. */
+  --primary-foreground: 0 0% 100%; /** White, matching light mode and matching --blue-contrast. It was near-black (222 14% 9%) when --primary was a LIGHT fill at L* 68.3, where dark ink read 6.20:1. Once --primary became a deep fill at L* 55.9 the pairing inverted and measured 3.74:1, below AA — the fill moved and the ink did not. The deep-fill tier takes white in both modes; --blue-contrast says the same thing, and they must agree because --primary and --blue-9 are now the same value. */
   --secondary: 222 10% 18%;
   --secondary-foreground: 210 18% 96%;
   --muted: 222 10% 17%;
@@ -161,10 +162,13 @@
   --accent-foreground: 228 95% 80%;
   --destructive: 0 63% 38%;
   --destructive-foreground: 210 18% 96%;
+  --destructive-strong: 0 80% 66%; /** Red as FOREGROUND on a dark surface. --destructive (0 63% 38%) is 2.15:1 on --card here — a fill only. Lightened to 5.18:1 on --card / 5.61:1 on --neutral-1, which sits alongside the light-mode 5.42:1 so red reads with the same weight in both themes. Use --destructive for fills with --destructive-foreground on top; use this for red text and icons. */
   --success: 142 60% 42%;
   --success-foreground: 222 14% 9%;
+  --success-strong: 142 60% 42%; /** Green as foreground on a dark surface. Needs no adjustment — 142 60% 42% is already 4.83:1 as ink on its own 10% tint — so it deliberately equals --success, matching how --warning-strong behaves in this theme. */
   --warning: 38 80% 52%;
   --warning-foreground: 222 14% 9%;
+  --warning-strong: 38 80% 52%; /** Amber as foreground on a dark surface. Unlike light mode this needs no adjustment — 38 80% 52% is already 7.98:1 against --neutral-1 — so it deliberately equals --warning. The token exists in both themes so consumers can reference one name. */
   --info: 228 95% 72%;
   --info-foreground: 222 14% 9%;
   --border: 220 8% 22%;
@@ -223,6 +227,18 @@
   --elevation-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.8);
   --elevation-brand: 0 0 0 1px rgb(92 124 250 / 0.25), 0 4px 20px -2px rgb(92 124 250 / 0.3);
   --elevation-brand-lg: 0 0 0 1px rgb(92 124 250 / 0.3), 0 8px 40px -4px rgb(92 124 250 / 0.4);
+  --elevation-ambient-sm: 0 1px 2px -1px rgb(0 0 0 / 0.4), 0 6px 16px -6px rgb(0 0 0 / 0.5); /** Ambient elevation, small. Contact layer plus a wide soft pool — the marketing-surface counterpart to the tight xs..2xl product ramp. */
+  --elevation-ambient-md: 0 2px 4px -2px rgb(0 0 0 / 0.4), 0 12px 32px -10px rgb(0 0 0 / 0.55); /** Ambient elevation, medium. Default resting depth for a floating marketing card. */
+  --elevation-ambient-lg: 0 4px 8px -4px rgb(0 0 0 / 0.4), 0 24px 56px -18px rgb(0 0 0 / 0.6); /** Ambient elevation, large. One step up from md; use for hover of a md surface, not as a resting default. */
+  --elevation-glass-sm: inset 0 1px 0 rgb(255 255 255 / 0.08), 0 1px 2px -1px rgb(0 0 0 / 0.4), 0 6px 16px -6px rgb(0 0 0 / 0.5); /** Ambient-sm plus a lit top edge, for translucent panels over a blurred backdrop. */
+  --elevation-glass-md: inset 0 1px 0 rgb(255 255 255 / 0.08), 0 2px 4px -2px rgb(0 0 0 / 0.4), 0 12px 32px -10px rgb(0 0 0 / 0.55); /** Ambient-md plus a lit top edge. */
+  --elevation-glass-lg: inset 0 1px 0 rgb(255 255 255 / 0.08), 0 4px 8px -4px rgb(0 0 0 / 0.4), 0 24px 56px -18px rgb(0 0 0 / 0.6); /** Ambient-lg plus a lit top edge. */
+  --elevation-sheen: inset 0 1px 0 rgb(0 0 0 / 0.12); /** Top-edge sheen for solid inverted fills (bg-foreground). Lifts with light on a dark fill, with shade on a light one. */
+  --elevation-ambient-glow: 0 0 80px rgb(255 255 255 / 0.06); /** Centred offsetless halo — the only non-directional step on the ramp. Inverted from the light value: a black halo has nothing to darken against a dark surround, so the halo becomes light. Keep the alpha low; this is separation, not a bloom. */
+  --elevation-glow-accent: 0 8px 32px rgb(0 0 0 / 0.4), 0 0 60px color-mix(in srgb, var(--brand-accent) 8%, transparent); /** Identical to the light value by design. The pool is theme-invariant black because glow-accent surfaces are fixed dark glass in both themes; only the accent halo shifts, via --brand-accent. */
+  --elevation-glow-accent-lg: 0 12px 48px rgb(0 0 0 / 0.5), 0 0 80px color-mix(in srgb, var(--brand-accent) 12%, transparent); /** Hover escalation of glow-accent. Identical to the light value by design. */
+  --elevation-glow-accent-sm: 0 0 20px color-mix(in srgb, var(--brand-accent) 10%, transparent); /** Accent halo alone, no pool. Identical to the light value by design. */
+  --elevation-glow-primary: 0 20px 25px -5px hsl(var(--primary) / 0.05), 0 8px 10px -6px hsl(var(--primary) / 0.05); /** xl geometry tinted with the action fill at 5 percent. Same reference as light; --primary carries the dark channels. */
 }
 
 .dark {

package/build/css/light.css

@@ -52,23 +52,24 @@
   --breakpoint-tight: 67.5rem; /** 1080px — dense dashboard header horizontal */
   --breakpoint-shell: 73.75rem; /** 1180px — three-pane shell threshold */
   --breakpoint-3xl: 112.5rem; /** 1800px — 4K / Studio Display friendliness */
-  --radius-none: 0;
-  --radius-sm: 0.25rem;
-  --radius-md: 0.375rem;
-  --radius-lg: 0.5rem;
-  --radius-xl: 0.75rem;
-  --radius-2xl: 1rem;
-  --radius-3xl: 1.5rem;
-  --radius-full: 9999px;
-  --radius-button: 0.5rem; /** 2026 button radius — Vercel/Linear/Cursor consensus */
-  --radius-card: 0.75rem; /** 2026 card radius */
-  --radius-panel: 1rem; /** 2026 bento/hero panel radius */
+  --radius-none: 0; /** Job: flush. Edge-to-edge surfaces — a full-bleed table row, a segment welded to its neighbour, an inset that must not round twice. */
+  --radius-xs: 0.125rem; /** Job: swatch. The smallest corner that still reads as intentional at 8-12px: chart legend keys, mark highlights, progress and sparkline bar caps. Added because 18 call sites had hand-written 1px, 2px and 3px corners with no step to reach for. Matches the bottom of the Tailwind scale, so rounded-xs and var(--radius-xs) agree. */
+  --radius-sm: 0.25rem; /** Job: inner. The corner of something nested inside a control — a thumbnail inside a chip, a swatch inside a tile, a code span inside a paragraph. One step inside md. */
+  --radius-md: 0.375rem; /** Job: control. The default for anything you can click or type into at text height: input, select trigger, small button, menu item, badge with square corners. The most-used step on the ladder. */
+  --radius-lg: 0.5rem; /** Job: container. Things that hold controls rather than being one: popover, dropdown surface, tooltip, toolbar, inline code block. Aliased as radius-button. */
+  --radius-xl: 0.75rem; /** Job: card. A discrete surface in a list or grid that carries its own padding and elevation. Aliased as radius-card. */
+  --radius-2xl: 1rem; /** Job: panel. A region that holds cards — bento cell, dialog, sheet, dashboard section. Aliased as radius-panel. */
+  --radius-3xl: 1.5rem; /** Job: frame. The outermost shell of a marketing or docs composition — mockup window, hero frame, screenshot chrome. The top of the ladder. */
+  --radius-full: 9999px; /** Job: pill. Fully round by intent, not by size: avatar, dot, toggle track, tag. Kept as one step, not a pair, so there is exactly one way to say round. */
+  --radius-button: 0.5rem; /** Intent alias for the container step. Reach for this in product code instead of lg so the shape can be re-tuned in one place. */
+  --radius-card: 0.75rem; /** Intent alias for the card step. Reach for this in product code instead of xl. */
+  --radius-panel: 1rem; /** Intent alias for the panel step. Reach for this in product code instead of 2xl. */
   --duration-micro: 100ms; /** Micro-feedback: hover, focus, toggle, button press */
   --duration-flow: 200ms; /** State flow: modal open, dropdown reveal, tab switch, default page transition */
   --duration-reveal: 300ms; /** Content unveil: slide-in, expand, accordion, drawer */
   --duration-cinematic: 500ms; /** Hero-grade entrance: landing reveal, large delight moments */
   --ease-in: cubic-bezier(0.4, 0, 1, 1);
-  --ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
   --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
   --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
   --tracking-display: -0.04em; /** Hero H1 */
@@ -78,13 +79,11 @@
   --leading-heading: 1.15;
   --ring-hairline: inset 0 0 0 1px rgb(255 255 255 / 0.04); /** Etched-glass hairline (light mode value, dark mode override in themes/dark.json) */
   --overlay-faint: rgb(0 0 0 / 0.06); /** Light-mode faint overlay (6% black) */
-  --font-sans: var(--font-geist-sans), "Geist", "Noto Sans SC", "PingFang SC", "Microsoft YaHei", -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
-  --font-cn: "Noto Sans SC", "PingFang SC", "Microsoft YaHei", "vivo Sans", sans-serif;
-  --font-display: var(--font-geist-sans), "Geist", "Noto Sans SC", sans-serif;
-  --font-heading: var(--font-geist-sans), "Geist", "Noto Sans SC", sans-serif;
+  --font-sans: var(--font-geist-sans), "Geist", var(--font-noto-sans-sc, "Noto Sans SC"), "PingFang SC", "Microsoft YaHei", -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+  --font-cn: var(--font-geist-sans), "Geist", var(--font-noto-sans-sc, "Noto Sans SC"), "PingFang SC", "Microsoft YaHei", sans-serif; /** CJK-locale stack — same order as sans, minus the Latin-only system faces */
+  --font-display: var(--font-geist-sans), "Geist", var(--font-noto-sans-sc, "Noto Sans SC"), sans-serif;
+  --font-heading: var(--font-geist-sans), "Geist", var(--font-noto-sans-sc, "Noto Sans SC"), sans-serif;
   --font-mono: var(--font-geist-mono), "Geist Mono", ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
-  --transition-duration: 200ms; /** Default transition duration — 200ms flow rail. */
-  --transition-easing: ease-out; /** ease-out keyword form (CSS-friendly). Equivalent to cubic-bezier(0,0,0.2,1). */
   --brand-primary: #0033fe; /** Brand primary — 云毓蓝 */
   --brand-accent: #0bf1c3; /** Brand accent — 云毓青 */
   --brand-tertiary: #8b5cf6;
@@ -114,44 +113,46 @@
   --neutral-3: #f1f5f9; /** component bg default */
   --neutral-4: #e2e8f0; /** component bg hover */
   --neutral-5: #cbd5e1; /** component bg active */
-  --neutral-6: #e2e8f0; /** subtle border */
-  --neutral-7: #cbd5e1; /** default border */
-  --neutral-8: #94a3b8; /** hovered border */
+  --neutral-6: #b0bccb; /** subtle border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp step5 → step9 at t=0.25. The $value here is a placeholder anchor only; the preprocessor overwrites it. */
+  --neutral-7: #96a3b5; /** default border — DERIVED: OKLab lerp step5 → step9 at t=0.50. */
+  --neutral-8: #7d8ba0; /** hovered border — DERIVED: OKLab lerp step5 → step9 at t=0.75. */
   --neutral-9: #64748b; /** solid fill */
   --neutral-10: #475569; /** solid fill hover */
   --neutral-11: #334155; /** secondary text */
   --neutral-12: #0f172a; /** primary text */
-  --blue-1: #f0f4ff;
-  --blue-2: #dbe4ff;
-  --blue-3: #bac8ff;
-  --blue-4: #91a7ff;
-  --blue-5: #5c7cfa;
-  --blue-6: #bac8ff;
-  --blue-7: #91a7ff;
-  --blue-8: #5c7cfa;
-  --blue-9: #0033fe; /** solid fill — main brand */
-  --blue-10: #002ad4;
-  --blue-11: #0021ab;
-  --blue-12: #000f59;
-  --cyan-1: #e6fff8;
-  --cyan-2: #b3ffec;
-  --cyan-3: #80ffe0;
-  --cyan-4: #4dfcd4;
-  --cyan-5: #1af7c8;
-  --cyan-6: #80ffe0;
-  --cyan-7: #4dfcd4;
-  --cyan-8: #1af7c8;
-  --cyan-9: #0bf1c3;
-  --cyan-10: #09c9a3;
-  --cyan-11: #07a183;
-  --cyan-12: #035143;
+  --blue-1: #fafcfe; /** app tint — L* 99.01, C 0.003, hue 264. Radix blue-1 sits at L* 99.31 C 0.003. */
+  --blue-2: #f2f6fd; /** subtle background — L* 97.21, C 0.010. */
+  --blue-3: #e7eefc; /** component background default — L* 94.79, C 0.020. */
+  --blue-4: #d8e4fb; /** component background hover — L* 91.69, C 0.034. */
+  --blue-5: #c6d7fa; /** component background active — L* 87.77, C 0.052. Anchor for the derived border tier. */
+  --blue-6: #9fbcf9; /** subtle border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step9 (deep scale, span 32.3 L*) at t=0.25. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 79.61, C 0.093. */
+  --blue-7: #79a1f7; /** default border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step9 (deep scale, span 32.3 L*) at t=0.50. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 71.63, C 0.134. */
+  --blue-8: #5384f3; /** hovered border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step9 (deep scale, span 32.3 L*) at t=0.75. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 63.47, C 0.175. */
+  --blue-9: #2e65ee; /** solid fill — L* 55.50, C 0.215, hue 264.0. White label 4.99:1, inside the 4.7-5.4 band comparable products ship. Same value as shadcn --primary so the deep solid fill has one source, not two. The VI hex #0033FE (C 0.290, L* 48.4) stays the identity token --brand-primary and is deliberately NOT pinned into this ramp slot: pinning it left steps 6-9 only 3.5 L* apart with chroma climbing to 0.290. */
+  --blue-10: #2253d4; /** solid fill hover — L* 49.52, C 0.205. White label 6.45:1. */
+  --blue-11: #1740ad; /** secondary text — L* 42.04, C 0.180. 8.60:1 on step 1. */
+  --blue-12: #031654; /** primary text — L* 23.91, C 0.115. 16.38:1 on step 1. */
+  --blue-contrast: #ffffff; /** Label ink for the solid fill tier. Absolute value, identical in both modes: a deep fill always takes white, never the scale's own step 12, which is light in dark mode. 4.99:1 on step 9, 6.45:1 on step 10. */
+  --cyan-1: #f9fdfb; /** app tint — L* 99.05, C 0.005, hue 172. */
+  --cyan-2: #effbf7; /** subtle background — L* 97.81, C 0.014. */
+  --cyan-3: #daf9ee; /** component background default — L* 95.68, C 0.035. */
+  --cyan-4: #c3f6e4; /** component background hover — L* 93.29, C 0.058. */
+  --cyan-5: #a3f2d8; /** component background active — L* 90.27, C 0.086. Anchor for the derived border tier. */
+  --cyan-6: #8eefd1; /** subtle border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step10 (bright scale: |L9-L5| = 4.9 L* < 6.0, so the tier continues toward step 10) at t=0.25. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 88.38, C 0.102. */
+  --cyan-7: #77ecc9; /** default border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step10 (bright scale: |L9-L5| = 4.9 L* < 6.0, so the tier continues toward step 10) at t=0.50. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 86.50, C 0.119. */
+  --cyan-8: #5be8c2; /** hovered border — DERIVED at build time (scripts/derive-border-tier.mjs): OKLab lerp of step 5 toward step10 (bright scale: |L9-L5| = 4.9 L* < 6.0, so the tier continues toward step 10) at t=0.75. The value here is a placeholder anchor only; the preprocessor overwrites it. Lands at L* 84.42, C 0.134. */
+  --cyan-9: #0bf1c3; /** solid fill — bright scale, so the fill is LIGHT and takes dark ink: L* 85.41, C 0.164, hue 172.1. Ink 10.35:1 against --cyan-contrast. Step 9 legitimately sits above step 8 on a bright scale, exactly as Radix mint does (8 at L* 72.2, 9 at L* 87.0). */
+  --cyan-10: #33e5bb; /** solid fill hover — L* 82.61, C 0.150. 2.80 L* below step 9, matching Radix mint's own 2.95 L* step9-to-step10 drop, so hovering the bright fill deepens it slightly instead of collapsing past its own border tier. The previous value was 10.87 L* below step 9 and landed DARKER than step 8. Ink 9.40:1. */
+  --cyan-11: #027a61; /** secondary text — L* 51.64, C 0.100. 5.17:1 on step 1. */
+  --cyan-12: #004133; /** primary text — L* 33.45, C 0.065. 11.35:1 on step 1. */
+  --cyan-contrast: #0d2b25; /** Label ink for the bright fill tier. Absolute near-black, identical in both modes, carrying a trace of the scale hue. A bright fill needs an explicit dark ink; comparing white against the scale's own step 12 picks white in dark mode, where step 12 is light, and measures 1.52:1. 10.35:1 on step 9, 9.40:1 on step 10. */
   --background: 0 0% 100%; /** HSL channel triple — consume via hsl(var(--background)) */
   --foreground: 222 47% 11%;
   --card: 0 0% 100%;
   --card-foreground: 222 47% 11%;
   --popover: 0 0% 100%;
   --popover-foreground: 222 47% 11%;
-  --primary: 228 85% 56%; /** Softer brand blue #254bfa */
+  --primary: 222.8 85% 55.7%; /** Product action blue. Derived, not borrowed: hue 264 is the VI hue, L* and C were chosen inside the band the industry actually ships (measured OKLCH C 0.167-0.235, L* 54-67 across Vercel, Stripe, Linear, GitHub, Tailwind, Radix, Figma, Notion). #2e65ee = L*55.5 C0.215, white label 4.99:1. The previous 228 85% 56% (#2f56ee, C0.232) also passed at 5.70:1 — this trims it to the middle of the band rather than its top edge. The VI lock --blue-9 (#0033FE, C0.290) is 23% above anything in that band and must never surface on a component. */
   --primary-foreground: 0 0% 100%;
   --secondary: 210 40% 96%;
   --secondary-foreground: 222 47% 11%;
@@ -161,10 +162,13 @@
   --accent-foreground: 228 85% 56%; /** Softer brand blue — desaturated to match --primary, avoids 100% saturation glare on focus/accent */
   --destructive: 0 84% 45%;
   --destructive-foreground: 0 0% 100%;
+  --destructive-strong: 0 84% 45%; /** Red as FOREGROUND. In light mode --destructive already passes (5.42:1 on white), so this equals it; the token exists so consumers reference one name across themes. In DARK, --destructive is 0 63% 38% = 2.15:1 on --card, unreadable as text — see dark.json. Mirrors --warning-strong. */
   --success: 142 71% 29%;
   --success-foreground: 0 0% 100%;
+  --success-strong: 142 71% 27%; /** Green as FOREGROUND. --success (142 71% 29%) is 5.15:1 on white but only 4.49:1 as ink on its own 10% tint — one hundredth under AA, which is where badge green-subtle sat. Darkened two points: 5.71:1 on white, 4.99:1 on the tint, alongside --warning-strong (5.40) and --destructive-strong (5.42) so the three status foregrounds read with the same weight. Completes the trio; use --success for fills with --success-foreground on top. */
   --warning: 38 92% 50%;
   --warning-foreground: 222 47% 11%;
+  --warning-strong: 38 92% 30%; /** Amber as FOREGROUND on a light surface. --warning is a fill: at 38 92% 50% it is 2.04:1 against --neutral-2, so it is unreadable as text or as an icon stroke. This darkened step is 5.17:1, which sits between --success (4.92) and --destructive (5.19) so the three status colours read with the same weight. Use --warning for fills with --warning-foreground on top; use this for amber text and icons. Destructive and success need no equivalent — they already pass AA as foreground. */
   --info: 228 85% 56%;
   --info-foreground: 0 0% 100%;
   --border: 240 5.9% 90%;
@@ -223,6 +227,18 @@
   --elevation-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.25);
   --elevation-brand: 0 0 0 1px rgb(0 51 254 / 0.15), 0 4px 20px -2px rgb(0 51 254 / 0.2);
   --elevation-brand-lg: 0 0 0 1px rgb(0 51 254 / 0.2), 0 8px 40px -4px rgb(0 51 254 / 0.3);
+  --elevation-ambient-sm: 0 1px 2px -1px hsl(222 47% 11% / 0.06), 0 6px 16px -6px hsl(222 47% 11% / 0.12); /** Ambient elevation, small. Contact layer plus a wide soft pool — the marketing-surface counterpart to the tight xs..2xl product ramp. */
+  --elevation-ambient-md: 0 2px 4px -2px hsl(222 47% 11% / 0.06), 0 12px 32px -10px hsl(222 47% 11% / 0.14); /** Ambient elevation, medium. Default resting depth for a floating marketing card. */
+  --elevation-ambient-lg: 0 4px 8px -4px hsl(222 47% 11% / 0.06), 0 24px 56px -18px hsl(222 47% 11% / 0.16); /** Ambient elevation, large. One step up from md; use for hover of a md surface, not as a resting default. */
+  --elevation-glass-sm: inset 0 1px 0 rgb(255 255 255 / 0.5), 0 1px 2px -1px hsl(222 47% 11% / 0.06), 0 6px 16px -6px hsl(222 47% 11% / 0.12); /** Ambient-sm plus a lit top edge, for translucent panels over a blurred backdrop. */
+  --elevation-glass-md: inset 0 1px 0 rgb(255 255 255 / 0.5), 0 2px 4px -2px hsl(222 47% 11% / 0.06), 0 12px 32px -10px hsl(222 47% 11% / 0.14); /** Ambient-md plus a lit top edge. */
+  --elevation-glass-lg: inset 0 1px 0 rgb(255 255 255 / 0.5), 0 4px 8px -4px hsl(222 47% 11% / 0.06), 0 24px 56px -18px hsl(222 47% 11% / 0.16); /** Ambient-lg plus a lit top edge. */
+  --elevation-sheen: inset 0 1px 0 rgb(255 255 255 / 0.2); /** Top-edge sheen for solid inverted fills (bg-foreground). Lifts with light on a dark fill, with shade on a light one. */
+  --elevation-ambient-glow: 0 0 80px hsl(222 47% 11% / 0.1); /** Centred offsetless halo — the only non-directional step on the ramp. For a translucent panel that needs separation from its backdrop without reading as lifted off a surface. In dark mode this inverts to a low-alpha light halo, because a black halo cannot read against a dark surround. */
+  --elevation-glow-accent: 0 8px 32px rgb(0 0 0 / 0.4), 0 0 60px color-mix(in srgb, var(--brand-accent) 8%, transparent); /** Directional pool plus a wide brand-accent halo, for fixed dark-glass surfaces. The pool is theme-invariant black on purpose: the surfaces that carry an accent halo present the same dark glass in both themes, so a theme-flipping pool would lighten in light mode exactly where the panel needs the most separation. Accent sourced from --brand-accent, so it follows the light and dark accent values. */
+  --elevation-glow-accent-lg: 0 12px 48px rgb(0 0 0 / 0.5), 0 0 80px color-mix(in srgb, var(--brand-accent) 12%, transparent); /** Hover escalation of glow-accent. Deeper pool, wider and stronger accent halo. */
+  --elevation-glow-accent-sm: 0 0 20px color-mix(in srgb, var(--brand-accent) 10%, transparent); /** Accent halo alone, no pool. For a small accent-tinted chip or icon plate inside a glow-accent surface. */
+  --elevation-glow-primary: 0 20px 25px -5px hsl(var(--primary) / 0.05), 0 8px 10px -6px hsl(var(--primary) / 0.05); /** xl geometry tinted with the action fill at 5 percent. For the emphasised card in a set (a highlighted plan) where the lift should read as coloured rather than neutral. */
 }
 
 :root {