@nebutra/design-sync 0.1.1 → 2.0.0

package/dist/serialize/to-brand-package.d.ts

@@ -0,0 +1,37 @@
+/**
+ * DTCG token sets (design-sync pull result) → Brand Package.
+ *
+ * Create Center path:
+ *   getDesignSync().pull() → compileBrandFromTokenSets() → applyBrandPackage()
+ */
+import { type BrandPackage, type CompileResult } from "@nebutra/tokens/brand-package";
+import type { DesignTokenSet, DesignTokenTree } from "../types";
+export interface ToBrandPackageOptions {
+    id?: string;
+    name?: string;
+    /** Raw DESIGN.md text for recipe inference */
+    designMd?: string;
+}
+/** Deep-merge DTCG trees (later sets win on leaf collision). */
+export declare function mergeTokenTrees(trees: DesignTokenTree[]): DesignTokenTree;
+/**
+ * Normalize design-sync token sets into the flat Refero-like shape
+ * expected by compileReferoTokens (color/font/radius/surface at top level).
+ */
+export declare function tokenSetsToReferoShape(sets: DesignTokenSet[]): Record<string, unknown>;
+/** Compile Brand Package + CSS from design-sync pull token sets. */
+export declare function compileBrandFromTokenSets(sets: DesignTokenSet[], options?: ToBrandPackageOptions): CompileResult;
+/** Convenience: only CSS string */
+export declare function serializeToBrandCss(sets: DesignTokenSet[], options?: ToBrandPackageOptions): {
+    brand: BrandPackage;
+    css: string;
+    warnings: string[];
+};
+/**
+ * Full Create Center pipeline step after pull:
+ *   const { brand, css, warnings } = await pullAndCompileBrand()
+ */
+export declare function pullAndCompileBrand(pull: () => Promise<{
+    sets: DesignTokenSet[];
+}>, options?: ToBrandPackageOptions): Promise<CompileResult>;
+//# sourceMappingURL=to-brand-package.d.ts.map

package/dist/serialize/to-brand-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-brand-package.d.ts","sourceRoot":"","sources":["../../src/serialize/to-brand-package.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,aAAa,EAGnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,eAAe,CAMzE;AA8BD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQtF;AAED,oEAAoE;AACpE,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,cAAc,EAAE,EACtB,OAAO,GAAE,qBAA0B,GAClC,aAAa,CAQf;AAED,mCAAmC;AACnC,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,cAAc,EAAE,EACtB,OAAO,GAAE,qBAA0B,GAClC;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAO1D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,OAAO,CAAC;IAAE,IAAI,EAAE,cAAc,EAAE,CAAA;CAAE,CAAC,EAC/C,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,aAAa,CAAC,CAGxB"}

package/dist/serialize/to-brand-package.js

@@ -0,0 +1,87 @@
+/**
+ * DTCG token sets (design-sync pull result) → Brand Package.
+ *
+ * Create Center path:
+ *   getDesignSync().pull() → compileBrandFromTokenSets() → applyBrandPackage()
+ */
+import { compileReferoTokens, emitBrandCss, } from "@nebutra/tokens/brand-package";
+function isLeaf(node) {
+    return Boolean(node && typeof node === "object" && "$value" in node);
+}
+/** Deep-merge DTCG trees (later sets win on leaf collision). */
+export function mergeTokenTrees(trees) {
+    const out = {};
+    for (const tree of trees) {
+        mergeInto(out, tree);
+    }
+    return out;
+}
+function mergeInto(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        if (key === "__proto__" || key === "constructor" || key === "prototype")
+            continue;
+        if (isLeaf(value)) {
+            Object.defineProperty(target, key, {
+                value,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+            continue;
+        }
+        if (value && typeof value === "object") {
+            const existing = target[key];
+            if (existing && typeof existing === "object" && !isLeaf(existing)) {
+                mergeInto(existing, value);
+            }
+            else {
+                Object.defineProperty(target, key, {
+                    value: structuredClone(value),
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+        }
+    }
+}
+/**
+ * Normalize design-sync token sets into the flat Refero-like shape
+ * expected by compileReferoTokens (color/font/radius/surface at top level).
+ */
+export function tokenSetsToReferoShape(sets) {
+    const merged = mergeTokenTrees(sets.map((s) => s.tokens));
+    // If pull already looks like Refero (has color.*), use as-is
+    if (merged.color || merged.surface || merged.font) {
+        return merged;
+    }
+    // design-tokens monorepo shape often nests under themes — still pass through
+    return merged;
+}
+/** Compile Brand Package + CSS from design-sync pull token sets. */
+export function compileBrandFromTokenSets(sets, options = {}) {
+    const tokens = tokenSetsToReferoShape(sets);
+    return compileReferoTokens({
+        tokens,
+        ...(options.id ? { id: options.id } : {}),
+        ...(options.name ? { name: options.name } : {}),
+        ...(options.designMd ? { designMd: options.designMd } : {}),
+    });
+}
+/** Convenience: only CSS string */
+export function serializeToBrandCss(sets, options = {}) {
+    const result = compileBrandFromTokenSets(sets, options);
+    return {
+        brand: result.brand,
+        css: result.css || emitBrandCss(result.brand),
+        warnings: result.warnings,
+    };
+}
+/**
+ * Full Create Center pipeline step after pull:
+ *   const { brand, css, warnings } = await pullAndCompileBrand()
+ */
+export async function pullAndCompileBrand(pull, options = {}) {
+    const { sets } = await pull();
+    return compileBrandFromTokenSets(sets, options);
+}

package/dist/serialize/to-design-md.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DTCG → DESIGN.md serializer
+ *
+ * Converts a set of W3C DTCG token files into a DESIGN.md document:
+ *   - YAML front matter (machine tokens): colors, typography, rounded, spacing
+ *   - Markdown prose sections in the spec-mandated order
+ *
+ * Pure function — no filesystem I/O, no @google/design.md dependency.
+ *
+ * Known v1 scope limits:
+ *   - No `components:` group in front matter (avoids contrast-lint risk from
+ *     lack of structured component token data in this version).
+ *   - Elevation/shadows are prose-only (DESIGN.md spec has no structured
+ *     elevation token type; this is a documented spec gap).
+ *
+ * File layout:
+ *   to-design-md.ts        — public API + YAML front-matter builder (this file)
+ *   to-design-md.resolve.ts — token index building + alias/hex resolution
+ *   to-design-md.prose.ts  — markdown prose builder + shared types + constants
+ */
+import type { DesignTokenSet } from "../types";
+export interface ToDesignMdOptions {
+    /**
+     * Design system name written into the exported artefact.
+     *
+     * Defaults to a generic label on purpose: this package is provider-agnostic
+     * and has no brand of its own, so naming one here would stamp it onto every
+     * downstream design system that did not pass this option.
+     */
+    name?: string;
+    /** One-line brand description for the front matter and prose Overview. */
+    description?: string;
+    /**
+     * Name of a theme token set (e.g. "themes/light") whose
+     * `color.background` and `color.foreground` tokens are included in the
+     * `colors` front-matter group.
+     */
+    theme?: string;
+}
+/**
+ * Serialize an array of DTCG token sets into a DESIGN.md string.
+ *
+ * @param sets    All token sets to merge (e.g. core + semantic + theme).
+ * @param options Optional overrides for name, description, and theme.
+ * @returns A deterministic DESIGN.md string (YAML front matter + markdown prose).
+ */
+export declare function serializeToDesignMd(sets: DesignTokenSet[], options?: ToDesignMdOptions): string;
+//# sourceMappingURL=to-design-md.d.ts.map

package/dist/serialize/to-design-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-design-md.d.ts","sourceRoot":"","sources":["../../src/serialize/to-design-md.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAqB/C,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,MAAM,CA2C/F"}

package/dist/serialize/to-design-md.js

@@ -0,0 +1,114 @@
+/**
+ * DTCG → DESIGN.md serializer
+ *
+ * Converts a set of W3C DTCG token files into a DESIGN.md document:
+ *   - YAML front matter (machine tokens): colors, typography, rounded, spacing
+ *   - Markdown prose sections in the spec-mandated order
+ *
+ * Pure function — no filesystem I/O, no @google/design.md dependency.
+ *
+ * Known v1 scope limits:
+ *   - No `components:` group in front matter (avoids contrast-lint risk from
+ *     lack of structured component token data in this version).
+ *   - Elevation/shadows are prose-only (DESIGN.md spec has no structured
+ *     elevation token type; this is a documented spec gap).
+ *
+ * File layout:
+ *   to-design-md.ts        — public API + YAML front-matter builder (this file)
+ *   to-design-md.resolve.ts — token index building + alias/hex resolution
+ *   to-design-md.prose.ts  — markdown prose builder + shared types + constants
+ */
+import { buildProse, COLOR_ORDER, } from "./to-design-md.prose";
+import { buildIndex, buildIndexForSet, buildRounded, buildSpacing, buildTypography, readContainers, resolveColorRoles, } from "./to-design-md.resolve";
+/**
+ * Serialize an array of DTCG token sets into a DESIGN.md string.
+ *
+ * @param sets    All token sets to merge (e.g. core + semantic + theme).
+ * @param options Optional overrides for name, description, and theme.
+ * @returns A deterministic DESIGN.md string (YAML front matter + markdown prose).
+ */
+export function serializeToDesignMd(sets, options) {
+    const name = options?.name ?? "Design System";
+    const description = options?.description;
+    // 1. Build a flat path→leaf index across ALL sets
+    const index = buildIndex(sets);
+    // 2. Build a flat path→leaf index for only the theme set (if requested)
+    const themeIndex = options?.theme != null
+        ? buildIndexForSet(sets.find((s) => s.name === options.theme)?.tokens ?? {})
+        : new Map();
+    // 3. Resolve roles to hex (skip if source absent; throw if alias is dangling)
+    const { roles: colors, descriptions: colorDescriptions } = resolveColorRoles(index, themeIndex);
+    const typography = buildTypography(index);
+    const rounded = buildRounded(index);
+    const spacing = buildSpacing(index);
+    const containers = readContainers(index);
+    // 4. Emit
+    const fmDescription = description ??
+        "AI-native SaaS design system. Brand: 云毓蓝 blue (#0033fe) → 云毓青 cyan (#0bf1c3).";
+    const frontMatter = buildFrontMatter({
+        name,
+        description: fmDescription,
+        colors,
+        typography,
+        rounded,
+        spacing,
+    });
+    const prose = buildProse({
+        name,
+        ...(description !== undefined ? { description } : {}),
+        colors,
+        colorDescriptions,
+        typography,
+        rounded,
+        containers,
+    });
+    return `---\n${frontMatter}---\n${prose}`;
+}
+/**
+ * Escape a string value for use in YAML double-quoted scalars.
+ * Backslash must be escaped first (to avoid double-escaping), then double-quotes.
+ */
+function yamlString(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function buildFrontMatter(args) {
+    const lines = [];
+    lines.push(`version: alpha`);
+    lines.push(`name: ${yamlString(args.name)}`);
+    lines.push(`description: ${yamlString(args.description)}`);
+    // colors:
+    const colorEntries = Object.entries(args.colors);
+    if (colorEntries.length > 0) {
+        lines.push(`colors:`);
+        const ordered = COLOR_ORDER.filter((k) => args.colors[k] != null);
+        for (const key of ordered) {
+            lines.push(`  ${key}: ${yamlString(args.colors[key])}`);
+        }
+    }
+    // typography:
+    lines.push(`typography:`);
+    for (const [variant, entry] of Object.entries(args.typography)) {
+        lines.push(`  ${variant}:`);
+        lines.push(`    fontFamily: ${yamlString(entry.fontFamily)}`);
+        lines.push(`    fontSize: ${yamlString(entry.fontSize)}`);
+    }
+    // rounded:
+    const roundedEntries = Object.entries(args.rounded);
+    if (roundedEntries.length > 0) {
+        lines.push(`rounded:`);
+        for (const [key, value] of roundedEntries) {
+            lines.push(`  ${key}: ${yamlString(value)}`);
+        }
+    }
+    // spacing: (optional)
+    if (args.spacing != null) {
+        const spacingEntries = Object.entries(args.spacing);
+        if (spacingEntries.length > 0) {
+            lines.push(`spacing:`);
+            for (const [key, value] of spacingEntries) {
+                lines.push(`  ${key}: ${yamlString(value)}`);
+            }
+        }
+    }
+    return lines.join("\n") + "\n";
+}

package/dist/serialize/to-design-md.prose.d.ts

@@ -0,0 +1,55 @@
+/**
+ * DTCG → DESIGN.md prose layer
+ *
+ * Contains the markdown prose builder (`buildProse`) and all section helpers.
+ * Imported by `to-design-md.ts`; do NOT import this file directly in app code.
+ */
+export interface ColorRoles {
+    primary?: string;
+    accent?: string;
+    tertiary?: string;
+    danger?: string;
+    warning?: string;
+    success?: string;
+    background?: string;
+    foreground?: string;
+}
+/** Per-role descriptions sourced from the source semantic token's $description field. */
+export type ColorDescriptions = Partial<Record<keyof ColorRoles, string>>;
+export interface TypographyEntry {
+    fontFamily: string;
+    fontSize: string;
+}
+export interface TypographyMap {
+    h1: TypographyEntry;
+    "body-md": TypographyEntry;
+    label: TypographyEntry;
+}
+export interface RoundedMap {
+    [key: string]: string;
+}
+export interface SpacingMap {
+    [key: string]: string;
+}
+export interface ContainerInfo {
+    text?: string;
+    content?: string;
+    wide?: string;
+}
+export interface ProseArgs {
+    name: string;
+    /** Optional custom description. Replaces the generated Overview paragraph. */
+    description?: string;
+    colors: ColorRoles;
+    colorDescriptions: ColorDescriptions;
+    typography: TypographyMap;
+    rounded: RoundedMap;
+    containers: ContainerInfo;
+}
+export declare const COLOR_ORDER: Array<keyof ColorRoles>;
+export declare const DESIGN_MD_GOVERNANCE: {
+    readonly dos: readonly ["Use semantic tokens / CSS variables (`bg-primary`, `text-foreground`, `border-border`) — never raw hex values.", "Use the brand gradient (135° blue→cyan) for primary CTAs and gradient text effects.", "Use `AnimateIn` presets for entrance animations; never use raw `motion.div` with hardcoded transition values.", "Constrain layouts to the container width tiers; use the wide (1400px) container for feature sections.", "Give icon-only buttons an `aria-label`; rely on the global `:focus-visible` ring — do not add component-level focus rings."];
+    readonly donts: readonly ["Don't hardcode brand or status hex values in components — use token aliases (`var(--brand-primary)`, etc.).", "Don't use `max-w-5xl` or `max-w-7xl` for feature sections — use the wide container (`max-w-wide`).", "Don't reintroduce hardcoded focus rings (they double-render with the global `:focus-visible` rule).", "Don't use raw form controls (`<input>`, `<select>`, `<textarea>`) in app surfaces — use the primitives from `@nebutra/ui/primitives`."];
+};
+export declare function buildProse(args: ProseArgs): string;
+//# sourceMappingURL=to-design-md.prose.d.ts.map

package/dist/serialize/to-design-md.prose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-design-md.prose.d.ts","sourceRoot":"","sources":["../../src/serialize/to-design-md.prose.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAE1E,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,eAAe,CAAC;IACpB,SAAS,EAAE,eAAe,CAAC;IAC3B,KAAK,EAAE,eAAe,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,UAAU,EAAE,aAAa,CAAC;IAC1B,OAAO,EAAE,UAAU,CAAC;IACpB,UAAU,EAAE,aAAa,CAAC;CAC3B;AAID,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,MAAM,UAAU,CAS/C,CAAC;AAIF,eAAO,MAAM,oBAAoB;;;CAcvB,CAAC;AAIX,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAalD"}

package/dist/serialize/to-design-md.prose.js

@@ -0,0 +1,143 @@
+/**
+ * DTCG → DESIGN.md prose layer
+ *
+ * Contains the markdown prose builder (`buildProse`) and all section helpers.
+ * Imported by `to-design-md.ts`; do NOT import this file directly in app code.
+ */
+// ─── Stable color key order (used by both front-matter and prose) ─────────────
+export const COLOR_ORDER = [
+    "primary",
+    "accent",
+    "tertiary",
+    "danger",
+    "warning",
+    "success",
+    "background",
+    "foreground",
+];
+// ─── Governance list (exported for consumers who want to inspect the rules) ────
+export const DESIGN_MD_GOVERNANCE = {
+    dos: [
+        "Use semantic tokens / CSS variables (`bg-primary`, `text-foreground`, `border-border`) — never raw hex values.",
+        "Use the brand gradient (135° blue→cyan) for primary CTAs and gradient text effects.",
+        "Use `AnimateIn` presets for entrance animations; never use raw `motion.div` with hardcoded transition values.",
+        "Constrain layouts to the container width tiers; use the wide (1400px) container for feature sections.",
+        "Give icon-only buttons an `aria-label`; rely on the global `:focus-visible` ring — do not add component-level focus rings.",
+    ],
+    donts: [
+        "Don't hardcode brand or status hex values in components — use token aliases (`var(--brand-primary)`, etc.).",
+        "Don't use `max-w-5xl` or `max-w-7xl` for feature sections — use the wide container (`max-w-wide`).",
+        "Don't reintroduce hardcoded focus rings (they double-render with the global `:focus-visible` rule).",
+        "Don't use raw form controls (`<input>`, `<select>`, `<textarea>`) in app surfaces — use the primitives from `@nebutra/ui/primitives`.",
+    ],
+};
+// ─── Prose builder ────────────────────────────────────────────────────────────
+export function buildProse(args) {
+    const sections = [];
+    sections.push(buildOverview(args.name, args.colors, args.description));
+    sections.push(buildColors(args.colors, args.colorDescriptions));
+    sections.push(buildTypographySection(args.typography));
+    sections.push(buildLayout(args.containers));
+    sections.push(buildElevation());
+    sections.push(buildShapes(args.rounded));
+    sections.push(buildComponents());
+    sections.push(buildDosDonts());
+    return "\n" + sections.join("\n\n") + "\n";
+}
+// ─── Section helpers ──────────────────────────────────────────────────────────
+/**
+ * The fallback paragraph is generated from the caller's own tokens.
+ *
+ * It used to be Nebutra's: it named 云毓蓝 #0033fe and 云毓青 #0bf1c3 as "the
+ * brand palette" and asserted Vercel/Geist parity, so every downstream design
+ * system exported a document describing someone else's colours as its own.
+ */
+function buildOverview(name, colors, description) {
+    if (description)
+        return `## Overview\n\n${description}`;
+    const palette = [
+        colors.primary ? `primary ${colors.primary}` : null,
+        colors.accent ? `accent ${colors.accent}` : null,
+    ]
+        .filter(Boolean)
+        .join(" → ");
+    const paragraph = `${name} is a token-first design system` +
+        (palette ? ` built on a ${palette} palette` : "") +
+        ". It favours semantic tokens over raw hex values and follows the DTCG " +
+        "(W3C draft) format, which drives CSS variables, Tailwind utilities and " +
+        "the Style Dictionary pipeline.";
+    return `## Overview\n\n${paragraph}`;
+}
+const COLOR_LABELS = {
+    primary: "Primary",
+    accent: "Accent",
+    tertiary: "Tertiary",
+    danger: "Danger",
+    warning: "Warning",
+    success: "Success",
+    background: "Background",
+    foreground: "Foreground",
+};
+function buildColors(colors, colorDescriptions) {
+    const colorLines = [];
+    for (const key of COLOR_ORDER) {
+        const hex = colors[key];
+        if (!hex)
+            continue;
+        const label = COLOR_LABELS[key];
+        const desc = colorDescriptions[key];
+        colorLines.push(`- **${label}** (\`${hex}\`)${desc ? ` — ${desc}` : ""}`);
+    }
+    return (`## Colors\n\n` + (colorLines.length > 0 ? colorLines.join("\n") : "_No color roles resolved._"));
+}
+function buildTypographySection(typography) {
+    const typLines = [];
+    for (const [variant, entry] of Object.entries(typography)) {
+        typLines.push(`- **${variant}**: \`${entry.fontSize}\` — ${entry.fontFamily}`);
+    }
+    return `## Typography\n\n` + typLines.join("\n");
+}
+function buildLayout(containers) {
+    const containerLines = [];
+    if (containers.text) {
+        containerLines.push(`- **text** (\`${containers.text}\`) — Reading-focused: hero copy, FAQ, article body`);
+    }
+    if (containers.content) {
+        containerLines.push(`- **content** (\`${containers.content}\`) — Pricing tables, blog index, architecture diagrams`);
+    }
+    if (containers.wide) {
+        containerLines.push(`- **wide** (\`${containers.wide}\`) — Feature bento grids, testimonials, product demo sections, navbar`);
+    }
+    const layoutBody = containerLines.length > 0
+        ? `Three container-width tiers constrain layout density:\n\n` + containerLines.join("\n")
+        : `Use the \`--container-text\`, \`--container-content\`, and \`--container-wide\` CSS variables for layout constraints.`;
+    return `## Layout\n\n` + layoutBody;
+}
+function buildElevation() {
+    return (`## Elevation & Depth\n\n` +
+        `Elevation is expressed as layered box-shadows (xs → 2xl) plus brand-tinted glow variants (\`brand\`, \`brand-lg\`). ` +
+        `No structured elevation token is emitted in this DESIGN.md because the current DESIGN.md specification ` +
+        `has no elevation token type (this is a documented spec gap). ` +
+        `Consume shadows via the \`elevation.*\` token set in the DTCG source files or the ` +
+        `Tailwind \`shadow-*\` utilities mapped from those tokens.`);
+}
+function buildShapes(rounded) {
+    const roundedKeys = Object.keys(rounded);
+    const shapeBody = roundedKeys.length > 0
+        ? `Border-radius follows a named scale: ${roundedKeys.map((k) => `**${k}** (\`${rounded[k]}\`)`).join(", ")}. ` +
+            `Use \`size.radius.*\` tokens — never hardcode \`border-radius\` values.`
+        : `Border-radius follows the \`size.radius.*\` token scale. Use named tokens, never hardcode values.`;
+    return `## Shapes\n\n` + shapeBody;
+}
+function buildComponents() {
+    return (`## Components\n\n` +
+        `No structured component tokens are emitted in DESIGN.md v1 (avoids contrast-lint risk without full component token coverage). ` +
+        `Component rules live in the Storybook \`@nebutra/ui\` library and the \`@nebutra/tokens\` CSS variable sheet. ` +
+        `All interactive components must use \`@nebutra/ui/primitives\` form controls — raw \`<input>\`/\`<select>\`/\`<textarea>\` ` +
+        `are banned in \`apps/**\` (lint-enforced via \`scripts/lint-no-raw-inputs.mjs\`).`);
+}
+function buildDosDonts() {
+    const doSection = DESIGN_MD_GOVERNANCE.dos.map((d) => `- ✓ ${d}`).join("\n");
+    const dontSection = DESIGN_MD_GOVERNANCE.donts.map((d) => `- ✗ ${d}`).join("\n");
+    return `## Do's and Don'ts\n\n### Do\n\n${doSection}\n\n### Don't\n\n${dontSection}`;
+}

package/dist/serialize/to-design-md.resolve.d.ts

@@ -0,0 +1,36 @@
+/**
+ * DTCG → DESIGN.md resolver layer
+ *
+ * Builds flat token indexes from token sets, resolves aliases, extracts
+ * typed values (colors, typography, rounded, spacing, containers).
+ *
+ * Imported by `to-design-md.ts`; do NOT import this file directly in app code.
+ */
+import type { DesignTokenLeaf, DesignTokenSet, DesignTokenTree } from "../types";
+import type { ColorDescriptions, ColorRoles, ContainerInfo, RoundedMap, SpacingMap, TypographyMap } from "./to-design-md.prose";
+export type { ResolvedColors };
+export { buildIndex, buildIndexForSet, buildRounded, buildSpacing, buildTypography, readContainers, resolveColorRoles, };
+type FlatIndex = Map<string, DesignTokenLeaf>;
+interface ResolvedColors {
+    roles: ColorRoles;
+    descriptions: ColorDescriptions;
+}
+declare function buildIndex(sets: DesignTokenSet[]): FlatIndex;
+declare function buildIndexForSet(tree: DesignTokenTree): FlatIndex;
+/**
+ * Resolve a token value to its literal (non-alias) string.
+ * Throws if the alias is dangling (referenced path not in index).
+ * Returns null only if the path itself is missing from the index (graceful skip).
+ *
+ * @param path       The current token path being resolved.
+ * @param index      The flat token index to look up.
+ * @param visited    Set of paths already visited (cycle detection).
+ * @param originPath The originating token path (for cycle error messages).
+ */
+export declare function resolveValue(path: string, index: FlatIndex, visited?: Set<string>, originPath?: string): string | null;
+declare function resolveColorRoles(index: FlatIndex, themeIndex: FlatIndex): ResolvedColors;
+declare function buildTypography(index: FlatIndex): TypographyMap;
+declare function buildRounded(index: FlatIndex): RoundedMap;
+declare function buildSpacing(index: FlatIndex): SpacingMap | null;
+declare function readContainers(index: FlatIndex): ContainerInfo;
+//# sourceMappingURL=to-design-md.resolve.d.ts.map

package/dist/serialize/to-design-md.resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-design-md.resolve.d.ts","sourceRoot":"","sources":["../../src/serialize/to-design-md.resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACjF,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,sBAAsB,CAAC;AAI9B,YAAY,EAAE,cAAc,EAAE,CAAC;AAC/B,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,iBAAiB,GAClB,CAAC;AAIF,KAAK,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE9C,UAAU,cAAc;IACtB,KAAK,EAAE,UAAU,CAAC;IAClB,YAAY,EAAE,iBAAiB,CAAC;CACjC;AAID,iBAAS,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,SAAS,CAMrD;AAED,iBAAS,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,CAI1D;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,GAAG,CAAC,MAAM,CAAa,EAChC,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CA0Bf;AAiCD,iBAAS,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,GAAG,cAAc,CAqClF;AAID,iBAAS,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,aAAa,CAYxD;AAmBD,iBAAS,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CA+BlD;AAOD,iBAAS,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,IAAI,CA+BzD;AAID,iBAAS,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,aAAa,CAavD"}