@theme-registry/refract 0.1.0

package/skills/theme-foundations/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: theme-foundations
+description: The cross-cutting vocabulary shared by every refract subsystem — breakpoints, containers, the responsive/variant/target/modes/states override axes, and bare-string references. Read once; the domain guides (colors, typography, layout, …) build on it instead of re-explaining. Triggers: "breakpoints", "container queries / container sizes", "responsive override", "variant vs target", "dark mode / modes", "states (hover/disabled)", "how do refs work".
+tier: core
+---
+
+# Theme foundations
+
+Vocabulary reused across every subsystem. Learn it here so the domain guides can stay focused
+on their own tokens. All of this is defined once in the core and validated on every reference.
+
+## Literals vs references — the one rule
+
+Whether a bare string is a token reference or a raw literal depends on the context:
+
+- **Composition fields** — a recipe's cross-subsystem fields (`colors: "solid.brand"`) and a
+  colour recipe's declaration fields (`background: "brand"`, `color: "brand.text"`) — **compose
+  tokens**, so a bare string there is always a **reference** (lowers to `var(--…)`). Paths are
+  dotted and subsystem-scoped (`"colors.link"`); within a subsystem's own recipe the leading
+  segment is implied (`"brand"` inside a colors recipe).
+- **The `css` block** and **`globals` element declarations** are **raw CSS**, so a bare string
+  there is a **literal** (`display: "flex"` just works). Mark the occasional token with the
+  **`ref()`** helper — `color: ref("colors.brand.text")` — or the JSON-safe **`{ ref: "…" }`**
+  object (for a `theme.raw.json`, which can't call a function).
+- A plain **number** is always a literal.
+- **Prefer `ref()` explicitly** when authoring — it makes the intent unmistakable. A `ref()` at a
+  token that doesn't exist fails loud at build; a bare literal is never validated.
+- **Trust boundary:** a literal `css` value passes through to the output **verbatim** (refract
+  validates structure, not the content of raw declarations). Token values are re-serialized to a
+  canonical form, but the `css` block is passthrough — so if you compile an **untrusted** (user- or
+  agent-authored) theme and serve the result, sanitize its literal `css` values first, as you would
+  any untrusted CSS.
+
+## Breakpoints — set them first
+
+Top-level, min-width pixels:
+
+```ts
+breakpoints: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1280 }   // the default set
+```
+
+Every `responsive` entry references these **names**, so settle them before authoring anything
+responsive. Threshold **units** (how `@media` widths render — `px | em | rem`) are a build-time
+concern set on `createTheme({ media })` / the config, not in the raw theme.
+
+## Containers — container queries
+
+Top-level, opt-in. A container defines named sizes that recipe overrides target with
+`{ container, size }` instead of `{ breakpoint }`:
+
+```ts
+containers: {
+  card: { type: "inline-size", sizes: { sm: 320, md: 480 } },
+}
+```
+
+Use breakpoints for viewport-relative variation and containers for component-relative variation.
+
+## The override axes
+
+Both **properties** and **recipes** carry a `responsive: [...]` list. Each entry combines a
+condition with a change:
+
+- **Condition:** `breakpoint` (+ `query: "min" | "max" | "exact"`, default `min`),
+  `orientation`, or `container` + `size`.
+- **Change (pick one):**
+  - a plain new value for the property/field;
+  - `variant: X` — reassign the base to reference sibling variant `X`;
+  - `target: X, …` — override variant `X`'s value specifically (not the base).
+
+```ts
+responsive: [
+  { breakpoint: "md", query: "min", fontSize: "typography.fontSize.lg" },  // plain
+  { breakpoint: "sm", query: "max", variant: "compact" },                  // swap base → compact
+  { breakpoint: "lg", target: "wide", padding: "layout.spacing.xl" },      // scope to variant "wide"
+]
+```
+
+**variant vs target:** `variant` *swaps which variant the base points at*; `target` *edits one
+named variant*. A recipe's `variants` map (see **recipes-and-composition**) desugars each variant
+into a flat sibling, so `variant:` / `target:` references resolve against those siblings.
+
+## modes — light/dark appearance
+
+Two things share the name. A top-level **`modes` registry** declares which appearance modes exist
+(`modes: ["dark", "light"]` — the default; declare more to use a custom mode like `hc`). And a
+per-property **`modes` axis** (chiefly on colors) is a **LIST of override entries**, each
+`{ mode, target?, …value }`: `mode` is the WHEN (validated against the registry), the optional
+`target` scopes into a variant's var, and the value is a literal or a `{ ref?, modifiers }`
+derivation. Adapters realize modes as conditional blocks (`prefers-color-scheme` media,
+`[data-theme]` attribute, or both).
+
+```ts
+modes: ["dark", "light"],                                   // top-level registry (optional; this is the default)
+colors: {
+  surface: {
+    base: "#fff",
+    modes: [
+      { mode: "dark", base: "#111" },                       // a literal mode override
+      { mode: "dark", modifiers: [{ darken: 10 }] },        // …or a derivation off the own base
+    ],
+  },
+}
+```
+
+Because dark rides the **referenced token**, anything that refs `colors.surface` flips for free —
+so `globals` element rules and recipes never need their own `modes` axis.
+
+## states — recipe conditions
+
+`states` is a **recipe-only** axis (hover, focus, disabled, …), a **LIST of override entries**,
+each `{ state, target?, …deltas }`. The **allowed set is owned by the adapter** — an unknown state
+throws at build. `state` is the WHEN; the optional `target` scopes the override onto a recipe
+variant's sibling (`<item>-<variant>`), so two same-state entries can behave differently per
+variant.
+
+```ts
+states: [
+  { state: "hover", background: "brand.dark" },
+  { state: "disabled", opacity: 0.5 },
+  { state: "hover", target: "lg", background: "brand" },    // a hover just for the `lg` variant sibling
+]
+```
+
+modes / states / responsive are all **arrays of overrides over one spine** — WHEN
+(`mode`/`state`/`breakpoint`) · WHERE (`target`) · WHAT (the value/deltas). See
+**recipes-and-composition** for how states compose with variants and responsive entries.

package/skills/troubleshooting/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: troubleshooting
+description: Diagnose refract build errors — map createTheme's validation messages (unknown token/breakpoint/variant/state, cyclic or duplicate recipes, mode overrides nothing) to their cause and fix. Use when createTheme or refract build throws. Triggers: "createTheme throws", "references unknown token/breakpoint/variant", "state not allowed", "cyclic recipe", "duplicate recipe name", "overrides nothing".
+tier: optional
+---
+
+# Troubleshooting
+
+refract validates the theme up front and throws a message that **names the offending reference**.
+Read the quoted name first — it points straight at the authoring mistake. Common errors and fixes:
+
+Every authoring/build error is a **`RefractError`** with a stable machine `code` (`err.code`, e.g.
+`REFRACT_E_COLOR_INPUT`, `REFRACT_E_STEPS`, `REFRACT_E_NAMING`) you can branch on without matching the
+message text. Post-build reference validation **collects all failures** and throws them at once as
+`REFRACT_E_VALIDATION` — `err.failures` is the array of every bad reference, so fix them in one pass:
+
+```ts
+import { RefractError } from "@theme-registry/refract";
+try { createTheme(raw, { adapter }); }
+catch (e) {
+  if (e instanceof RefractError && e.code === "REFRACT_E_VALIDATION") console.error(e.failures);
+}
+```
+
+## `references unknown token '<ref>'`
+
+> `components.<group>.<variant>: css '<prop>' references unknown token '<ref>' — check the token path, or use a bare string / number for a raw CSS value`
+> `globals element '<sel>': '<prop>' references unknown token '<ref>' — …`
+
+A `ref("…")` (or `{ ref: "…" }`) pointed at a token that doesn't exist. **Fix the path** — e.g.
+`ref("colors.link")`, `ref("typography.fontSize.lg")`. (A raw CSS value doesn't need a ref at all
+— inside a `css` block a bare string is already a literal: `cursor: "pointer"`.) See the
+literals-vs-references rule in **theme-foundations**.
+
+## `references unknown breakpoint "<name>"`
+
+> `Responsive entry … references unknown breakpoint "<name>".`
+> `Responsive entry … is missing a "breakpoint" value.`
+
+A `responsive` entry names a breakpoint not in the top-level `breakpoints` map (or omits one).
+Add the breakpoint, or fix the name. Set `breakpoints` first — see **theme-foundations**.
+
+## `references unknown variant "<name>"` / `unknown target "<name>"`
+
+A `variant:` / `target:` in a responsive entry points at a variant that doesn't exist on that
+property/recipe. Define the variant, or fix the reference. Remember a recipe's `variants` map
+desugars to siblings that `variant:`/`target:` can then reach — see **recipes-and-composition**.
+
+## `references unknown state "<name>"`
+
+> `Responsive recipe entry … references unknown state "<name>".`
+
+The state isn't in the **adapter's** allowed set. Use a state the adapter supports (CSS knows
+`hover`/`focus`/`disabled`/…), or choose an adapter that renders it. States are adapter-owned, not
+authored — see **theme-foundations** → states.
+
+## `Unknown recipe property "<prop>" in <path>`
+
+> `Unknown recipe property "<prop>" in <path> — expected a CSS property or a reserved key (variant, target, state, breakpoint, query, orientation, container, size).`
+
+A declaration key that's neither a real CSS property nor a reserved recipe key — almost always a
+typo: `ref:` where you meant a `variant:` swap, or `colr:` for `color:`. refract rejects it so it
+can't ship as a stray literal declaration. Use the CSS property, or the reserved key you meant.
+
+## `Recipe variant "<name>" is not defined` / `Cyclic recipe reference`
+
+> `Recipe variant "<name>" is not defined in "<group>".`
+> `Cyclic recipe reference in "<group>": <cycle>`
+
+A recipe references a sibling that doesn't exist, or two recipes reference each other in a loop.
+Fix the composition graph so references point at real, acyclic recipes.
+
+## `produced a duplicate recipe name "<name>"`
+
+> `Recipe variant expansion … produced a duplicate recipe name "<name>" — a desugared "<recipe>-<variant>" collides with an existing sibling recipe.`
+
+A `variants` entry desugars to `<recipe>-<variant>`, which collides with a hand-authored sibling.
+Rename the variant or the sibling recipe.
+
+## `Appearance mode "<path>" overrides nothing` / `Unable to resolve base value`
+
+> `Appearance mode "<path>" overrides nothing.`
+> `Unable to resolve base value…`
+
+A `modes` block redefines a field the property never had, or a property has no resolvable base
+value. Give the property a real base, and make each mode redefine an existing field — see
+**theme-foundations** → modes.
+
+## General
+
+- The message's quoted path is the location — start there, fix the *theme*, never the engine.
+- If the shape itself is wrong, the `satisfies RawTheme` typecheck usually catches it before
+  runtime — check the red squiggle first.
+- **Validate against the real adapters.** With an MCP server connected, `validateTheme(candidate)`
+  builds the edit against every configured target and returns **all** problems at once (per target) —
+  it catches adapter-level rules (unknown state, naming collision) a bare core build misses. See
+  **theme-authoring → Agent tools**.

package/skills/typography/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: typography
+description: Author the `typography` slice of a refract theme — the open map of type properties (font families, weights, line-height, letter-spacing, text props) and the `fontSize` modular scale synthesized from a base + named ratio. Use when writing or tuning the type domain. Triggers: "type scale", "modular scale / ratio", "font sizes", "fontFamily / fontWeight / lineHeight", "typography recipe".
+tier: core
+---
+
+# Typography
+
+The `typography` key is an **open** map: each key is a type property holding a value, plus the
+reserved `recipes` block. Cross-cutting axes (`responsive`, `variants`, refs) are in
+**theme-foundations**; recipe mechanics are in **recipes-and-composition**. Exhaustive options live
+in `docs/authoring.md`.
+
+## Type properties
+
+Properties are heterogeneous — a value is `string | number`, or an extended `{ base, … }`:
+
+```ts
+typography: {
+  fontFamily: { base: "Inter, sans-serif", variants: { mono: "ui-monospace, monospace" } },
+  fontWeight: { base: 400, variants: { medium: 500, bold: 700 } },
+  lineHeight: { base: 1.5, variants: { tight: 1.25 } },
+  letterSpacing: { base: "0", variants: { wide: "0.05em" } },
+  // text props also live here: fontStyle, textTransform, textDecoration, textAlign
+}
+```
+
+Each `variants` entry is named and referenced elsewhere by bare name (see **recipes-and-composition**).
+
+## fontSize — the modular scale
+
+Give `fontSize` a `base` plus a named `ratio` and refract synthesizes the scale steps as variants —
+each `base × ratio^step`, rounded to `precision`:
+
+```ts
+fontSize: {
+  base: 16,
+  ratio: "minor-third",   // one of the named ratios below
+  precision: 4,           // decimal places (default 4)
+  baseFontSize: 16,        // scale origin if it differs from `base` (defaults to `base`)
+  unit: "rem",             // "px" | "rem"
+}
+```
+
+Generated step keys and their exponents: `xs` (−2), `sm` (−1), `md` (0), `lg` (1), `xl` (2), `2xl`
+(3), `3xl` (4), `4xl` (5). Named ratios:
+
+| Name | Factor | | Name | Factor |
+|---|---|---|---|---|
+| `minor-second` | 1.067 | | `augmented-fourth` | 1.414 |
+| `major-second` | 1.125 | | `perfect-fifth` | 1.5 |
+| `minor-third` | 1.2 | | `golden` | 1.618 |
+| `major-third` | 1.25 | | | |
+| `perfect-fourth` | 1.333 | | | |
+
+Without a (recognized) `ratio`, `fontSize` passes through untouched. Author-declared `variants` win
+over synthesized steps and **seed the chain** — a hand-pinned step becomes the origin the next
+generated step compounds from.
+
+## recipes — typography recipes
+
+The reserved `recipes` block declares typographic properties (`fontFamily`, `fontSize`, `fontWeight`,
+`lineHeight`, `letterSpacing`, `fontStyle`, `textTransform`, `textDecoration`, `textAlign`, plus any
+extra passed through). Each value names a **variant** of the matching property (`fontSize: "3xl"`,
+`fontWeight: "bold"`, or `"base"` for the base value). Recipe structure (states, responsive,
+composition) is in **recipes-and-composition**.

package/skills/visual-effects/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: visual-effects
+description: Author the three visual-effect slices of a refract theme — `effects` (shadows, transitions, blur, opacity, z-index), `borders` (stroke geometry: width/style/offset/radius), and `animation` (motion tokens + keyframes + animation-shorthand recipes). Use when writing shadows, transitions, strokes, or motion. Triggers: "box shadow", "transition tokens", "border / outline / radius", "keyframes", "animation recipe", "blur / opacity / z-index".
+tier: core
+---
+
+# Visual effects — effects · borders · animation
+
+Three sibling subsystems, each with its own top-level key. Cross-cutting axes (`responsive`,
+`variants`, `modes`, refs) are in **theme-foundations**; recipe mechanics in
+**recipes-and-composition**. Exhaustive options live in `docs/authoring.md`.
+
+## effects
+
+Open map. `shadow` and `transitions` are **structured object-leaf** properties — format-neutral flat
+leaves, never raw CSS. `blur` / `opacity` / `zIndex` are plain scalars.
+
+The flat leaf fields sit at the property top level and **are** the (single-layer) base — there is
+**no `base` key**. A `variants` entry — and the value of each `modes` / `responsive` entry (both are
+lists of `{ mode|breakpoint, …leaf }`, per **theme-foundations**) — is a full leaf value, or an
+**array** of leaves for a multi-layer value. The keyword `"none"` means no shadow / no transition.
+**Raw CSS strings are rejected** (only `"none"` is accepted).
+
+```ts
+effects: {
+  shadow: {
+    offsetY: 2, blur: 8, color: "colors.shadow",     // top-level leaf = the base
+    variants: {
+      lg: [                                            // array = multi-layer
+        { offsetY: 4, blur: 12, color: "colors.shadow" },
+        { offsetY: 1, blur: 3,  color: "colors.shadow.a20" },
+      ],
+      none: "none",
+    },
+  },
+  transitions: { property: "opacity", duration: 200, timingFunction: "ease-out", delay: 0 },
+  blur: 8, opacity: 1, zIndex: 10,
+}
+```
+
+Shadow leaf fields: `offsetX`, `offsetY`, `blur`, `spread` (a bare number is a **deferred** length
+resolved by the unit pass; a `"1px"` / `"0.5rem"` string is **pinned**), `color` (a `colors.*`
+**ref** — translucency comes from an `alpha` colour variant, e.g. `colors.shadow.a20`, never a shadow
+field), and `inset` (boolean). Transition part fields: `property` (**required**), `duration` (ms),
+`timingFunction` (keyword or `cubic-bezier(...)`), `delay` (ms).
+
+Reserved `recipes` (EffectsRecipeProps): `boxShadow` (→ `shadow`), `transition` (→ `transitions`),
+`blur` (lowers to `filter: blur(var(--…))`), `opacity`, `zIndex` — each naming a variant.
+
+## borders
+
+Open map of **stroke geometry only** — colour is never a borders token. Properties: `width` (px
+number), `style` (string), `offset` (px number, outline only), `radius` (px number, or a string like
+`"9999px"`).
+
+```ts
+borders: {
+  width:  { base: 1, variants: { thick: 2 } },
+  style:  { base: "solid", variants: { dashed: "dashed" } },
+  radius: { base: 4, variants: { pill: "9999px" } },
+  offset: { base: 2 },
+}
+```
+
+Reserved `recipes` (BordersRecipeProps): `as` (`"border"` default | `"outline"`) and `side`
+(`top`/`right`/`bottom`/`left`, border only) are **modifiers** that route each aspect to its
+longhand. The geometry aspects `width` / `style` / `offset` / `radius` name a **variant** of the
+matching property by bare name (`"thick"` → `borders.width.thick`). `color` is a **value-level
+`colors.*` ref** (`"colors.primary"`), never a borders token.
+
+## animation
+
+Motion tokens `duration` (ms number) / `easing` (string) / `delay` (ms number) are regular
+properties (base + variants). The reserved `keyframes` key holds named definitions; `recipes`
+composes them into an `animation:` shorthand.
+
+```ts
+animation: {
+  duration: { base: 200, variants: { fast: 120, slow: 400 } },
+  easing:   { base: "ease-out", variants: { spring: "cubic-bezier(.5,1.5,.5,1)" } },
+  keyframes: {
+    fadeInUp: {
+      from: { opacity: 0, transform: "translateY(20px)" },   // literal or { ref: "colors.surface" }
+      to:   { opacity: 1, transform: "translateY(0)" },
+    },
+  },
+}
+```
+
+A keyframe definition maps a step selector (`from` / `to` / `"0%"` / `"50%"` / grouped `"0%, 100%"`)
+to declarations — kebab-case CSS property → a **literal** value or a **`{ ref }`** (resolved late so a
+keyframe can animate a themed value). Authoring order is preserved.
+
+Reserved `recipes` (AnimationRecipeProps): `keyframes` names a keyframe; `duration` / `easing` /
+`delay` name a **variant** of the matching motion token; `iterationCount` / `direction` / `fillMode`
+/ `playState` pass through — all composed into one `animation:` shorthand.