@nebutra/design-sync 0.1.1 → 2.0.0

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAoGA,wBAAsB,GAAG,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyDxE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAgHA,wBAAsB,GAAG,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8ExE"}

package/dist/cli/index.js

@@ -16,12 +16,15 @@
 // =============================================================================
 import { describeEnv } from "../detect";
 import { createDesignSync } from "../factory";
+import { compileBrandFromTokenSets } from "../serialize/to-brand-package";
 function parseArgs(argv) {
     const [, , command = "help", ...rest] = argv;
     let dryRun = false;
     let json = false;
     const themes = [];
     let provider;
+    let brandId;
+    let brandName;
     for (let i = 0; i < rest.length; i++) {
         const arg = rest[i];
         if (arg === "--dry-run")
@@ -46,8 +49,14 @@ function parseArgs(argv) {
                 i++;
             }
         }
+        else if (arg === "--id") {
+            brandId = rest[++i];
+        }
+        else if (arg === "--name") {
+            brandName = rest[++i];
+        }
     }
-    return { command, dryRun, json, themes, provider };
+    return { command, dryRun, json, themes, provider, brandId, brandName };
 }
 function emit(payload, json) {
     if (json) {
@@ -77,12 +86,15 @@ Commands:
   detect            Print the resolved provider + env diagnostics
   healthcheck       Run the provider's healthcheck()
   pull              Pull design-tool → repo (DTCG JSON)
-  push              Push repo → design-tool (defaults to dry-run on figma/penpot)
+  push              Push repo → design-tool (defaults to dry-run on figma/penpot/design-md)
+  brand             Pull tokens then compile a Brand Package (Create Center)
   help              Show this message
 
 Options:
-  --provider <X>    Override provider (figma|penpot|git-only|memory)
+  --provider <X>    Override provider (figma|penpot|git-only|memory|design-md)
   --themes a,b      Restrict to specific token sets
+  --id <id>         Brand package id (for brand command)
+  --name <name>     Brand package display name
   --dry-run         Force dry-run on push
   --json            Emit machine-readable JSON
 `;
@@ -124,6 +136,23 @@ export async function run(argv = process.argv) {
                 : `${result.summary} (provider=${result.provider}, dryRun=${result.dryRun})`, args.json);
             return 0;
         }
+        if (args.command === "brand") {
+            const themes = args.themes.length > 0 ? { themes: args.themes } : {};
+            const pull = await provider.pull(themes);
+            const compiled = compileBrandFromTokenSets(pull.sets, {
+                ...(args.brandId ? { id: args.brandId } : {}),
+                ...(args.brandName ? { name: args.brandName } : {}),
+            });
+            emit(args.json
+                ? {
+                    provider: pull.provider,
+                    brand: compiled.brand,
+                    css: compiled.css,
+                    warnings: compiled.warnings,
+                }
+                : `brand=${compiled.brand.id} recipe=${compiled.brand.recipe.buttonDefault} fonts=${compiled.brand.typography.faces?.length ?? 0} warnings=${compiled.warnings.length}`, args.json);
+            return 0;
+        }
         emitError(`unknown command: ${args.command}\n\n${HELP_TEXT}`, args.json);
         return 2;
     }

package/dist/detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAsBtD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,sBAAsB,GAAG,SAAS,CAOpC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,sBAAsB,CAa3F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG;IACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,sBAAsB,CAAC;CAClC,CA0BA"}
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAuBtD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,sBAAsB,GAAG,SAAS,CAOpC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,sBAAsB,CAa3F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG;IACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,sBAAsB,CAAC;CAClC,CA2BA"}

package/dist/detect.js

@@ -7,14 +7,15 @@
 //   3. PENPOT_API_URL + PENPOT_TOKEN                → "penpot"
 //   4. fallback                                      → "git-only"
 //
-// `memory` is never auto-detected; it must be requested explicitly via the
-// DESIGN_SYNC_PROVIDER env var or a config object (used in tests).
+// `memory` and `design-md` are never auto-detected; they must be requested
+// explicitly via the DESIGN_SYNC_PROVIDER env var or a config object.
 // =============================================================================
 const VALID_PROVIDERS = new Set([
     "figma",
     "penpot",
     "git-only",
     "memory",
+    "design-md",
 ]);
 /**
  * Read `DESIGN_SYNC_PROVIDER` from the environment, validate it, and return
@@ -64,6 +65,7 @@ export function describeEnv(env = process.env) {
         "PENPOT_TOKEN",
         "PENPOT_FILE_ID",
         "PENPOT_TEAM_ID",
+        "DESIGN_MD_PATH",
     ];
     for (const key of known) {
         if (env[key]?.trim())

package/dist/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAA0B,MAAM,SAAS,CAAC;AAe5F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiC7F;AAED;;;GAGG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAKjE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAA0B,MAAM,SAAS,CAAC;AAe5F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAuC7F;AAED;;;GAGG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAKjE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/factory.js

@@ -61,6 +61,11 @@ export async function createDesignSync(config) {
             const memConfig = config?.provider === "memory" ? config : undefined;
             return new MemoryProvider(memConfig ?? { provider: "memory" });
         }
+        case "design-md": {
+            const { DesignMdProvider } = await import("./providers/design-md");
+            const mdConfig = config?.provider === "design-md" ? config : undefined;
+            return new DesignMdProvider(mdConfig ?? { provider: "design-md" });
+        }
         default:
             throw new Error(`Unknown design-sync provider: ${providerType}`);
     }

package/dist/index.d.ts

@@ -3,10 +3,14 @@ export { createDesignSync, getDesignSync, resetDesignSync, setDesignSync, } from
 export type { FigmaTokensStudioConfig } from "./figma-config/index";
 export { FIGMA_TOKENS_STUDIO_CONFIG } from "./figma-config/index";
 export { defaultTokensDir, defaultTokensStudioDir, readTokenSets, validateDtcgTree, writeTokenSet, } from "./io";
+export type { DesignMdProvider } from "./providers/design-md";
 export { FigmaProvider } from "./providers/figma";
 export { GitOnlyProvider } from "./providers/git-only";
 export { MemoryProvider } from "./providers/memory";
 export { PenpotProvider } from "./providers/penpot";
-export type { BaseProviderConfig, DesignSyncConfig, DesignSyncProvider, DesignSyncProviderType, DesignTokenLeaf, DesignTokenSet, DesignTokenTree, FigmaProviderConfig, GitOnlyProviderConfig, HealthStatus, MemoryProviderConfig, PenpotProviderConfig, PullOptions, PullResult, PushOptions, PushResult, } from "./types";
+export { compileBrandFromTokenSets, mergeTokenTrees, pullAndCompileBrand, serializeToBrandCss, type ToBrandPackageOptions, tokenSetsToReferoShape, } from "./serialize/to-brand-package";
+export { serializeToDesignMd, type ToDesignMdOptions } from "./serialize/to-design-md";
+export { serializeToPreviewHtml, type ToPreviewHtmlOptions, } from "./serialize/to-preview-html";
+export type { BaseProviderConfig, DesignMdProviderConfig, DesignSyncConfig, DesignSyncProvider, DesignSyncProviderType, DesignTokenLeaf, DesignTokenSet, DesignTokenTree, FigmaProviderConfig, GitOnlyProviderConfig, HealthStatus, MemoryProviderConfig, PenpotProviderConfig, PullOptions, PullResult, PushOptions, PushResult, } from "./types";
 export { DesignTokenLeafSchema } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAE/E,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,MAAM,CAAC;AAEd,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAE/E,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,MAAM,CAAC;AASd,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EACL,yBAAyB,EACzB,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,qBAAqB,EAC1B,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAEvF,OAAO,EACL,sBAAsB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -6,6 +6,7 @@
 //   - Penpot                  (REST API, self-hostable, China-friendly)
 //   - git-only                (zero-config default — DTCG files only)
 //   - memory                  (test fixture)
+//   - design-md               (AI-native DESIGN.md, markdown + YAML front matter)
 //
 // Usage:
 //   import { getDesignSync } from "@nebutra/design-sync";
@@ -23,10 +24,15 @@ export { createDesignSync, getDesignSync, resetDesignSync, setDesignSync, } from
 export { FIGMA_TOKENS_STUDIO_CONFIG } from "./figma-config/index";
 // ── DTCG I/O helpers (re-exported for advanced consumers) ───────────────────
 export { defaultTokensDir, defaultTokensStudioDir, readTokenSets, validateDtcgTree, writeTokenSet, } from "./io";
-// ── Providers (tree-shakable direct imports) ────────────────────────────────
 export { FigmaProvider } from "./providers/figma";
 export { GitOnlyProvider } from "./providers/git-only";
 export { MemoryProvider } from "./providers/memory";
 export { PenpotProvider } from "./providers/penpot";
+// ── DTCG → Brand Package (Create Center) ───────────────────────────────────
+export { compileBrandFromTokenSets, mergeTokenTrees, pullAndCompileBrand, serializeToBrandCss, tokenSetsToReferoShape, } from "./serialize/to-brand-package";
+// ── DTCG → DESIGN.md serializer ────────────────────────────────────────────
+export { serializeToDesignMd } from "./serialize/to-design-md";
+// ── DTCG → preview.html serializer ─────────────────────────────────────────
+export { serializeToPreviewHtml, } from "./serialize/to-preview-html";
 // ── Types ───────────────────────────────────────────────────────────────────
 export { DesignTokenLeafSchema } from "./types";

package/dist/io.js

@@ -85,7 +85,7 @@ export async function readTokenSets(tokensDir) {
             throw new Error(`[design-sync] DTCG file ${file} must contain an object at the root.`);
         }
         const relativePath = relative(tokensDir, file).split(sep).join("/");
-        const name = relativePath.replace(/\.json$/u, "").replace(/\//gu, "/");
+        const name = relativePath.replace(/\.json$/u, "");
         sets.push({
             name,
             relativePath,

package/dist/providers/design-md.d.ts

@@ -0,0 +1,49 @@
+import type { LintReport } from "@google/design.md/linter";
+import type { DesignMdProviderConfig, DesignSyncProvider, HealthStatus, PullOptions, PullResult, PushOptions, PushResult } from "../types";
+export { type ImportReport, importFromDesignMd } from "../serialize/from-design-md";
+/**
+ * Derive the preview file path from the DESIGN.md path.
+ *
+ * Replaces a trailing `.md` extension with `.preview.html`;
+ * if the path does not end in `.md`, appends `.preview.html`.
+ *
+ * Examples:
+ *   "/repo/DESIGN.md"        → "/repo/DESIGN.preview.html"
+ *   "/repo/design/tokens.md" → "/repo/design/tokens.preview.html"
+ *   "/repo/DESIGN"           → "/repo/DESIGN.preview.html"
+ */
+export declare function previewHtmlPathFor(mdPath: string): string;
+/**
+ * Throw if the LintReport contains any error-severity findings.
+ * Warnings do not throw — they are surfaced in the push summary.
+ * Used as the fail-closed gate before writing a DESIGN.md.
+ *
+ * Fail-closed on either signal: error-severity findings in `findings[]`
+ * OR a non-zero `summary.errors` count.
+ *
+ * @param report - The LintReport returned by `lint(content)`.
+ * @param source - A human-readable label for the file (used in the error message).
+ * @throws When error-severity findings are present or `summary.errors > 0`.
+ */
+export declare function assertLintClean(report: LintReport, source: string): void;
+/**
+ * Dynamically imports the @google/design.md linter and runs it on `content`.
+ * Extracted as a named export so tests can verify the `[design-md]`-prefixed
+ * error thrown when the dynamic import or lint call itself fails.
+ *
+ * @throws When the linter import or invocation throws — error is wrapped with a
+ *   `[design-md] Lint gate failed to run on <label>:` prefix.
+ */
+export declare function runLintGate(content: string, label: string): Promise<LintReport>;
+export declare class DesignMdProvider implements DesignSyncProvider {
+    readonly name: "design-md";
+    private readonly tokensDir;
+    private readonly designMdPath;
+    private readonly designSystemName;
+    private readonly designSystemDescription;
+    constructor(config: DesignMdProviderConfig);
+    pull(options?: PullOptions): Promise<PullResult>;
+    push(options?: PushOptions): Promise<PushResult>;
+    healthcheck(): Promise<HealthStatus>;
+}
+//# sourceMappingURL=design-md.d.ts.map

package/dist/providers/design-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-md.d.ts","sourceRoot":"","sources":["../../src/providers/design-md.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAM3D,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACX,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,KAAK,YAAY,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAuBpF;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKzD;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAUxE;AAID;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CASrF;AAID,qBAAa,gBAAiB,YAAW,kBAAkB;IACzD,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IAErC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAqB;gBAEjD,MAAM,EAAE,sBAAsB;IAcpC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAuDpD,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAoEpD,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;CAyD3C"}

package/dist/providers/design-md.js

@@ -0,0 +1,264 @@
+import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { logger } from "@nebutra/logger";
+import { defaultTokensDir, readTokenSets, writeTokenSet } from "../io";
+import { importFromDesignMd } from "../serialize/from-design-md";
+import { serializeToDesignMd } from "../serialize/to-design-md";
+import { serializeToPreviewHtml } from "../serialize/to-preview-html";
+export { importFromDesignMd } from "../serialize/from-design-md";
+// =============================================================================
+// DesignMd Provider — AI-native DESIGN.md format (@google/design.md)
+// =============================================================================
+// The "design tool" here is a DESIGN.md file in the repo root (or a
+// configurable path). Push = repo DTCG → DESIGN.md (with official lint gate).
+// Pull = DESIGN.md → a `themes/<brand>.json` DTCG file in tokensDir.
+//
+// Why DESIGN.md?
+//   - Zero external dependencies at runtime (just a file in git)
+//   - AI-native: models can read/write DESIGN.md directly
+//   - Google's @google/design.md spec mandates lint rules (broken-ref, contrast)
+//   - Bridges the gap for indie hackers who want typed tokens without a design tool
+// =============================================================================
+/**
+ * Default DESIGN.md path: <cwd>/DESIGN.md
+ */
+function defaultDesignMdPath(cwd = process.cwd()) {
+    return join(cwd, "DESIGN.md");
+}
+/**
+ * Derive the preview file path from the DESIGN.md path.
+ *
+ * Replaces a trailing `.md` extension with `.preview.html`;
+ * if the path does not end in `.md`, appends `.preview.html`.
+ *
+ * Examples:
+ *   "/repo/DESIGN.md"        → "/repo/DESIGN.preview.html"
+ *   "/repo/design/tokens.md" → "/repo/design/tokens.preview.html"
+ *   "/repo/DESIGN"           → "/repo/DESIGN.preview.html"
+ */
+export function previewHtmlPathFor(mdPath) {
+    if (mdPath.endsWith(".md")) {
+        return `${mdPath.slice(0, -3)}.preview.html`;
+    }
+    return `${mdPath}.preview.html`;
+}
+// ─── Lint Gate ────────────────────────────────────────────────────────────────
+/**
+ * Throw if the LintReport contains any error-severity findings.
+ * Warnings do not throw — they are surfaced in the push summary.
+ * Used as the fail-closed gate before writing a DESIGN.md.
+ *
+ * Fail-closed on either signal: error-severity findings in `findings[]`
+ * OR a non-zero `summary.errors` count.
+ *
+ * @param report - The LintReport returned by `lint(content)`.
+ * @param source - A human-readable label for the file (used in the error message).
+ * @throws When error-severity findings are present or `summary.errors > 0`.
+ */
+export function assertLintClean(report, source) {
+    const errorFindings = report.findings.filter((f) => f.severity === "error");
+    if (errorFindings.length === 0 && report.summary.errors === 0)
+        return;
+    const count = errorFindings.length || report.summary.errors;
+    const detail = errorFindings
+        .map((f) => (f.path ? `  ${f.path}: ${f.message}` : `  ${f.message}`))
+        .join("\n");
+    throw new Error(`[design-md] Lint failed for ${source} — ${count} error(s):\n${detail}`);
+}
+// ─── Lint Runner ─────────────────────────────────────────────────────────────
+/**
+ * Dynamically imports the @google/design.md linter and runs it on `content`.
+ * Extracted as a named export so tests can verify the `[design-md]`-prefixed
+ * error thrown when the dynamic import or lint call itself fails.
+ *
+ * @throws When the linter import or invocation throws — error is wrapped with a
+ *   `[design-md] Lint gate failed to run on <label>:` prefix.
+ */
+export async function runLintGate(content, label) {
+    try {
+        const { lint } = await import("@google/design.md/linter");
+        return lint(content);
+    }
+    catch (err) {
+        throw new Error(`[design-md] Lint gate failed to run on ${label}: ${err?.message ?? String(err)}`);
+    }
+}
+// ─── Provider ────────────────────────────────────────────────────────────────
+export class DesignMdProvider {
+    name = "design-md";
+    tokensDir;
+    designMdPath;
+    designSystemName;
+    designSystemDescription;
+    constructor(config) {
+        this.tokensDir = config.tokensDir ?? defaultTokensDir();
+        this.designMdPath = config.designMdPath ?? process.env.DESIGN_MD_PATH ?? defaultDesignMdPath();
+        this.designSystemName = config.name;
+        this.designSystemDescription = config.description;
+        logger.info("[design-sync:design-md] Provider initialised", {
+            tokensDir: this.tokensDir,
+            designMdPath: this.designMdPath,
+        });
+    }
+    // ── Pull: DESIGN.md → tokensDir/themes/<brand>.json ──────────────────────
+    async pull(options = {}) {
+        // Graceful handling: if DESIGN.md does not exist, return an empty result.
+        let content;
+        try {
+            content = await readFile(this.designMdPath, "utf8");
+        }
+        catch {
+            logger.warn("[design-sync:design-md] DESIGN.md not found, returning empty pull result", {
+                designMdPath: this.designMdPath,
+            });
+            return {
+                sets: [],
+                written: false,
+                provider: "design-md",
+                pulledAt: new Date().toISOString(),
+                summary: `design-md: DESIGN.md not found at ${this.designMdPath} — no sets pulled`,
+            };
+        }
+        const { set, report } = importFromDesignMd(content);
+        if (report.warnings.length > 0 || report.missingRequired.length > 0) {
+            logger.warn("[design-sync:design-md] imported DESIGN.md has gaps", {
+                warnings: report.warnings.length,
+                missingRequired: report.missingRequired,
+            });
+        }
+        const dryRun = options.dryRun ?? false;
+        if (!dryRun) {
+            await writeTokenSet(this.tokensDir, set);
+            logger.info("[design-sync:design-md] pull wrote token set", {
+                relativePath: set.relativePath,
+            });
+        }
+        const missingCount = report.missingRequired.length;
+        const unmappedCount = report.unmapped.length;
+        const reportSuffix = missingCount > 0 || unmappedCount > 0
+            ? ` (missingRequired: ${missingCount}, unmapped: ${unmappedCount})`
+            : "";
+        return {
+            sets: [set],
+            written: !dryRun,
+            provider: "design-md",
+            pulledAt: new Date().toISOString(),
+            summary: dryRun
+                ? `design-md: dry-run — would write ${set.relativePath}${reportSuffix}`
+                : `design-md: wrote ${set.relativePath}${reportSuffix}`,
+        };
+    }
+    // ── Push: tokensDir → DESIGN.md (with official lint gate) ────────────────
+    async push(options = {}) {
+        const all = await readTokenSets(this.tokensDir);
+        // Serialize all sets into DESIGN.md content.
+        const content = serializeToDesignMd(all, {
+            ...(this.designSystemName !== undefined ? { name: this.designSystemName } : {}),
+            ...(this.designSystemDescription !== undefined
+                ? { description: this.designSystemDescription }
+                : {}),
+        });
+        // Compute a consistent, human-readable path label (relative preferred).
+        const mdLabel = relative(process.cwd(), this.designMdPath) || this.designMdPath;
+        // Run the official lint gate — fail closed on any error finding.
+        const lintReport = await runLintGate(content, mdLabel);
+        // Collect warnings for the summary (they don't block the write).
+        const warnings = lintReport.findings
+            .filter((f) => f.severity === "warning")
+            .map((f) => (f.path ? `${f.path}: ${f.message}` : f.message));
+        // Throw if any error-severity findings are present.
+        assertLintClean(lintReport, mdLabel);
+        // Compute the sibling preview path (before the write, so it's always defined)
+        const previewPath = previewHtmlPathFor(this.designMdPath);
+        const dryRun = options.dryRun ?? false;
+        if (!dryRun) {
+            await mkdir(dirname(this.designMdPath), { recursive: true });
+            await writeFile(this.designMdPath, content, "utf8");
+            logger.info("[design-sync:design-md] push wrote DESIGN.md", {
+                designMdPath: this.designMdPath,
+                sets: all.length,
+            });
+            // Generate and write the sibling visual preview
+            const previewHtml = serializeToPreviewHtml(all, {
+                ...(this.designSystemName !== undefined ? { name: this.designSystemName } : {}),
+            });
+            await writeFile(previewPath, previewHtml, "utf8");
+            logger.info("[design-sync:design-md] push wrote preview", {
+                previewPath,
+            });
+        }
+        else {
+            logger.info("[design-sync:design-md] push dry-run — lint passed, files NOT written", {
+                designMdPath: this.designMdPath,
+                previewPath,
+            });
+        }
+        const warnSuffix = warnings.length > 0 ? ` (${warnings.length} warning(s))` : "";
+        return {
+            pushed: !dryRun,
+            sets: dryRun ? [this.designMdPath] : [this.designMdPath, previewPath],
+            provider: "design-md",
+            pushedAt: new Date().toISOString(),
+            summary: dryRun
+                ? `design-md: dry-run — lint passed, would write ${mdLabel}${warnSuffix}`
+                : `design-md: wrote ${mdLabel} from ${all.length} DTCG set(s)${warnSuffix}`,
+            dryRun,
+        };
+    }
+    // ── Healthcheck ───────────────────────────────────────────────────────────
+    async healthcheck() {
+        const detected = [];
+        const missing = [];
+        // 1. Check tokensDir exists.
+        let tokensDirOk = false;
+        try {
+            const info = await stat(this.tokensDir);
+            if (info.isDirectory()) {
+                tokensDirOk = true;
+                detected.push("tokensDir");
+            }
+            else {
+                missing.push("tokensDir (not a directory)");
+            }
+        }
+        catch {
+            missing.push("tokensDir (does not exist)");
+        }
+        // 2. Check the @google/design.md lib is importable (it's a dep, should always be).
+        let lintLibOk = false;
+        try {
+            await import("@google/design.md/linter");
+            lintLibOk = true;
+            detected.push("@google/design.md");
+        }
+        catch {
+            missing.push("@google/design.md (lib not importable)");
+        }
+        // 3. List DESIGN_MD_PATH in detectedEnv when it's set (it's optional, not required).
+        const envPath = process.env.DESIGN_MD_PATH;
+        if (envPath) {
+            detected.push(`DESIGN_MD_PATH=${envPath}`);
+        }
+        // 4. Check the parent directory of designMdPath is accessible.
+        let mdDirOk = false;
+        const mdDir = dirname(this.designMdPath);
+        try {
+            await access(mdDir);
+            mdDirOk = true;
+            detected.push("designMdPath.parent");
+        }
+        catch {
+            missing.push("designMdPath.parent (not accessible)");
+        }
+        const ok = tokensDirOk && lintLibOk && mdDirOk;
+        return {
+            ok,
+            provider: "design-md",
+            message: ok
+                ? `design-md: ready — tokensDir found, lint lib present, designMdPath=${this.designMdPath}`
+                : `design-md: not ready — missing: ${missing.join(", ")}`,
+            detectedEnv: detected,
+            missingEnv: missing,
+        };
+    }
+}

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

@@ -0,0 +1,80 @@
+/**
+ * DESIGN.md → DTCG theme importer
+ *
+ * Parse approach: programmatic via `lint()` from `@google/design.md/linter`.
+ * The `lint()` function parses the DESIGN.md content synchronously and returns
+ * a `DesignSystemState` with typed Maps for colors, rounded, spacing, and
+ * typography. We reshape that state into our DTCG naming convention:
+ *   - colors.<x>   → color.<x>    ($type: "color",      $value: hex string)
+ *   - rounded.<x>  → radius.<x>   ($type: "dimension",  $value: "<n><unit>" string)
+ *   - spacing.<x>  → spacing.<x>  ($type: "dimension",  $value: "<n><unit>" string)
+ *   - body font    → fontFamily.sans ($type: "fontFamily", $value: string)
+ *
+ * PROSE-COLOR FALLBACK: When @google/design.md extracts zero colors (e.g. the
+ * VoltAgent extended DESIGN.md format where colors are written as markdown prose
+ * rather than YAML front-matter), `extractColorsFromProse` is called to scrape
+ * labeled color literals of the form `**Label** (\`<value>\`)`.
+ *
+ * NEVER import `@google/design.md` (main entry — auto-runs CLI). Only the
+ * `@google/design.md/linter` subpath export is used here.
+ *
+ * All @google/design.md coupling is isolated in THIS file.
+ */
+import type { DesignTokenSet } from "../types";
+export interface ImportReport {
+    /** Human-readable strings noting content that has no structured DTCG equivalent. */
+    unmapped: string[];
+    /** Registry-required token keys absent from the produced tree (dot-path format). */
+    missingRequired: string[];
+    /** Non-fatal warnings encountered during import. */
+    warnings: string[];
+}
+export interface ImportResult {
+    set: DesignTokenSet;
+    report: ImportReport;
+}
+export interface ImportFromDesignMdOptions {
+    /**
+     * Override the slug used for `relativePath` and `name`.
+     * Takes precedence over the `name` field in the DESIGN.md front matter.
+     */
+    brandName?: string;
+}
+/**
+ * Extract color entries from DESIGN.md prose content (VoltAgent extended format).
+ *
+ * Looks for labeled color literals matching: `**Label** (\`<value>\`)`
+ * where `<value>` is a valid CSS color (hex, rgb, rgba, hsl, hsla, oklch).
+ *
+ * Also handles the `{colors.xxx} — #hex` variant (backtick-quoted or unquoted hex).
+ *
+ * Scoping: if a heading matching `/^#{1,3}\s+.*colou?r/i` exists in the
+ * document, extraction is limited to the content under that heading (up to
+ * the next same-or-higher heading). Otherwise the whole document is scanned.
+ *
+ * Effect labels (shadow, overlay, glow, gradient, elevation, blur, scrim) are
+ * excluded regardless of scoping — they describe visual effects, not palette colors.
+ *
+ * Token naming: labels are kebab-cased (`"Spotify Green"` → `"spotify-green"`).
+ * De-duplicates by token name (first wins). Capped at 48 entries.
+ *
+ * Returns a plain `Record<string, string>` mapping slug → raw CSS color string.
+ *
+ * @public — exported so tests can unit-test the helper directly.
+ */
+export declare function extractColorsFromProse(content: string): Record<string, string>;
+/**
+ * Parse a DESIGN.md document and produce a DTCG-compliant `DesignTokenSet`
+ * scoped to the `themes/` bucket (SSOT-safe — never overwrites core or semantic).
+ *
+ * The function is SYNCHRONOUS; it never reads from or writes to the filesystem.
+ *
+ * @param content - Raw DESIGN.md content (markdown + YAML front matter).
+ * @param options - Optional: `brandName` to override the slug.
+ * @returns `ImportResult` containing the token set and a diagnostic report.
+ * @throws If `@google/design.md` fails to parse the content, or if the produced
+ *         DTCG tree is invalid (invalid leaves). Empty input produces an
+ *         empty-but-valid tree and does NOT throw.
+ */
+export declare function importFromDesignMd(content: string, options?: ImportFromDesignMdOptions): ImportResult;
+//# sourceMappingURL=from-design-md.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"from-design-md.d.ts","sourceRoot":"","sources":["../../src/serialize/from-design-md.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,UAAU,CAAC;AAIhE,MAAM,WAAW,YAAY;IAC3B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oFAAoF;IACpF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAg5BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO9E;AAsKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,yBAAyB,GAClC,YAAY,CA0Td"}