@theme-registry/refract 0.1.2 → 0.1.4

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 = {
@@ -7185,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";
@@ -7226,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();
@@ -7234,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 };
 }
 
 /**
@@ -7869,6 +7947,961 @@ 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) };
+}
+
+/**
+ * Interactive prompts over `node:readline` and raw stdin (Node-only).
+ *
+ * The package ships zero runtime dependencies and this is the build layer, so rather than pull in a
+ * prompt library these are the shapes the CLIs actually need, implemented directly.
+ *
+ * Three tiers, chosen per call:
+ *
+ *  1. **Raw mode** (a TTY that grants `setRawMode`) — arrow keys move, space toggles, Enter confirms.
+ *     What people expect from `npm create`.
+ *  2. **Line mode** (a TTY that refuses raw mode — some CI shells, some remote terminals) — the same
+ *     questions answered by typing a number. Plainer, but never wedged.
+ *  3. **Non-interactive** (no TTY at all: a pipe, CI, `--yes`) — every prompt takes its default
+ *     without blocking, so a scripted run can't deadlock on stdin that will never arrive.
+ *
+ * Key handling is a **pure reducer** (`applyKey`), so navigation is unit-testable without a terminal;
+ * the raw loop is only plumbing around it.
+ */
+/** 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);
+/** Terminal control, named so the rendering below reads as intent rather than escape soup. */
+const cursorUp = (n) => (n > 0 ? `\u001b[${n}A` : "");
+const CLEAR_DOWN = "\u001b[0J";
+const HIDE_CURSOR = "\u001b[?25l";
+const SHOW_CURSOR = "\u001b[?25h";
+/** Decode a raw stdin chunk into a {@link ListKey}. Arrows arrive as escape sequences; j/k mirror vim. */
+function decodeKey(chunk) {
+    switch (chunk) {
+        case "\u001b[A":
+        case "k":
+            return "up";
+        case "\u001b[B":
+        case "j":
+            return "down";
+        case " ":
+            return "space";
+        case "\r":
+        case "\n":
+            return "submit";
+        case "a":
+            return "all";
+        case "\u0003": // Ctrl-C
+        case "\u001b": // bare Escape
+            return "cancel";
+        default:
+            return "none";
+    }
+}
+/**
+ * Split one stdin chunk into the keys it contains.
+ *
+ * A held-down arrow key, or fast typing, delivers several sequences in a single `data` event — so
+ * decoding the chunk as one key would swallow all but the first and make the list feel like it drops
+ * input. Escape sequences (`ESC [ <letter>`) are taken as a unit; everything else is one key each.
+ */
+function decodeKeys(chunk) {
+    const keys = [];
+    for (let i = 0; i < chunk.length;) {
+        if (chunk[i] === "\u001b" && chunk[i + 1] === "[" && i + 2 < chunk.length) {
+            keys.push(decodeKey(chunk.slice(i, i + 3)));
+            i += 3;
+        }
+        else {
+            keys.push(decodeKey(chunk[i]));
+            i += 1;
+        }
+    }
+    return keys;
+}
+/**
+ * Advance a list prompt by one key. Pure — no I/O — so navigation is testable without a terminal.
+ *
+ * The cursor **wraps** at both ends: with six options, up from the first should land on the last
+ * rather than stick. `space` and `a` toggle only in multi mode; in single mode Enter is the commit,
+ * so space would be ambiguous.
+ */
+function applyKey(state, key, count, multi) {
+    if (state.done || state.cancelled || count === 0)
+        return state;
+    switch (key) {
+        case "up":
+            return { ...state, cursor: (state.cursor - 1 + count) % count };
+        case "down":
+            return { ...state, cursor: (state.cursor + 1) % count };
+        case "space": {
+            if (!multi)
+                return state;
+            const next = new Set(state.selected);
+            if (next.has(state.cursor))
+                next.delete(state.cursor);
+            else
+                next.add(state.cursor);
+            return { ...state, selected: next };
+        }
+        case "all": {
+            if (!multi)
+                return state;
+            const everything = state.selected.size === count;
+            return {
+                ...state,
+                selected: everything ? new Set() : new Set(Array.from({ length: count }, (_, i) => i)),
+            };
+        }
+        case "submit":
+            return { ...state, done: true };
+        case "cancel":
+            return { ...state, cancelled: true };
+        default:
+            return state;
+    }
+}
+/** Can we drive the terminal directly? Some TTYs (and most CI) don't grant raw mode. */
+const rawCapable = () => Boolean(process.stdin.isTTY) && typeof process.stdin.setRawMode === "function";
+/**
+ * A prompt session. Holds at most one readline interface, so stdin is opened and closed 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)));
+    }
+    /** Raw write, no newline — for cursor control during a live render. */
+    out(s) {
+        process.stdout.write(s);
+    }
+    /** Print a line. 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 — arrows to move, Enter to choose. */
+    async select(label, choices, defaultIndex = 0) {
+        var _a, _b, _c;
+        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;
+        if (rawCapable()) {
+            const picked = await this.runList(label, choices, {
+                multi: false,
+                cursor: defaultIndex,
+                selected: new Set(),
+            });
+            return choices[(_c = picked[0]) !== null && _c !== void 0 ? _c : defaultIndex].value;
+        }
+        return this.selectByNumber(label, choices, defaultIndex);
+    }
+    /** Pick any — arrows to move, space to toggle, `a` for all/none, Enter to confirm. */
+    async multiselect(label, choices, preselected) {
+        var _a;
+        if (!this.interactive)
+            return preselected.map(i => choices[i].value);
+        if (rawCapable()) {
+            const picked = await this.runList(label, choices, {
+                multi: true,
+                cursor: (_a = preselected[0]) !== null && _a !== void 0 ? _a : 0,
+                selected: new Set(preselected),
+            });
+            return picked.map(i => choices[i].value);
+        }
+        return this.multiselectByNumber(label, choices, preselected);
+    }
+    /**
+     * The raw-mode list loop. Renders in place: each keypress rewinds over the block just drawn and
+     * repaints it, so the list stays put instead of scrolling the terminal away.
+     *
+     * Any readline interface is closed first — it would otherwise swallow the keystrokes we need.
+     * `cleanup` always restores the terminal (raw mode off, cursor shown), including on cancel, so a
+     * Ctrl-C can't leave the shell in a state where typing is invisible.
+     */
+    runList(label, choices, init) {
+        this.close(); // readline and raw mode can't both own stdin
+        const stdin = process.stdin;
+        const { multi } = init;
+        let state = {
+            cursor: Math.max(0, Math.min(init.cursor, choices.length - 1)),
+            selected: init.selected,
+            done: false,
+            cancelled: false,
+        };
+        let painted = 0;
+        const help = multi ? "↑↓ move · space toggle · a all · enter confirm" : "↑↓ move · enter select";
+        const frame = () => {
+            const rows = choices.map((c, i) => {
+                const here = i === state.cursor;
+                const mark = multi ? (state.selected.has(i) ? green("◉") : dim("◯")) : here ? green("❯") : " ";
+                const name = here ? bold(c.label) : c.label;
+                const hint = c.hint ? ` ${dim(`— ${c.hint}`)}` : "";
+                return `  ${mark} ${name}${hint}`;
+            });
+            return [`${cyan("?")} ${bold(label)} ${dim(help)}`, ...rows].join("\n");
+        };
+        const paintFrame = () => {
+            if (painted)
+                this.out(cursorUp(painted) + CLEAR_DOWN);
+            const text = frame();
+            this.out(`${text}\n`);
+            painted = text.split("\n").length;
+        };
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                stdin.removeListener("data", onData);
+                stdin.removeListener("end", onEnd);
+                if (stdin.isTTY)
+                    stdin.setRawMode(false);
+                stdin.pause();
+                this.out(SHOW_CURSOR);
+            };
+            /**
+             * stdin closed while we were waiting — a piped run, a closed terminal, a killed parent. There
+             * is no further input coming, so commit what's on screen instead of blocking forever.
+             */
+            const onEnd = () => {
+                const chosen = multi ? [...state.selected].sort((a, b) => a - b) : [state.cursor];
+                this.out(cursorUp(painted) + CLEAR_DOWN);
+                cleanup();
+                resolve(chosen);
+            };
+            const onData = (chunk) => {
+                // One event can carry several keys (a held-down arrow); apply them all, then paint once.
+                for (const key of decodeKeys(chunk)) {
+                    state = applyKey(state, key, choices.length, multi);
+                    if (state.done || state.cancelled)
+                        break;
+                }
+                if (state.cancelled) {
+                    this.out(cursorUp(painted) + CLEAR_DOWN);
+                    cleanup();
+                    reject(new Error("Cancelled."));
+                    return;
+                }
+                if (state.done) {
+                    const chosen = multi ? [...state.selected].sort((a, b) => a - b) : [state.cursor];
+                    // Replace the live block with a one-line record of the answer, so a finished interview
+                    // reads back as a transcript rather than a wall of spent menus.
+                    this.out(cursorUp(painted) + CLEAR_DOWN);
+                    const summary = chosen.length ? chosen.map(i => choices[i].label).join(", ") : "none";
+                    this.write(`${cyan("?")} ${bold(label)} ${dim("›")} ${green(summary)}`);
+                    cleanup();
+                    resolve(chosen);
+                    return;
+                }
+                paintFrame();
+            };
+            stdin.setRawMode(true);
+            stdin.resume();
+            stdin.setEncoding("utf8");
+            this.out(HIDE_CURSOR);
+            stdin.on("data", onData);
+            stdin.on("end", onEnd);
+            paintFrame();
+        });
+    }
+    /** Line-mode fallback: pick one by number. */
+    async selectByNumber(label, choices, defaultIndex) {
+        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}.`);
+        }
+    }
+    /** Line-mode fallback: pick any by comma-separated numbers. */
+    async multiselectByNumber(label, choices, preselected) {
+        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.
  *
@@ -7885,6 +8918,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,…>]
@@ -7898,6 +8936,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.
@@ -7938,14 +8977,98 @@ 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) {
         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) {
     const { values, positionals } = node_util.parseArgs({
         args: argv,
@@ -8255,6 +9378,8 @@ async function cmdSkills(argv) {
 async function main(argv) {
     const [command, ...rest] = argv;
     switch (command) {
+        case "create":
+            return cmdCreate(rest);
         case "init":
             return cmdInit(rest);
         case "import":