@theme-registry/refract 0.1.0

package/dist/subsystems/layout/recipes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Layout's `interpretRecipe` hook — resolves recipe declarations to token-path Refs.
+ *
+ * A layout recipe prop names a **spacing variant** (`paddingY: "xl"`, `gap: "relaxed"`),
+ * which this interpreter emits as a `layout.spacing.<variant>` token-path {@link Ref}
+ * (`layout.spacing` for the base). `background` passes through as a literal. One recipe prop
+ * can fan out to several CSS declarations (`paddingY` → `padding-top` + `padding-bottom`).
+ * Emits refs **directly** — no `var(--…)` strings; the CSS adapter maps each path to a
+ * `var(--…)` at render time. Ported + reshaped from the old `subsystems/layout/recipes.ts`.
+ */
+import type { InterpretedRecipeVariant } from "../../core/model";
+import type { NormalizedRecipeVariant } from "../../core/normalize";
+import type { RecipeInterpretContext } from "../../core/subsystem";
+import type { LayoutRecipeProps } from "./types";
+/** Interpret one layout recipe variant into base + responsive/state override declarations. */
+export declare const interpretLayoutRecipeVariant: (variantName: string, variant: NormalizedRecipeVariant<LayoutRecipeProps, string>, ctx: RecipeInterpretContext) => InterpretedRecipeVariant<string>;

package/dist/subsystems/layout/structural.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Layout structural generators → **Model rule-sets** (the clean-room payoff).
+ *
+ * `columns` / `grids` / `stacks` / `container` used to emit `CssNode[]` that a lossless
+ * node↔rule-set codec (`routeLayoutStructuralThroughModel`) round-tripped into the Model.
+ * Here the generators emit {@link RuleSetGroup}s **natively** — declarations carry token-path
+ * {@link Ref}s (`layout.spacing.relaxed`), never `var(--…)` — so the codec never exists. The CSS
+ * adapter lowers these rule-sets to `CssRuleNode[]` (columns/grids/stacks via `lowerRecipeGroup`,
+ * container via the two-pass `lowerContainerGroup`, matching the old unshift-bases/push-medias order).
+ *
+ * The columns/container config knobs (`--…-columns--size`, `--…-container--inset`, …) ride along as
+ * **layout property tokens** (`configProperties`, merged as `extraProperties` in the Model); the
+ * structural rule declarations reference those config tokens by path (`layout.container--inset`),
+ * exactly the two-level indirection the old generators produced. Math ported verbatim from the old
+ * `subsystems/layout/tokens.ts`; only the output shape (rule-sets, not CSS) differs.
+ *
+ * The math forms variant keys from raw breakpoint keys + span numbers (`col-sm-3`); the adapter
+ * prepends the class prefix + sanitizes. No CSS syntax is produced here — core stays format-neutral.
+ */
+import type { PropertyModel, RuleSetGroup } from "../../core/model";
+import { type MediaConfig } from "../../core/media";
+import type { ColumnsValue, GridsDefinition, StacksDefinition } from "./types";
+/** The structural output: rule-set groups (for the Model + CSS) + config `:root` tokens. */
+export type LayoutStructuralOutput = {
+    ruleSetGroups: Record<string, RuleSetGroup>;
+    configProperties: Record<string, PropertyModel>;
+};
+export declare const buildColumns: (input: ColumnsValue | undefined, breakpoints: Record<string, number>) => LayoutStructuralOutput | undefined;
+export declare const buildGrids: (grids: GridsDefinition | undefined) => LayoutStructuralOutput | undefined;
+export declare const buildStacks: (stacks: StacksDefinition | undefined) => LayoutStructuralOutput | undefined;
+export declare const buildContainer: (containerInput: unknown, breakpoints: Record<string, number>, sizeNames?: ReadonlySet<string>, mediaConfig?: MediaConfig) => LayoutStructuralOutput;
+/**
+ * Run all four structural generators over the raw layout slice, merging their rule-set groups
+ * (structural order: columns → grids → stacks → container) and config tokens. Container always
+ * runs; the rest run only when their raw key is present.
+ */
+export declare const buildLayoutStructural: (rawSlice: Record<string, unknown>, breakpoints: Record<string, number>, mediaConfig?: MediaConfig) => LayoutStructuralOutput;

package/dist/subsystems/layout/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Layout subsystem types (clean-room).
+ *
+ * Regular property keys (`spacing` / `gutters` / `aspectRatio`) normalize like any other
+ * subsystem; the structural keys (`columns` / `grids` / `stacks` / `container`) drive the
+ * structural generators (see `structural.ts`); `recipes` are ordinary token-path recipes.
+ */
+import type { PropertyValue, RecipeBlock } from "../../core/normalize";
+export type ResponsiveQuery = "min" | "max" | "exact";
+/** The whitelisted "regular" layout property keys (the ones that become `PropertyModel`s). */
+export declare const LAYOUT_PROPERTY_KEYS: readonly string[];
+/**
+ * Scale-synthesis authoring keys (§10.6) for a length scale (`spacing`/`gutters`/`sizes`). Declare
+ * one curve — `ratio` (geometric `base × ratio^n`, `steps` an ordered name array) or `step` (linear
+ * `step × n`, `steps` a name→multiplier map) — to synthesize the variant ramp instead of hand-listing
+ * it. Opt-in: absent both, the property behaves exactly as before. The same keys inside a `responsive`
+ * entry regenerate the whole named scale at that breakpoint (D6). Authored `variants` still win.
+ */
+export type LayoutScaleExtras = {
+    ratio?: number;
+    step?: number;
+    steps?: readonly string[] | Record<string, number>;
+};
+export type ColumnsConfig = {
+    size: number;
+    gutter?: string;
+    inset?: string;
+};
+export type ColumnsValue = number | ColumnsConfig;
+export type GridDefinition = {
+    templateColumns?: string;
+    templateRows?: string;
+    autoRows?: string;
+    autoColumns?: string;
+    justifyItems?: string;
+    alignItems?: string;
+    justifyContent?: string;
+    alignContent?: string;
+    gap?: string;
+    responsive?: Array<{
+        breakpoint: string;
+        query?: ResponsiveQuery;
+        templateColumns?: string;
+        templateRows?: string;
+        autoRows?: string;
+        autoColumns?: string;
+        justifyItems?: string;
+        alignItems?: string;
+        justifyContent?: string;
+        alignContent?: string;
+        gap?: string;
+    }>;
+};
+export type GridsDefinition = Record<string, GridDefinition>;
+export type StackDefinition = {
+    direction?: "row" | "column";
+    align?: string;
+    justify?: string;
+    wrap?: string;
+    inline?: boolean;
+    gap?: string;
+    responsive?: Array<{
+        breakpoint: string;
+        query?: ResponsiveQuery;
+        direction?: "row" | "column";
+        align?: string;
+        justify?: string;
+        wrap?: string;
+        inline?: boolean;
+    }>;
+};
+export type StacksDefinition = Record<string, StackDefinition>;
+export type ContainerConfig = {
+    /** The resolved mode: `"fixed"` / `"fluid"` / a custom width string. */
+    mode: string;
+    inset?: string;
+    gutter?: string;
+    direction?: string;
+    align?: string;
+    justify?: string;
+    maxWidth?: string | number;
+};
+/**
+ * One authored container variant (§8a) — a mode string (`"fixed"` / `"fluid"` / a width) or a
+ * config object. Distinct from {@link ContainerConfig}, which is the resolved `{ mode }` shape the
+ * structural generator produces.
+ */
+export type ContainerVariantRaw = string | {
+    base?: string;
+    inset?: string;
+    gutter?: string;
+    direction?: string;
+    align?: string;
+    justify?: string;
+    maxWidth?: string | number;
+};
+/** The authored `layout.container` value (§8a) — a mode string or a config with variants/responsive. */
+export type ContainerRaw = string | {
+    base?: string;
+    inset?: string;
+    gutter?: string;
+    direction?: string;
+    align?: string;
+    justify?: string;
+    maxWidth?: string | number;
+    variants?: Record<string, ContainerVariantRaw>;
+    responsive?: Array<{
+        breakpoint: string;
+        query?: ResponsiveQuery;
+        target?: string;
+        direction?: string;
+        align?: string;
+        justify?: string;
+        inset?: string;
+        gutter?: string;
+    }>;
+};
+export type LayoutRecipeProps = {
+    paddingY?: string;
+    paddingX?: string;
+    marginY?: string;
+    marginX?: string;
+    gap?: string;
+    background?: string;
+    /**
+     * Sizing verbs (§22) — each names a `layout.sizes` variant and routes to its CSS longhand
+     * (`maxWidth` → `max-width`, no fan-out). A verb exists because it consumes a themed scale (`sizes`);
+     * dimensional CSS with no scale (`display`, `position`, …) stays in a component `css` delta.
+     */
+    width?: string;
+    minWidth?: string;
+    maxWidth?: string;
+    height?: string;
+    minHeight?: string;
+    maxHeight?: string;
+    [property: string]: string | undefined;
+};
+/**
+ * The authored `raw.layout` slice (§8a). The only **closed** subsystem — its keys are fixed:
+ * the regular property tokens (`spacing`/`gutters`/`aspectRatio`), the four structural generators
+ * (`columns`/`grids`/`stacks`/`container`), and the `recipes` block. Authoring type only.
+ */
+export interface LayoutRaw {
+    spacing?: PropertyValue<string | number, LayoutScaleExtras>;
+    gutters?: PropertyValue<string | number, LayoutScaleExtras>;
+    aspectRatio?: PropertyValue<string | number>;
+    /** The sizing scale (§22) — one length scale for width/height/min/max, chosen at the recipe verb. */
+    sizes?: PropertyValue<string | number, LayoutScaleExtras>;
+    columns?: ColumnsValue;
+    grids?: GridsDefinition;
+    stacks?: StacksDefinition;
+    container?: ContainerRaw;
+    recipes?: RecipeBlock<LayoutRecipeProps>;
+}

package/dist/subsystems/typography/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The typography subsystem — a "regular" subsystem (no synthesized-ref derivations,
+ * unlike colors' tonal steps). Iterates `raw.typography` (skipping the reserved `recipes`
+ * key), runs the shared property normalize + the fontSize modular-scale synthesis per
+ * property, and interprets recipes into token-path refs. It grows a hook, never the spine.
+ */
+import type { Subsystem } from "../../core/subsystem";
+export declare const typographySubsystem: Subsystem;
+export type { TypographyRaw, TypographyPropertyValue } from "./types";

package/dist/subsystems/typography/normalize.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Typography's `normalizeProperty` hook — modular font-size scale synthesis.
+ *
+ * When `fontSize` is authored with a `ratio`, this generates the scale steps
+ * (`xs`…`4xl`) as variants — each `base * ratio^step` (or a custom `algorithm`),
+ * rounded to `precision`. Author-declared steps are preserved and seed the chain.
+ * Non-`fontSize` properties and ratio-less `fontSize` pass through untouched.
+ */
+import type { NormalizedPropertyValue } from "../../core/normalize";
+/**
+ * The typography `normalizeProperty` hook. Synthesizes the modular scale for
+ * `fontSize`; a pass-through for every other typography property.
+ *
+ * @param propertyKey The property being normalized (only `"fontSize"` is transformed).
+ * @param normalized  The property after the shared property normalize pass.
+ */
+export declare const finalizeTypographyNormalization: (propertyKey: string, normalized: NormalizedPropertyValue<unknown>) => NormalizedPropertyValue<unknown>;

package/dist/subsystems/typography/recipes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Typography's `interpretRecipe` hook — resolves recipe declarations to token-path Refs.
+ *
+ * A typography recipe prop value names a **variant** of the matching property (`fontSize:
+ * "3xl"`, `fontWeight: "bold"`), or the base value (`fontSize: "base"`). This interpreter
+ * emits a format-neutral {@link Ref} carrying the canonical token path — `typography.fontSize.3xl`
+ * for a variant, `typography.fontSize` for the base. It emits refs **directly** (no `var(--…)`
+ * strings); the CSS adapter maps each path to a `var(--…)` at render time, so `theme.model`
+ * carries no CSS syntax. Ported + reshaped from the old `subsystems/typography/recipes.ts`
+ * (which produced `var(--…)` strings via a prefix resolver).
+ */
+import type { InterpretedRecipeVariant } from "../../core/model";
+import type { NormalizedRecipeVariant } from "../../core/normalize";
+import type { RecipeInterpretContext } from "../../core/subsystem";
+import type { TypographyRecipeProps } from "./types";
+/**
+ * Interpret one typography recipe variant into base + responsive/state override declarations,
+ * each a token-path {@link Ref}. A responsive `variant:` swap inherits the sibling's base
+ * declarations (via `ctx.resolveRecipeVariant`).
+ */
+export declare const interpretTypographyRecipeVariant: (variantName: string, variant: NormalizedRecipeVariant<TypographyRecipeProps, string>, ctx: RecipeInterpretContext) => InterpretedRecipeVariant<string>;

package/dist/subsystems/typography/types.d.ts

@@ -0,0 +1,49 @@
+import type { PropertyValue, RecipeBlock } from "../../core/normalize";
+/**
+ * Typography's fontSize-scale config. Only the normalize-relevant subset is ported
+ * for Step 0b (the recipe / token / source types grow in Step 2).
+ */
+export type TypographyScaleKey = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl";
+export type TypographyRatioKey = "minor-second" | "major-second" | "minor-third" | "major-third" | "perfect-fourth" | "augmented-fourth" | "perfect-fifth" | "golden";
+export type FontSizeExtras = {
+    ratio?: TypographyRatioKey;
+    precision?: number;
+    unit?: "px" | "rem";
+    baseFontSize?: number;
+    algorithm?: (base: number, key: string, step: number, prev: number | null) => number;
+};
+export type FontSizeValue = PropertyValue<number, FontSizeExtras>;
+/**
+ * A typography recipe declaration block. Each value names a **variant** of the
+ * matching typography property (`fontSize: "3xl"`, `fontWeight: "bold"`, `fontSize: "base"`
+ * for the base value) — the interpreter maps it to a token-path {@link import("../../core/model").Ref}.
+ * Only the keys in the property map are lowered; unknown keys are ignored.
+ */
+export type TypographyRecipeProps = {
+    fontFamily?: string;
+    fontSize?: string;
+    fontWeight?: string;
+    lineHeight?: string;
+    letterSpacing?: string;
+    fontStyle?: string;
+    textTransform?: string;
+    textDecoration?: string;
+    textAlign?: string;
+    [property: string]: string | undefined;
+};
+/**
+ * A typography property value (§8a). Typography properties are heterogeneous —
+ * `fontFamily` is a string, `fontSize`/`fontWeight`/`lineHeight` numbers, `letterSpacing`
+ * a string — so the value unions `string | number`; the fontSize modular-scale extras
+ * (`ratio`/`precision`/…) ride along on every key (all optional, harmless elsewhere).
+ */
+export type TypographyPropertyValue = PropertyValue<string | number, FontSizeExtras>;
+/**
+ * The authored `raw.typography` slice (§8a). An **open** map: keys are typography property
+ * names (`fontFamily`, `fontSize`, …), each a {@link TypographyPropertyValue}; the reserved
+ * `recipes` key is a {@link RecipeBlock} of typography recipes. Authoring type only.
+ */
+export interface TypographyRaw {
+    recipes?: RecipeBlock<TypographyRecipeProps>;
+    [property: string]: TypographyPropertyValue | RecipeBlock<TypographyRecipeProps> | undefined;
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@theme-registry/refract",
+  "version": "0.1.0",
+  "description": "The framework-agnostic, format-neutral theme compiler core — build a ThemeModel from a RawTheme, then lower it with any adapter package (CSS, SCSS, JSON, styled-components).",
+  "author": {
+    "name": "Petyo Stoyanov",
+    "email": "petyosv@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theme-registry/refract.git",
+    "directory": "packages/refract"
+  },
+  "bugs": {
+    "url": "https://github.com/theme-registry/refract/issues"
+  },
+  "homepage": "https://github.com/theme-registry/refract#readme",
+  "license": "MIT",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "refract": "./dist/cli.js"
+  },
+  "files": [
+    "/dist",
+    "/skills",
+    "/src/subsystems/colors/utils.ts"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js"
+    },
+    "./dtcg": {
+      "types": "./dist/dtcg/index.d.ts",
+      "import": "./dist/dtcg.esm.js",
+      "require": "./dist/dtcg.cjs.js"
+    },
+    "./build": {
+      "types": "./dist/build/index.d.ts",
+      "import": "./dist/build.esm.js",
+      "require": "./dist/build.cjs.js"
+    },
+    "./adapter-kit": {
+      "types": "./dist/adapter-kit.d.ts",
+      "import": "./dist/adapter-kit.esm.js",
+      "require": "./dist/adapter-kit.cjs.js"
+    },
+    "./color-math": {
+      "types": "./dist/subsystems/colors/utils.d.ts",
+      "import": "./dist/color-math.esm.js",
+      "require": "./dist/color-math.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/node": "^24",
+    "rimraf": "^5.0.5",
+    "rollup": "^3.29.4",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "typescript": "^5.4.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "clean": "rimraf dist",
+    "test": "vitest run"
+  }
+}

package/skills/adapter-scaffold/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: adapter-scaffold
+description: Write your own refract output adapter when no shipped adapter targets your format — a standalone package or a local module in your own project, against the public defineAdapter contract. Use when you need a format refract doesn't ship (React-Native, Flutter, a bespoke JSON shape, …). Triggers: "no adapter for X", "write my own adapter", "custom output format", "defineAdapter", "React Native adapter".
+tier: optional
+---
+
+# Write your own adapter
+
+refract's adapter contract is public and stable, so if the shipped adapters (CSS, SCSS,
+styled-components, JSON — see **adapter-usage**) don't target your format, you can write one **in
+your own project** — a small standalone npm package or just a local module. You depend only on the
+published `@theme-registry/refract`; you do **not** fork or clone the refract repo. Full contract
+reference: `docs/extending.md`.
+
+## The contract
+
+`createTheme` calls your adapter's `bind(model, ctx)` once, then curries the returned `BoundSpec`
+onto the theme. You author an `AdapterSpec<TUnit>` and wrap it with `defineAdapter`.
+
+- **`TUnit`** — your output unit: `string` for text formats, an object type for JSON / RN / style
+  objects. `recipeName` is always `string`; only `renderRecipe` / `renderVariables` / `join` are
+  `TUnit`.
+- **Required primitives** (the only format-specific work):
+  - `recipeName(subsystem, group, variant): string` — the rule-set's identity (a class, a key).
+  - `renderRecipe(subsystem, group, variant): TUnit` — one rule-set (base + state/responsive rules).
+  - `renderVariables(subsystem): TUnit` — one subsystem's tokens.
+  - `join(parts: TUnit[]): TUnit` — combine units.
+- **`allowedStates?`** — the states your format can render (`["hover","focus",…]`); omit to accept
+  any. Core validates recipe `state:` refs against it before `bind`.
+- **Optional:** `renderToken`, aggregator overrides (`renderAllRecipes`/`…Variables`/`renderAll`),
+  `extend(theme)` (attach runtime glue), `emit(plan?)` (build-time files — switch on `plan.type`
+  and throw a clear error for modes you don't support).
+
+`defineAdapter(spec)` supplies the default aggregators as pure Model walks — override only if the
+full document isn't a flat concatenation.
+
+## The module
+
+```ts
+import type { ThemeModel, AdapterSpec, RenderContext, ThemeAdapter } from "@theme-registry/refract";
+import { defineAdapter } from "@theme-registry/refract";
+// naming helpers if you need them: from "@theme-registry/refract/adapter-kit"
+// OKLCH color math if you need it:  from "@theme-registry/refract/color-math"
+
+export type MyUnit = string;                       // ← or your object type
+export type MyAdapterOptions = { /* prefix?, … */ };
+
+export const createMyAdapter = (options: MyAdapterOptions = {}): ThemeAdapter<MyUnit> =>
+  defineAdapter({
+    name: "my-format",
+    version: 1,
+    // allowedStates: ["hover", "focus", "disabled"],
+    bind(model: ThemeModel, ctx: RenderContext) {
+      const { media, containers, resolve } = ctx;   // resolve(ref) → value; containers = §10.5
+      void options; void media; void containers;
+      // Precompute per-subsystem lowering here (walk model.subsystems.<sub>.properties / .ruleSets).
+      return {
+        recipeName(subsystem, group, variant) { /* … */ return `${subsystem}-${group}-${variant}`; },
+        renderRecipe(subsystem, group, variant) { /* … */ return "" as MyUnit; },
+        renderVariables(subsystem) { /* … */ return "" as MyUnit; },
+        join(parts) { return parts.join("\n\n") as MyUnit; },
+      };
+    },
+  });
+```
+
+Use it like any adapter: `createTheme(raw, { adapter: createMyAdapter() })`.
+
+## Packaging choices
+
+- **Local module** — simplest: a file in your app, imported straight into your `theme.config` or a
+  `createTheme` call. No publishing.
+- **Standalone package** — if you want to reuse or share it: a normal npm package with
+  `@theme-registry/refract` as a **peer dependency** (the consumer's single installed core is
+  shared), marked `external` in your bundler so you never ship a copy of core.
+
+## Notes
+
+- Never import from a relative core path — always the published specifiers
+  (`@theme-registry/refract`, `/adapter-kit`, `/color-math`).
+- Adapters are **not** subsystems; you don't register anything on core.
+- Read `docs/extending.md` for the full `ThemeModel` walk and the `emit()` file contract.
+
+*(Contributing an adapter back into the refract monorepo itself is a different, internal workflow —
+that's the repo's own `adapter-scaffold` contributor skill, not this one.)*

package/skills/adapter-usage/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: adapter-usage
+description: Choose a refract output adapter and use its call surface — CSS, SCSS, styled-components, or JSON, each a separate installable package. Use when deciding which format to emit, wiring createTheme with an adapter, or installing the adapter package. Triggers: "which adapter", "createTheme adapter", "CSS vs styled-components", "install refract-css", "adapter options / prefix / colorFormat / scheme".
+tier: core
+---
+
+# Adapter usage
+
+Core (`@theme-registry/refract`) ships **zero adapters** — that's what keeps it format-neutral.
+Each adapter is a **separate package** you install alongside core. Pick by target format, then
+pass a constructed adapter to `createTheme`.
+
+## Which adapter
+
+| Package | Factory | Emits | Choose it when |
+|---|---|---|---|
+| `@theme-registry/refract-css` | `createCssAdapter` | `:root` custom properties + recipe classes, `@media`/`@container`/`@keyframes` | Default. Framework-agnostic; runtime theming by swapping `:root`; MFE isolation via `prefix`. |
+| `@theme-registry/refract-styled-components` | `createStyledComponentsAdapter` | TS/JS modules (literal `theme` object + tree-shakeable `css` recipes + `GlobalStyle`) | React apps on styled-components ^6. No `var()`; dark lives in each recipe so it tree-shakes. |
+| `@theme-registry/refract-scss` | `createScssAdapter` | Sass `$variables` + `@use` partials + mixins/classes | A Sass build wanting compile-time `$variables`. |
+| `@theme-registry/refract-json` | `createJsonAdapter` | The full model as address-keyed JSON (refs kept beside resolved values) | Data-interchange, tooling, or feeding a non-CSS consumer. |
+
+If the format you need has no adapter, you can write one — see the opt-in **adapter-scaffold**
+guide (build a standalone adapter against the public `defineAdapter` contract).
+
+## Install the package you picked
+
+Add core **and** the chosen adapter (detect the package manager from the lockfile):
+
+```
+npm i @theme-registry/refract @theme-registry/refract-css
+# styled-components target also needs the peer:
+npm i @theme-registry/refract-styled-components styled-components
+```
+
+## Call surface
+
+`createTheme(raw, { adapter })` — `adapter` is **required**. Returns a `Theme` with the
+format-neutral surface (`model`, `tokens`, `resolveToken(path)`, `override(partial)`), plus
+whatever the adapter attaches via `extend()`:
+
+```ts
+import { createTheme } from "@theme-registry/refract";
+import { createCssAdapter } from "@theme-registry/refract-css";
+
+const theme = createTheme(raw, { adapter: createCssAdapter({ prefix: "acme" }) });
+theme.css;                       // full stylesheet
+theme.classes;                   // recipe → class name map
+theme.getClass("components", "buttons", "primary");
+```
+
+- **CSS** adds `theme.css` / `variablesCss` / `recipesCss` / `classes` / `getClass()` /
+  `renderRecipe()` / `media`.
+- **styled-components** adds `theme.theme` (for `<ThemeProvider>`) / `recipes` / `GlobalStyle` /
+  `media` / `scheme`.
+- **JSON** adds `theme.json` / `jsonString`; **SCSS** adds `theme.scss` / `variablesScss` /
+  `rulesScss` / `classes`.
+
+See **consuming-the-output** for wiring these into an app.
+
+## Adapter options (constructor)
+
+Options are passed when constructing the adapter, never as CLI flags. The common ones:
+
+- **CSS** — `prefix` (default `"dt"`, also the class prefix + MFE isolation), `classPrefix`,
+  `inline` (bake values, drop `var()`), `colorFormat: "rgb" | "hex" | "oklch"`, `naming` (§7B
+  override hook), `layer: string | boolean` (wrap output in `@layer` for deterministic precedence
+  under app CSS), `reducedMotion: true` (append a `prefers-reduced-motion` reduce block). The last
+  two are single-file-emit only and off by default (byte-identical).
+- **styled-components** — `language: "ts" | "js"`, `emit: "single" | "split"`,
+  `scheme: "media" | "attribute" | "both"` (dark realization), `helpers: ["color-math"]`,
+  `naming`.
+- **SCSS** — `prefix`, `inline`, `indent`, `layer` (same as CSS). **JSON** — minimal; see
+  `docs/css-adapter.md` and `docs/authoring.md` for the full tables.
+
+Cross-format concerns — emit modes, dark-mode strategy, the CLI — live in **build-config**.

package/skills/build-config/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: build-config
+description: Wire the refract build — theme.config.ts (defineConfig, targets), the emit modes (single/split/subsystem/components), the refract CLI (init/build/import/tokens), and per-target dark-mode strategy. Use when emitting a theme to disk rather than building it at runtime. Triggers: "theme.config", "defineConfig", "refract build", "emit split/subsystem/components", "output multiple formats", "dark mode strategy", "refract init".
+tier: core
+---
+
+# Build config
+
+Two ways to realize a theme: **at runtime** via `createTheme(raw, { adapter })` (see
+**adapter-usage**), or **to disk** via a `theme.config` + the `refract` CLI. This guide is the
+disk path.
+
+## `theme.config.(ts|mjs|js)`
+
+The config is **your code** — it imports the adapter(s) and the raw theme, and that import *is*
+the extensibility seam (like Rollup/Vite). Adapter options are passed at construction, not as CLI
+flags. Multiple targets emit multiple formats from one theme. Keep the raw theme in a sibling
+`theme.raw.ts` (the `.ts` config graph-compiles, so `import { raw } from "./theme.raw"` resolves).
+
+```ts
+import { defineConfig } from "@theme-registry/refract/build";
+import { createCssAdapter } from "@theme-registry/refract-css";
+import { createStyledComponentsAdapter } from "@theme-registry/refract-styled-components";
+import { raw } from "./theme.raw";
+
+export default defineConfig({
+  raw,
+  targets: [
+    { name: "css", adapter: createCssAdapter(), outDir: "dist/theme" },
+    { name: "sc",  adapter: createStyledComponentsAdapter({ language: "ts" }), outDir: "dist/sc" },
+  ],
+  // media / units / baseFontSize resolve once so every target emits identical units.
+});
+```
+
+`ThemeConfig` = `{ raw, targets, media?, units?, baseFontSize? }`. Each `EmitTarget` =
+`{ adapter, outDir, name?, emit?, helpers? }`. Resolution order: `theme.config.ts` → `.mjs` →
+`.js` (a `.ts` config lazy-loads the optional `typescript` peer).
+
+## Emit modes (`emit` on a target)
+
+Core owns the vocabulary; **each adapter decides which modes it honors** and throws a clear error
+otherwise.
+
+| Mode | Output | Notes |
+|---|---|---|
+| `single` (default) | one file | `{ file }` renames it |
+| `split` | rules file + variables file | load-order contract, **no `@import`** |
+| `subsystem` | a styles+variables pair per subsystem | `filename(subsystem, kind)` |
+| `components` | one self-contained rule-set per component variant | `inline` defaults **true** (bakes values); `inline: false` emits `var()` + a tree-shaken variables file |
+
+Only `single` / `split` may omit `type`. Support matrix: **CSS** and **JSON** = all four; **SCSS**
+= single/split/components (subsystem throws); **styled-components** = single/split only (ES modules
+tree-shake, so the CSS-only modes are redundant).
+
+## The `refract` CLI
+
+- `refract init [--js|--mjs] [--force]` — scaffold a runnable `theme.config`.
+- `refract build [--config <path>] [--target <name|index>] [--out <dir>]` — emit each target.
+- `refract import <tokens.json> […]` — seed a theme from a DTCG document (see **dtcg-import**).
+- `refract tokens [--config <path>] [--out <file>]` — DTCG export (see **dtcg-import**).
+- `refract help`.
+
+Run via `npx refract <cmd>`. `outDir` resolves relative to the config file's directory.
+
+## Dark-mode strategy (differs by target)
+
+- **CSS / SCSS / JSON** — dark rides the *referenced token's own `modes`* (see **theme-foundations**);
+  a token with a `dark` value emits `@media (prefers-color-scheme: dark)` overrides. No separate
+  global switch; `colorFormat` is the main CSS colour knob.
+- **styled-components** — an explicit `scheme` option: `"media"` (OS), `"attribute"`
+  (`[data-theme="dark"]` manual toggle), or `"both"`.
+
+## Vendored helpers
+
+`helpers: ["color-math"]` on a target materializes a shared helper module (live `lighten`/`darken`/
+`alpha`) next to the output — opt-in, only when named.