@nebutra/design-tokens 0.1.2 → 2.0.0

package/style-dictionary.config.mjs

@@ -24,6 +24,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { readFile, rm, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import StyleDictionary from "style-dictionary";
+import { multiThemeName, pathToCssVarName } from "./scripts/css-var-name.mjs";
+import { assertLadder, deriveBorderTier } from "./scripts/derive-border-tier.mjs";
 
 // Multi-mood oklch catalog removed (2026.07). Only light/dark modes remain.
 // Design-language swap lives in @nebutra/theme (Brand Packages / skins.css).
@@ -49,10 +51,13 @@ function formatCssWithBiome(content, stdinFilePath) {
   }
 }
 
+// Mirror of FONT_REGISTRY in packages/design/fonts/src/index.ts (duplicated
+// because this generator is plain ESM and cannot import the TS source).
 const FONT_REGISTRY = {
   geist: "--font-geist-sans",
   "geist sans": "--font-geist-sans",
   "geist mono": "--font-geist-mono",
+  "vivo sans sc": "--font-noto-sans-sc",
   inter: "--font-inter",
   "space grotesk": "--font-space-grotesk",
   "playfair display": "--font-playfair-display",
@@ -85,85 +90,12 @@ function withRegistryFont(stack) {
   return variable ? `var(${variable}), ${stack}` : stack;
 }
 
-/**
- * Custom CSS variable namer.
- *
- * Maps DTCG paths to the same names the legacy SSOT uses.
- */
-function pathToCssVarName(token) {
-  const path = token.path;
-  const [head, ...rest] = path;
-
-  // Drop primitive `color.` prefix → keep child name.
-  if (head === "color") {
-    if (rest[0] === "white" || rest[0] === "black") return null;
-    if (rest[0] === "tertiary-purple") return "brand-tertiary";
-    return rest.join("-");
-  }
-
-  if (head === "size") return rest.join("-");
-  if (head === "duration") return `duration-${rest.join("-")}`;
-  if (head === "easing") return `ease-${rest.join("-")}`;
-  if (head === "fontFamily") return `font-${rest.join("-")}`;
-
-  if (head === "brand") {
-    if (rest[0] === "gradient") {
-      const sub = rest.slice(1).join("-");
-      return sub === "primary" ? "brand-gradient" : `brand-gradient-${sub}`;
-    }
-    return `brand-${rest.join("-")}`;
-  }
-
-  if (head === "status") return `status-${rest.join("-")}`;
-
-  if (head === "container") return `container-${rest.join("-")}`;
-  if (head === "radius") {
-    return rest[0] === "default" ? "radius" : `radius-${rest.join("-")}`;
-  }
-  if (head === "transition") {
-    if (rest[0] === "shorthand") return "transition";
-    if (rest[0] === "default") return null; // composite — emitted via post-process
-    return `transition-${rest.join("-")}`;
-  }
-  if (head === "focusRing") {
-    if (rest[0] === "default") return "focus-ring";
-    return `focus-ring-${rest.join("-")}`;
-  }
-
-  if (head === "scale") return rest.join("-");
-  if (head === "shadcn") return rest.join("-");
-  if (head === "ds") return `ds-${rest.join("-")}`;
-  if (head === "elevation") return `elevation-${rest.join("-")}`;
-
-  if (head === "theme") return null;
-
-  if (head === "shadow") return `shadow-${rest.join("-")}`;
-
-  return path.join("-");
-}
-
 StyleDictionary.registerTransform({
   name: "name/nebutra/css",
   type: "name",
   transform: (token) => pathToCssVarName(token) ?? `__skip__${token.path.join("-")}`,
 });
 
-/**
- * CSS variable namer for theme token trees (light/dark).
- * Emits Tailwind v4 `@theme`-compatible names: color.primary → --color-primary.
- */
-function multiThemeName(token) {
-  const path = token.path;
-  const [head, ...rest] = path;
-  if (head === "theme") return null;
-  if (head === "color") return `color-${rest.join("-")}`;
-  if (head === "radius") return `radius-${rest.join("-")}`;
-  if (head === "fontFamily") return `font-${rest.join("-")}`;
-  if (head === "shadow") return `shadow-${rest.join("-")}`;
-  if (head === "transition") return `transition-${rest.join("-")}`;
-  return path.join("-");
-}
-
 StyleDictionary.registerTransform({
   name: "name/nebutra/css/multi-theme",
   type: "name",
@@ -292,6 +224,60 @@ function registerLayeredNameTransform({ name, sources, nameForPath }) {
   return name;
 }
 
+/**
+ * Border-tier derivation.
+ *
+ * core.json ships 11 primitive stops; the functional layer needs 12 steps. The
+ * gap used to be closed by aliasing 6/7/8 to the same primitives as 3/4/5,
+ * which made the border tier identical to the component-background tier. Steps
+ * 6/7/8 are now computed from the scale's own 5 and 9 (or 10, for bright
+ * scales) in OKLab. See scripts/derive-border-tier.mjs for the rule.
+ *
+ * This runs as a global preprocessor, so it sees the merged core + semantic +
+ * theme tree and can resolve the `{color.…}` references the anchors point at.
+ * Deriving here rather than authoring literals in core.json is what makes the
+ * fix survive `scripts/brand-apply.ts`, which rewrites the three brand palettes
+ * wholesale over a fixed 11-stop list on every rebrand.
+ */
+StyleDictionary.registerPreprocessor({
+  name: "nebutra/derive-border-tier",
+  preprocessor: (tokens) => {
+    deriveBorderTier(tokens);
+    return tokens;
+  },
+});
+
+/**
+ * A token description must not be able to break the build.
+ *
+ * $description is emitted verbatim into `/** … *\/` comments in the CSS and the
+ * TypeScript declarations, so a description containing the comment terminator
+ * closes it early and the generated .ts stops parsing. Writing an asterisk-slash inside a note
+ * about a colour ramp is enough to do it, and the failure surfaces as a
+ * sixty-line minified prettier stack trace pointing at a blank line in
+ * build/ts/estree.ts — nowhere near the token that caused it.
+ *
+ * Neutralised rather than rejected: the author's sentence still reads the same,
+ * and there is nothing for a contributor to learn or remember.
+ */
+StyleDictionary.registerPreprocessor({
+  name: "nebutra/safe-descriptions",
+  preprocessor: (tokens) => {
+    const walk = (node) => {
+      if (node === null || typeof node !== "object") return;
+      if (typeof node.$description === "string" && node.$description.includes("*/")) {
+        node.$description = node.$description.replaceAll("*/", "* /");
+      }
+      for (const [key, child] of Object.entries(node)) {
+        if (key === "$description") continue;
+        walk(child);
+      }
+    };
+    walk(tokens);
+    return tokens;
+  },
+});
+
 StyleDictionary.registerTransform({
   name: "color/nebutra/passthrough",
   type: "value",
@@ -330,7 +316,7 @@ const buildMode = ({ mode, selector, sources, outputFile, nameTransform = "name/
 
   return {
     log: { verbosity: "default", warnings: "error" },
-    preprocessors: ["tokens-studio"],
+    preprocessors: ["tokens-studio", "nebutra/safe-descriptions", "nebutra/derive-border-tier"],
     include: sources.slice(0, -1),
     source: sources.slice(-1),
     platforms: {
@@ -448,6 +434,35 @@ for (const cfg of configs) {
   await sd.buildAllPlatforms();
 }
 
+// ─── Ladder invariant ────────────────────────────────────────────────────────
+//
+// Fail the build if the 12-step scales regress to the state this package was
+// fixed out of: duplicated steps, or a ramp (1…8) that is not monotonic in
+// OKLab lightness. Step 9 is exempt from monotonicity — on bright scales the
+// solid accent legitimately sits off the ramp.
+//
+// This is the guard that makes the derivation load-bearing rather than
+// decorative: if the preprocessor ever stops running, the placeholder `$value`
+// aliases collapse 6/7/8 onto step 5 and this throws instead of shipping.
+for (const mode of ["light", "dark"]) {
+  const css = await readFile(`build/css/${mode}.css`, "utf8");
+  const scales = new Map();
+  for (const [, scaleName, step, value] of css.matchAll(
+    /--(neutral|blue|cyan)-(\d{1,2}):\s*(#[0-9a-f]{6})\s*;/giu,
+  )) {
+    const key = scaleName.toLowerCase();
+    if (!scales.has(key)) scales.set(key, {});
+    scales.get(key)[step] = value;
+  }
+
+  const problems = [...scales].flatMap(([name, values]) => assertLadder(`${mode} ${name}`, values));
+  if (problems.length > 0) {
+    throw new Error(
+      `[design-tokens] 12-step scale ladder invariant violated:\n  ${problems.join("\n  ")}`,
+    );
+  }
+}
+
 const tsIndex = `${tsExportModes
   .map((mode) => `export * as ${toNamespaceIdentifier(mode)} from "./${mode}.js";`)
   .join("\n")}
@@ -788,6 +803,22 @@ function buildTailwindThemeInline() {
   --radius-3xl: 1.5rem;
   --radius-full: 9999px;
 
+  /* Containers — the page-width contract from CLAUDE.md, as real utilities.
+     max-w-text (reading), max-w-content (pricing/blog), max-w-wide (feature bento, navbar).
+
+     These values also reach :root through the semantic layer, so var(--container-wide) keeps
+     working; what was missing was the Tailwind side. Without it there is no max-w-wide to reach
+     for, and 92 call sites across apps/** had typed max-w-wide instead — a decided number
+     living in a className, where changing the token cannot move it.
+
+     Literals rather than var(--container-wide): Tailwind emits an @theme entry into its own
+     layer, so a same-named reference becomes self-referential and survives only because the
+     semantic :root happens to come later in the cascade. Duplicating the number and pinning it
+     with a parity test is the honest trade — see design-tokens' container parity test. */
+  --container-text: 896px;
+  --container-content: 1152px;
+  --container-wide: 1400px;
+
   /* Shadows */
   --shadow-xs: var(--elevation-xs);
   --shadow-sm: var(--elevation-sm);
@@ -798,23 +829,78 @@ function buildTailwindThemeInline() {
   --shadow-brand: var(--elevation-brand);
   --shadow-brand-lg: var(--elevation-brand-lg);
 
-  /* Motion — Easing curves */
-  --ease-in: cubic-bezier(0.4, 0, 1, 1);
-  --ease-out: cubic-bezier(0, 0, 0.2, 1);
-  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
-  --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
+  /* shadow-ambient-md / shadow-glass-lg / shadow-sheen — so marketing surfaces
+     reach for a step on the ramp instead of spelling out a blur and a spread.
+     Aliased to var() rather than inlined so the dark theme's values apply. */
+  --shadow-ambient-sm: var(--elevation-ambient-sm);
+  --shadow-ambient-md: var(--elevation-ambient-md);
+  --shadow-ambient-lg: var(--elevation-ambient-lg);
+  --shadow-glass-sm: var(--elevation-glass-sm);
+  --shadow-glass-md: var(--elevation-glass-md);
+  --shadow-glass-lg: var(--elevation-glass-lg);
+  --shadow-sheen: var(--elevation-sheen);
+
+  /* Coloured and centred elevation. shadow-ambient-glow is the one
+     non-directional step; shadow-glow-accent|-lg|-sm carry a brand-accent halo
+     so a glass card never hand-types the accent as raw rgba; shadow-glow-primary
+     tints the xl geometry with the action fill. */
+  --shadow-ambient-glow: var(--elevation-ambient-glow);
+  --shadow-glow-accent: var(--elevation-glow-accent);
+  --shadow-glow-accent-lg: var(--elevation-glow-accent-lg);
+  --shadow-glow-accent-sm: var(--elevation-glow-accent-sm);
+  --shadow-glow-primary: var(--elevation-glow-primary);
+
+  /* Motion — Easing curves.
+     Indirect, like the shadows above: an @theme entry holding a literal is
+     inlined into the utility, so the ease-out class compiled to a fixed
+     cubic-bezier and no Brand Package could move it. Pointing at the runtime
+     rail in static/base.css makes it follow the language the page is under.
+     (No backticks in this block — it is inside a JS template literal.) */
+  --ease-in: var(--motion-ease-in);
+  --ease-out: var(--motion-ease-out);
+  --ease-brand: var(--motion-ease-brand);
+  --ease-in-out: var(--motion-ease-in-out);
+  --ease-spring: var(--motion-ease-spring);
 
   /* Motion — Durations (four-rail; see core.json:duration). Names denote intent, not relative speed. */
-  --duration-micro: 100ms;
-  --duration-flow: 200ms;
-  --duration-reveal: 300ms;
-  --duration-cinematic: 500ms;
-
-  /* Font family — Geist primary stack with CJK fallbacks */
-  --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;
+  --duration-micro: var(--motion-duration-micro);
+  --duration-flow: var(--motion-duration-flow);
+  --duration-reveal: var(--motion-duration-reveal);
+  --duration-cinematic: var(--motion-duration-cinematic);
+
+  /* The same four rails on the namespace Tailwind reads for duration-*.
+     --duration-* is the variable other CSS consumes; the utility class is built
+     from --transition-duration-*, and only that one. Without these,
+     duration-micro and duration-reveal are class names that generate nothing:
+     they were in use in the component library and on the marketing site, and
+     every one of them silently fell back to the 150ms default. */
+  --transition-duration-micro: var(--motion-duration-micro);
+  --transition-duration-flow: var(--motion-duration-flow);
+  --transition-duration-reveal: var(--motion-duration-reveal);
+  --transition-duration-cinematic: var(--motion-duration-cinematic);
+
+  /* Likewise for ease-*: the utility namespace is --ease-* already, so the four
+     above are reachable as ease-brand / ease-spring without further mapping. */
+
+  /* Spacing — DO NOT register --spacing-sm|md|lg|xl|2xl here.
+     Tailwind v4 puts every --spacing-{key} on the shared size rail, so
+     max-w-sm / max-w-2xl (and width/height/gap utilities with the same keys)
+     resolve to the breathing-room lengths (0.75rem to 3rem) instead of the
+     container scale (24rem to 42rem). That shipped as one-word-per-line prose
+     and a 32px install box on nebutra.com (measured 2026-08-03).
+     Brand Packages still override --space-source-*; consumers must read
+     those vars directly (var(--space-source-md, ...)), never via a @theme
+     --spacing-{step} alias. --spacing itself (0.25rem arithmetic base) stays
+     untouched. See static/base.css. */
+
+  /* Font family — Geist keeps Latin + numerals, self-hosted Noto Sans SC takes
+     CJK, system CJK faces behind it. Order is the design decision; see the
+     fontFamily $description in tokens/core.json. Mirror of those tokens — keep
+     the two in sync (verify:parity compares them). */
+  --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;
+  --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;
 }
 `;

package/tokens/core.json

@@ -267,52 +267,66 @@
       }
     },
     "radius": {
+      "$description": "Radius ladder. Every step names a job; nothing on the ladder exists only because a t-shirt scale has that size. Steps below 1rem climb by 2px so a nested corner can sit one step inside its parent without looking loose; above 1rem the ladder jumps, because a large panel does not read a 2px difference. The three intent aliases (button, card, panel) are the names product code should reach for — they resolve onto lg/xl/2xl today and exist so a future re-shape moves one value instead of a thousand call sites. Nothing above 3xl: a corner larger than 24px is a composition, not a surface, and belongs in the component that draws it.",
       "none": {
         "$value": "0",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "Job: flush. Edge-to-edge surfaces — a full-bleed table row, a segment welded to its neighbour, an inset that must not round twice."
+      },
+      "xs": {
+        "$value": "0.125rem",
+        "$type": "dimension",
+        "$description": "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."
       },
       "sm": {
         "$value": "0.25rem",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "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."
       },
       "md": {
         "$value": "0.375rem",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "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."
       },
       "lg": {
         "$value": "0.5rem",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "Job: container. Things that hold controls rather than being one: popover, dropdown surface, tooltip, toolbar, inline code block. Aliased as radius-button."
       },
       "xl": {
         "$value": "0.75rem",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "Job: card. A discrete surface in a list or grid that carries its own padding and elevation. Aliased as radius-card."
       },
       "2xl": {
         "$value": "1rem",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "Job: panel. A region that holds cards — bento cell, dialog, sheet, dashboard section. Aliased as radius-panel."
       },
       "3xl": {
         "$value": "1.5rem",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "Job: frame. The outermost shell of a marketing or docs composition — mockup window, hero frame, screenshot chrome. The top of the ladder."
       },
       "full": {
         "$value": "9999px",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "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."
       },
       "button": {
         "$value": "0.5rem",
         "$type": "dimension",
-        "$description": "2026 button radius — Vercel/Linear/Cursor consensus"
+        "$description": "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."
       },
       "card": {
         "$value": "0.75rem",
         "$type": "dimension",
-        "$description": "2026 card radius"
+        "$description": "Intent alias for the card step. Reach for this in product code instead of xl."
       },
       "panel": {
         "$value": "1rem",
         "$type": "dimension",
-        "$description": "2026 bento/hero panel radius"
+        "$description": "Intent alias for the panel step. Reach for this in product code instead of 2xl."
       }
     }
   },
@@ -345,7 +359,7 @@
       "$type": "cubicBezier"
     },
     "out": {
-      "$value": "cubic-bezier(0, 0, 0.2, 1)",
+      "$value": "cubic-bezier(0.16, 1, 0.3, 1)",
       "$type": "cubicBezier"
     },
     "in-out": {
@@ -403,21 +417,22 @@
     }
   },
   "fontFamily": {
-    "$description": "Geist + Geist Mono primary (Vercel typography) with Noto Sans SC / PingFang SC / Microsoft YaHei CJK fallbacks. Replaces Poppins per VI 2026 update. Each stack prefixes the next/font variable (--font-geist-sans / --font-geist-mono) so the actual loaded face wins over the literal 'Geist' family name (which the browser cannot resolve directly when next/font assigns a generated unique font-family identifier).",
+    "$description": "Geist + Geist Mono for Latin, self-hosted Noto Sans SC (SIL OFL) for CJK, system CJK faces (PingFang SC / Microsoft YaHei) as the fallback behind it. ORDER IS THE DESIGN DECISION: Geist comes first so it keeps Latin and the numerals (tabular figures, tighter x-height — what dense dashboard tables need, and the locked UI face); Noto Sans SC follows so only CJK falls through to it. Reversed, Noto would take the Latin too and its Latin is not as good as Geist's for UI. Each stack prefixes the next/font variable (--font-geist-sans / --font-geist-mono / --font-noto-sans-sc) so the actual loaded face wins over the literal family name, which the browser cannot resolve directly once next/font assigns a generated unique font-family identifier. The Noto entry carries a literal fallback inside var() so a surface that never applies cjkFontClassName degrades to the family name instead of making the whole declaration invalid at computed-value time. `cn` is kept rather than deleted because it still has a job: the `font-cn` utility and the `html:lang(zh|ja|ko) body` auto-activation rule in static/base.css both set font-family to that token ALONE (they exist for the CJK line-height / word-break metrics), so it governs Chinese pages entirely — including their Latin.",
     "sans": {
-      "$value": "var(--font-geist-sans), \"Geist\", \"Noto Sans SC\", \"PingFang SC\", \"Microsoft YaHei\", -apple-system, BlinkMacSystemFont, system-ui, sans-serif",
+      "$value": "var(--font-geist-sans), \"Geist\", var(--font-noto-sans-sc, \"Noto Sans SC\"), \"PingFang SC\", \"Microsoft YaHei\", -apple-system, BlinkMacSystemFont, system-ui, sans-serif",
       "$type": "fontFamily"
     },
     "cn": {
-      "$value": "\"Noto Sans SC\", \"PingFang SC\", \"Microsoft YaHei\", \"vivo Sans\", sans-serif",
-      "$type": "fontFamily"
+      "$value": "var(--font-geist-sans), \"Geist\", var(--font-noto-sans-sc, \"Noto Sans SC\"), \"PingFang SC\", \"Microsoft YaHei\", sans-serif",
+      "$type": "fontFamily",
+      "$description": "CJK-locale stack — same order as sans, minus the Latin-only system faces"
     },
     "display": {
-      "$value": "var(--font-geist-sans), \"Geist\", \"Noto Sans SC\", sans-serif",
+      "$value": "var(--font-geist-sans), \"Geist\", var(--font-noto-sans-sc, \"Noto Sans SC\"), sans-serif",
       "$type": "fontFamily"
     },
     "heading": {
-      "$value": "var(--font-geist-sans), \"Geist\", \"Noto Sans SC\", sans-serif",
+      "$value": "var(--font-geist-sans), \"Geist\", var(--font-noto-sans-sc, \"Noto Sans SC\"), sans-serif",
       "$type": "fontFamily"
     },
     "mono": {

package/tokens/semantic.json

@@ -87,18 +87,6 @@
       "cinematic": { "$value": "{duration.cinematic}", "$type": "duration" }
     }
   },
-  "transition": {
-    "duration": {
-      "$value": "{duration.flow}",
-      "$type": "duration",
-      "$description": "Default transition duration — 200ms flow rail."
-    },
-    "easing": {
-      "$value": "ease-out",
-      "$type": "string",
-      "$description": "ease-out keyword form (CSS-friendly). Equivalent to cubic-bezier(0,0,0.2,1)."
-    }
-  },
   "focusRing": {
     "default": {
       "$type": "string",