@theme-registry/refract 0.1.1 → 0.1.3

package/README.md

@@ -47,6 +47,21 @@ npm install @theme-registry/refract
 `styled-components` and `typescript` are **optional** peers — only needed if you use the
 styled-components adapter or the `.ts` build config, respectively.
 
+## Scaffold a theme
+
+Don't start from a blank file. One seed colour becomes a full theme — palettes with tonal ladders,
+semantic colours, a type scale with derived leading, a spacing ramp — with every colour checked
+against **WCAG contrast before the file is written**:
+
+```bash
+npx refract create                 # in an existing project → theme.raw.ts
+npm create refract-theme my-theme  # from nothing → a publishable theme package
+```
+
+The generator runs **once**; what it writes is an ordinary theme file you own and edit. It emits
+**tokens only** — no recipes, so nothing composes into a class list yet. That's the next step, and
+it's design work: see [Recipes](https://theme-registry.github.io/refract/r-recipes).
+
 ## Quick start
 
 `createTheme(raw, { adapter })` builds the theme. The `adapter` is **required** — core
@@ -104,7 +119,7 @@ const raw = {
 Property values can be **literals** (`"#4c6ef5"`, `16`), **references** to other tokens
 (`color: "brand.text"`), and carry **responsive / variant / target** overrides keyed on
 your breakpoints. Recipes group reusable rule-sets with **states** (`hover`, `disabled`, …).
-Full field-by-field walkthrough: **[docs/authoring.md](docs/authoring.md)**.
+Full field-by-field walkthrough: **[docs/authoring.md](https://github.com/theme-registry/refract/blob/main/docs/authoring.md)**.
 
 ## Adapters — the multi-format thesis
 
@@ -121,12 +136,13 @@ Core ships **zero** adapters; each is its own installable package (`npm i @theme
 
 Write your own with `defineAdapter(spec)` — you fill four primitives (`recipeName`,
 `renderRecipe`, `renderVariables`, `join`) and core supplies the rest. See
-**[docs/extending.md](docs/extending.md)** or run the `adapter-scaffold` skill.
+**[docs/extending.md](https://github.com/theme-registry/refract/blob/main/docs/extending.md)** or run the `adapter-scaffold` skill.
 
 ## Build to disk (CLI)
 
 ```bash
-npx refract init      # scaffold a theme.config.(ts|js|mjs)
+npx refract create    # design a theme.raw.(ts|js|json) from one seed colour
+npx refract init      # scaffold a theme.config.(ts|js|mjs) — imports theme.raw.* if present
 npx refract build     # load the config → write every target's files to its outDir
 npx refract tokens    # export theme.tokens as a DTCG tokens.json (adapter-free)
 ```
@@ -182,8 +198,8 @@ const doc   = toDTCG(theme);                     // built theme's tokens → DTC
 
 ## Documentation
 
-- **[docs/authoring.md](docs/authoring.md)** — author a theme + consume its output (the user guide).
-- **[docs/extending.md](docs/extending.md)** — write a subsystem or an adapter against the frozen contract.
+- **[docs/authoring.md](https://github.com/theme-registry/refract/blob/main/docs/authoring.md)** — author a theme + consume its output (the user guide).
+- **[docs/extending.md](https://github.com/theme-registry/refract/blob/main/docs/extending.md)** — write a subsystem or an adapter against the frozen contract.
 - **[AGENTS.md](AGENTS.md)** — orientation for AI coding agents.
 
 ## License

package/dist/_errors-be768b25.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"_errors-be768b25.cjs.js","sources":["../src/core/errors.ts"],"sourcesContent":["/**\n * Stable, machine-readable error codes (§P2-3). Every error refract throws for a theme authoring /\n * build problem — everything reachable from {@link createTheme} (subsystem normalization, token\n * derivation, DTCG parsing) — is a {@link RefractError} carrying a `code` from {@link RefractErrorCode}:\n * a stable identifier an agent (or a catch block) can branch on without string-matching the human\n * message. The message text stays human-first and unchanged; the code is additive.\n *\n * Scope: authoring/build errors. Pure CLI-tooling failures in `src/build/*` (bad arguments, a missing\n * file, an unknown command) stay plain `Error`s — they're usage errors from `refract <cmd>`, not a\n * problem with the theme an agent is editing.\n *\n * Dependency-free leaf on purpose, so any module (including the standalone `adapter-kit`) can throw one\n * without pulling in the core graph.\n */\nexport type RefractErrorCode =\n  | \"REFRACT_E_COLOR_INPUT\" // a colour value wasn't a derivable colour\n  | \"REFRACT_E_COLOR_TUPLE\" // an [r,g,b] tuple was malformed\n  | \"REFRACT_E_STEPS\" // colors.<name>.steps out of range / non-numeric\n  | \"REFRACT_E_VARIANT\" // a derivation-spec variant / modifier chain was malformed\n  | \"REFRACT_E_VARIANT_REF\" // a variant referenced an unknown source\n  | \"REFRACT_E_CYCLE\" // a cyclic reference (colour variant, token, recipe, DTCG alias)\n  | \"REFRACT_E_ADJUST\" // an adjust dial was out of range\n  | \"REFRACT_E_HARMONY\" // an invalid harmony scheme\n  | \"REFRACT_E_VALIDATION\" // aggregate: one or more post-build ref-validation failures (see `failures`)\n  | \"REFRACT_E_RECIPE_PROPERTY\" // a recipe declaration key is neither a known CSS property nor a reserved key\n  | \"REFRACT_E_TOKEN_PATH\" // a token path is unknown / malformed / uses an unknown derivation fn\n  | \"REFRACT_E_BREAKPOINT\" // a responsive entry omitted or named an unknown breakpoint\n  | \"REFRACT_E_STATE\" // a recipe state entry named a state the adapter doesn't know\n  | \"REFRACT_E_CONTAINER\" // a container-query entry named an unknown container / size / unsupported axis\n  | \"REFRACT_E_RESPONSIVE\" // a responsive/mode override was malformed (variant+target conflict, unknown ref)\n  | \"REFRACT_E_MEDIA\" // an invalid media / container query range (min > max)\n  | \"REFRACT_E_MODE\" // an appearance-mode override with no base to override\n  | \"REFRACT_E_PRESET\" // an unknown globals preset name\n  | \"REFRACT_E_EFFECTS\" // a malformed effects value (shadow / transition layer)\n  | \"REFRACT_E_LAYOUT\" // a malformed layout scale (ratio+step, bad rung)\n  | \"REFRACT_E_UNITS\" // a malformed units config\n  | \"REFRACT_E_PROPERTY\" // a property couldn't be normalized (no resolvable base value)\n  | \"REFRACT_E_REFERENCE\" // a composition / rule-set reference didn't resolve\n  | \"REFRACT_E_NAMING\" // a naming override / default path produced a collision\n  | \"REFRACT_E_DTCG_VERSION\" // an unreadable DTCG refract-extension version\n  | \"REFRACT_E_AUDIT\"; // a strict contrast audit failed\n\n/**\n * An authoring / build error with a stable {@link RefractErrorCode}. For an aggregate (collect-all)\n * error, `failures` lists each individual message so a caller can report them all at once.\n */\nexport class RefractError extends Error {\n  readonly code: RefractErrorCode;\n  readonly failures?: readonly string[];\n\n  constructor(code: RefractErrorCode, message: string, failures?: readonly string[]) {\n    super(message);\n    this.name = \"RefractError\";\n    this.code = code;\n    if (failures) this.failures = failures;\n    // Keep `instanceof RefractError` working after transpilation to ES5-ish targets.\n    Object.setPrototypeOf(this, RefractError.prototype);\n  }\n}\n"],"names":["RefractError","Error","constructor","code","message","failures","super","this","name","Object","setPrototypeOf","prototype"],"mappings":"aA8CM,MAAOA,UAAqBC,MAIhC,WAAAC,CAAYC,EAAwBC,EAAiBC,GACnDC,MAAMF,GACNG,KAAKC,KAAO,eACZD,KAAKJ,KAAOA,EACRE,IAAUE,KAAKF,SAAWA,GAE9BI,OAAOC,eAAeH,KAAMP,EAAaW,UAC1C"}
+{"version":3,"file":"_errors-be768b25.cjs.js","sources":["../src/core/errors.ts"],"sourcesContent":["/**\n * Stable, machine-readable error codes (§P2-3). Every error refract throws for a theme authoring /\n * build problem — everything reachable from {@link createTheme} (subsystem normalization, token\n * derivation, DTCG parsing) — is a {@link RefractError} carrying a `code` from {@link RefractErrorCode}:\n * a stable identifier an agent (or a catch block) can branch on without string-matching the human\n * message. The message text stays human-first and unchanged; the code is additive.\n *\n * Scope: authoring/build errors. Pure CLI-tooling failures in `src/build/*` (bad arguments, a missing\n * file, an unknown command) stay plain `Error`s — they're usage errors from `refract <cmd>`, not a\n * problem with the theme an agent is editing. The one build-layer exception is `REFRACT_E_RAW_SHAPE`:\n * a value handed to `diff` / `validate` (or the MCP server) where a `RawTheme` is required but the\n * value isn't theme-shaped — that IS a theme problem, and a governance tool must fail loud + coded on\n * it (see {@link assertRawTheme}) rather than emit a nonsense \"everything removed\" diff at exit 0.\n *\n * Dependency-free leaf on purpose, so any module (including the standalone `adapter-kit`) can throw one\n * without pulling in the core graph.\n */\nexport type RefractErrorCode =\n  | \"REFRACT_E_COLOR_INPUT\" // a colour value wasn't a derivable colour\n  | \"REFRACT_E_COLOR_TUPLE\" // an [r,g,b] tuple was malformed\n  | \"REFRACT_E_STEPS\" // colors.<name>.steps out of range / non-numeric\n  | \"REFRACT_E_VARIANT\" // a derivation-spec variant / modifier chain was malformed\n  | \"REFRACT_E_VARIANT_REF\" // a variant referenced an unknown source\n  | \"REFRACT_E_CYCLE\" // a cyclic reference (colour variant, token, recipe, DTCG alias)\n  | \"REFRACT_E_ADJUST\" // an adjust dial was out of range\n  | \"REFRACT_E_HARMONY\" // an invalid harmony scheme\n  | \"REFRACT_E_VALIDATION\" // aggregate: one or more post-build ref-validation failures (see `failures`)\n  | \"REFRACT_E_RECIPE_PROPERTY\" // a recipe declaration key is neither a known CSS property nor a reserved key\n  | \"REFRACT_E_TOKEN_PATH\" // a token path is unknown / malformed / uses an unknown derivation fn\n  | \"REFRACT_E_BREAKPOINT\" // a responsive entry omitted or named an unknown breakpoint\n  | \"REFRACT_E_STATE\" // a recipe state entry named a state the adapter doesn't know\n  | \"REFRACT_E_CONTAINER\" // a container-query entry named an unknown container / size / unsupported axis\n  | \"REFRACT_E_RESPONSIVE\" // a responsive/mode override was malformed (variant+target conflict, unknown ref)\n  | \"REFRACT_E_MEDIA\" // an invalid media / container query range (min > max)\n  | \"REFRACT_E_MODE\" // an appearance-mode override with no base to override\n  | \"REFRACT_E_PRESET\" // an unknown globals preset name\n  | \"REFRACT_E_EFFECTS\" // a malformed effects value (shadow / transition layer)\n  | \"REFRACT_E_LAYOUT\" // a malformed layout scale (ratio+step, bad rung)\n  | \"REFRACT_E_UNITS\" // a malformed units config\n  | \"REFRACT_E_PROPERTY\" // a property couldn't be normalized (no resolvable base value)\n  | \"REFRACT_E_REFERENCE\" // a composition / rule-set reference didn't resolve\n  | \"REFRACT_E_NAMING\" // a naming override / default path produced a collision\n  | \"REFRACT_E_DTCG_VERSION\" // an unreadable DTCG refract-extension version\n  | \"REFRACT_E_AUDIT\" // a strict contrast audit failed\n  | \"REFRACT_E_RAW_SHAPE\"; // a value passed where a RawTheme is required isn't theme-shaped (e.g. a defineConfig, an array, null)\n\n/**\n * An authoring / build error with a stable {@link RefractErrorCode}. For an aggregate (collect-all)\n * error, `failures` lists each individual message so a caller can report them all at once.\n */\nexport class RefractError extends Error {\n  readonly code: RefractErrorCode;\n  readonly failures?: readonly string[];\n\n  constructor(code: RefractErrorCode, message: string, failures?: readonly string[]) {\n    super(message);\n    this.name = \"RefractError\";\n    this.code = code;\n    if (failures) this.failures = failures;\n    // Keep `instanceof RefractError` working after transpilation to ES5-ish targets.\n    Object.setPrototypeOf(this, RefractError.prototype);\n  }\n}\n"],"names":["RefractError","Error","constructor","code","message","failures","super","this","name","Object","setPrototypeOf","prototype"],"mappings":"aAkDM,MAAOA,UAAqBC,MAIhC,WAAAC,CAAYC,EAAwBC,EAAiBC,GACnDC,MAAMF,GACNG,KAAKC,KAAO,eACZD,KAAKJ,KAAOA,EACRE,IAAUE,KAAKF,SAAWA,GAE9BI,OAAOC,eAAeH,KAAMP,EAAaW,UAC1C"}

package/dist/_errors-d75a5c74.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"_errors-d75a5c74.esm.js","sources":["../src/core/errors.ts"],"sourcesContent":["/**\n * Stable, machine-readable error codes (§P2-3). Every error refract throws for a theme authoring /\n * build problem — everything reachable from {@link createTheme} (subsystem normalization, token\n * derivation, DTCG parsing) — is a {@link RefractError} carrying a `code` from {@link RefractErrorCode}:\n * a stable identifier an agent (or a catch block) can branch on without string-matching the human\n * message. The message text stays human-first and unchanged; the code is additive.\n *\n * Scope: authoring/build errors. Pure CLI-tooling failures in `src/build/*` (bad arguments, a missing\n * file, an unknown command) stay plain `Error`s — they're usage errors from `refract <cmd>`, not a\n * problem with the theme an agent is editing.\n *\n * Dependency-free leaf on purpose, so any module (including the standalone `adapter-kit`) can throw one\n * without pulling in the core graph.\n */\nexport type RefractErrorCode =\n  | \"REFRACT_E_COLOR_INPUT\" // a colour value wasn't a derivable colour\n  | \"REFRACT_E_COLOR_TUPLE\" // an [r,g,b] tuple was malformed\n  | \"REFRACT_E_STEPS\" // colors.<name>.steps out of range / non-numeric\n  | \"REFRACT_E_VARIANT\" // a derivation-spec variant / modifier chain was malformed\n  | \"REFRACT_E_VARIANT_REF\" // a variant referenced an unknown source\n  | \"REFRACT_E_CYCLE\" // a cyclic reference (colour variant, token, recipe, DTCG alias)\n  | \"REFRACT_E_ADJUST\" // an adjust dial was out of range\n  | \"REFRACT_E_HARMONY\" // an invalid harmony scheme\n  | \"REFRACT_E_VALIDATION\" // aggregate: one or more post-build ref-validation failures (see `failures`)\n  | \"REFRACT_E_RECIPE_PROPERTY\" // a recipe declaration key is neither a known CSS property nor a reserved key\n  | \"REFRACT_E_TOKEN_PATH\" // a token path is unknown / malformed / uses an unknown derivation fn\n  | \"REFRACT_E_BREAKPOINT\" // a responsive entry omitted or named an unknown breakpoint\n  | \"REFRACT_E_STATE\" // a recipe state entry named a state the adapter doesn't know\n  | \"REFRACT_E_CONTAINER\" // a container-query entry named an unknown container / size / unsupported axis\n  | \"REFRACT_E_RESPONSIVE\" // a responsive/mode override was malformed (variant+target conflict, unknown ref)\n  | \"REFRACT_E_MEDIA\" // an invalid media / container query range (min > max)\n  | \"REFRACT_E_MODE\" // an appearance-mode override with no base to override\n  | \"REFRACT_E_PRESET\" // an unknown globals preset name\n  | \"REFRACT_E_EFFECTS\" // a malformed effects value (shadow / transition layer)\n  | \"REFRACT_E_LAYOUT\" // a malformed layout scale (ratio+step, bad rung)\n  | \"REFRACT_E_UNITS\" // a malformed units config\n  | \"REFRACT_E_PROPERTY\" // a property couldn't be normalized (no resolvable base value)\n  | \"REFRACT_E_REFERENCE\" // a composition / rule-set reference didn't resolve\n  | \"REFRACT_E_NAMING\" // a naming override / default path produced a collision\n  | \"REFRACT_E_DTCG_VERSION\" // an unreadable DTCG refract-extension version\n  | \"REFRACT_E_AUDIT\"; // a strict contrast audit failed\n\n/**\n * An authoring / build error with a stable {@link RefractErrorCode}. For an aggregate (collect-all)\n * error, `failures` lists each individual message so a caller can report them all at once.\n */\nexport class RefractError extends Error {\n  readonly code: RefractErrorCode;\n  readonly failures?: readonly string[];\n\n  constructor(code: RefractErrorCode, message: string, failures?: readonly string[]) {\n    super(message);\n    this.name = \"RefractError\";\n    this.code = code;\n    if (failures) this.failures = failures;\n    // Keep `instanceof RefractError` working after transpilation to ES5-ish targets.\n    Object.setPrototypeOf(this, RefractError.prototype);\n  }\n}\n"],"names":["RefractError","Error","constructor","code","message","failures","super","this","name","Object","setPrototypeOf","prototype"],"mappings":"AA8CM,MAAOA,UAAqBC,MAIhC,WAAAC,CAAYC,EAAwBC,EAAiBC,GACnDC,MAAMF,GACNG,KAAKC,KAAO,eACZD,KAAKJ,KAAOA,EACRE,IAAUE,KAAKF,SAAWA,GAE9BI,OAAOC,eAAeH,KAAMP,EAAaW,UAC1C"}
+{"version":3,"file":"_errors-d75a5c74.esm.js","sources":["../src/core/errors.ts"],"sourcesContent":["/**\n * Stable, machine-readable error codes (§P2-3). Every error refract throws for a theme authoring /\n * build problem — everything reachable from {@link createTheme} (subsystem normalization, token\n * derivation, DTCG parsing) — is a {@link RefractError} carrying a `code` from {@link RefractErrorCode}:\n * a stable identifier an agent (or a catch block) can branch on without string-matching the human\n * message. The message text stays human-first and unchanged; the code is additive.\n *\n * Scope: authoring/build errors. Pure CLI-tooling failures in `src/build/*` (bad arguments, a missing\n * file, an unknown command) stay plain `Error`s — they're usage errors from `refract <cmd>`, not a\n * problem with the theme an agent is editing. The one build-layer exception is `REFRACT_E_RAW_SHAPE`:\n * a value handed to `diff` / `validate` (or the MCP server) where a `RawTheme` is required but the\n * value isn't theme-shaped — that IS a theme problem, and a governance tool must fail loud + coded on\n * it (see {@link assertRawTheme}) rather than emit a nonsense \"everything removed\" diff at exit 0.\n *\n * Dependency-free leaf on purpose, so any module (including the standalone `adapter-kit`) can throw one\n * without pulling in the core graph.\n */\nexport type RefractErrorCode =\n  | \"REFRACT_E_COLOR_INPUT\" // a colour value wasn't a derivable colour\n  | \"REFRACT_E_COLOR_TUPLE\" // an [r,g,b] tuple was malformed\n  | \"REFRACT_E_STEPS\" // colors.<name>.steps out of range / non-numeric\n  | \"REFRACT_E_VARIANT\" // a derivation-spec variant / modifier chain was malformed\n  | \"REFRACT_E_VARIANT_REF\" // a variant referenced an unknown source\n  | \"REFRACT_E_CYCLE\" // a cyclic reference (colour variant, token, recipe, DTCG alias)\n  | \"REFRACT_E_ADJUST\" // an adjust dial was out of range\n  | \"REFRACT_E_HARMONY\" // an invalid harmony scheme\n  | \"REFRACT_E_VALIDATION\" // aggregate: one or more post-build ref-validation failures (see `failures`)\n  | \"REFRACT_E_RECIPE_PROPERTY\" // a recipe declaration key is neither a known CSS property nor a reserved key\n  | \"REFRACT_E_TOKEN_PATH\" // a token path is unknown / malformed / uses an unknown derivation fn\n  | \"REFRACT_E_BREAKPOINT\" // a responsive entry omitted or named an unknown breakpoint\n  | \"REFRACT_E_STATE\" // a recipe state entry named a state the adapter doesn't know\n  | \"REFRACT_E_CONTAINER\" // a container-query entry named an unknown container / size / unsupported axis\n  | \"REFRACT_E_RESPONSIVE\" // a responsive/mode override was malformed (variant+target conflict, unknown ref)\n  | \"REFRACT_E_MEDIA\" // an invalid media / container query range (min > max)\n  | \"REFRACT_E_MODE\" // an appearance-mode override with no base to override\n  | \"REFRACT_E_PRESET\" // an unknown globals preset name\n  | \"REFRACT_E_EFFECTS\" // a malformed effects value (shadow / transition layer)\n  | \"REFRACT_E_LAYOUT\" // a malformed layout scale (ratio+step, bad rung)\n  | \"REFRACT_E_UNITS\" // a malformed units config\n  | \"REFRACT_E_PROPERTY\" // a property couldn't be normalized (no resolvable base value)\n  | \"REFRACT_E_REFERENCE\" // a composition / rule-set reference didn't resolve\n  | \"REFRACT_E_NAMING\" // a naming override / default path produced a collision\n  | \"REFRACT_E_DTCG_VERSION\" // an unreadable DTCG refract-extension version\n  | \"REFRACT_E_AUDIT\" // a strict contrast audit failed\n  | \"REFRACT_E_RAW_SHAPE\"; // a value passed where a RawTheme is required isn't theme-shaped (e.g. a defineConfig, an array, null)\n\n/**\n * An authoring / build error with a stable {@link RefractErrorCode}. For an aggregate (collect-all)\n * error, `failures` lists each individual message so a caller can report them all at once.\n */\nexport class RefractError extends Error {\n  readonly code: RefractErrorCode;\n  readonly failures?: readonly string[];\n\n  constructor(code: RefractErrorCode, message: string, failures?: readonly string[]) {\n    super(message);\n    this.name = \"RefractError\";\n    this.code = code;\n    if (failures) this.failures = failures;\n    // Keep `instanceof RefractError` working after transpilation to ES5-ish targets.\n    Object.setPrototypeOf(this, RefractError.prototype);\n  }\n}\n"],"names":["RefractError","Error","constructor","code","message","failures","super","this","name","Object","setPrototypeOf","prototype"],"mappings":"AAkDM,MAAOA,UAAqBC,MAIhC,WAAAC,CAAYC,EAAwBC,EAAiBC,GACnDC,MAAMF,GACNG,KAAKC,KAAO,eACZD,KAAKJ,KAAOA,EACRE,IAAUE,KAAKF,SAAWA,GAE9BI,OAAOC,eAAeH,KAAMP,EAAaW,UAC1C"}

package/dist/build/createCommand.d.ts

@@ -0,0 +1,47 @@
+import { type ScaffoldAnswers, type ScaffoldReport } from "./scaffold";
+import type { RawTheme } from "../core";
+/** The file flavours `create` can emit. */
+export type RawFormat = "ts" | "js" | "json";
+export declare const DEFAULT_RAW_BASENAME = "theme.raw";
+export interface CreateOptions extends ScaffoldAnswers {
+    /** Project dir to write into (default `process.cwd()`). */
+    readonly cwd?: string;
+    /** Which flavour to write (default `"ts"`). */
+    readonly format?: RawFormat;
+    /** Output filename, relative to `cwd` (default `theme.raw.<format>`). */
+    readonly out?: string;
+    /** Overwrite an existing file instead of refusing (default `false`). */
+    readonly force?: boolean;
+    /** Package name the `.ts`/`.js` type import points at (default: this package's own `name`). */
+    readonly packageName?: string;
+}
+export interface CreateResult {
+    /** Absolute path of the written file. */
+    readonly path: string;
+    readonly format: RawFormat;
+    /** The generated theme, so callers can compile it without re-reading the file. */
+    readonly raw: RawTheme;
+    /** What the generator derived — the CLI prints this as its summary. */
+    readonly report: ScaffoldReport;
+    /** Count of emitted top-level subsystem slices. */
+    readonly sections: readonly string[];
+}
+/**
+ * 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.
+ */
+export declare function renderRawTheme(raw: RawTheme, options: {
+    format: RawFormat;
+    packageName: string;
+    seed: string;
+    detail: string;
+}): string;
+/**
+ * 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.
+ */
+export declare function runCreate(options: CreateOptions): CreateResult;

package/dist/build/createInterview.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The `refract create` interview (Node-only) — the question flow, separated from both CLIs that run it.
+ *
+ * `refract create` asks it to write a theme into an existing project; `create-refract-theme` asks it
+ * while scaffolding a whole new package. Two entry points, one script of questions — because an
+ * interview duplicated across two packages is an interview that drifts.
+ *
+ * Every answer can be supplied up front (a flag, or a caller's default), and every prompt is
+ * non-interactive-safe, so the same function serves a human at a terminal and a scripted run.
+ */
+import type { Prompter } from "./prompt";
+import { type ScaffoldAnswers } from "./scaffold";
+import type { CreateResult, RawFormat } from "./createCommand";
+/** What each harmony scheme is for, in one line — the names mean nothing to most people. */
+export declare const SCHEME_HINTS: Readonly<Record<string, string>>;
+/**
+ * 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.
+ */
+export declare const TYPE_SCALE_CHOICES: ReadonlyArray<readonly [string, string]>;
+/** Answers a caller already has — from CLI flags, or a host tool's own defaults. */
+export interface InterviewGiven {
+    readonly seed?: string;
+    /** Brand count in auto mode, or a comma-separated colour list in manual mode. */
+    readonly colors?: string;
+    readonly scheme?: string;
+    readonly manual?: boolean;
+    readonly feel?: string;
+    readonly ratio?: string;
+    readonly baseSize?: string | number;
+    readonly contrast?: string;
+    readonly reset?: string;
+    readonly format?: string;
+    readonly noSemantics?: boolean;
+    readonly noNeutral?: boolean;
+    readonly noShadows?: boolean;
+}
+/** The fully-resolved answer set, ready for `runCreate`. */
+export type InterviewAnswers = ScaffoldAnswers & {
+    readonly format: RawFormat;
+};
+/**
+ * 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.
+ */
+export declare function promptCreateAnswers(p: Prompter, given?: InterviewGiven): Promise<InterviewAnswers>;
+/**
+ * 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.
+ */
+export declare function createReportLines(result: CreateResult, variableCount: number): string[];

package/dist/build/index.d.ts

@@ -12,6 +12,10 @@ export * from "./emitTheme";
 export * from "./emit";
 export * from "./config";
 export * from "./init";
+export * from "./scaffold";
+export * from "./createCommand";
+export * from "./createInterview";
+export * from "./prompt";
 export * from "./importCommand";
 export * from "./buildCommand";
 export * from "./tokensCommand";

package/dist/build/init.d.ts

@@ -13,6 +13,11 @@ export interface InitOptions {
     readonly force?: boolean;
     /** Package name to import from in the scaffold (default: this package's own `name`). */
     readonly packageName?: string;
+    /**
+     * Override the raw-theme detection: a {@link DetectedRawTheme} to wire up regardless of what's on
+     * disk, or `null` to force the self-contained starter config. Omit to detect (the normal path).
+     */
+    readonly rawTheme?: DetectedRawTheme | null;
 }
 export interface InitResult {
     /** Absolute path of the written config. */
@@ -20,9 +25,46 @@ export interface InitResult {
     readonly variant: ConfigVariant;
     /** The package name the scaffold imports from. */
     readonly packageName: string;
+    /** The raw theme the config was wired to, or `undefined` when it carries its own starter palette. */
+    readonly rawTheme?: DetectedRawTheme;
 }
 /** Read this package's own `name` (so the scaffold imports the currently-installed package name). */
 export declare function readOwnPackageName(): string;
+/** A raw theme found next to the config, and how a config should reach it. */
+export interface DetectedRawTheme {
+    /** Absolute path of the file found. */
+    readonly path: string;
+    /** Its basename, e.g. `theme.raw.json`. */
+    readonly filename: string;
+    /** The extension, including the dot. */
+    readonly ext: string;
+}
+/**
+ * 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.
+ */
+export declare const findRawTheme: (fromDir?: string) => DetectedRawTheme | 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.
+ */
+export declare function rawThemeImport(detected: DetectedRawTheme): {
+    head: string;
+    expression: string;
+};
+/**
+ * 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.
+ */
+export declare function scaffoldConfigForRaw(packageName: string, detected: DetectedRawTheme): string;
 /** The scaffolded config body — one shared ESM template across ts/js/mjs. */
 export declare function scaffoldConfig(packageName: string): string;
 /**

package/dist/build/prompt.d.ts

@@ -0,0 +1,38 @@
+export declare const bold: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const yellow: (s: string) => string;
+/** One choice in a `select` / `multiselect`. */
+export interface Choice<T> {
+    readonly value: T;
+    readonly label: string;
+    /** Trailing grey note — what this option means. */
+    readonly hint?: string;
+}
+/**
+ * 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.
+ */
+export declare class Prompter {
+    private rl;
+    readonly interactive: boolean;
+    constructor(interactive?: boolean);
+    private get io();
+    close(): void;
+    private question;
+    /** Print a line to stdout. Kept on the prompter so command code never touches `process.stdout`. */
+    write(line?: string): void;
+    /** Free-text, with a default shown in the prompt. Blank input takes the default. */
+    text(label: string, fallback: string, validate?: (v: string) => string | undefined): Promise<string>;
+    /** A number, validated as finite. */
+    number(label: string, fallback: number, validate?: (v: number) => string | undefined): Promise<number>;
+    /** Pick one. Answers are 1-based indices; blank takes the default (the first choice unless given). */
+    select<T>(label: string, choices: readonly Choice<T>[], defaultIndex?: number): Promise<T>;
+    /**
+     * 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.
+     */
+    multiselect<T>(label: string, choices: readonly Choice<T>[], preselected: readonly number[]): Promise<T[]>;
+}

package/dist/build/scaffold.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+import type { RawTheme } from "../core";
+import type { WcagLevel } from "../subsystems/colors/audit";
+/**
+ * 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.
+ */
+declare const SCHEME_ROTATIONS: Readonly<Record<string, readonly number[]>>;
+export type Feel = "neutral" | "compact" | "editorial" | "technical";
+interface FeelPreset {
+    readonly label: string;
+    readonly blurb: string;
+    /** `fontFamily` base + the `mono` variant (system stacks only — a CLI can't install fonts). */
+    readonly fontFamily: {
+        readonly base: string;
+        readonly mono: string;
+    };
+    /** Multiplier map for the linear spacing curve (`step: 4`). */
+    readonly spacing: Readonly<Record<string, number>>;
+    /** Radius base + variants. */
+    readonly radius: {
+        readonly base: number;
+        readonly variants: Readonly<Record<string, number | string>>;
+    };
+    /** Suggested type ratio when the user takes the default. */
+    readonly ratio: string;
+}
+export declare const FEEL_PRESETS: Readonly<Record<Feel, FeelPreset>>;
+export type BrandScheme = keyof typeof SCHEME_ROTATIONS;
+export type ResetPreset = "preflight" | "normalize" | "none";
+export type ContrastTarget = "AA" | "AAA" | "none";
+export interface ScaffoldAnswers {
+    /** The seed colour — any form `parseColor` accepts (hex, `rgb()`, `oklch()`). */
+    readonly seed: string;
+    /** `auto` derives colours 2…N by hue rotation; `manual` takes them verbatim from `extraColors`. */
+    readonly mode?: "auto" | "manual";
+    /** Total brand colours including the primary, 1–5. Default 2. */
+    readonly brandCount?: number;
+    /** Which rotation set to use. Ignored unless `mode: "auto"`; defaulted from `brandCount`. */
+    readonly scheme?: BrandScheme;
+    /** `mode: "manual"` — the colours after the primary, in order. */
+    readonly extraColors?: readonly string[];
+    /** Add success / info / warning / danger. Default true. */
+    readonly semantics?: boolean;
+    /** Add the neutral ramp. Default true. */
+    readonly neutral?: boolean;
+    /** Add shadow ink + alpha tints, and the effects ramp that references them. Default true. */
+    readonly shadows?: boolean;
+    /** Contrast bar for the text-on-base pass. Default `"AA"`; `"none"` skips the pass entirely. */
+    readonly contrast?: ContrastTarget;
+    /** Base font size in px. Default 16. */
+    readonly baseFontSize?: number;
+    /** Named type ratio. Defaults to the feel preset's suggestion. */
+    readonly ratio?: string;
+    /** Type family + density + corners, moved together. Default `"neutral"`. */
+    readonly feel?: Feel;
+    /** Which normalization layer `globals.preset` gets. Default `"preflight"`. */
+    readonly reset?: ResetPreset;
+}
+/** What the contrast pass did to one palette — surfaced so the CLI can report it honestly. */
+export interface ContrastAdjustment {
+    readonly name: string;
+    /** The colour before the pass. */
+    readonly seed: string;
+    /** The colour written to the file. */
+    readonly final: string;
+    /** OKLCH lightness points removed (0 when untouched). */
+    readonly nudge: number;
+    /** Ratio before, and after. */
+    readonly ratioBefore: number;
+    readonly ratioAfter: number;
+    readonly levelAfter: WcagLevel;
+    /** True when the pass ran out of room without reaching the bar. */
+    readonly unresolved: boolean;
+}
+export interface ScaffoldReport {
+    /** The seed's OKLCH lightness, 0–100. */
+    readonly seedLightness: number;
+    /** The ladder label the seed sits nearest — `base` stays canonical, this is orientation only. */
+    readonly nearestStep: number;
+    /** Brand palettes in order, with the hue rotation that produced each (0 for the primary/manual). */
+    readonly brand: ReadonlyArray<{
+        readonly name: string;
+        readonly hex: string;
+        readonly rotation: number;
+    }>;
+    /** Every palette the contrast pass looked at. Empty when `contrast: "none"`. */
+    readonly contrast: readonly ContrastAdjustment[];
+    /** Derived per-step leading and tracking, for the CLI's summary line. */
+    readonly type: ReadonlyArray<{
+        readonly step: string;
+        readonly px: number;
+        readonly leading: number;
+        readonly tracking: string;
+    }>;
+    /** The resolved spacing ramp in px, for the CLI's summary line. */
+    readonly spacing: ReadonlyArray<{
+        readonly step: string;
+        readonly px: number;
+    }>;
+}
+export interface ScaffoldResult {
+    readonly raw: RawTheme;
+    readonly report: ScaffoldReport;
+}
+/** Leading for a size, from the curve above. */
+export declare const deriveLeading: (sizePx: number) => number;
+/** Tracking (em) for a size, from the curve above. */
+export declare const deriveTracking: (sizePx: number) => string;
+/**
+ * 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.
+ */
+export declare const nearestLadderStep: (lightness: number) => number;
+/** Which scheme a brand count implies when the caller doesn't name one. */
+export declare const defaultSchemeFor: (brandCount: number) => BrandScheme | undefined;
+/** Schemes that produce exactly `brandCount − 1` members — the valid choices at that count. */
+export declare const schemesFor: (brandCount: number) => readonly BrandScheme[];
+/**
+ * Build a complete `RawTheme` from the interview answers. Pure — no filesystem, no prompting, no
+ * randomness — so the same answers always produce the same theme.
+ */
+export declare function scaffoldTheme(answers: ScaffoldAnswers): ScaffoldResult;
+export {};