@theme-registry/refract 0.1.1 → 0.1.3

package/dist/cli.js

@@ -7,6 +7,7 @@ var node_path = require('node:path');
 var node_fs = require('node:fs');
 var node_url = require('node:url');
 var node_os = require('node:os');
+var node_readline = require('node:readline');
 
 /**
  * Build-layer path + transpile helpers (Node-only).
@@ -3150,7 +3151,7 @@ const apcaLc = (text, bg) => {
     }
     return out * 100;
 };
-const round$1 = (n, dp) => {
+const round$2 = (n, dp) => {
     const f = 10 ** dp;
     return Math.round(n * f) / f;
 };
@@ -3200,9 +3201,9 @@ const scorePair = (kind, label, fg, bg, options) => {
     const pass = LEVEL_RANK[level] >= LEVEL_RANK[options.minWcag];
     return {
         kind, label, fg, bg,
-        wcagRatio: round$1(ratio, 2),
+        wcagRatio: round$2(ratio, 2),
         wcagLevel: level,
-        apcaLc: round$1(apcaLc(fgRgb, bgRgb), 1),
+        apcaLc: round$2(apcaLc(fgRgb, bgRgb), 1),
         pass,
     };
 };
@@ -3591,7 +3592,7 @@ const FORCE_NONE_PROPERTIES = new Set(["spacing", "gutters"]);
 const SCALE_PRECISION = 4;
 /** The default step ladder used when a curve is declared without an explicit `steps`. */
 const DEFAULT_LADDER = ["xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl"];
-const round = (n) => Number(n.toFixed(SCALE_PRECISION));
+const round$1 = (n) => Number(n.toFixed(SCALE_PRECISION));
 /**
  * The `scaleStep` derivation fn (registered by the layout subsystem). Re-derives a synthesized step
  * from its curve config: **geometric** `base × ratio^exp` (from the resolved base token, so an
@@ -3603,10 +3604,10 @@ const round = (n) => Number(n.toFixed(SCALE_PRECISION));
 const scaleStep = (value, arg) => {
     const a = (arg !== null && arg !== void 0 ? arg : {});
     if (a.curve === "linear") {
-        return round(Number(a.step) * Number(a.mult));
+        return round$1(Number(a.step) * Number(a.mult));
     }
     const base = a.base !== undefined ? Number(a.base) : Number(value);
-    return round(base * Math.pow(Number(a.ratio), Number(a.exp)));
+    return round$1(base * Math.pow(Number(a.ratio), Number(a.exp)));
 };
 /**
  * Read the top-level curve config off a normalized property. `ratio` selects geometric, `step`
@@ -3654,14 +3655,14 @@ const synthesizeVariants = (propertyKey, base, config) => {
     const out = {};
     for (const spec of config.specs) {
         if (config.curve === "geometric") {
-            const value = round(Number(base) * Math.pow(config.ratio, spec.exp));
+            const value = round$1(Number(base) * Math.pow(config.ratio, spec.exp));
             out[spec.name] = {
                 base: value,
                 derive: { ref, fn: "scaleStep", arg: { curve: "geometric", ratio: config.ratio, exp: spec.exp } },
             };
         }
         else {
-            const value = round(config.step * spec.mult);
+            const value = round$1(config.step * spec.mult);
             out[spec.name] = {
                 base: value,
                 derive: { ref, fn: "scaleStep", arg: { curve: "linear", step: config.step, mult: spec.mult } },
@@ -3707,7 +3708,7 @@ const expandResponsive = (propertyKey, propBase, responsive, config) => {
                 const ratio = Number(e.ratio);
                 const hasBase = e.base !== undefined;
                 const b = hasBase ? Number(e.base) : Number(propBase);
-                value = round(b * Math.pow(ratio, spec.exp));
+                value = round$1(b * Math.pow(ratio, spec.exp));
                 arg = { curve: "geometric", ratio, exp: spec.exp, ...(hasBase ? { base: b } : {}) };
             }
             else {
@@ -3715,7 +3716,7 @@ const expandResponsive = (propertyKey, propBase, responsive, config) => {
                     throw new RefractError("REFRACT_E_LAYOUT", `layout.${propertyKey}: a linear responsive ramp ("step") requires a linear base scale (a name→multiplier "steps").`);
                 }
                 const step = Number(e.step);
-                value = round(step * spec.mult);
+                value = round$1(step * spec.mult);
                 arg = { curve: "linear", step, mult: spec.mult };
             }
             const expanded = {
@@ -6118,6 +6119,33 @@ const resolveReferences = (value, tokensByPath, visited = new Set()) => {
     return value;
 };
 
+/**
+ * Fail-loud shape guard for a value that is *supposed* to be a {@link RawTheme}.
+ *
+ * `createTheme` accepts a bare object, and an empty `{}` is a valid (empty) theme — so a value of the
+ * *wrong* shape doesn't necessarily throw during a build. That's the trap `refract diff` fell into: hand
+ * it a `defineConfig({ raw, targets })` where it wanted the raw theme and it built the config as an
+ * (effectively empty) theme, then reported a nonsense "every token removed" diff and exited 0. A
+ * governance tool must not quietly mis-report. This guard is the loud, coded gate for that class of
+ * mistake — used by `diff` (and available to `validate` / the MCP server) before anything is compared.
+ *
+ * It is deliberately narrow: it rejects only values that cannot be a RawTheme (non-objects, arrays,
+ * `null`) or that are affirmatively something else (a `defineConfig`, spotted by its `targets` array).
+ * A bare `{}` still passes — an empty theme is legitimately empty.
+ */
+function assertRawTheme(value, source) {
+    const at = source ? ` (${source})` : "";
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        const got = Array.isArray(value) ? "an array" : value === null ? "null" : typeof value;
+        throw new RefractError("REFRACT_E_RAW_SHAPE", `Expected a RawTheme object${at}, got ${got}. Pass the raw theme (a module's default export, or a .json raw theme).`);
+    }
+    // The documented mistake: a defineConfig({ raw, targets }) passed where the bare RawTheme was wanted.
+    // A RawTheme never has a top-level `targets`; a config always does.
+    if (Array.isArray(value.targets)) {
+        throw new RefractError("REFRACT_E_RAW_SHAPE", `Expected a RawTheme object${at}, but got what looks like a defineConfig({ raw, targets }). Pass its \`raw\` (or a module that default-exports the raw theme), not the whole config.`);
+    }
+}
+
 /**
  * `defineAdapter` — turns an `AdapterSpec` (identity + a `bind` returning the four
  * required primitives) into a full `ThemeAdapter` whose `bind` yields a complete
@@ -7158,6 +7186,78 @@ function readOwnPackageName() {
     const pkg = JSON.parse(node_fs.readFileSync(pkgPath, "utf8"));
     return (_a = pkg.name) !== null && _a !== void 0 ? _a : "@theme-registry/refract";
 }
+/**
+ * Raw-theme filenames `init` will wire up, in resolution order. `.ts` first (the richest), then the
+ * plain-ESM flavours, then `.json`. Matches what `refract create` and `refract import` write.
+ */
+const RAW_BASENAME = "theme.raw";
+const RAW_EXT_ORDER = [".ts", ".mts", ".mjs", ".js", ".json"];
+/**
+ * Look for an authored raw theme in `fromDir`.
+ *
+ * This is the seam between `create` and `init`: `create` designs the theme, `init` wires the build.
+ * When a theme is already there, `init` must not invent a second one — a project with two sources of
+ * truth for its tokens is worse than a project with none.
+ */
+const findRawTheme = (fromDir = process.cwd()) => {
+    for (const ext of RAW_EXT_ORDER) {
+        const candidate = node_path.join(fromDir, `${RAW_BASENAME}${ext}`);
+        if (node_fs.existsSync(candidate)) {
+            return { path: candidate, filename: `${RAW_BASENAME}${ext}`, ext };
+        }
+    }
+    return undefined;
+};
+/**
+ * The import line (or lines) a config uses to reach a detected raw theme.
+ *
+ * `.ts` is graph-compiled alongside the config, so an extensionless specifier resolves and the
+ * transformer rewrites it. `.mjs`/`.js` are imported by Node directly, so they keep their extension.
+ * `.json` is read rather than imported: an import attribute (`with { type: "json" }`) would work on
+ * current Node but pins the scaffolded config to a version floor for no benefit, and `readFileSync`
+ * behaves identically in every flavour.
+ */
+function rawThemeImport(detected) {
+    if (detected.ext === ".json") {
+        return {
+            head: `import { readFileSync } from "node:fs";\n` +
+                `\n// The theme is JSON, so it's read rather than imported — no module-attribute support needed.\n` +
+                `const raw = JSON.parse(readFileSync(new URL("./${detected.filename}", import.meta.url), "utf8"));\n`,
+            expression: "raw",
+        };
+    }
+    const specifier = detected.ext === ".ts" || detected.ext === ".mts"
+        ? `./${RAW_BASENAME}`
+        : `./${detected.filename}`;
+    return { head: `import { raw } from "${specifier}";\n`, expression: "raw" };
+}
+/**
+ * The config body when a raw theme already exists — it imports that theme instead of carrying one.
+ * Deliberately short: everything about the design lives in the theme file, and this is only wiring.
+ */
+function scaffoldConfigForRaw(packageName, detected) {
+    const { head, expression } = rawThemeImport(detected);
+    return `import { defineConfig } from "${packageName}/build";
+import { createCssAdapter } from "${CSS_ADAPTER_PACKAGE}";
+${head}
+// refract build config. \`refract build\` reads this file, builds the theme once, and writes each
+// target's emitted files into that target's \`outDir\`. The config is your code: it \`import\`s the
+// adapters it wants and passes their options at construction (not via CLI flags).
+//
+// Your tokens live in \`${detected.filename}\` — edit them there, not here.
+export default defineConfig({
+  raw: ${expression},
+  targets: [
+    // The CSS adapter (from @theme-registry/refract-css). Pass its options here, at construction.
+    { adapter: createCssAdapter(/* { colors: { prefix: "app" } } */), outDir: "dist/theme" },
+
+    // Add another adapter target once its package is installed, e.g.:
+    // import { createStyledComponentsAdapter } from "@theme-registry/refract-styled-components";
+    // { adapter: createStyledComponentsAdapter(), outDir: "dist/theme-sc" },
+  ],
+});
+`;
+}
 /** The scaffolded config body — one shared ESM template across ts/js/mjs. */
 function scaffoldConfig(packageName) {
     return `import { defineConfig } from "${packageName}/build";
@@ -7171,8 +7271,10 @@ export default defineConfig({
   raw: {
     breakpoints: { sm: 576, md: 768, lg: 1024, xl: 1280 },
     colors: {
-      primary: { base: "#4dabf7", text: "#fff", variants: { dark: "#1c7ed6", light: "#a5d8ff" } },
-      neutral: { base: "#868e96", text: "#fff", variants: { light: "#f1f3f5", dark: "#343a40" } },
+      // Starter palette passes its own contrast audit (WCAG AA): white text clears 4.5:1 on both
+      // bases. Keep that when you retune — the auditor is a shipped feature; the default should model it.
+      primary: { base: "#1864ab", text: "#fff", variants: { dark: "#0b4a86", light: "#a5d8ff" } },
+      neutral: { base: "#495057", text: "#fff", variants: { light: "#f1f3f5", dark: "#212529" } },
       recipes: {
         solid: {
           primary: { background: "primary", color: "primary.text" },
@@ -7197,7 +7299,7 @@ export default defineConfig({
  * (never silently clobbers a user's config).
  */
 function runInit(options = {}) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
     const cwd = (_a = options.cwd) !== null && _a !== void 0 ? _a : process.cwd();
     const variant = (_b = options.variant) !== null && _b !== void 0 ? _b : "ts";
     const packageName = (_c = options.packageName) !== null && _c !== void 0 ? _c : readOwnPackageName();
@@ -7205,8 +7307,13 @@ function runInit(options = {}) {
     if (node_fs.existsSync(path) && !options.force) {
         throw new Error(`theme.config.${variant} already exists at "${path}". Pass --force to overwrite it.`);
     }
-    node_fs.writeFileSync(path, scaffoldConfig(packageName), "utf8");
-    return { path, variant, packageName };
+    // If the project already has a theme, wire it up rather than inventing a second one. Only when
+    // there's nothing to find does the config carry a starter palette of its own — so `refract init`
+    // on its own still produces something runnable, exactly as it always has.
+    const detected = options.rawTheme === null ? undefined : (_d = options.rawTheme) !== null && _d !== void 0 ? _d : findRawTheme(cwd);
+    const body = detected ? scaffoldConfigForRaw(packageName, detected) : scaffoldConfig(packageName);
+    node_fs.writeFileSync(path, body, "utf8");
+    return { path, variant, packageName, rawTheme: detected };
 }
 
 /**
@@ -7745,26 +7852,35 @@ function diffThemes(base, candidate) {
  */
 const WCAG_RANK = { fail: 0, "AA-large": 1, AA: 2, AAA: 3 };
 let counter = 0;
-/** Load a candidate raw theme from a module (default export) or a `.json` file. */
+/**
+ * Load a candidate raw theme from a module (default export) or a `.json` file, and assert it's actually
+ * theme-shaped before returning — a mis-shaped candidate (e.g. a `defineConfig`) must fail loud here,
+ * not silently diff as "everything removed" (see {@link assertRawTheme}).
+ */
 async function loadCandidate(path) {
     var _a, _b, _c, _d;
     if (!node_fs.existsSync(path))
         throw new Error(`candidate theme not found at "${path}".`);
+    let candidate;
     if (node_path.extname(path) === ".json") {
-        return JSON.parse(node_fs.readFileSync(path, "utf8"));
+        candidate = JSON.parse(node_fs.readFileSync(path, "utf8"));
     }
-    if (node_path.extname(path) === ".ts") {
+    else if (node_path.extname(path) === ".ts") {
         const { entry, cleanup } = await compileTsConfigGraph(path);
         try {
             const mod = (await import(node_url.pathToFileURL(entry).href));
-            return ((_b = (_a = mod.default) !== null && _a !== void 0 ? _a : mod.raw) !== null && _b !== void 0 ? _b : mod);
+            candidate = (_b = (_a = mod.default) !== null && _a !== void 0 ? _a : mod.raw) !== null && _b !== void 0 ? _b : mod;
         }
         finally {
             cleanup();
         }
     }
-    const mod = (await import(`${node_url.pathToFileURL(path).href}?v=${++counter}`));
-    return ((_d = (_c = mod.default) !== null && _c !== void 0 ? _c : mod.raw) !== null && _d !== void 0 ? _d : mod);
+    else {
+        const mod = (await import(`${node_url.pathToFileURL(path).href}?v=${++counter}`));
+        candidate = (_d = (_c = mod.default) !== null && _c !== void 0 ? _c : mod.raw) !== null && _d !== void 0 ? _d : mod;
+    }
+    assertRawTheme(candidate, path);
+    return candidate;
 }
 /** Does this built theme expose the class-emitting surface (CSS-style adapter)? */
 const emitsClasses = (theme) => typeof theme.renderRecipe === "function";
@@ -7831,6 +7947,746 @@ async function runDiff(options) {
     return { configPath, candidatePath, diff, targets, ok: violations.length === 0, violations };
 }
 
+/**
+ * Guided raw-theme generator (Node-only, pure) — the engine behind `refract create`.
+ *
+ * Turns a seed colour plus a handful of answers into a complete `RawTheme`. Deliberately split from
+ * the prompting (`cli.ts`) and from the file writing (`createCommand.ts`) so the whole generator is
+ * testable without a TTY and reusable programmatically.
+ *
+ * The governing rule for what lands in the output:
+ *
+ *   **Bake a literal** where the value came from an opinion the engine does not hold — the harmony
+ *   rotation, the contrast nudge, the leading/tracking curves. Those are this module's taste, and a
+ *   scaffolded theme is a style guide the user then owns, so it must hold still.
+ *
+ *   **Write the declaration** where the engine already synthesizes — `fontSize.ratio`,
+ *   `layout.spacing.step`. Baking those would throw the intent away: re-tuning a scale should stay a
+ *   one-word edit, not a regeneration of eight numbers.
+ *
+ * Nothing here changes the palette model. It calls the colour helpers the package already ships
+ * (`rotateHue`/`darken`, and `audit` for the contrast gate) and writes down what they return, once.
+ * Callers who want a companion that *re-derives* on `override()` should use `colors.harmony` instead —
+ * that is the other tool, for the other job.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Tunable constants — the generator's opinions, deliberately in the open.
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Leading falls as size grows: `LEADING_AT_BASE × (BASE_PX / size) ^ LEADING_EXPONENT`, clamped.
+ * Fitted to land on conventional values at 16px (1.50) and to tighten a display line enough that a
+ * dramatic ratio doesn't ship a 67px headline set at 1.5. Another designer would pick differently.
+ */
+const LEADING_AT_BASE = 1.5;
+const LEADING_EXPONENT = 0.22;
+const LEADING_MIN = 1.1;
+const LEADING_MAX = 1.7;
+/**
+ * Tracking crosses from positive (small text wants air) to negative (display text wants tightening):
+ * `TRACKING_NUMERATOR / size − TRACKING_OFFSET`, in em. Zero at 16px by construction.
+ */
+const TRACKING_NUMERATOR = 0.36;
+const TRACKING_OFFSET = 0.0225;
+/** The reference size both curves are anchored at. */
+const CURVE_ANCHOR_PX = 16;
+/** The engine's default `fontSize` step names and their exponent off `base`. Mirrors typography. */
+const TYPE_STEPS = [
+    ["xs", -2], ["sm", -1], ["md", 0], ["lg", 1],
+    ["xl", 2], ["2xl", 3], ["3xl", 4], ["4xl", 5],
+];
+/** Numeric value of each named type ratio. Mirrors `TYPOGRAPHY_RATIOS` in the typography subsystem. */
+const RATIO_VALUES = {
+    "minor-second": 1.067, "major-second": 1.125, "minor-third": 1.2, "major-third": 1.25,
+    "perfect-fourth": 1.333, "augmented-fourth": 1.414, "perfect-fifth": 1.5, golden: 1.618,
+};
+/**
+ * Hue rotations per scheme. Aligned with the colours subsystem's own `HARMONY_SCHEMES` where they
+ * overlap, so a scaffolded literal and an authored `harmony:` key agree. `pentadic` is local — the
+ * subsystem has no five-way scheme, and the scaffolder needs one to reach five brand colours.
+ */
+const SCHEME_ROTATIONS = {
+    complement: [180],
+    analogous: [-30, 30],
+    "split-complement": [150, 210],
+    triadic: [120, 240],
+    tetradic: [90, 180, 270],
+    pentadic: [72, 144, 216, 288],
+};
+/** Ordinal names for the generated brand palettes. Rename freely — it's your file. */
+const BRAND_NAMES = ["primary", "secondary", "tertiary", "quaternary", "quinary"];
+/**
+ * Semantic colours start from fixed hue anchors, NOT from a rotation off the seed. Rotating would
+ * make "danger" whatever hue lands at +150° — from a red seed you'd get a green danger, which is
+ * worse than useless. These are conventional anchors; the contrast pass then adapts their lightness.
+ */
+const SEMANTIC_ANCHORS = [
+    ["success", "#2f9e44", "#ffffff"],
+    ["info", "#1c7ed6", "#ffffff"],
+    ["warning", "#e89012", "#1f2733"],
+    ["danger", "#e03131", "#ffffff"],
+];
+/** The neutral seed and the shadow ink. Both are deliberately cool — they sit under everything. */
+const NEUTRAL_SEED = "#6b7280";
+const SHADOW_INK = "#18274b";
+/** The absolute lightness ladder every palette carries. `L = (1000 − label) / 10`. */
+const LADDER = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+/** Alpha levels for the shadow tints, matched to the three elevation levels. */
+const SHADOW_ALPHAS = [8, 14, 22];
+/** How many times the contrast pass may darken a failing palette before giving up. */
+const MAX_CONTRAST_ITERATIONS = 40;
+const SYSTEM_SANS = "system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
+const SYSTEM_MONO = "ui-monospace, 'SF Mono', Menlo, Consolas, monospace";
+const SYSTEM_SERIF = "'Iowan Old Style', 'Palatino Linotype', Palatino, Georgia, serif";
+const FEEL_PRESETS = {
+    neutral: {
+        label: "Neutral",
+        blurb: "system type, comfortable spacing, soft corners",
+        fontFamily: { base: SYSTEM_SANS, mono: SYSTEM_MONO },
+        spacing: { xs: 1, sm: 2, md: 4, lg: 6, xl: 8, "2xl": 12 },
+        radius: { base: 8, variants: { none: 0, sm: 4, lg: 14, pill: "9999px" } },
+        ratio: "major-third",
+    },
+    compact: {
+        label: "Compact",
+        blurb: "dense UI, tight scale, small radius",
+        fontFamily: { base: SYSTEM_SANS, mono: SYSTEM_MONO },
+        spacing: { xs: 1, sm: 2, md: 3, lg: 4, xl: 6, "2xl": 8 },
+        radius: { base: 4, variants: { none: 0, sm: 2, lg: 8, pill: "9999px" } },
+        ratio: "major-second",
+    },
+    editorial: {
+        label: "Editorial",
+        blurb: "serif display, spacious, generous leading",
+        fontFamily: { base: SYSTEM_SERIF, mono: SYSTEM_MONO },
+        spacing: { xs: 2, sm: 4, md: 6, lg: 8, xl: 12, "2xl": 16 },
+        radius: { base: 2, variants: { none: 0, sm: 1, lg: 4, pill: "9999px" } },
+        ratio: "perfect-fourth",
+    },
+    technical: {
+        label: "Technical",
+        blurb: "mono accents, compact, sharp corners",
+        fontFamily: { base: SYSTEM_MONO, mono: SYSTEM_MONO },
+        spacing: { xs: 1, sm: 2, md: 3, lg: 4, xl: 6, "2xl": 8 },
+        radius: { base: 0, variants: { none: 0, sm: 0, lg: 2, pill: "9999px" } },
+        ratio: "minor-third",
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+const round = (n, places) => Number(n.toFixed(places));
+/** Normalize any accepted colour input to a `#rrggbb` literal, so the written file is uniform. */
+const toHex = (value) => convertRgbToHex(parseColor(value).rgb);
+/** Leading for a size, from the curve above. */
+const deriveLeading = (sizePx) => round(Math.min(LEADING_MAX, Math.max(LEADING_MIN, LEADING_AT_BASE * Math.pow(CURVE_ANCHOR_PX / sizePx, LEADING_EXPONENT))), 2);
+/** Tracking (em) for a size, from the curve above. */
+const deriveTracking = (sizePx) => `${round(TRACKING_NUMERATOR / sizePx - TRACKING_OFFSET, 3)}em`;
+/**
+ * The ladder label a colour's lightness sits nearest. `base` stays the brand colour — this exists so
+ * the CLI can tell you which stops are your hover and active shades without moving the hex you typed.
+ */
+const nearestLadderStep = (lightness) => {
+    const label = 1000 - lightness * 10;
+    let best = LADDER[0];
+    for (const stop of LADDER)
+        if (Math.abs(stop - label) < Math.abs(best - label))
+            best = stop;
+    return best;
+};
+/** Which scheme a brand count implies when the caller doesn't name one. */
+const defaultSchemeFor = (brandCount) => {
+    if (brandCount <= 1)
+        return undefined;
+    if (brandCount === 2)
+        return "complement";
+    if (brandCount === 3)
+        return "triadic";
+    if (brandCount === 4)
+        return "tetradic";
+    return "pentadic";
+};
+/** Schemes that produce exactly `brandCount − 1` members — the valid choices at that count. */
+const schemesFor = (brandCount) => Object.keys(SCHEME_ROTATIONS).filter((s) => SCHEME_ROTATIONS[s].length === brandCount - 1);
+/**
+ * The contrast gate. Builds the palette set, audits every text-on-base pairing, and walks the
+ * lightness of each failing colour down one OKLCH point at a time until it clears the bar.
+ *
+ * Iterative rather than closed-form because the ratio is not monotonic in a way worth inverting, and
+ * because `audit` owns the thresholds — re-running it is how the generator stays honest about what
+ * the library considers a pass.
+ */
+function applyContrastPass(palettes, bar) {
+    var _a;
+    const current = palettes.map((p) => ({ ...p }));
+    const nudges = new Map(current.map((p) => [p.name, 0]));
+    const firstRatio = new Map();
+    const scoreAll = () => {
+        var _a, _b;
+        const colors = {};
+        for (const p of current)
+            colors[p.name] = { base: p.base, text: p.text };
+        const theme = createTheme({ colors }, { adapter: createNoopAdapter() });
+        const result = audit(theme, { minWcag: bar, includeRecipes: false });
+        const out = new Map();
+        for (const pairing of result.pairings) {
+            // A pairing whose fg/bg isn't a derivable colour is reported as `skipped` with no score. It
+            // can't be nudged toward a bar it was never measured against, so leave it out entirely.
+            if (pairing.skipped || pairing.wcagRatio === undefined)
+                continue;
+            const name = pairing.label.replace(/^colors\./, "");
+            out.set(name, {
+                ratio: pairing.wcagRatio,
+                level: (_a = pairing.wcagLevel) !== null && _a !== void 0 ? _a : "fail",
+                pass: (_b = pairing.pass) !== null && _b !== void 0 ? _b : false,
+            });
+        }
+        return out;
+    };
+    let scores = scoreAll();
+    for (const [name, s] of scores)
+        if (!firstRatio.has(name))
+            firstRatio.set(name, s.ratio);
+    for (let i = 0; i < MAX_CONTRAST_ITERATIONS; i++) {
+        const failing = current.filter((p) => scores.get(p.name) && !scores.get(p.name).pass);
+        if (!failing.length)
+            break;
+        for (const p of failing) {
+            p.base = toHex(darken(p.base, 1));
+            nudges.set(p.name, ((_a = nudges.get(p.name)) !== null && _a !== void 0 ? _a : 0) + 1);
+        }
+        scores = scoreAll();
+    }
+    const adjustments = current.map((p, idx) => {
+        var _a, _b, _c, _d;
+        const s = scores.get(p.name);
+        return {
+            name: p.name,
+            seed: palettes[idx].base,
+            final: p.base,
+            nudge: (_a = nudges.get(p.name)) !== null && _a !== void 0 ? _a : 0,
+            ratioBefore: round((_b = firstRatio.get(p.name)) !== null && _b !== void 0 ? _b : 0, 2),
+            ratioAfter: round((_c = s === null || s === void 0 ? void 0 : s.ratio) !== null && _c !== void 0 ? _c : 0, 2),
+            levelAfter: (_d = s === null || s === void 0 ? void 0 : s.level) !== null && _d !== void 0 ? _d : "fail",
+            unresolved: !!s && !s.pass,
+        };
+    });
+    return { palettes: current, adjustments };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// The generator
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Build a complete `RawTheme` from the interview answers. Pure — no filesystem, no prompting, no
+ * randomness — so the same answers always produce the same theme.
+ */
+function scaffoldTheme(answers) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const mode = (_a = answers.mode) !== null && _a !== void 0 ? _a : "auto";
+    const feel = FEEL_PRESETS[(_b = answers.feel) !== null && _b !== void 0 ? _b : "neutral"];
+    const brandCount = Math.min(5, Math.max(1, (_c = answers.brandCount) !== null && _c !== void 0 ? _c : 2));
+    const baseFontSize = (_d = answers.baseFontSize) !== null && _d !== void 0 ? _d : CURVE_ANCHOR_PX;
+    const ratioName = (_e = answers.ratio) !== null && _e !== void 0 ? _e : feel.ratio;
+    const ratioValue = RATIO_VALUES[ratioName];
+    if (!ratioValue) {
+        throw new Error(`Unknown type ratio "${ratioName}". Use one of: ${Object.keys(RATIO_VALUES).join(", ")}.`);
+    }
+    // ── brand colours ──────────────────────────────────────────────────────────
+    const seedHex = toHex(answers.seed);
+    const brand = [
+        { name: BRAND_NAMES[0], hex: seedHex, rotation: 0 },
+    ];
+    if (mode === "manual") {
+        ((_f = answers.extraColors) !== null && _f !== void 0 ? _f : []).slice(0, BRAND_NAMES.length - 1).forEach((c, i) => {
+            brand.push({ name: BRAND_NAMES[i + 1], hex: toHex(c), rotation: 0 });
+        });
+    }
+    else if (brandCount > 1) {
+        const scheme = (_g = answers.scheme) !== null && _g !== void 0 ? _g : defaultSchemeFor(brandCount);
+        const rotations = SCHEME_ROTATIONS[scheme];
+        if (!rotations)
+            throw new Error(`Unknown harmony scheme "${scheme}".`);
+        rotations.slice(0, brandCount - 1).forEach((deg, i) => {
+            brand.push({ name: BRAND_NAMES[i + 1], hex: toHex(rotateHue(seedHex, deg)), rotation: deg });
+        });
+    }
+    // ── the contrast gate ──────────────────────────────────────────────────────
+    const contrastTarget = (_h = answers.contrast) !== null && _h !== void 0 ? _h : "AA";
+    const candidates = [
+        ...brand.map((b) => ({ name: b.name, base: b.hex, text: "#ffffff" })),
+        ...(answers.semantics === false ? [] : SEMANTIC_ANCHORS.map(([n, base, text]) => ({ name: n, base, text }))),
+        ...(answers.neutral === false ? [] : [{ name: "neutral", base: NEUTRAL_SEED, text: "#ffffff" }]),
+    ];
+    const { palettes, adjustments } = contrastTarget === "none"
+        ? { palettes: candidates, adjustments: [] }
+        : applyContrastPass(candidates, contrastTarget);
+    // ── colors ─────────────────────────────────────────────────────────────────
+    const colors = {};
+    for (const p of palettes)
+        colors[p.name] = { base: p.base, text: p.text, steps: [...LADDER] };
+    if (answers.shadows !== false) {
+        const variants = {};
+        for (const a of SHADOW_ALPHAS)
+            variants[`a${String(a).padStart(2, "0")}`] = { modifiers: [{ alpha: a }] };
+        colors.shadow = { base: SHADOW_INK, variants };
+    }
+    // ── typography ─────────────────────────────────────────────────────────────
+    // `fontSize` is a DECLARATION — the engine synthesizes xs…4xl from base + ratio. Leading and
+    // tracking are baked, because the curves are this module's opinion, and they're named after the
+    // size step they were tuned for so the pairing documents itself without a recipe.
+    const sizes = TYPE_STEPS.map(([step, exp]) => ({ step, px: round(baseFontSize * Math.pow(ratioValue, exp), 2) }));
+    const leading = {};
+    const tracking = {};
+    for (const { step, px } of sizes) {
+        if (step === "md")
+            continue; // md === base; the base value covers it
+        leading[step] = deriveLeading(px);
+        tracking[step] = deriveTracking(px);
+    }
+    tracking.caps = "0.06em"; // caps always want more air than the curve gives
+    const typography = {
+        fontFamily: { base: feel.fontFamily.base, variants: { mono: feel.fontFamily.mono } },
+        fontWeight: { base: 400, variants: { medium: 500, semibold: 600, bold: 700 } },
+        fontSize: { base: baseFontSize, ratio: ratioName },
+        lineHeight: { base: deriveLeading(baseFontSize), variants: leading },
+        letterSpacing: { base: "0em", variants: tracking },
+    };
+    // ── layout ─────────────────────────────────────────────────────────────────
+    // The LINEAR curve, not the geometric one: `step: 4` keeps every stop on a 4px grid, where
+    // `ratio: 1.5` would give 8·12·18·27·40.5·60.75. Geometric is right for type and wrong for space.
+    const layout = { spacing: { base: 4, step: 4, steps: { ...feel.spacing } } };
+    // ── borders · effects · animation · globals ────────────────────────────────
+    const borders = {
+        width: { base: 1, variants: { thick: 2 } },
+        style: { base: "solid" },
+        radius: { base: feel.radius.base, variants: { ...feel.radius.variants } },
+    };
+    const effects = answers.shadows === false
+        ? undefined
+        : {
+            shadow: {
+                offsetY: 1, blur: 3, color: "colors.shadow.a08",
+                variants: {
+                    md: { offsetY: 6, blur: 16, color: "colors.shadow.a14" },
+                    lg: { offsetY: 14, blur: 34, color: "colors.shadow.a22" },
+                    none: "none",
+                },
+            },
+        };
+    // No `keyframes`: one would only pay off with a recipe to reference it, and the scaffold writes
+    // no recipes — so generating one would ship dead CSS.
+    const animation = {
+        duration: { base: 200, variants: { fast: 120, slow: 400 } },
+        easing: { base: "cubic-bezier(.2,.7,.3,1)", variants: { out: "cubic-bezier(.16,.84,.44,1)" } },
+    };
+    const raw = {
+        colors,
+        typography,
+        layout,
+        borders,
+        ...(effects ? { effects } : {}),
+        animation,
+        ...(answers.reset === "none" ? {} : { globals: { preset: (_j = answers.reset) !== null && _j !== void 0 ? _j : "preflight" } }),
+    };
+    const seedLightness = round(rgbToOklch(parseColor(seedHex).rgb).L, 1);
+    return {
+        raw,
+        report: {
+            seedLightness,
+            nearestStep: nearestLadderStep(seedLightness),
+            brand: brand.map((b) => {
+                var _a;
+                const adjusted = adjustments.find((a) => a.name === b.name);
+                return { name: b.name, hex: (_a = adjusted === null || adjusted === void 0 ? void 0 : adjusted.final) !== null && _a !== void 0 ? _a : b.hex, rotation: b.rotation };
+            }),
+            contrast: adjustments,
+            type: sizes.map(({ step, px }) => ({
+                step, px, leading: deriveLeading(px), tracking: deriveTracking(px),
+            })),
+            spacing: Object.entries(feel.spacing).map(([step, mult]) => ({ step, px: mult * 4 })),
+        },
+    };
+}
+
+/**
+ * `refract create` — write a scaffolded `theme.raw.(ts|js|json)` (Node-only).
+ *
+ * The interview lives in `cli.ts`; the generator lives in `scaffold.ts`. This module is only the
+ * seam between them: resolve answers → generate → serialize → write, refusing to clobber.
+ *
+ * One artefact per command. `create` writes the raw theme and nothing else — no build config (that's
+ * `init`, which detects this file), and no rendered specimen (that's a build-time concern, since a
+ * `RawTheme` has no rendered form and this command has no idea which adapter you'll build with).
+ *
+ * Mirrors `import`'s conventions on purpose — same default filename, same refuse-to-clobber, same
+ * "a theme you then own and edit" framing — because they're the same job from a different input.
+ */
+const DEFAULT_RAW_BASENAME = "theme.raw";
+/** A key that can be written bare in JS/TS source rather than quoted. */
+const BARE_KEY = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Characters that must be escaped inside a double-quoted source string. */
+const escapeString = (s) => JSON.stringify(s);
+/** Width at which a primitive-only array stops being inlined and goes one-per-line. */
+const INLINE_ARRAY_WIDTH = 76;
+/**
+ * Pretty-print a value as JS/TS source.
+ *
+ * `JSON.stringify` would be shorter, but it quotes every key and explodes a ten-number ladder over
+ * ten lines — and this file's entire premise is that you open it and edit it. So: bare keys where
+ * they're legal, and primitive arrays kept on one line while they fit.
+ */
+function formatLiteral(value, indent = 0) {
+    const pad = "  ".repeat(indent);
+    const padInner = "  ".repeat(indent + 1);
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return escapeString(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        if (!value.length)
+            return "[]";
+        const primitives = value.every(v => v === null || typeof v !== "object");
+        if (primitives) {
+            const inline = `[${value.map(v => formatLiteral(v)).join(", ")}]`;
+            if (pad.length + inline.length <= INLINE_ARRAY_WIDTH)
+                return inline;
+        }
+        const items = value.map(v => `${padInner}${formatLiteral(v, indent + 1)}`);
+        return `[\n${items.join(",\n")}\n${pad}]`;
+    }
+    const entries = Object.entries(value);
+    if (!entries.length)
+        return "{}";
+    const lines = entries.map(([key, v]) => {
+        const name = BARE_KEY.test(key) ? key : escapeString(key);
+        return `${padInner}${name}: ${formatLiteral(v, indent + 1)}`;
+    });
+    return `{\n${lines.join(",\n")}\n${pad}}`;
+}
+/** Shared preamble for the code flavours. Kept short — the file is the user's from here on. */
+const banner = (seed, detail) => `// Generated by \`refract create\` — seed ${seed} · ${detail}.\n` +
+    `// This is YOUR theme now: every value is a literal you can read, edit and delete. The generator\n` +
+    `// does not run again. Tonal ladders, the type scale and the spacing ramp are synthesized by the\n` +
+    `// engine from the declarations below — re-tune a scale by editing one word, not eight numbers.\n`;
+/**
+ * Serialize a generated theme to source text.
+ *
+ * `ts` and `js` share one body and differ only in how the type is attached (a real `satisfies` vs a
+ * JSDoc cast), so a JS user gets the same editor completion without adding a compile step. `json`
+ * carries no types and no shared `ladder` const — it is the portable flavour, and for a scaffolded
+ * theme it is exactly as faithful, because nothing here is a function or a recipe.
+ */
+function renderRawTheme(raw, options) {
+    // JSON stays strict JSON — quoted keys, no trailing anything — so it parses anywhere.
+    if (options.format === "json")
+        return `${JSON.stringify(raw, null, 2)}\n`;
+    const body = formatLiteral(raw);
+    if (options.format === "js") {
+        return (`${banner(options.seed, options.detail)}\n` +
+            `/** @type {import("${options.packageName}/build").RawTheme} */\n` +
+            `export const raw = ${body};\n`);
+    }
+    return (`${banner(options.seed, options.detail)}` +
+        `import type { RawTheme } from "${options.packageName}/build";\n\n` +
+        `export const raw = ${body} satisfies RawTheme;\n`);
+}
+/** A one-line description of the choices that produced a theme, for the file banner. */
+function describeChoices(options) {
+    var _a, _b, _c, _d, _e, _f;
+    const parts = [];
+    const count = options.mode === "manual" ? ((_b = (_a = options.extraColors) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) + 1 : (_c = options.brandCount) !== null && _c !== void 0 ? _c : 2;
+    parts.push(`${count} brand colour${count === 1 ? "" : "s"}`);
+    if (options.mode !== "manual" && count > 1)
+        parts.push((_d = options.scheme) !== null && _d !== void 0 ? _d : "auto");
+    parts.push((_e = options.feel) !== null && _e !== void 0 ? _e : "neutral");
+    if (options.contrast !== "none")
+        parts.push(`WCAG ${(_f = options.contrast) !== null && _f !== void 0 ? _f : "AA"}`);
+    return parts.join(" · ");
+}
+/**
+ * Generate and write the raw theme. Throws when the target exists and `force` is not set — the same
+ * guard `init` and `import` use, so no command in this CLI can silently destroy authored work.
+ */
+function runCreate(options) {
+    var _a, _b, _c, _d;
+    const cwd = (_a = options.cwd) !== null && _a !== void 0 ? _a : process.cwd();
+    const format = (_b = options.format) !== null && _b !== void 0 ? _b : "ts";
+    const filename = (_c = options.out) !== null && _c !== void 0 ? _c : `${DEFAULT_RAW_BASENAME}.${format}`;
+    const path = node_path.join(cwd, filename);
+    if (node_fs.existsSync(path) && !options.force) {
+        throw new Error(`"${filename}" already exists. Re-run with --force to overwrite it.`);
+    }
+    const { raw, report } = scaffoldTheme(options);
+    const packageName = (_d = options.packageName) !== null && _d !== void 0 ? _d : readOwnPackageName();
+    const source = renderRawTheme(raw, {
+        format,
+        packageName,
+        seed: options.seed,
+        detail: describeChoices(options),
+    });
+    node_fs.writeFileSync(path, source, "utf8");
+    return { path, format, raw, report, sections: Object.keys(raw) };
+}
+
+/**
+ * Minimal interactive prompts over `node:readline` (Node-only).
+ *
+ * The package ships zero runtime dependencies and this is the build layer, so rather than pull in a
+ * prompt library for one command these are the four shapes the CLI actually needs. They are
+ * line-based, not raw-mode: you type a number or a value and press Enter. That loses arrow-key
+ * navigation, and buys a prompt that behaves predictably over SSH, in CI logs, in a Docker build,
+ * and under any terminal that doesn't grant raw mode — where a fancier prompt would hang or garble.
+ *
+ * Every prompt is **non-interactive-safe**: with no TTY (a pipe, CI, `--yes`) it takes the default
+ * without blocking, so a scripted run never deadlocks waiting on stdin that will never arrive.
+ */
+/** ANSI helpers — no-ops when the stream isn't a TTY, so piped output stays clean. */
+const useColor = () => Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const paint = (code, s) => (useColor() ? `\u001b[${code}m${s}\u001b[0m` : s);
+const bold = (s) => paint("1", s);
+const dim = (s) => paint("2", s);
+const cyan = (s) => paint("36", s);
+const green = (s) => paint("32", s);
+const yellow = (s) => paint("33", s);
+/**
+ * A prompt session. Holds one readline interface for the whole interview so stdin is opened and
+ * closed exactly once; `interactive` is false when there's no TTY, and every ask short-circuits to
+ * its default.
+ */
+class Prompter {
+    constructor(interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)) {
+        this.interactive = interactive;
+    }
+    get io() {
+        if (!this.rl)
+            this.rl = node_readline.createInterface({ input: process.stdin, output: process.stdout });
+        return this.rl;
+    }
+    close() {
+        var _a;
+        (_a = this.rl) === null || _a === void 0 ? void 0 : _a.close();
+        this.rl = undefined;
+    }
+    question(text) {
+        return new Promise(resolve => this.io.question(text, answer => resolve(answer)));
+    }
+    /** Print a line to stdout. Kept on the prompter so command code never touches `process.stdout`. */
+    write(line = "") {
+        process.stdout.write(`${line}\n`);
+    }
+    /** Free-text, with a default shown in the prompt. Blank input takes the default. */
+    async text(label, fallback, validate) {
+        if (!this.interactive)
+            return fallback;
+        for (;;) {
+            const answer = (await this.question(`${cyan("?")} ${bold(label)} ${dim(`(${fallback})`)} `)).trim();
+            const value = answer || fallback;
+            const error = validate === null || validate === void 0 ? void 0 : validate(value);
+            if (!error)
+                return value;
+            this.write(`  ${yellow("!")} ${error}`);
+        }
+    }
+    /** A number, validated as finite. */
+    async number(label, fallback, validate) {
+        const answer = await this.text(label, String(fallback), v => {
+            const n = Number(v);
+            if (!Number.isFinite(n))
+                return `"${v}" is not a number.`;
+            return validate === null || validate === void 0 ? void 0 : validate(n);
+        });
+        return Number(answer);
+    }
+    /** Pick one. Answers are 1-based indices; blank takes the default (the first choice unless given). */
+    async select(label, choices, defaultIndex = 0) {
+        var _a, _b;
+        if (!this.interactive || choices.length === 1)
+            return (_b = (_a = choices[defaultIndex]) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : choices[0].value;
+        this.write(`${cyan("?")} ${bold(label)}`);
+        choices.forEach((c, i) => {
+            const marker = i === defaultIndex ? green("❯") : " ";
+            const hint = c.hint ? ` ${dim(`— ${c.hint}`)}` : "";
+            this.write(`  ${marker} ${dim(`${i + 1}.`)} ${i === defaultIndex ? bold(c.label) : c.label}${hint}`);
+        });
+        for (;;) {
+            const answer = (await this.question(`  ${dim(`1–${choices.length}`)} `)).trim();
+            if (!answer)
+                return choices[defaultIndex].value;
+            const index = Number(answer) - 1;
+            if (Number.isInteger(index) && index >= 0 && index < choices.length)
+                return choices[index].value;
+            this.write(`  ${yellow("!")} Enter a number between 1 and ${choices.length}.`);
+        }
+    }
+    /**
+     * Pick any. Answers are comma-separated indices; blank keeps the pre-selected set, and an explicit
+     * `none` clears it — otherwise there'd be no way to deselect everything with a line-based prompt.
+     */
+    async multiselect(label, choices, preselected) {
+        if (!this.interactive)
+            return preselected.map(i => choices[i].value);
+        this.write(`${cyan("?")} ${bold(label)} ${dim("(comma-separated, blank = keep, \"none\" = clear)")}`);
+        choices.forEach((c, i) => {
+            const on = preselected.includes(i);
+            const hint = c.hint ? ` ${dim(`— ${c.hint}`)}` : "";
+            this.write(`  ${on ? green("◉") : dim("◯")} ${dim(`${i + 1}.`)} ${c.label}${hint}`);
+        });
+        for (;;) {
+            const answer = (await this.question(`  ${dim(`1–${choices.length}`)} `)).trim().toLowerCase();
+            if (!answer)
+                return preselected.map(i => choices[i].value);
+            if (answer === "none")
+                return [];
+            const parts = answer.split(",").map(s => Number(s.trim()) - 1);
+            if (parts.every(i => Number.isInteger(i) && i >= 0 && i < choices.length)) {
+                return parts.map(i => choices[i].value);
+            }
+            this.write(`  ${yellow("!")} Enter numbers between 1 and ${choices.length}, separated by commas.`);
+        }
+    }
+}
+
+/** What each harmony scheme is for, in one line — the names mean nothing to most people. */
+const SCHEME_HINTS = {
+    complement: "one companion, 180° opposite — maximum separation",
+    analogous: "two neighbours, ±30° — quiet and cohesive",
+    "split-complement": "the complement's neighbours — contrast with less tension",
+    triadic: "even thirds, ±120° — three colours of equal weight",
+    tetradic: "two complementary pairs — the most range",
+    pentadic: "five evenly spaced hues — needs a dominant colour picked by hand",
+};
+/**
+ * Ratio choices, tightest to most dramatic, each showing the ladder it produces from 16px. The ratio
+ * is the most consequential typographic choice in the theme and its name carries no information, so
+ * the numbers do the explaining.
+ */
+const TYPE_SCALE_CHOICES = [
+    ["major-second", "1.125 · 16 · 18 · 20 · 23 · 26 · 29"],
+    ["minor-third", "1.2 · 16 · 19 · 23 · 28 · 33 · 40"],
+    ["major-third", "1.25 · 16 · 20 · 25 · 31 · 39 · 49"],
+    ["perfect-fourth", "1.333 · 16 · 21 · 28 · 38 · 51 · 67"],
+    ["perfect-fifth", "1.5 · 16 · 24 · 36 · 54 · 81 · 122"],
+    ["golden", "1.618 · 16 · 26 · 42 · 68 · 110 · 178"],
+];
+const isColor = (v) => {
+    try {
+        parseColor(v);
+        return undefined;
+    }
+    catch {
+        return `"${v}" isn't a colour refract can parse. Try a hex like #4c6ef5.`;
+    }
+};
+/**
+ * Run the interview. Anything present in `given` is taken as answered and never asked.
+ *
+ * The scheme question only appears when the brand count admits more than one rotation set — which is
+ * only at three colours. Two is a complement, four a tetradic, five a pentadic: asking would be a
+ * prompt with a single option.
+ */
+async function promptCreateAnswers(p, given = {}) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const seed = (_a = given.seed) !== null && _a !== void 0 ? _a : (await p.text("Primary colour", "#4c6ef5", isColor));
+    const lightness = Math.round(rgbToOklch(parseColor(seed).rgb).L * 10) / 10;
+    p.write(`  ${dim(`parsed · lightness ${lightness}% — lands at ≈${nearestLadderStep(lightness)} on the ladder`)}`);
+    p.write();
+    const manual = Boolean(given.manual);
+    let brandCount = 2;
+    let scheme;
+    let extraColors = [];
+    if (manual) {
+        extraColors = ((_b = given.colors) !== null && _b !== void 0 ? _b : "").split(",").map(s => s.trim()).filter(Boolean);
+        if (!extraColors.length && p.interactive) {
+            const total = await p.number("How many brand colours in total?", 2, n => Number.isInteger(n) && n >= 1 && n <= 5 ? undefined : "Pick a whole number from 1 to 5.");
+            for (let i = 1; i < total; i++) {
+                extraColors.push(await p.text(`Brand colour ${i + 1}`, "#e64980", isColor));
+            }
+        }
+        brandCount = extraColors.length + 1;
+    }
+    else {
+        brandCount = given.colors
+            ? Number(given.colors)
+            : await p.number("How many brand colours? (including the primary)", 2, n => Number.isInteger(n) && n >= 1 && n <= 5 ? undefined : "Pick a whole number from 1 to 5.");
+        const options = schemesFor(brandCount);
+        scheme = (_c = given.scheme) !== null && _c !== void 0 ? _c : defaultSchemeFor(brandCount);
+        if (!given.scheme && options.length > 1) {
+            scheme = await p.select("Harmony scheme", options.map(s => ({ value: s, label: s, hint: SCHEME_HINTS[s] })), Math.max(0, options.indexOf(scheme)));
+        }
+        if (scheme && brandCount > 1) {
+            p.write(`  ${dim(`→ ${scheme} · each member becomes its own palette with a full ladder`)}`);
+            p.write();
+        }
+    }
+    const anyExtraFlag = given.noSemantics || given.noNeutral || given.noShadows;
+    const extras = anyExtraFlag || !p.interactive
+        ? { semantics: !given.noSemantics, neutral: !given.noNeutral, shadows: !given.noShadows }
+        : await (async () => {
+            const picked = await p.multiselect("Also add", [
+                { value: "semantics", label: "Semantic colours", hint: "success · info · warning · danger" },
+                { value: "neutral", label: "Neutral ramp", hint: "50 … 900" },
+                { value: "shadows", label: "Shadow tints", hint: "3 alpha levels + the effects ramp" },
+            ], [0, 1, 2]);
+            return {
+                semantics: picked.includes("semantics"),
+                neutral: picked.includes("neutral"),
+                shadows: picked.includes("shadows"),
+            };
+        })();
+    const contrast = (_d = given.contrast) !== null && _d !== void 0 ? _d : await p.select("Contrast target", [
+        { value: "AA", label: "WCAG AA", hint: "4.5:1 body text" },
+        { value: "AAA", label: "WCAG AAA", hint: "7:1 — expect heavier nudges" },
+        { value: "none", label: "Skip", hint: "write the colours exactly as given" },
+    ]);
+    const baseFontSize = given.baseSize !== undefined
+        ? Number(given.baseSize)
+        : await p.number("Base font size (px)", 16, n => (n > 0 ? undefined : "Must be greater than zero."));
+    const feel = (_e = given.feel) !== null && _e !== void 0 ? _e : await p.select("Overall feel", Object.keys(FEEL_PRESETS).map(k => ({
+        value: k, label: FEEL_PRESETS[k].label, hint: FEEL_PRESETS[k].blurb,
+    })));
+    const ratio = (_f = given.ratio) !== null && _f !== void 0 ? _f : await p.select("Type scale", TYPE_SCALE_CHOICES.map(([value, hint]) => ({ value, label: value, hint })), Math.max(0, TYPE_SCALE_CHOICES.findIndex(([v]) => v === FEEL_PRESETS[feel].ratio)));
+    const reset = (_g = given.reset) !== null && _g !== void 0 ? _g : await p.select("CSS reset", [
+        { value: "preflight", label: "preflight", hint: "full normalization + an h1–h6 size map" },
+        { value: "normalize", label: "normalize", hint: "the classic, no heading map" },
+        { value: "none", label: "none", hint: "you already ship one" },
+    ]);
+    const format = (_h = given.format) !== null && _h !== void 0 ? _h : await p.select("Format", [
+        { value: "ts", label: "theme.raw.ts", hint: "typed, `satisfies RawTheme`" },
+        { value: "js", label: "theme.raw.js", hint: "plain ESM, no build step" },
+        { value: "json", label: "theme.raw.json", hint: "portable, no code at all" },
+    ]);
+    return {
+        seed, mode: manual ? "manual" : "auto", brandCount, scheme, extraColors,
+        ...extras, contrast, baseFontSize, ratio, feel, reset, format,
+    };
+}
+/**
+ * The post-generation summary: what the contrast pass did, and what landed. Returned as lines rather
+ * than printed so each host can frame them — the standalone command and the project scaffolder put
+ * different things around the same facts.
+ */
+function createReportLines(result, variableCount) {
+    const lines = [];
+    const { contrast } = result.report;
+    if (contrast.length) {
+        lines.push(`  ${dim(`Contrast · ${contrast.length} pairings checked`)}`);
+        for (const c of contrast) {
+            const shift = c.nudge > 0
+                ? `${yellow(`−${c.nudge}`)} ${green(`${c.ratioAfter} ${c.levelAfter}`)}`
+                : dim("unchanged");
+            const flag = c.unresolved ? ` ${yellow("! still short of the bar")}` : "";
+            lines.push(`    ${c.name.padEnd(10)} ${String(c.ratioBefore).padStart(5)}  ${shift}${flag}`);
+        }
+        lines.push("");
+    }
+    const nudged = contrast.filter(c => c.nudge > 0).length;
+    lines.push(`  ${dim(`${result.sections.length} subsystems · ${variableCount} variables · 0 recipes`)}`);
+    if (nudged)
+        lines.push(`  ${dim(`${nudged} colour${nudged === 1 ? "" : "s"} darkened to clear the contrast bar`)}`);
+    return lines;
+}
+
 /**
  * `refract` CLI (Node-only, §7 Step 10c) — a thin subcommand dispatcher over the build layer.
  *
@@ -7847,6 +8703,11 @@ async function runDiff(options) {
 const HELP = `refract — build a refract theme to disk.
 
 Usage:
+  refract create [--seed <color>] [--colors <n|list>] [--scheme <name>] [--manual]
+                   [--feel <neutral|compact|editorial|technical>] [--ratio <name>]
+                   [--base-size <px>] [--contrast <AA|AAA|none>] [--reset <name>]
+                   [--format <ts|js|json>] [--out <file>] [--no-semantics]
+                   [--no-neutral] [--no-shadows] [--yes] [--force]
   refract init [--js | --mjs] [--force]
   refract import <tokens.json> [--out <file>] [--raw-only] [--force]
                    [--breakpoint-group <name>] [--breakpoints <n:px,…>]
@@ -7860,6 +8721,7 @@ Usage:
   refract help
 
 Commands:
+  create   Design a theme.raw.(ts|js|json) from one seed colour and a short interview.
   init     Scaffold a runnable theme.config.(ts|js|mjs) in the current directory.
   import   Seed a theme.raw.ts (+ theme.config.ts) from a DTCG tokens.json (one-shot).
   build    Load the config and emit every target's files to its outDir.
@@ -7868,6 +8730,21 @@ Commands:
   audit    Score colour pairings for WCAG-2 contrast (+ advisory APCA). Reports; --strict fails.
   skills   Install the bundled AI skills into your agent CLI(s) (claude/codex/…).
 `;
+/**
+ * Uniform error reporter for a command's catch block. Surfaces a `RefractError`'s stable `code`
+ * (`[REFRACT_E_…] message`) so an agent or CI log sees the machine-readable code, and lists each
+ * collect-all `failure` — a plain `Error` just prints its message. Returns the exit code (1).
+ */
+function reportError(cmd, err) {
+    var _a;
+    const e = err;
+    const code = typeof e.code === "string" && e.code.startsWith("REFRACT_E_") ? `[${e.code}] ` : "";
+    process.stderr.write(`refract ${cmd}: ${code}${(_a = e.message) !== null && _a !== void 0 ? _a : String(err)}\n`);
+    if (e.failures)
+        for (const f of e.failures)
+            process.stderr.write(`  - ${f}\n`);
+    return 1;
+}
 async function cmdInit(argv) {
     const { values } = node_util.parseArgs({
         args: argv,
@@ -7885,13 +8762,96 @@ async function cmdInit(argv) {
     const variant = values.mjs ? "mjs" : values.js ? "js" : "ts";
     try {
         const result = runInit({ variant, force: Boolean(values.force) });
+        if (result.rawTheme) {
+            process.stdout.write(`Found ${result.rawTheme.filename} — wired it up.\n`);
+        }
         process.stdout.write(`Created ${result.path}\n`);
-        process.stdout.write(`Next: edit the raw theme, then run \`refract build\`.\n`);
+        process.stdout.write(result.rawTheme
+            ? `Next: run \`refract build\`.\n`
+            : `Next: edit the starter theme in the config (or run \`refract create\` to design one), then \`refract build\`.\n`);
         return 0;
     }
     catch (err) {
-        process.stderr.write(`refract init: ${err.message}\n`);
-        return 1;
+        return reportError("init", err);
+    }
+}
+/**
+ * `refract create` — the guided raw-theme scaffolder.
+ *
+ * Flags only here: the question flow lives in `createInterview.ts` so `create-refract-theme` runs
+ * the identical script, and the generation lives in `scaffold.ts`. Every prompt has a flag and every
+ * flag has a default, so this command is fully scriptable (`--yes`) and never blocks in CI.
+ */
+async function cmdCreate(argv) {
+    var _a;
+    const { values } = node_util.parseArgs({
+        args: argv,
+        options: {
+            seed: { type: "string" },
+            colors: { type: "string" },
+            scheme: { type: "string" },
+            manual: { type: "boolean", default: false },
+            feel: { type: "string" },
+            ratio: { type: "string" },
+            "base-size": { type: "string" },
+            contrast: { type: "string" },
+            reset: { type: "string" },
+            format: { type: "string" },
+            out: { type: "string" },
+            "no-semantics": { type: "boolean", default: false },
+            "no-neutral": { type: "boolean", default: false },
+            "no-shadows": { type: "boolean", default: false },
+            yes: { type: "boolean", default: false },
+            force: { type: "boolean", default: false },
+        },
+        allowPositionals: false,
+    });
+    const p = new Prompter(values.yes ? false : undefined);
+    try {
+        p.write();
+        p.write(`  ${bold("refract")} ${dim("· raw-theme scaffold")}`);
+        p.write();
+        const answers = await promptCreateAnswers(p, {
+            seed: values.seed,
+            colors: values.colors,
+            scheme: values.scheme,
+            manual: values.manual,
+            feel: values.feel,
+            ratio: values.ratio,
+            baseSize: values["base-size"],
+            contrast: values.contrast,
+            reset: values.reset,
+            format: values.format,
+            noSemantics: values["no-semantics"],
+            noNeutral: values["no-neutral"],
+            noShadows: values["no-shadows"],
+        });
+        const result = runCreate({ ...answers, out: values.out, force: Boolean(values.force) });
+        p.write();
+        for (const line of createReportLines(result, countVariables(result.raw)))
+            p.write(line);
+        p.write();
+        p.write(`  ${bold((_a = result.path.split(/[\\/]/).pop()) !== null && _a !== void 0 ? _a : "")} written`);
+        p.write();
+        p.write(`  ${dim("Next — wire up a build:")}  ${bold("refract init")}`);
+        p.write();
+        return 0;
+    }
+    catch (err) {
+        return reportError("create", err);
+    }
+    finally {
+        p.close();
+    }
+}
+/** Compile the generated theme with the null adapter purely to count what it emits, for the report. */
+function countVariables(raw) {
+    try {
+        const theme = createTheme(raw, { adapter: createNoopAdapter() });
+        return Object.keys(theme.tokens).length;
+    }
+    catch {
+        return 0;
     }
 }
 async function cmdImport(argv) {
@@ -7935,8 +8895,7 @@ async function cmdImport(argv) {
         return 0;
     }
     catch (err) {
-        process.stderr.write(`refract import: ${err.message}\n`);
-        return 1;
+        return reportError("import", err);
     }
 }
 async function cmdBuild(argv) {
@@ -7965,8 +8924,7 @@ async function cmdBuild(argv) {
         return 0;
     }
     catch (err) {
-        process.stderr.write(`refract build: ${err.message}\n`);
-        return 1;
+        return reportError("build", err);
     }
 }
 async function cmdTokens(argv) {
@@ -7988,8 +8946,7 @@ async function cmdTokens(argv) {
         return 0;
     }
     catch (err) {
-        process.stderr.write(`refract tokens: ${err.message}\n`);
-        return 1;
+        return reportError("tokens", err);
     }
 }
 const WCAG_LEVELS = new Set(["AAA", "AA", "AA-large"]);
@@ -8046,8 +9003,7 @@ async function cmdDiff(argv) {
         return 0;
     }
     catch (err) {
-        process.stderr.write(`refract diff: ${err.message}\n`);
-        return 1;
+        return reportError("diff", err);
     }
 }
 async function cmdAudit(argv) {
@@ -8089,8 +9045,7 @@ async function cmdAudit(argv) {
         return 0;
     }
     catch (err) {
-        process.stderr.write(`${err.message}\n`);
-        return 1;
+        return reportError("audit", err);
     }
 }
 /** Parse an `--agent` value (`"all"` or a comma list) into validated targets. */
@@ -8142,8 +9097,7 @@ async function cmdSkills(argv) {
             return 0;
         }
         catch (err) {
-            process.stderr.write(`refract skills list: ${err.message}\n`);
-            return 1;
+            return reportError("skills list", err);
         }
     }
     const { values } = node_util.parseArgs({
@@ -8202,14 +9156,15 @@ async function cmdSkills(argv) {
         return 1;
     }
     catch (err) {
-        process.stderr.write(`refract skills: ${err.message}\n`);
-        return 1;
+        return reportError("skills", err);
     }
 }
 /** Dispatch a parsed argv (without the node/script prefix). Returns a process exit code. */
 async function main(argv) {
     const [command, ...rest] = argv;
     switch (command) {
+        case "create":
+            return cmdCreate(rest);
         case "init":
             return cmdInit(rest);
         case "import":