design-pact 0.2.2 → 0.3.1

package/dist/cli.js

@@ -890,21 +890,21 @@ var require_react_development = __commonJS({
         );
         actScopeDepth = prevActScopeDepth;
       }
-      function recursivelyFlushAsyncActWork(returnValue, resolve3, reject) {
+      function recursivelyFlushAsyncActWork(returnValue, resolve4, reject) {
         var queue = ReactSharedInternals.actQueue;
         if (null !== queue)
           if (0 !== queue.length)
             try {
               flushActQueue(queue);
               enqueueTask(function() {
-                return recursivelyFlushAsyncActWork(returnValue, resolve3, reject);
+                return recursivelyFlushAsyncActWork(returnValue, resolve4, reject);
               });
               return;
             } catch (error) {
               ReactSharedInternals.thrownErrors.push(error);
             }
           else ReactSharedInternals.actQueue = null;
-        0 < ReactSharedInternals.thrownErrors.length ? (queue = aggregateErrors(ReactSharedInternals.thrownErrors), ReactSharedInternals.thrownErrors.length = 0, reject(queue)) : resolve3(returnValue);
+        0 < ReactSharedInternals.thrownErrors.length ? (queue = aggregateErrors(ReactSharedInternals.thrownErrors), ReactSharedInternals.thrownErrors.length = 0, reject(queue)) : resolve4(returnValue);
       }
       function flushActQueue(queue) {
         if (!isFlushing) {
@@ -1091,7 +1091,7 @@ var require_react_development = __commonJS({
             ));
           });
           return {
-            then: function(resolve3, reject) {
+            then: function(resolve4, reject) {
               didAwaitActCall = true;
               thenable.then(
                 function(returnValue) {
@@ -1101,7 +1101,7 @@ var require_react_development = __commonJS({
                       flushActQueue(queue), enqueueTask(function() {
                         return recursivelyFlushAsyncActWork(
                           returnValue,
-                          resolve3,
+                          resolve4,
                           reject
                         );
                       });
@@ -1115,7 +1115,7 @@ var require_react_development = __commonJS({
                       ReactSharedInternals.thrownErrors.length = 0;
                       reject(_thrownError);
                     }
-                  } else resolve3(returnValue);
+                  } else resolve4(returnValue);
                 },
                 function(error) {
                   popActScope(prevActQueue, prevActScopeDepth);
@@ -1137,15 +1137,15 @@ var require_react_development = __commonJS({
         if (0 < ReactSharedInternals.thrownErrors.length)
           throw callback = aggregateErrors(ReactSharedInternals.thrownErrors), ReactSharedInternals.thrownErrors.length = 0, callback;
         return {
-          then: function(resolve3, reject) {
+          then: function(resolve4, reject) {
             didAwaitActCall = true;
             0 === prevActScopeDepth ? (ReactSharedInternals.actQueue = queue, enqueueTask(function() {
               return recursivelyFlushAsyncActWork(
                 returnValue$jscomp$0,
-                resolve3,
+                resolve4,
                 reject
               );
-            })) : resolve3(returnValue$jscomp$0);
+            })) : resolve4(returnValue$jscomp$0);
           }
         };
       };
@@ -1451,8 +1451,8 @@ var require_react = __commonJS({
 });
 
 // src/cli.ts
-import { readFileSync as readFileSync2, writeFileSync, mkdirSync } from "fs";
-import { join as join3, resolve as resolve2 } from "path";
+import { readFileSync as readFileSync3, writeFileSync, mkdirSync, existsSync as existsSync2 } from "fs";
+import { join as join3, resolve as resolve3 } from "path";
 
 // src/locale.ts
 var envLang = (process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || "").toLowerCase();
@@ -1497,6 +1497,33 @@ function parseDesignSystem(md) {
 import { converter, formatHex, parse, formatCss } from "culori";
 var toOklch = converter("oklch");
 var toRgb = converter("rgb");
+function hexToOklch(hex) {
+  const c = toOklch(parse(hex));
+  if (!c) return { mode: "oklch", l: 0, c: 0, h: 0 };
+  return { ...c, h: c.h ?? 0 };
+}
+function oklchToHex(c) {
+  const rgb = toRgb(c);
+  if (!rgb) return "#000000";
+  const clamp2 = (v) => Math.max(0, Math.min(1, v));
+  return formatHex({ ...rgb, r: clamp2(rgb.r), g: clamp2(rgb.g), b: clamp2(rgb.b) }) || "#000000";
+}
+function relativeLuminance(hex) {
+  const rgb = toRgb(parse(hex));
+  if (!rgb) return 0;
+  const lin = (v) => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  return 0.2126 * lin(rgb.r) + 0.7152 * lin(rgb.g) + 0.0722 * lin(rgb.b);
+}
+function contrastRatio(a, b) {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+  return (hi + 0.05) / (lo + 0.05);
+}
+function oklchString(hex) {
+  const c = hexToOklch(hex);
+  return formatCss(c) || "";
+}
 
 // ../../lib/scales.ts
 var SPACING_STEPS = [
@@ -1596,6 +1623,7 @@ function buildOpacityScale(base) {
 }
 
 // ../../lib/tokens-core.ts
+var SEMANTIC_KINDS = ["success", "warning", "error", "info"];
 var defaultTypography = {
   base: 16,
   ratio: 1.25,
@@ -1635,6 +1663,95 @@ function buildScale(t2) {
 }
 
 // ../../lib/export.ts
+var OPACITY_USAGE = {
+  hover: "tint/overlay on hover (e.g. button or row background)",
+  pressed: "active/pressed feedback",
+  focus: "focus ring or focused-row background",
+  disabled: "opacity of disabled controls",
+  overlay: "modal/drawer backdrop scrim"
+};
+function w3cTokens(colors, typography, spacing, radius, shadow, motion, border, opacity, darkColors, semantic, darkSemantic) {
+  const darkById = new Map((darkColors ?? []).map((c) => [c.id, c.displayHex]));
+  const colorGroup = {};
+  for (const c of colors) {
+    const key = c.role === "unassigned" ? c.id : c.role;
+    const ext = {
+      proportion: c.proportion,
+      oklch: oklchString(c.displayHex)
+    };
+    const dark = darkById.get(c.id);
+    if (dark) ext.dark = dark;
+    colorGroup[key] = {
+      $value: c.displayHex,
+      $type: "color",
+      $extensions: { "design-pact": ext }
+    };
+  }
+  const fontSizes = {};
+  for (const s of buildScale(typography)) {
+    fontSizes[s.name] = { $value: `${s.rem}rem`, $type: "dimension" };
+  }
+  const spacingGroup = {};
+  for (const s of buildSpacing(spacing.base)) {
+    spacingGroup[s.name] = { $value: `${s.px}px`, $type: "dimension" };
+  }
+  const radiusGroup = {};
+  for (const r of buildRadius(radius.base)) {
+    radiusGroup[r.name] = { $value: `${r.px}px`, $type: "dimension" };
+  }
+  const shadowGroup = {};
+  for (const level of ["sm", "md", "lg"]) {
+    shadowGroup[level] = { $value: shadowToCss(shadow[level]), $type: "shadow" };
+  }
+  const motionGroup = {};
+  for (const d of buildDurations(motion.base)) {
+    motionGroup[`duration-${d.name}`] = { $value: `${d.ms}ms`, $type: "duration" };
+  }
+  motionGroup["easing"] = { $value: EASING_PRESETS[motion.easing], $type: "cubicBezier" };
+  const borderGroup = {};
+  for (const b of buildBorderScale(border.base)) {
+    borderGroup[b.name] = { $value: `${b.px}px`, $type: "dimension" };
+  }
+  const opacityGroup = {};
+  for (const o of buildOpacityScale(opacity.base)) {
+    opacityGroup[o.name] = { $value: o.value, $type: "number" };
+  }
+  const semanticGroup = semantic ? Object.fromEntries(
+    SEMANTIC_KINDS.map((k) => [
+      k,
+      {
+        $value: semantic[k],
+        $type: "color",
+        ...darkSemantic ? { $extensions: { "design-pact": { dark: darkSemantic[k] } } } : {}
+      }
+    ])
+  ) : void 0;
+  return {
+    color: colorGroup,
+    ...semanticGroup ? { semantic: semanticGroup } : {},
+    typography: {
+      fontFamily: {
+        body: { $value: typography.fontFamily, $type: "fontFamily" },
+        heading: { $value: typography.headingFamily, $type: "fontFamily" }
+      },
+      fontSize: fontSizes,
+      fontWeight: { $value: typography.fontWeight, $type: "fontWeight" },
+      fontWeightHeading: { $value: headingWeight(typography.fontWeight), $type: "fontWeight" },
+      fontWeightBold: { $value: boldWeight(typography.fontWeight), $type: "fontWeight" },
+      lineHeight: { $value: typography.lineHeight, $type: "number" },
+      letterSpacing: { $value: `${typography.letterSpacing}em`, $type: "dimension" },
+      $extensions: {
+        "design-pact": { base: typography.base, ratio: typography.ratio }
+      }
+    },
+    spacing: spacingGroup,
+    borderRadius: radiusGroup,
+    borderWidth: borderGroup,
+    shadow: shadowGroup,
+    motion: motionGroup,
+    opacity: opacityGroup
+  };
+}
 function tailwindConfig(colors, typography, spacing, radius, shadow, motion, border, opacity) {
   const colorEntries = colors.map((c) => `        ${c.role === "unassigned" ? c.id : c.role}: "${c.displayHex}",`).join("\n");
   const sizeEntries = buildScale(typography).map((s) => `        "${s.name}": "${s.rem}rem",`).join("\n");
@@ -1694,6 +1811,205 @@ ${opacityEntries}
 };
 `;
 }
+function cssVars(colors, typography, spacing, radius, shadow, motion, border, opacity, darkColors, semantic, darkSemantic) {
+  const colorLines = colors.map((c) => `  --color-${c.role === "unassigned" ? c.id : c.role}: ${c.displayHex};`).join("\n");
+  const semanticLines = semantic ? "\n" + SEMANTIC_KINDS.map((k) => `  --color-${k}: ${semantic[k]};`).join("\n") : "";
+  const sizeLines = buildScale(typography).map((s) => `  --font-size-${s.name}: ${s.rem}rem;`).join("\n");
+  const spacingLines = buildSpacing(spacing.base).map((s) => `  --spacing-${s.name}: ${s.px}px;`).join("\n");
+  const radiusLines = buildRadius(radius.base).map((r) => `  --radius-${r.name}: ${r.px}px;`).join("\n");
+  const shadowLines = ["sm", "md", "lg"].map((level) => `  --shadow-${level}: ${shadowToCss(shadow[level])};`).join("\n");
+  const durationLines = buildDurations(motion.base).map((d) => `  --duration-${d.name}: ${d.ms}ms;`).join("\n");
+  const borderLines = buildBorderScale(border.base).map((b) => `  --border-${b.name}: ${b.px}px;`).join("\n");
+  const opacityLines = buildOpacityScale(opacity.base).map((o) => `  --opacity-${o.name}: ${o.value};`).join("\n");
+  const darkSemanticLines = darkColors && darkColors.length > 0 && darkSemantic ? "\n" + SEMANTIC_KINDS.map((k) => `    --color-${k}: ${darkSemantic[k]};`).join("\n") : "";
+  const darkBlock = darkColors && darkColors.length > 0 ? `
+@media (prefers-color-scheme: dark) {
+  :root {
+${darkColors.map((c) => `    --color-${c.role === "unassigned" ? c.id : c.role}: ${c.displayHex};`).join("\n")}${darkSemanticLines}
+  }
+}
+` : "";
+  return `:root {
+${colorLines}${semanticLines}
+  --font-family-body: ${typography.fontFamily};
+  --font-family-heading: ${typography.headingFamily};
+  --font-weight: ${typography.fontWeight};
+  --font-weight-heading: ${headingWeight(typography.fontWeight)};
+  --font-weight-bold: ${boldWeight(typography.fontWeight)};
+  --line-height: ${typography.lineHeight};
+  --letter-spacing: ${typography.letterSpacing}em;
+${sizeLines}
+${spacingLines}
+${radiusLines}
+${borderLines}
+${shadowLines}
+${durationLines}
+  --easing-standard: ${EASING_PRESETS[motion.easing]};
+${opacityLines}
+}
+${darkBlock}`;
+}
+function aiPrompt(colors, typography, spacing, radius, shadow, motion, border, opacity, darkColors, semantic, darkSemantic) {
+  const sorted = [...colors].sort((a, b) => b.proportion - a.proportion);
+  const palette = sorted.map(
+    (c) => `- ${c.role === "unassigned" ? c.id : c.role}: ${c.displayHex} (${(c.proportion * 100).toFixed(1)}% of source image)`
+  ).join("\n");
+  const scale = buildScale(typography).map((s) => `- ${s.name}: ${s.rem}rem (${s.px}px)`).join("\n");
+  const dominant = sorted[0];
+  const accent = sorted.find((c) => c.role === "accent") ?? sorted[1];
+  const primary = sorted.find((c) => c.role === "primary") ?? sorted[1];
+  const rootBlock = cssVars(colors, typography, spacing, radius, shadow, motion, border, opacity, darkColors, semantic, darkSemantic);
+  const semanticSection = semantic ? `
+## Status colors
+Use these for feedback only \u2014 never as brand/UI surface colors. \`--color-success\` ${semantic.success} (confirmations), \`--color-warning\` ${semantic.warning} (cautions), \`--color-error\` ${semantic.error} (errors/destructive), \`--color-info\` ${semantic.info} (informational). Reference via \`var(--color-\u2026)\`.${darkSemantic ? " In dark mode the `@media` block above overrides these with the dark-background variants \u2014 same convention as the brand colors." : ""}
+` : "";
+  const darkSection = darkColors && darkColors.length > 0 ? `
+## Dark mode
+The \`@media (prefers-color-scheme: dark)\` block above overrides COLOR variables only \u2014 every other token (type, spacing, radius, shadow, motion) stays identical in dark mode. Do not hand-pick dark colors or adjust non-color tokens for dark mode; the block is authoritative.
+` : "";
+  return `# Design system
+
+## Machine-readable tokens \u2014 COPY THIS BLOCK VERBATIM
+Paste the \`:root\` below into your \`<style>\` exactly as written, then reference
+every value through \`var(--\u2026)\`. This block is the single source of truth.
+
+Hard rules:
+- Do NOT redefine, round, rescale, or re-derive any value. Copy it character for character.
+- Do NOT introduce colors, fonts, font-sizes, spacing, radii, or shadows that are not declared here.
+- If you need a lighter/darker shade of a color, derive it in OKLCH by changing lightness only \u2014 keep hue and chroma fixed. Do not invent a new hue.
+- Every length in your CSS must be a \`var(--\u2026)\` reference. Do NOT convert a \`px\` token to \`rem\` (or any other unit) \u2014 reference it as-is. Spacing, radius, and border vars are in \`px\`; font sizes are in \`rem\`; keep each as declared.
+
+\`\`\`css
+${rootBlock}\`\`\`
+
+The prose below explains the intent behind these tokens. When prose and the \`:root\` block disagree, the block wins.
+
+---
+
+When generating UI from this token set, respect the following proportions and roles. The percentages reflect how much of the source design each color occupies \u2014 use them as a guide for surface area in the output.
+
+## Color palette
+${palette}
+
+The dominant background should occupy roughly ${(dominant.proportion * 100).toFixed(0)}% of the layout.
+
+Bind colors to roles exactly as the design tool renders them \u2014 do NOT swap primary and accent:
+
+- **primary (${primary.displayHex})** is the main interactive fill: primary buttons / CTAs, active nav item, key links, the logo mark. This is the button color.
+- **accent (${accent.displayHex})** is for SECONDARY emphasis only: badges/chips, chart & graphic accents, small highlights \u2014 typically ${Math.min(15, Math.round(accent.proportion * 100))}% or less of any screen. Do not use accent as the primary button fill.
+- **muted** for secondary/placeholder text, **border** for hairlines and dividers.
+
+## Typography
+Base size ${typography.base}px, modular scale ratio ${typography.ratio}.
+
+${scale}
+
+Body family: ${typography.fontFamily}
+Heading family: ${typography.headingFamily}
+Line-height: ${typography.lineHeight}, letter-spacing: ${typography.letterSpacing}em. There are three explicit font weights \u2014 bind them by role, and never let the browser default an element's weight:
+
+- **\`--font-weight\` (${typography.fontWeight})** \u2192 body text, labels, and any non-heading copy.
+- **\`--font-weight-heading\` (${headingWeight(typography.fontWeight)})** \u2192 all headings h1\u2013h5. Set this on every heading; do NOT leave headings at the body weight.
+- **\`--font-weight-bold\` (${boldWeight(typography.fontWeight)})** \u2192 emphasis only: primary CTA labels, \`<strong>\`, badges.
+
+## Spacing
+Base unit ${spacing.base}px. Use this 8-step scale for padding/margin/gap:
+
+${buildSpacing(spacing.base).map((s) => `- ${s.name}: ${s.px}px`).join("\n")}
+
+Bind padding & gaps to these steps exactly as the design tool renders them \u2014
+padding is written as \`vertical horizontal\`:
+
+- **Primary / prominent CTA button** \u2192 \`--spacing-sm\` \`--spacing-lg\` (e.g. \`padding: var(--spacing-sm) var(--spacing-lg)\`) \u2014 a taller, comfortable target.
+- **Compact buttons / inputs / chips** \u2192 \`--spacing-xxs\` \`--spacing-sm\`.
+- **List rows / nav items / card header & footer** \u2192 \`--spacing-xs\` \`--spacing-md\`.
+- **Card / panel / modal body** \u2192 \`--spacing-md\` on all sides.
+- **Gap between sibling controls, grid/flex gaps** \u2192 \`--spacing-sm\`.
+- **Vertical rhythm between page sections** \u2192 \`--spacing-xl\` \u2026 \`--spacing-section\`.
+
+Only use listed values; never improvise an intermediate gap.
+
+## Border radius
+Base ${radius.base}px. Use:
+
+${buildRadius(radius.base).map((r) => `- ${r.name}: ${r.name === "full" ? "9999px (pill)" : `${r.px}px`}`).join("\n")}
+
+Bind components to these steps exactly as the design tool renders them \u2014 do NOT
+pick a step freely (e.g. do not make buttons pill-shaped unless \`--radius-md\`
+resolves to a pill):
+
+- **Buttons / controls / nav items** \u2192 \`--radius-md\`
+- **Inputs / text fields / selects** \u2192 \`--radius-sm\`
+- **Cards / panels / modals / larger surfaces** \u2192 \`--radius-lg\`
+- **Badges / chips / avatars / toggles (intentionally pill)** \u2192 \`--radius-full\`
+- Bigger containers may use \`--radius-xl\`; \`--radius-full\` is reserved for
+  circles/pills, never for standard buttons or cards.
+
+## Shadow / elevation
+${shadow.advanced ? "Per-level custom values" : `Intensity ${shadow.intensity.toFixed(2)}`}.
+
+${["sm", "md", "lg"].map((level) => `- ${level}: ${shadowToCss(shadow[level])}`).join("\n")}
+
+Bind each level to an elevation exactly as the design tool renders them \u2014 do NOT
+pick a level freely:
+
+- **sm** \u2192 resting surfaces: cards, panels, subtle raise (the default for a raised element).
+- **md** \u2192 hovered / lifted state: a card or button on hover, raised popovers.
+- **lg** \u2192 floating overlays: modals, drawers, dropdowns, menus above the page.
+
+Flat elements (nav bar, page background, inline controls) get NO shadow. On hover, step a card up one level (sm \u2192 md), don't jump straight to lg.
+
+## Border width
+${buildBorderScale(border.base).map((b) => `- ${b.name}: ${b.px}px`).join("\n")}
+
+Bind each width as the design tool renders them:
+
+- **default** \u2192 all resting borders: card outlines, input borders, dividers.
+- **strong** \u2192 focused / active / selected emphasis (e.g. an input grows from \`default\` to \`strong\` on focus). Do not use \`strong\` for ordinary resting borders.
+
+## Opacity / transparency
+These drive interactive states \u2014 wire them up, don't leave them unused. Apply each via \`var(--opacity-\u2026)\` (or an rgba/overlay at that alpha):
+
+${buildOpacityScale(opacity.base).map((o) => `- ${o.name} (${(o.value * 100).toFixed(1)}%): ${OPACITY_USAGE[o.name] ?? "interactive state"}`).join("\n")}
+
+Every clickable element (buttons, links, cards) should show a hover state and a disabled state using these values. Use \`overlay\` for scrims behind modals/drawers.
+
+## Motion / Animation
+Base duration ${motion.base}ms, easing: ${motion.easing} (${EASING_PRESETS[motion.easing]}).
+
+${buildDurations(motion.base).map((d) => `- ${d.name}: ${d.ms}ms`).join("\n")}
+
+Use \`--duration-normal\` as the default transition. Prefer \`--duration-fast\` for hover states and micro-interactions. Reserve \`--duration-page\` for route/page-level transitions.
+${darkSection}${semanticSection}
+## Output guidance
+- Maintain the proportional relationships above when laying out a page.
+- Do not introduce new hues. If you need additional shades, derive them by adjusting OKLCH lightness only, keeping hue and chroma fixed.
+- Respect the modular scale \u2014 pick from the listed sizes rather than introducing new ones.
+- Use only the listed spacing values; do not improvise intermediate gaps.
+- ${SCALE_STEPS.length} type sizes is intentional. Use semantic mapping: h1-h5 for headings, body for paragraphs, small/caption for metadata.
+`;
+}
+function designSystemMarkdown(colors, typography, spacing, radius, shadow, motion, border, opacity, darkColors, semantic, darkSemantic) {
+  const prompt = aiPrompt(colors, typography, spacing, radius, shadow, motion, border, opacity, darkColors, semantic, darkSemantic);
+  const tokens = w3cTokens(colors, typography, spacing, radius, shadow, motion, border, opacity, darkColors, semantic, darkSemantic);
+  const generated = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  return `---
+design-pact: 1
+generated: ${generated}
+---
+
+${prompt}
+---
+
+## Machine-readable tokens (W3C Design Tokens)
+
+Humans and AI can read the prose above. The JSON below lets tools (the companion CLI) reconstruct the design system precisely and deterministically, and convert it to CSS / Tailwind / etc.
+
+\`\`\`json
+${JSON.stringify(tokens, null, 2)}
+\`\`\`
+`;
+}
 
 // ../../node_modules/zustand/esm/vanilla.mjs
 var createStoreImpl = (createState) => {
@@ -2151,21 +2467,21 @@ function serveStatic(port) {
     res.writeHead(200, { "content-type": MIME[extname(file)] || "application/octet-stream" });
     createReadStream(file).pipe(res);
   });
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     server.once("error", reject);
-    server.listen(port, () => resolve3());
+    server.listen(port, () => resolve4());
   });
 }
 function probe(port) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const req = httpGet({ host: "localhost", port, path: "/", timeout: 700 }, (r) => {
       r.resume();
-      resolve3(true);
+      resolve4(true);
     });
-    req.on("error", () => resolve3(false));
+    req.on("error", () => resolve4(false));
     req.on("timeout", () => {
       req.destroy();
-      resolve3(false);
+      resolve4(false);
     });
   });
 }
@@ -2387,19 +2703,359 @@ function reportCheck(result) {
   return 1;
 }
 
+// src/import.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { basename, resolve as resolve2 } from "path";
+
+// ../../lib/darkMode.ts
+var clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+function deriveOppositeHex(hex, role) {
+  const c = hexToOklch(hex);
+  const flipped = 1 - c.l;
+  let l;
+  let chroma = c.c;
+  switch (role) {
+    case "background":
+      l = c.l >= 0.5 ? clamp(flipped, 0.14, 0.24) : clamp(flipped, 0.92, 0.985);
+      chroma = Math.min(c.c, 0.04);
+      break;
+    case "foreground":
+      l = c.l < 0.5 ? clamp(flipped, 0.85, 0.97) : clamp(flipped, 0.12, 0.3);
+      break;
+    case "border":
+      l = c.l >= 0.5 ? clamp(flipped, 0.25, 0.38) : clamp(flipped, 0.7, 0.85);
+      chroma = Math.min(c.c, 0.04);
+      break;
+    case "muted":
+      l = clamp(flipped, 0.55, 0.75);
+      break;
+    case "primary":
+    case "accent":
+      l = c.l < 0.55 ? clamp(c.l + 0.18, 0.55, 0.8) : c.l;
+      break;
+    default:
+      l = clamp(flipped, 0.2, 0.9);
+  }
+  return oklchToHex({ mode: "oklch", l, c: chroma, h: c.h ?? 0 });
+}
+
+// ../../lib/semantic.ts
+var HUE = {
+  success: 150,
+  warning: 75,
+  error: 27,
+  info: 255
+};
+var CHROMA = {
+  success: 0.15,
+  warning: 0.16,
+  error: 0.19,
+  info: 0.16
+};
+function deriveSemantic(bgHex) {
+  const bg = hexToOklch(bgHex);
+  const darkBg = bg.l < 0.5;
+  const out = {};
+  for (const kind of SEMANTIC_KINDS) {
+    const h = HUE[kind];
+    const c = CHROMA[kind];
+    let l = darkBg ? 0.72 : 0.58;
+    let hex = oklchToHex({ mode: "oklch", l, c, h });
+    for (let i = 0; i < 16 && contrastRatio(hex, bgHex) < 3.2; i++) {
+      l = darkBg ? Math.min(0.92, l + 0.03) : Math.max(0.38, l - 0.03);
+      hex = oklchToHex({ mode: "oklch", l, c, h });
+    }
+    out[kind] = hex;
+  }
+  return out;
+}
+
+// src/import.ts
+var ROLES2 = ["background", "foreground", "primary", "accent", "muted", "border"];
+var NAME_HINTS = [
+  ["background", /\b(?:background|bg|surface|canvas|page)\b/i],
+  ["foreground", /\b(?:foreground|fg|text|ink|body)\b/i],
+  ["primary", /\b(?:primary|brand|main|cta)\b/i],
+  ["accent", /\b(?:accent|highlight|secondary)\b/i],
+  ["muted", /\b(?:muted|gr[ae]y|neutral|subtle|placeholder)\b/i],
+  ["border", /\b(?:border|divider|outline|stroke|input|ring)\b/i]
+];
+var COLOR_LITERAL = /(#[0-9a-fA-F]{3,8}\b|rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*(?:,\s*[\d.]+\s*)?\))/g;
+function literalToHex(raw) {
+  if (raw.startsWith("#")) return normalizeHex(raw);
+  const m = /rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})/.exec(raw);
+  if (!m) return null;
+  const [r, g, b] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  if ([r, g, b].some((v) => v > 255)) return null;
+  return "#" + [r, g, b].map((v) => v.toString(16).padStart(2, "0")).join("");
+}
+function lineName(line, literalIndex) {
+  const before = line.slice(0, literalIndex);
+  const m = /([$@\w-]+)\s*:\s*["']?$/.exec(before);
+  return m ? m[1] : "";
+}
+var CSS_PROPERTIES = /* @__PURE__ */ new Set([
+  "background",
+  "background-color",
+  "color",
+  "border",
+  "border-color",
+  "outline",
+  "outline-color",
+  "fill",
+  "stroke",
+  "caret-color",
+  "accent-color"
+]);
+var STATE_WORDS = /\b(?:focus|hover|active|pressed|disabled|selected|visited|checked)\b/i;
+var STRUCTURAL_ROLES = /* @__PURE__ */ new Set(["background", "foreground", "border", "muted"]);
+function scanSignals(text, weight, into) {
+  for (const line of text.split("\n")) {
+    for (const m of line.matchAll(COLOR_LITERAL)) {
+      const hex = literalToHex(m[0]);
+      if (!hex) continue;
+      const sig = into.get(hex) ?? { hex, count: 0, hints: {} };
+      sig.count += weight;
+      const name = lineName(line, m.index ?? 0);
+      if (name) {
+        const hintWeight = CSS_PROPERTIES.has(name.toLowerCase()) ? 1 : weight * 2;
+        const normalized = name.replace(/([a-z])([A-Z])/g, "$1-$2");
+        if (!STATE_WORDS.test(normalized)) {
+          let matched = NAME_HINTS.filter(([, re]) => re.test(normalized)).map(([role]) => role);
+          if (matched.some((r) => STRUCTURAL_ROLES.has(r))) {
+            matched = matched.filter((r) => r !== "primary" && r !== "accent");
+          }
+          for (const role of matched) sig.hints[role] = (sig.hints[role] ?? 0) + hintWeight;
+        }
+      }
+      into.set(hex, sig);
+    }
+  }
+}
+var RADIUS_RE = /(?:border-radius|borderRadius|--radius[\w-]*)["']?\s*:\s*["']?(\d{1,2})px/g;
+var SPACING_VAR_RE = /--spacing-[\w-]*\s*:\s*(\d{1,2}(?:\.\d+)?)px/g;
+var FONT_FAMILY_RE = /font-family\s*:\s*([^;}]{3,120})/i;
+var FONT_SIZE_RE = /(?:html|body|:root)[^{]*\{[^}]*?font-size\s*:\s*(\d{2})px/;
+var isTailwindConfig = (f) => /^tailwind\.config\.(js|cjs|mjs|ts)$/.test(basename(f));
+function pick(arr, score) {
+  let best;
+  let bestScore = -Infinity;
+  for (const t2 of arr) {
+    const s = score(t2);
+    if (s > bestScore) {
+      bestScore = s;
+      best = t2;
+    }
+  }
+  return bestScore > 0 ? best : void 0;
+}
+var hueDist = (a, b) => {
+  const d = Math.abs(a - b) % 360;
+  return d > 180 ? 360 - d : d;
+};
+function blend(aHex, bHex, t2) {
+  const a = hexToOklch(aHex);
+  const b = hexToOklch(bHex);
+  return oklchToHex({
+    mode: "oklch",
+    l: a.l + (b.l - a.l) * t2,
+    c: a.c + (b.c - a.c) * t2,
+    h: a.h ?? b.h ?? 0
+  });
+}
+function assignRoles(signals) {
+  const used = /* @__PURE__ */ new Set();
+  const out = /* @__PURE__ */ new Map();
+  const take = (role, hex, provenance) => {
+    out.set(role, { hex, provenance });
+    used.add(hex);
+  };
+  const free = () => signals.filter((s) => !used.has(s.hex));
+  for (const role of ROLES2) {
+    const named = pick(free().filter((s) => (s.hints[role] ?? 0) > 0), (s) => (s.hints[role] ?? 0) * 1e6 + s.count);
+    if (named) take(role, named.hex, "named");
+  }
+  const ok = (s) => hexToOklch(s.hex);
+  if (!out.has("background")) {
+    const bg = pick(free(), (s) => {
+      const c = ok(s);
+      return c.l >= 0.85 || c.l <= 0.2 ? s.count : 0;
+    });
+    if (bg) take("background", bg.hex, "heuristic");
+    else take("background", "#ffffff", "derived");
+  }
+  const bgHex = out.get("background").hex;
+  const bgDark = hexToOklch(bgHex).l < 0.5;
+  if (!out.has("foreground")) {
+    const fg = pick(free(), (s) => contrastRatio(s.hex, bgHex) >= 4.5 ? s.count * (1 + contrastRatio(s.hex, bgHex) / 21) : 0);
+    if (fg) take("foreground", fg.hex, "heuristic");
+    else take("foreground", bgDark ? "#e6e8ec" : "#1a1a1a", "derived");
+  }
+  const fgHex = out.get("foreground").hex;
+  if (!out.has("primary")) {
+    const p = pick(free(), (s) => {
+      const c = ok(s);
+      return c.c >= 0.09 && contrastRatio(s.hex, bgHex) >= 2 ? s.count : 0;
+    });
+    if (p) take("primary", p.hex, "heuristic");
+    else take("primary", "#2f6df6", "derived");
+  }
+  const primaryHue = hexToOklch(out.get("primary").hex).h ?? 0;
+  if (!out.has("accent")) {
+    const a = pick(free(), (s) => {
+      const c = ok(s);
+      return c.c >= 0.09 && hueDist(c.h ?? 0, primaryHue) >= 40 ? s.count : 0;
+    });
+    if (a) take("accent", a.hex, "heuristic");
+    else {
+      const p = hexToOklch(out.get("primary").hex);
+      take("accent", oklchToHex({ ...p, h: ((p.h ?? 0) + 60) % 360 }), "derived");
+    }
+  }
+  if (!out.has("muted")) {
+    const m = pick(free(), (s) => {
+      const c = ok(s);
+      return c.c < 0.08 && c.l >= 0.3 && c.l <= 0.78 ? s.count : 0;
+    });
+    if (m) take("muted", m.hex, "heuristic");
+    else take("muted", blend(bgHex, fgHex, 0.55), "derived");
+  }
+  if (!out.has("border")) {
+    const bgL = hexToOklch(bgHex).l;
+    const b = pick(free(), (s) => {
+      const c = ok(s);
+      return c.c < 0.08 && Math.abs(c.l - bgL) > 0.02 && Math.abs(c.l - bgL) < 0.25 ? s.count : 0;
+    });
+    if (b) take("border", b.hex, "heuristic");
+    else take("border", blend(bgHex, fgHex, 0.12), "derived");
+  }
+  return ROLES2.map((role) => ({ role, ...out.get(role) }));
+}
+var mode = (values) => {
+  const counts = /* @__PURE__ */ new Map();
+  for (const v of values) counts.set(v, (counts.get(v) ?? 0) + 1);
+  return pick([...counts.keys()], (k) => counts.get(k));
+};
+function scanProject(targets) {
+  const signals = /* @__PURE__ */ new Map();
+  const radii = [];
+  const spacings = [];
+  let fontFamily;
+  let fontSizeBase;
+  let filesScanned = 0;
+  for (const target of targets) {
+    for (const file of collectFiles(resolve2(target))) {
+      let text;
+      try {
+        text = readFileSync2(file, "utf8");
+      } catch {
+        continue;
+      }
+      filesScanned++;
+      const isCss = /\.(css|scss|sass|less)$/.test(file);
+      scanSignals(text, isTailwindConfig(file) ? 5 : isCss ? 3 : 1, signals);
+      for (const m of text.matchAll(RADIUS_RE)) {
+        const px = Number(m[1]);
+        if (px > 0 && px <= 24) radii.push(px);
+      }
+      for (const m of text.matchAll(SPACING_VAR_RE)) {
+        const px = Number(m[1]);
+        if (px >= 2 && px <= 8) spacings.push(px);
+      }
+      if (!fontFamily && (isCss || isTailwindConfig(file))) {
+        for (const m of text.matchAll(new RegExp(FONT_FAMILY_RE.source, "gi"))) {
+          const value2 = m[1].trim().replace(/["']/g, "").replace(/\s+/g, " ");
+          if (!/^var\(/i.test(value2)) {
+            fontFamily = value2;
+            break;
+          }
+        }
+      }
+      if (!fontSizeBase) {
+        const m = FONT_SIZE_RE.exec(text);
+        if (m) {
+          const px = Number(m[1]);
+          if (px >= 12 && px <= 22) fontSizeBase = px;
+        }
+      }
+    }
+  }
+  const all = [...signals.values()].filter((s) => s.count >= 2 || Object.keys(s.hints).length > 0);
+  all.sort((a, b) => b.count - a.count);
+  return {
+    colors: assignRoles(all.slice(0, 64)),
+    radiusBase: mode(radii),
+    spacingBase: spacings.length > 0 ? Math.min(...spacings) : void 0,
+    fontFamily,
+    fontSizeBase,
+    filesScanned
+  };
+}
+var PROPORTION = {
+  background: 0.55,
+  foreground: 0.2,
+  primary: 0.1,
+  accent: 0.06,
+  muted: 0.05,
+  border: 0.04
+};
+function draftToMarkdown(draft) {
+  const detectedDark = hexToOklch(draft.colors.find((c) => c.role === "background").hex).l < 0.5;
+  const face = (colors, flip) => colors.map(({ role, hex }, i) => {
+    const display = flip ? deriveOppositeHex(hex, role) : hex;
+    return {
+      id: `c${i + 1}`,
+      hex: display,
+      baseHex: display,
+      proportion: PROPORTION[role],
+      role,
+      displayHex: display
+    };
+  });
+  const base = face(draft.colors, detectedDark);
+  const dark = face(draft.colors, !detectedDark);
+  const bg = base.find((c) => c.role === "background").displayHex;
+  const darkBg = dark.find((c) => c.role === "background").displayHex;
+  const typography = {
+    ...defaultTypography,
+    ...draft.fontSizeBase ? { base: draft.fontSizeBase } : {},
+    ...draft.fontFamily ? { fontFamily: draft.fontFamily, headingFamily: draft.fontFamily } : {}
+  };
+  return designSystemMarkdown(
+    base,
+    typography,
+    draft.spacingBase ? { base: draft.spacingBase } : defaultSpacing,
+    draft.radiusBase ? { base: draft.radiusBase } : defaultRadius,
+    defaultShadow,
+    defaultMotion,
+    defaultBorder,
+    defaultOpacity,
+    dark,
+    deriveSemantic(bg),
+    deriveSemantic(darkBg)
+  );
+}
+function studioQuery(draft) {
+  const hexes = draft.colors.map((c) => c.hex.slice(1)).join("-");
+  return `p=${hexes}~${encodeURIComponent("Imported")}~${encodeURIComponent("Derived from your codebase")}`;
+}
+
 // src/cli.ts
 var FORMATS = ["css", "tailwind", "w3c"];
 function fail(msg) {
   console.error(`\u2717 ${msg}`);
   process.exit(1);
 }
+var BOOL_FLAGS = /* @__PURE__ */ new Set(["force", "global"]);
 function parseArgs(argv) {
   const positional = [];
   const opts = {};
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a.startsWith("--")) opts[a.slice(2)] = argv[++i] ?? "";
-    else positional.push(a);
+    if (a.startsWith("--")) {
+      const name = a.slice(2);
+      opts[name] = BOOL_FLAGS.has(name) ? "true" : argv[++i] ?? "";
+    } else positional.push(a);
   }
   return { positional, opts };
 }
@@ -2412,7 +3068,7 @@ function readMd(file) {
       )
     );
   try {
-    return readFileSync2(resolve2(file), "utf8");
+    return readFileSync3(resolve3(file), "utf8");
   } catch {
     return fail(t(`Cannot read file: ${file}`, `\u8BFB\u4E0D\u5230\u6587\u4EF6\uFF1A${file}`));
   }
@@ -2436,7 +3092,7 @@ function cmdAdd(file, opts) {
   if (fmt !== "all" && !FORMATS.includes(fmt))
     fail(t(`Unknown format: ${fmt} (css|tailwind|w3c|all)`, `\u672A\u77E5\u683C\u5F0F\uFF1A${fmt}\uFF08css|tailwind|w3c|all\uFF09`));
   const want = fmt === "all" ? FORMATS : [fmt];
-  const outDir = resolve2(opts.out || ".");
+  const outDir = resolve3(opts.out || ".");
   mkdirSync(outDir, { recursive: true });
   const written = [];
   const write = (name, content) => {
@@ -2471,6 +3127,36 @@ async function main() {
       const result = runCheck(ds.w3c, targets.length > 0 ? targets : ["."], allow);
       process.exit(reportCheck(result));
     }
+    case "import": {
+      const targets = positional.length > 0 ? positional : ["."];
+      const outPath = resolve3(opts.out || "design.md");
+      if (existsSync2(outPath) && !opts.force)
+        fail(t(`${outPath} already exists \u2014 pass --force to overwrite.`, `${outPath} \u5DF2\u5B58\u5728\u2014\u2014\u7528 --force \u8986\u76D6\u3002`));
+      const draft = scanProject(targets);
+      writeFileSync(outPath, draftToMarkdown(draft), "utf8");
+      console.log(t(
+        `\u2713 Draft design.md written to ${outPath} (${draft.filesScanned} file(s) scanned)`,
+        `\u2713 design.md \u8349\u7A3F\u5DF2\u5199\u5165 ${outPath}\uFF08\u626B\u63CF ${draft.filesScanned} \u4E2A\u6587\u4EF6\uFF09`
+      ));
+      console.log(t("  Detected palette:", "  \u8BC6\u522B\u51FA\u7684\u8272\u677F\uFF1A"));
+      const provenanceLabel = {
+        named: ["from a named variable", "\u6765\u81EA\u547D\u540D\u53D8\u91CF"],
+        heuristic: ["by usage heuristic", "\u6309\u4F7F\u7528\u9891\u7387\u63A8\u65AD"],
+        derived: ["derived (no signal found)", "\u6D3E\u751F\uFF08\u672A\u627E\u5230\u4FE1\u53F7\uFF09"]
+      };
+      for (const c of draft.colors) {
+        const [en, zh] = provenanceLabel[c.provenance];
+        console.log(`    ${c.role.padEnd(12)} ${c.hex}  ${t(en, zh)}`);
+      }
+      const q = studioQuery(draft);
+      console.log("\n" + t(
+        "Review it visually before adopting \u2014 heuristic/derived roles deserve a look:",
+        "\u91C7\u7528\u524D\u5EFA\u8BAE\u5148\u5230 studio \u91CC\u8FC7\u76EE\u2014\u2014\u63A8\u65AD/\u6D3E\u751F\u7684\u89D2\u8272\u503C\u5F97\u786E\u8BA4\uFF1A"
+      ));
+      console.log(`  https://design-pact.vercel.app/?${q}`);
+      console.log(t(`  or locally: npx design-pact open "${q}"`, `  \u6216\u672C\u5730\u6253\u5F00\uFF1Anpx design-pact open "${q}"`));
+      return;
+    }
     case void 0:
     case "-h":
     case "--help":
@@ -2501,6 +3187,10 @@ async function main() {
             '  check <file> [paths\u2026] [--allow "#hex,#hex"]            find color literals outside the contract',
             '  check <file> [paths\u2026] [--allow "#hex,#hex"]            \u627E\u51FA\u5951\u7EA6\u5916\u7684\u989C\u8272\u5B57\u9762\u91CF'
           ),
+          t(
+            "  import [paths\u2026] [--out design.md] [--force]            derive a draft design.md from existing code",
+            "  import [paths\u2026] [--out design.md] [--force]            \u4ECE\u73B0\u6709\u4EE3\u7801\u53CD\u63A8 design.md \u8349\u7A3F"
+          ),
           "",
           t(
             'design.md is exported from the studio ("Download design.md").',
@@ -2510,7 +3200,7 @@ async function main() {
       );
       return;
     default:
-      fail(t(`Unknown command: ${cmd} (init|open|add|inspect|check)`, `\u672A\u77E5\u547D\u4EE4\uFF1A${cmd}\uFF08init|open|add|inspect|check\uFF09`));
+      fail(t(`Unknown command: ${cmd} (init|open|add|inspect|check|import)`, `\u672A\u77E5\u547D\u4EE4\uFF1A${cmd}\uFF08init|open|add|inspect|check|import\uFF09`));
   }
 }
 main().catch((e) => fail(e instanceof Error ? e.message : String(e)));