@theme-registry/refract 0.1.0

package/skills/colors/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: colors
+description: Author the `colors` slice of a refract theme — palettes as bare hex / `[r,g,b]` / extended colours, the OKLCH numeric step ladder, tonal + derivation-spec + harmony variants, and palette recipes. Also the `@theme-registry/refract/color-math` helper subpath for computing colours live in an app that match the emitted CSS. Use when writing or tuning a palette. Triggers: "add a palette", "colour steps / tonal ramp", "lighten / darken / alpha a colour", "colour harmony", "OKLCH steps", "colour math helpers".
+tier: core
+---
+
+# Colors
+
+The `colors` key is an **open** map: each key is a palette name (`primary`, `neutral`, …)
+holding a colour value. The reserved `recipes` block holds palette recipes. Cross-cutting axes
+(`responsive`, `modes`, refs) are in **theme-foundations**; recipe mechanics are in
+**recipes-and-composition**. Exhaustive options live in `docs/authoring.md`.
+
+## A colour value
+
+Three forms, cheapest first:
+
+```ts
+colors: {
+  accent: "#4dabf7",                 // bare hex (3- or 6-digit)
+  ink: [33, 37, 41],                 // [r, g, b] tuple, 0–255
+  brand: {                           // extended
+    base: "#4dabf7",
+    text: "#ffffff",                 // paired foreground (same hex/tuple rule)
+    steps: [50, 100, 200, /* … */ 900],
+    variants: { subtle: { modifiers: [{ alpha: 40 }] } },
+    modes: [{ mode: "dark", base: "#1c7ed6" }],
+  },
+}
+```
+
+A base may be a **hex string, `[r,g,b]` tuple, or any CSS colour** — `oklch()`, `hsl()`/`hsla()`,
+`rgb()`/`rgba()`, or a named keyword (`"rebeccapurple"`). All normalize to a canonical `rgb(...)`
+string at build and derive in OKLCH. Only a `var(--…)` is rejected — it can't be tonally derived;
+borrow it as an [external token](../overrides-and-child-themes/SKILL.md) instead. Alpha is never
+authored on a base — use an `alpha` variant.
+
+## Steps — the numeric OKLCH ladder
+
+`steps` is **numeric only** and defines an **absolute** OKLCH lightness ladder: each Tailwind-style
+label maps to a fixed lightness via `L = (1000 − label) / 10`, so **low labels are light, high are
+dark**, and the same label reads at the same lightness across every palette. `0` / `1000` are pure
+white / black; every other label clamps to `[5, 98]`. The exact authored colour stays at the
+unnumbered `colors.<name>` token — a rung is never aliased to it, and `lightenBy` / `darkenBy` do
+**not** apply to numeric steps.
+
+With **no** `steps`, refract auto-generates the named tonal set `light` / `lighter` / `dark` /
+`darker`, each compounding `lightenBy` / `darkenBy` (default `10`) as OKLCH ΔL points.
+
+## Variants — derivation specs
+
+Beyond literals, a variant can be a **derivation spec** — a `modifiers` **chain** of single-key
+dials (`{ darken }` / `{ lighten }` / `{ alpha }` / `{ adjust }`), applied left-to-right, with an
+optional `ref` naming the source (defaults to the colour's own base; may point at another
+variant/step by name, or a cross-property token path like `colors.brand`):
+
+```ts
+variants: {
+  hover:   { modifiers: [{ darken: 8 }] },                    // −8 OKLCH ΔL from base
+  ghost:   { modifiers: [{ alpha: 15 }] },                     // absolute opacity: 15% opaque
+  onHover: { ref: "hover", modifiers: [{ lighten: 4 }] },      // read another variant, then transform
+  muted:   { modifiers: [{ adjust: { l: 60, c: 0.4, h: -10 } }] }, // absolute L, chroma ×, hue rotation
+  tinted:  { modifiers: [{ darken: 6 }, { alpha: 90 }] },      // a multi-dial chain (darken THEN alpha)
+}
+```
+
+`adjust` dials: `l` = absolute OKLCH lightness `0–100`; `c` = chroma **multiplier** (`1` keeps, `0`
+greys); `h` = signed hue rotation in degrees. The same `modifiers` chain is the value form for a
+mode (`{ mode, modifiers }`) and a responsive entry. Every generated variant carries `derive`
+metadata, so `override()` of the base — or of a **cross-property** source — re-bakes the whole set
+for free (see **overrides-and-child-themes**).
+
+## harmony
+
+Rotate the base's hue around the perceptual wheel (lightness + chroma held). String form uses default
+member names; object form renames positionally:
+
+```ts
+brand: { base: "#4dabf7", harmony: "triadic" },              // → triadic1, triadic2
+brand: { base: "#4dabf7", harmony: { triadic: ["mint", "coral"] } },
+```
+
+Schemes and their default members: `complement` → `complement`; `analogous` → `analogous1/2`;
+`split-complement` → `split1/2`; `triadic` → `triadic1/2`; `tetradic` → `tetradic1` / `complement`
+/ `tetradic2`. Exactly one scheme per colour.
+
+## recipes — palette recipes
+
+The reserved `recipes` block declares colour-bearing style properties (`background`,
+`backgroundColor`, `color`, `borderColor`, `outlineColor`, plus any extra property passed through as
+a literal). Each value names a palette reference (`"primary"`, `"primary.text"`, `"neutral.light"`)
+or a literal. Recipe structure (states, variants, composition) is in **recipes-and-composition**.
+
+## color-math — live colours that match the CSS
+
+The same OKLCH functions refract bakes with are published at `@theme-registry/refract/color-math`,
+string-in / string-out, so a colour computed live in the app matches the emitted CSS variable:
+
+```ts
+import { lighten, darken, setL, rotateHue, complement, adjust, alpha,
+         toHexColor, toOklchColor } from "@theme-registry/refract/color-math";
+
+lighten("#4dabf7", 10);   // shift OKLCH lightness +10
+alpha("#4dabf7", 40);     // absolute 40% opacity
+adjust("#4dabf7", { l: 60, c: 0.4, h: -10 });
+```
+
+Also exported: the conversion primitives `parseColor`, `serializeColor`, `convertHexToRGB`,
+`convertRgbToHex`, `rgbToOklch`, `oklchToRgb`, `isHexColor`, `coerceColorInput`.
+
+## Contrast audit — `refract audit`
+
+Colours are the flagship, so refract can score them. The audit checks every palette `base`↔`text`
+pairing and every recipe foreground↔background (all subsystems, incl. `:hover`) against **WCAG 2**
+contrast, with an advisory **APCA** Lc. It **reports** — it never rewrites a colour; a non-derivable
+side (`transparent`, a `var()`, a keyword) is `skipped`.
+
+```
+refract audit                      # report (exit 0)
+refract audit --strict             # fail the run (exit 1) on any pairing below the bar
+refract audit --min-wcag AAA       # raise the bar (AA | AAA | AA-large)
+refract audit --large              # relax to large-text thresholds
+```
+
+Programmatic — reads a built theme, same scores as structured data:
+
+```ts
+import { audit } from "@theme-registry/refract";
+const { pairings, summary, ok } = audit(theme, { minWcag: "AA" });
+// each pairing: { label, fg, bg, wcagRatio, wcagLevel, apcaLc, pass } or { skipped }
+```
+
+WCAG levels: `AAA` ≥ 7, `AA` ≥ 4.5, `AA-large` ≥ 3 (large text only). APCA is advisory — reported,
+never gated. `--strict` throws a `RefractError` (code `REFRACT_E_AUDIT`) listing every failing pair.

package/skills/consuming-the-output/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: consuming-the-output
+description: Wire a built refract theme into an app (per adapter), and publish a theme so others can consume it. Use after a theme is built, when integrating it into React/CSS/Sass or shipping it as a package or artifact. Triggers: "use the theme in my app", "ThemeProvider", "import theme.css", "runtime theme switching", "publish the theme", "consume the built output".
+tier: core
+---
+
+# Consuming the output
+
+How the *output* is used differs by adapter — different format, different integration. The theme
+you built (runtime `createTheme(...)` or `refract build`) exposes the shapes below.
+
+## CSS
+
+The emitted `.css` is self-contained — no refract at runtime.
+
+- Import the stylesheet once (`import "./dist/theme/theme.css"`), then use the recipe **class
+  names** on elements. Look them up with `theme.getClass(subsystem, group, recipe)` or the
+  `theme.classes` map at build time.
+- Values are `var(--…)` custom properties, so **runtime theming = swap `:root`**: override the
+  variables under a selector/attribute and everything rebinds with no re-render.
+- Container-query utilities emit as `.<prefix>-cq-<name>` classes.
+
+## styled-components
+
+The SC adapter emits **TS/JS modules**, not a stylesheet.
+
+- Wrap the app once: `<ThemeProvider theme={theme.theme}>`. This supplies token *values*; it's set
+  once and never swapped (dark rides `scheme`, not a provider swap).
+- Recipes are tree-shakeable `css` blocks that read the theme
+  (`${({ theme }) => theme.colors.primary}`): `styled.button\`${componentsButtonsPrimary}\``, or
+  import the grouped `recipes` barrel.
+- `GlobalStyle` (from the globals `preset` + element rules) mounts once.
+- `theme.media.<bp>.{min,max}` and `theme.scheme.dark` are tagged-template helpers for responsive
+  and dark blocks inside a recipe.
+- `theme.d.ts` (ts only) augments `DefaultTheme`, so `props.theme.*` is typed.
+
+## SCSS / JSON
+
+- **SCSS** — `@use` the emitted partials; consume the `$variables` and mixins in your Sass build.
+- **JSON** — `theme.json` is the whole model as data (tokens + rule-sets + refs); feed it to
+  tooling or a non-CSS renderer.
+
+## Publishing a theme others consume
+
+A built theme is just files under `outDir`, so it ships as an **npm package**, a **zip / CI
+artifact**, or a **vendored folder** — the downstream consumer needs neither refract nor these
+skills. Ship the emitted files plus, ideally, a machine-readable token export
+(`refract tokens` → `tokens.json`, see **dtcg-import**) and a short README pointing at the entry
+files.
+
+For AI-assisted consumers, refract can emit a **self-documenting guide** into `outDir` (an
+`llms.txt` describing this theme's real class names / exports / token paths, plus a
+`manifest.json`) so a downstream agent can consume the theme from the folder alone — enable it on
+the build target (see **build-config**). Because the guide sits in `outDir`, it travels with any
+distribution form, package specifier or not.
+
+While *authoring* against a live project, the **`@theme-registry/refract-mcp`** server exposes the
+same information as **live tools + resources** (schema 1) — `getClass` / `resolveToken` / `renderRecipe`
+and a `refract://manifest.json` resource — answering against the real compiled theme. Prefer it when
+connected; the emitted `manifest.json` / `llms.txt` are the offline fallback that ships with the theme.
+The tools, the emitted guide, and the refract skills all speak the same contract. See **theme-authoring
+→ Agent tools**.

package/skills/dtcg-import/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: dtcg-import
+description: Migrate existing design tokens into refract and export back out via the DTCG (W3C tokens.json) interop. Use when onboarding from Figma / Tokens Studio / Style Dictionary, or exporting a refract theme as standard tokens. Triggers: "import tokens.json", "Figma tokens", "Tokens Studio", "Style Dictionary", "DTCG", "refract import", "refract tokens", "export design tokens".
+tier: core
+---
+
+# DTCG import / export
+
+DTCG (the W3C Design Token Community Group `tokens.json` format) is refract's **interop** surface,
+not an adapter. It's how you get *into* refract from existing tokens and *out* to a standard
+format. It is Model-first and **property-tokens-only** — recipes and composition are out of scope
+(they have no DTCG equivalent).
+
+## Import — seed a theme from tokens
+
+```
+refract import tokens.json
+refract import tokens.json --out theme.raw.ts --breakpoints sm:576,md:768,lg:992
+```
+
+Turns a DTCG document into a `createTheme` raw input (and, unless `--raw-only`, a starter
+`theme.config`). Flags: `--out <file>`, `--raw-only`, `--force`, `--breakpoint-group <name>`,
+`--breakpoints <n:px,…>` (DTCG has no breakpoint concept, so supply them). After importing, the
+palettes/scales are plain tokens — layer refract's synthesis (`steps`, `ratio`), recipes, and
+composition on top by hand.
+
+## Export — emit standard tokens
+
+```
+refract tokens                 # → tokens.json
+refract tokens --out design-tokens.json
+```
+
+Walks the built theme's flat token map and writes a DTCG document. It's **adapter-free** (uses
+core's built-in noop adapter), reading only `theme.tokens` / `resolveToken` / breakpoints — so it
+ignores recipes and needs no output adapter. Handy for handing tokens back to design tooling, or
+as the machine-readable companion when **publishing a theme** (see **consuming-the-output**).
+
+## Lossless round-trip (opt-in) — `refract → DTCG → refract`
+
+The **standard** DTCG surface carries property tokens as *resolved literals* — so appearance
+`modes`, `responsive` overrides, derivation refs (`{ ref, modifiers }`), and recipes don't survive a
+plain round-trip. For a lossless refract-to-refract trip, opt in:
+
+```ts
+import { toDTCG, fromDTCGTheme } from "@theme-registry/refract/dtcg";
+
+const doc = toDTCG(theme, { includeRecipes: true }); // stashes the whole built Model under a $extensions key
+const restored = fromDTCGTheme(doc, { adapter: createCssAdapter() }); // byte-identical Model back
+```
+
+- `toDTCG(theme, { includeRecipes: true })` writes the built **property Model** (incl. modes /
+  responsive / derivations / external) **and** rule-set / keyframe / container IR under the
+  reverse-DNS `$extensions` key **`com.theme-registry.refract`** (with a `version`). Off by default →
+  standard output is byte-identical.
+- `fromDTCGTheme(doc, { adapter })` is the lossless entry — `fromDTCG` for the portable tokens **plus**
+  re-injects the stashed Model, reproducing a byte-identical theme.
+- **Not portable:** other DTCG tools ignore that extension and see the resolved property tokens only.
+
+## External tokens ↔ DTCG aliases
+
+An `external` token (a passthrough to a **parent-owned** var) is kept out of the portable token
+surface (a `var(--…)` colour can't be re-imported) — it round-trips via the extension above. Going
+the other way, a DTCG **alias** `"{group.token}"` whose target is **absent** from the document is
+treated as genuinely external and imported as a refract `external` token (`{color.brand}` →
+`{ external: "colors.brand" }`); a **resolvable** same-document alias flattens to its literal as before.
+
+## Programmatic API
+
+The same conversions are on the `@theme-registry/refract/dtcg` subpath:
+
+- `fromDTCG(doc, opts?)` → a raw theme input.
+- `toDTCG(theme, opts?)` → a DTCG document (`opts.includeRecipes` adds the round-trip extension).
+- `fromDTCGTheme(doc, { adapter, ... })` → a built `Theme` with recipes restored (lossless round-trip).
+- `readRefractExtension(doc)` → the `com.theme-registry.refract` payload, or `undefined`.
+- `parseDTCGDocument(doc)` — low-level walker resolving `{ref}` chains.

package/skills/layout/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: layout
+description: Author the `layout` slice of a refract theme — the length scales (spacing/gutters/sizes/aspectRatio) with geometric or linear scale synthesis, the four structural generators (columns/grids/stacks/container), and layout recipes with sizing verbs. The only CLOSED subsystem (fixed keys). Use when writing spacing scales or layout primitives. Triggers: "spacing scale", "sizes / min-width scale", "columns / grid / stack / container", "4/8-pt grid", "layout recipe padding/gap".
+tier: core
+---
+
+# Layout
+
+`layout` is the only **closed** subsystem — its keys are fixed: the length-scale properties
+(`spacing` / `gutters` / `sizes` / `aspectRatio`), the four structural generators (`columns` /
+`grids` / `stacks` / `container`), and the `recipes` block. Cross-cutting axes are in
+**theme-foundations**; recipe mechanics in **recipes-and-composition**. Exhaustive options live in
+`docs/authoring.md`.
+
+## Length scales — synthesis
+
+`spacing`, `gutters`, and `sizes` can synthesize their variant ramp from a base + one curve (declare
+`ratio` **or** `step`, never both). `aspectRatio` is a plain property (no ramp).
+
+```ts
+layout: {
+  // geometric: base × ratio^n, `steps` an ORDERED name array (index = exponent)
+  spacing: { base: 8, ratio: 1.5, steps: ["xs", "sm", "md", "lg", "xl"] },
+
+  // linear: step × mult, `steps` a name→multiplier map (the 4/8-pt grid)
+  gutters: { base: 0, step: 4, steps: { sm: 1, md: 2, lg: 4 } },
+
+  sizes: { base: "20rem", ratio: 1.25, steps: ["sm", "md", "lg"],
+           variants: { full: "100%", prose: "65ch" } },   // authored variants win, never synthesized
+}
+```
+
+Omitting `steps` uses the default ladder `xs sm md lg xl 2xl 3xl 4xl`. Each synthesized step is a
+**derived** ref (`scaleStep`), so `override()` of the base re-derives the whole ramp for free (see
+**overrides-and-child-themes**). Authored `variants` win over synthesized ones; `spacing` / `gutters`
+always expose a forced `none` (`0`). A `responsive` entry carrying `ratio` / `step` regenerates the
+**whole named scale** at that breakpoint (one `target` override per step).
+
+## Structural generators
+
+Each key drives a generator that emits layout primitives; declarations reference the length-scale
+tokens by name.
+
+- **`columns`** — `number` or `{ size, gutter?, inset? }`. Generates per-span × per-breakpoint
+  utilities: `col-<bp>-<n>` (`grid-column-end: span n`) and `offset-<bp>-<n>` (`grid-column-start`),
+  plus `columns--size/gutter/inset` config tokens.
+- **`grids`** — `{ <name>: { templateColumns, templateRows, autoRows, autoColumns, justifyItems,
+  alignItems, justifyContent, alignContent, gap, responsive } }`. Each emits a `grid-<name>` recipe
+  (`display: grid` + template props; `gap` resolves to a `spacing` ref).
+- **`stacks`** — `{ <name>: { direction: "row"|"column", align, justify, wrap, inline, gap,
+  responsive } }`. Each emits a `stack-<name>` recipe (flex / inline-flex, direction, align, justify,
+  wrap; `gap` → `spacing` ref).
+- **`container`** — a mode string (`"fixed"` / `"fluid"` / a width) or `{ base, inset, gutter,
+  direction, align, justify, maxWidth, variants, responsive }`. Always emits a default container
+  (defaults to `"fixed"`). `fixed` steps `max-width` per breakpoint; `fluid` applies a `maxWidth` cap
+  (a `sizes` variant name → unit-aware ref, a breakpoint name → its px width, else a literal); a
+  custom width becomes that `max-width`. Emits `container--inset/gutter` config tokens.
+
+## recipes — layout recipes
+
+The reserved `recipes` block declares spacing-bearing properties (`paddingX` / `paddingY` / `marginX`
+/ `marginY` / `gap` / `background`) plus **sizing verbs** — `width` / `minWidth` / `maxWidth` /
+`height` / `minHeight` / `maxHeight`, each naming a `layout.sizes` variant and routing to its CSS
+longhand. Non-scale dimensional CSS (`display`, `position`, …) stays in a component `css` delta.
+Recipe structure is in **recipes-and-composition**.

package/skills/overrides-and-child-themes/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: overrides-and-child-themes
+description: Derive brand variants and child themes from a base theme with theme.override(partial). Use for multi-brand, white-label, or sub-brand setups where several themes share one structure. Triggers: "child theme", "brand variant", "white-label", "theme.override", "override a token", "multi-brand".
+tier: core
+---
+
+# Overrides and child themes
+
+`theme.override(partial)` returns a **new theme** by delta-merging a partial raw theme onto the
+base. Use it for multi-brand / white-label setups: author one structural base, then derive brands
+that change only what differs.
+
+```ts
+const base = createTheme(raw, { adapter: createCssAdapter() });
+
+const acme = base.override({
+  colors: { brand: { base: "#d6336c" } },   // only the token(s) that differ
+});
+
+acme.css;                                    // fully re-derived output
+```
+
+## What re-derives
+
+The override re-runs the pipeline, so **derived values recompute** — a palette `base` change
+re-derives its `light`/`dark`/`steps`, a layout scale re-synthesizes its ramp, and every recipe
+that references those tokens picks up the new values. **Cross-property derivations re-derive too:**
+a variant or mode that reads *another* property (`{ ref: "colors.brand", modifiers: [{ darken: 12 }] }`)
+recomputes when you override its **source** — even though the deriving property isn't in your
+partial. This is why tokens are stored as derived refs, not frozen literals. The adapter surface
+(`.css`, `.classes`, …) recomputes for the child.
+
+## Guidelines
+
+- **Override the smallest delta.** Change the `base` of a palette, not each derived variant, and
+  let derivation do the rest.
+- **Structure stays in the base.** Overrides are for *values* — keep recipes, breakpoints, and
+  composition in the base theme so every brand shares one shape.
+- **Chain freely.** A child can itself be overridden (`acme.override({...})`), building a small
+  tree of brand → sub-brand.
+- **See the blast radius first.** An override re-derives everything downstream — before you commit
+  one, run `diffTheme(partial)` (via the MCP server, or `refract diff` in CI) to see exactly which
+  tokens, classes and contrast pairings the delta moves. Plan, then apply. See **theme-authoring →
+  Agent tools**.
+- For the merge semantics of individual fields (refs, `css`, `states`, `responsive`) the same
+  rules as recipe variants apply — see **recipes-and-composition**.
+
+For emitting several brands to disk, give each its own build target (or run the build per
+override) — see **build-config**.
+
+## Extending a theme you don't own — external tokens
+
+`override()` derives a child of a theme *you* built. To instead build ON TOP of a **published**
+theme — reusing its variables without redefining them — declare the borrowed tokens as external:
+
+```ts
+extends: { prefix: "dt" },                     // the parent theme's CSS-variable prefix
+colors: {
+  brand:   { external: "colors.brand" },       // path form → var(--dt-colors-brand)
+  surface: { external: "--mat-sys-surface" },  // literal form (leading --) → any var, verbatim
+  accent:  "#e64980",                          // your own new token
+  recipes: { solid: { cta: { background: "brand", color: "accent" } } },
+}
+```
+
+An external token is a passthrough to the parent's CSS variable: referenceable everywhere, never
+defined locally, never tonally derived, and it survives `override()`. Path form assumes the parent's
+default naming (`extends.prefix`, any string incl. `""`); literal form (`--…`) points at any variable
+(Material/Tailwind/hand-rolled). Best for individual tokens (colours, spacing, type). For a one-off,
+`css: { color: "var(--dt-colors-brand)" }` also works — a bare string in a `css` block is a literal.

package/skills/recipes-and-composition/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: recipes-and-composition
+description: How recipes work across every refract subsystem — the group → recipe → variant tiers, states, the variants modifier map, and cross-subsystem composition via components. Read this whenever authoring anything under a recipes block, not just colors or layout. Triggers: "add a recipe", "recipe variants", "compose a button/component", "components block", "recipe states", "variant vs recipe".
+tier: core
+---
+
+# Recipes and composition
+
+Every subsystem exposes the **same** recipe machinery under its `recipes` key (and `components`
+is composition-only). Learn it once here; the domain guides just say "and it has recipes." For
+the shared override axes (`responsive`, `variant:` / `target:`, `states`) see **theme-foundations**.
+
+## Three tiers
+
+`recipes: { <group>: { <recipe>: { …props } } }`
+
+- **group** (`solid`) — a namespace of related recipes.
+- **recipe** (`brand`) — the leaf that resolves to a class / export.
+- **variant** (`muted`) — an optional modifier delta on a recipe (below).
+
+```ts
+colors: {
+  recipes: {
+    solid: {
+      brand: {
+        background: "brand", color: "brand.text",
+        states: [{ state: "hover", background: "brand.dark" }],
+        responsive: [{ breakpoint: "md", query: "min", state: "hover", background: "brand.darker" }],
+      },
+    },
+  },
+}
+```
+
+Values that name a token become references (`var(--…)` in CSS) so overrides cascade; unknown
+names pass through as literals (see **theme-foundations** → References).
+
+## States
+
+`states` is validated against the **adapter's** known set (CSS: `hover` / `focus` / `disabled` /
+…); an unknown state throws at build. It's a **LIST of override entries**, each
+`{ state, target?, …deltas }` — author them directly, or put a `state` on a `responsive` entry to
+gate on a breakpoint too. An optional `target` scopes a state onto a recipe **variant** sibling
+(`<item>-<variant>`), so two same-state entries can differ per variant:
+`states: [{ state: "hover", … }, { state: "hover", target: "lg", … }]`.
+
+## Variants — a modifier map on any recipe
+
+Add a `variants` map of deltas to any recipe in any subsystem. Each desugars to a flat sibling
+`<recipe>-<variant>`; the bare recipe still emits. **Opt-in + additive** — no `variants` key
+means unchanged output.
+
+```ts
+solid: {
+  brand: {
+    background: "brand", color: "brand.text",
+    variants: { muted: { background: "brand.light" } },   // → solid.brand + solid.brand-muted
+  },
+}
+```
+
+Merge rules, per field:
+
+- a **ref** replaces the base ref;
+- **`css`** shallow-merges by property;
+- **`states`** merge by state name;
+- **`responsive[]`** concatenates;
+- a prop set to **`null`** drops an inherited ref (`borders: null`) — `null`, not `"none"`
+  (which stays a real value like `border: none`).
+
+The join separator is `-` (matching token variants). A desugared name that collides with an
+existing sibling throws. Variants are a flat axis — no nesting.
+
+## Composition — the `components` subsystem
+
+`components` owns no primitive tokens; each recipe **references other subsystems' recipes** and
+adds an own `css` delta (which wins on conflict):
+
+```ts
+import { ref } from "@theme-registry/refract";
+
+components: { recipes: { buttons: { primary: {
+  colors: "solid.brand", typography: "button.large", layout: "padding.button", borders: "outline.hairline",
+  css: { cursor: "pointer", border: "none", color: ref("colors.brand.text") },   // see the rule below
+  states: [{ state: "hover", css: { transform: "translateY(-1px)" } }],
+} } } }
+```
+
+**The `css` block is literal-first:** a **bare string / number is a raw CSS literal** (`cursor:
+"pointer"` just works), and a **token reference** uses `ref("…")` or the JSON-safe `{ ref: "…" }`
+object. This differs from the composition fields above (`colors: "solid.brand"`), where a bare
+string is always a reference — those compose tokens; the `css` block writes CSS. Prefer `ref()`
+explicitly. (Full rule in **theme-foundations**.)
+
+The referenced recipes are spread in (their resolved declarations), then the own `css` delta is
+applied on top. In CSS this emits a class list; in styled-components it spreads the referenced
+`css` blocks — see **adapter-usage** and **consuming-the-output** for how each adapter realizes
+composition. `variants` works here too (a component recipe can carry its own modifier map).
+
+Don't hand-derive the composed class name — read the **real** one: `theme.getClass("components",
+"buttons", "primary")` returns the full class list, or, with an MCP server connected, the `getClass`
+/ `renderRecipe` tools return the real class / emitted CSS live (configured prefix and all). See
+**theme-authoring → Agent tools**.
+
+**Precedence.** refract emits low, even specificity (single classes; zero-specificity `:where()` for
+globals) and relies on **source order** at equal specificity — the delta class is emitted last, so it
+wins. If you compose refract with an existing stylesheet or utility framework and want precedence that
+doesn't depend on load order, wrap the output in a cascade **`@layer`** via the CSS adapter's `layer`
+option (`createCssAdapter({ layer: true })` → `@layer refract`). Layered rules always lose to unlayered
+app CSS, so your styles win by default. Single-file emit only; off by default (byte-identical).

package/skills/theme-authoring/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: theme-authoring
+description: Entry point and hub for authoring a refract theme — frame a RawTheme (breakpoints + subsystem keys), then route to the focused domain guides. Use when starting a theme, adding a subsystem, or unsure which guide applies. Triggers: "author a theme", "write a raw theme", "set up refract", "add colors/typography/layout/a recipe", "which refract skill".
+tier: core
+---
+
+# Theme authoring — hub
+
+refract compiles **one `RawTheme`** into a format-neutral `ThemeModel`, then an **adapter**
+lowers that model to a concrete output (CSS variables, SCSS, styled-components modules, JSON).
+You author the `RawTheme`; the adapter and build config decide the output. This guide frames
+the theme and routes to the focused guide for whatever you're actually doing.
+
+**You are authoring input, not changing the engine.** Never edit the core or a subsystem to
+make a theme work — if the theme can't express something, that's a real gap to surface, not a
+patch. Full narrative reference lives in `docs/authoring.md`.
+
+## Frame the theme
+
+- **Type it.** `const raw = { … } satisfies RawTheme`, with
+  `import type { RawTheme } from "@theme-registry/refract/build"`. The `satisfies` gives
+  autocomplete and rejects bogus top-level keys — a red squiggle means the authored shape is
+  wrong; fix the theme, not the types.
+- **Breakpoints first.** `breakpoints: { name: minWidthPx }`. Every responsive override
+  references these names, so settle them before anything else (a `0`-width base is fine).
+  Breakpoints, containers, and the shared responsive/variant/target/modes/states vocabulary
+  are all covered in **theme-foundations** — read it once; the domain guides build on it.
+- **One key per subsystem**, each optional. Each holds properties plus an optional nested
+  `recipes` block:
+
+  | Key | Domain | Guide |
+  |---|---|---|
+  | `colors` | palettes, steps, harmony, modes | **colors** |
+  | `typography` | font families, modular type scale | **typography** |
+  | `layout` | spacing/sizes scales, columns/grids/stacks/container | **layout** |
+  | `effects`, `borders`, `animation` | shadows/transitions/blur, stroke geometry, motion | **visual-effects** |
+  | `components` | cross-subsystem composition (recipes only; `css` is literal-first, `ref()` for tokens) | **recipes-and-composition** |
+  | `globals` | `preset` + themed bare-element rules | this guide (below) |
+
+## Route to the right guide
+
+- **Any recipe, states, `variants`, or `components` composition** → **recipes-and-composition**.
+  Recipes work identically across every subsystem, so that vocabulary lives in one place.
+- **A specific token domain** (palettes, type scale, spacing, effects) → the domain guide above.
+- **Picking or configuring an output format** → **adapter-usage** (which adapter) and
+  **build-config** (`theme.config.ts`, the `refract` CLI, emit modes, dark-mode strategy).
+- **Using the built theme in an app**, or shipping a self-documenting theme package →
+  **consuming-the-output**.
+- **Brand variants / child themes** → **overrides-and-child-themes**.
+- **Importing existing design tokens** (Figma / Tokens Studio / Style Dictionary) →
+  **dtcg-import**.
+
+## Agent tools — MCP, then the static fallback
+
+When a **refract MCP server** is connected (a project can ship one — `@theme-registry/refract-mcp`,
+auto-discovers `theme.config.*`), prefer its **live tools** over guessing. They answer against the
+**real compiled theme**, per configured adapter — so class names carry the real prefix and validation
+runs the real build, not a stand-in:
+
+- `validateTheme(candidate)` — before writing an edit; returns **every** problem at once, per target.
+- `diffTheme(candidate)` — the **blast radius** of an edit *before* you apply it: which tokens moved,
+  which classes changed, which contrast pairings crossed a threshold, which targets stopped building.
+- `getClass` / `renderRecipe` — the real class / emitted CSS for a recipe.
+- `resolveToken` / `searchTokens` / `listTokens` — a token's value + `varName` + `derivedFrom`, or discovery.
+- `checkContrast` — a WCAG-2 audit of the theme's colour pairings.
+- The server also serves the guide as MCP resources: `refract://manifest.json` (schema 1 — real names +
+  DTCG tokens) and `refract://llms.txt`.
+
+**Fallback when no MCP server is connected:** read the emitted **`manifest.json`** / **`llms.txt`** (when
+the build enabled the guide — see **consuming-the-output**), or call the runtime accessors on the built
+theme (`theme.getClass(...)`, `theme.resolveToken(...)`). The MCP tools, the emitted guide, and these
+skills all speak the same **schema 1** contract, so they don't disagree.
+
+## Globals — themed element rules + reset
+
+Bare-element styling lives in the `globals` key (no separate guide). `preset` is the
+normalization base (`"preflight" | "normalize" | "reset" | false`) plus a default `h1`–`h6`
+scale map; `elements` are themed rules — each selector is a recipe-item (flat literal-first leaves,
+`ref()` for tokens, plus `states` / `responsive` / `variants`), no cross-subsystem composition refs. A variant
+is a delta-only modifier the adapters scope higher (CSS `a.subtle`, SC/SCSS nested `&.subtle`).
+There is no `modes` axis — light/dark rides the referenced token's own modes. Unknown refs fail
+loud; preset default headings drop opportunistically.
+
+```ts
+globals: {
+  preset: "preflight",                                   // + default h1–h6 → type scale
+  elements: {
+    a: {
+      color: ref("colors.link"),                         // ref() = token reference
+      textDecoration: "underline",                        // bare string = literal (raw CSS)
+      states: [{ state: "hover", color: ref("colors.link.dark") }],
+      responsive: [{ breakpoint: "md", query: "min", fontSize: ref("typography.fontSize.lg") }],
+      variants: { subtle: { color: ref("colors.muted") } }, // → a.subtle
+    },
+  },
+}
+```
+
+## Verify
+
+- Build once and inspect: `createTheme(raw, { adapter: createCssAdapter() }).css` (plus
+  `.tokens` / `.classes`). See **adapter-usage** for the call surface.
+- Building to disk? Run `refract build` and check the files under each `outDir` — see
+  **build-config**.
+- Typecheck the `satisfies RawTheme`.
+- MCP server connected? Run `validateTheme` (all problems at once) and `diffTheme` (the edit's blast
+  radius) against the real adapters *before* writing — see **Agent tools** above.