@theme-registry/refract 0.1.0

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

@@ -0,0 +1,98 @@
+import type { DerivationModifier, ExternalProperty, ModeOverride, NormalizedPropertyValue, RecipeBlock, ResponsiveOverride } from "../../core/normalize";
+import type { RGBTuple } from "./utils";
+export type { AdjustDials } from "./utils";
+/**
+ * A colour's authored **base** value — a hex string (`"#4dabf7"` / `"#4af"`), an `[r, g, b]` tuple
+ * (0–255), or any CSS colour string: `oklch()`, `hsl()/hsla()`, `rgb()/rgba()`, or a named keyword
+ * (`"rebeccapurple"`). All are normalized to the canonical `rgb()` form at build (derivation runs in
+ * OKLCH). A `var(--…)` is **rejected** — it can't be tonally derived at build time; borrow an external
+ * token instead (`{ external: … }`). Tuple/keyword/function forms are coerced at normalize time.
+ */
+export type ColorInput = string | RGBTuple;
+/**
+ * A **derivation spec** variant (§13.3, §20.4, dec.2) — a named variant derived from a source colour
+ * by an ordered `modifiers` chain of single-key `{ [fn]: args }` dials (`darken`/`lighten`/`alpha`/
+ * `adjust`/`setL`/`rotateHue`): `value = modifiers.reduce((v, {fn,arg}) => fn(v, arg), resolve(ref))`.
+ * `ref` names the source token (defaults to the property's own base; may point to another variant/step).
+ * `darken`/`lighten` shift OKLCH lightness by N points (alpha preserved); `alpha` sets absolute opacity
+ * (`{ alpha: 40 }` ⇒ 40% opaque); `adjust` places an absolute lightness and/or scales chroma and/or
+ * rotates hue in one shot (see {@link AdjustDials}).
+ */
+export type PaletteDerivationSpec = {
+    ref?: string;
+    modifiers: DerivationModifier[];
+};
+/**
+ * A built-in colour-harmony scheme — rotations of the base's hue around the perceptual wheel, each
+ * generated variant holding the base's lightness and chroma (only the hue turns).
+ */
+export type HarmonyScheme = "complement" | "analogous" | "split-complement" | "triadic" | "tetradic";
+/**
+ * The palette-level `harmony` option (§20.5). The **string** form uses each scheme's default member
+ * names (`"triadic"` → `triadic1` / `triadic2`); the **object** form renames them positionally
+ * (`{ triadic: ["mint", "coral"] }` → `mint` / `coral`). Exactly one scheme per colour.
+ */
+export type HarmonyOption = HarmonyScheme | Partial<Record<HarmonyScheme, string[]>>;
+/**
+ * One authored variant value — a literal colour, a {@link PaletteDerivationSpec}, or the extended
+ * `{ base, …extra }` form (for literal variants carrying siblings like `text`).
+ */
+export type PaletteVariantInput = ColorInput | PaletteDerivationSpec | ({
+    base: ColorInput;
+} & Record<string, unknown>);
+/**
+ * Colors' property extras — the palette-synthesis config that rides alongside a colour value.
+ * `steps` is **numeric only** and defines an absolute OKLCH lightness ladder (§20.2): each
+ * Tailwind-style label maps to a fixed lightness via `L = (1000 − label) / 10` (low = light, high =
+ * dark), so the same label reads at the same lightness across every palette. Named tonal variants
+ * (`light`/`lighter`/`dark`/`darker`) are auto-generated when no `steps` are declared; they stay
+ * relative, compounding `lightenBy`/`darkenBy` as OKLCH ΔL points (which do NOT apply to numeric
+ * steps). (`variants` is NOT here — it's a first-class key on {@link PaletteExtendedProperty},
+ * widened to accept derivation specs.)
+ */
+export type PalettePropertyExtras = {
+    text?: ColorInput;
+    steps?: number[];
+    lightenBy?: number;
+    darkenBy?: number;
+    harmony?: HarmonyOption;
+};
+/**
+ * Colors' extended-property authoring shape — mirrors core's `ExtendedProperty` but with a
+ * {@link ColorInput} base (hex string or `[r,g,b]` tuple) and a `variants` map widened to accept
+ * {@link PaletteVariantInput} (literal colours, derivation specs, or extended literals). Coerced to
+ * the canonical core shape (`base: string`) at normalize time.
+ */
+export type PaletteExtendedProperty = {
+    base: ColorInput;
+    responsive?: ResponsiveOverride<ColorInput, PalettePropertyExtras>[];
+    variants?: Record<string, PaletteVariantInput>;
+    modes?: ModeOverride<ColorInput, PalettePropertyExtras>[];
+} & PalettePropertyExtras;
+export type PalettePropertyValue = ColorInput | PaletteExtendedProperty | ExternalProperty;
+export type NormalizedPaletteValue = NormalizedPropertyValue<string, PalettePropertyExtras>;
+/**
+ * The palette recipe declaration shape — colour-bearing CSS properties whose values
+ * name a palette reference (`"primary"`, `"primary.text"`, `"neutral.light"`) or a
+ * literal. Any additional style property is allowed (passed through as a literal).
+ */
+export type PaletteRecipeValue = string | number;
+export type PaletteRecipeProps = {
+    background?: PaletteRecipeValue;
+    backgroundColor?: PaletteRecipeValue;
+    color?: PaletteRecipeValue;
+    borderColor?: PaletteRecipeValue;
+    outlineColor?: PaletteRecipeValue;
+    [property: string]: PaletteRecipeValue | undefined;
+};
+/**
+ * The authored `raw.colors` slice (§8a). An **open** map: keys are arbitrary palette names
+ * (`primary`, `neutral`, …), each a {@link PalettePropertyValue} — a bare hex/ref string, an
+ * `[r,g,b]` tuple, or a full `ExtendedProperty` with `text` / `steps` / `variants` / `responsive`.
+ * The reserved `recipes` key is a {@link RecipeBlock} of palette recipes. Authoring type only —
+ * the spine still consumes the slice as `Record<string, unknown>`.
+ */
+export interface ColorsRaw {
+    recipes?: RecipeBlock<PaletteRecipeProps>;
+    [palette: string]: PalettePropertyValue | RecipeBlock<PaletteRecipeProps> | undefined;
+}

package/dist/subsystems/colors/utils.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure colour math for palette step + variant synthesis.
+ *
+ * Lightness / hue / chroma work runs in **OKLCH** (a perceptual space) via Björn Ottosson's
+ * public-domain matrices — parse → sRGB → linear → OKLab → OKLCH → apply → gamut-map → linear →
+ * sRGB → quantize → serialize — so equal lightness steps look even and one lightness reads the same
+ * across hues. hex / `rgba()` strings are only touched at the boundary (`parseColor` in,
+ * `serializeColor` out). `lighten` / `darken` shift OKLCH lightness by ΔL points; `setL` places an
+ * absolute lightness; `rotateHue` / `complement` turn the hue; `alpha` sets opacity. All are
+ * string-in / string-out so the same fns run at normalize time (baking the cached value) and later
+ * in the derivation registry — AND are vendored to consumers (see `build/vendor.ts`) so a value
+ * computed live in the app matches the emitted CSS variable. Kept dependency-free for that vendoring.
+ */
+/** An `[r, g, b]` channel triple, each `0–255`. */
+export type RGBTuple = readonly [number, number, number];
+/** An `[r, g, b, a]` quad — channels `0–255`, alpha `0–1`. */
+export type RGBATuple = readonly [number, number, number, number];
+/** A colour authored/worked as a tuple — opaque `[r,g,b]` or translucent `[r,g,b,a]`. */
+export type ColorTuple = RGBTuple | RGBATuple;
+/** Parse a 3- or 6-digit hex string (with or without `#`) into an `[r, g, b]` tuple. */
+export declare const convertHexToRGB: (hex: string) => RGBTuple;
+/** Serialize an `[r, g, b]` tuple back to a `#rrggbb` string, clamping each channel to `0–255`. */
+export declare const convertRgbToHex: (rgb: RGBTuple) => string;
+/**
+ * Parse any canonical colour string this subsystem produces — a 3/6-digit hex **or** an
+ * `rgb()` / `rgba()` string — into `{ rgb, a }` (alpha defaults to `1`). This is the boundary
+ * gate; a value that isn't parseable rgb (e.g. a bare CSS keyword or `var(--…)`) throws, so
+ * callers can surface a friendly "this colour can't be derived from" error.
+ */
+export declare const parseColor: (value: string) => {
+    rgb: RGBTuple;
+    a: number;
+};
+/**
+ * Serialize `[r, g, b]` (+ optional alpha) to the canonical CSS string — always `rgb(r, g, b)`
+ * when fully opaque, else `rgba(r, g, b, a)`. The single serialization point for the subsystem, so
+ * the Model (and every adapter + `resolveToken`) always carries one canonical `rgb()/rgba()` form
+ * per colour — never hex. (`convertRgbToHex` remains for the vendored consumer helper + input parsing.)
+ */
+export declare const serializeColor: (rgb: RGBTuple, a?: number) => string;
+/** Whether a string is a 3- or 6-digit `#`-prefixed hex colour. */
+export declare const isHexColor: (value: string) => boolean;
+/** An OKLCH colour — perceptual lightness `L` (0–100), chroma `C` (≥ 0), hue `h` (degrees, 0–360). */
+export type OKLCH = {
+    L: number;
+    C: number;
+    h: number;
+};
+/** Convert an sRGB `[r, g, b]` (0–255) triple to OKLCH (`L` on a 0–100 scale). */
+export declare const rgbToOklch: (rgb: RGBTuple) => OKLCH;
+/**
+ * Convert OKLCH back to an sRGB `[r, g, b]` triple (**unquantized** 0–255 floats). Holds `L` and
+ * `h`; when the requested chroma is outside sRGB it binary-searches `C` downward — fixed iterations,
+ * no data-dependent early exit, so build- and runtime-computed values agree (§20.8) — until the
+ * linear result is in `[0, 1]`. Lightness and hue are never adjusted, so a synthesized ramp keeps
+ * its hue and even lightness spacing; only saturation gives way at the gamut boundary. The floats
+ * are quantized exactly once, later, by `serializeColor`, so the 0–255 channel clamp never fires.
+ */
+export declare const oklchToRgb: (color: OKLCH) => RGBTuple;
+/** Lighten a colour by `delta` OKLCH lightness points (0–100 scale); hue, chroma, alpha preserved. */
+export declare const lighten: (value: string, delta: number) => string;
+/** Darken a colour by `delta` OKLCH lightness points (0–100 scale); hue, chroma, alpha preserved. */
+export declare const darken: (value: string, delta: number) => string;
+/** Set a colour's absolute OKLCH lightness to `L` (0–100); hue, chroma, alpha preserved. */
+export declare const setL: (value: string, L: number) => string;
+/** Rotate a colour's OKLCH hue by `deg` (signed) around the perceptual wheel; L, C, alpha preserved. */
+export declare const rotateHue: (value: string, deg: number) => string;
+/** The perceptual complement — a 180° hue rotation at the same lightness and chroma. */
+export declare const complement: (value: string) => string;
+/**
+ * An `adjust` dial set — any subset. `l` = **absolute** OKLCH lightness target (0–100, raw L, the
+ * opposite direction from a numeric-`steps` label); `c` = chroma **multiplier** (`1` keep, `0` grey,
+ * `>1` more saturated where the gamut allows); `h` = **signed** hue rotation in degrees. Numbers
+ * only — keeps the vendored math string-free.
+ */
+export type AdjustDials = {
+    l?: number;
+    c?: number;
+    h?: number;
+};
+/**
+ * One-shot OKLCH placement — set an absolute lightness, scale chroma, and/or rotate hue in a single
+ * derivation (each dial optional; an omitted dial leaves that component untouched). Alpha preserved.
+ */
+export declare const adjust: (value: string, dials: AdjustDials) => string;
+/**
+ * Convert any canonical colour string (the subsystem's `rgb()` / `rgba()` form, or a hex string)
+ * to hex — 6-digit `#rrggbb` when opaque, 8-digit `#rrggbbaa` when translucent. Used by the DTCG
+ * exporter, whose `color` token type is conventionally hex (every other output stays `rgb()`).
+ */
+export declare const toHexColor: (value: string) => string;
+/**
+ * Convert any canonical colour string (the subsystem's `rgb()` / `rgba()` form, or a hex string) to
+ * a CSS Color 4 `oklch(L% C H)` string — `oklch(L% C H / a)` when translucent. `L` is a percentage
+ * (0–100), `C` the absolute chroma, `H` in degrees, derived from the stored (quantized) rgb. Used by
+ * the CSS adapter's `colorFormat: "oklch"` output; the colour is identical to the `rgb()` form.
+ */
+export declare const toOklchColor: (value: string) => string;
+/**
+ * Set a colour's opacity to `percent` (0–100) — an **absolute** alpha, not a relative fade
+ * (`alpha(x, 40)` ⇒ 40% opaque). The rgb channels are untouched; only the alpha channel is
+ * replaced. Result serializes to `rgba(…)` (or hex when `percent` is 100).
+ */
+export declare const alpha: (value: string, percent: number) => string;

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

@@ -0,0 +1,13 @@
+/**
+ * The components (composition) subsystem.
+ *
+ * Owns **no primitive properties** (the property pipeline never runs — `normalizeProperties`
+ * returns empty). It contributes only recipes that reference other subsystems' recipes plus an
+ * own `css` delta. The generic recipe path drives `interpretRecipe` (own delta → refs) and, via
+ * the `extractReferences` hook, keeps each variant's cross-subsystem references as Model pointers
+ * (`"colors:solid.primary"`) so the referenced recipe's states ride along on its shared class.
+ * It grows a hook, never the spine.
+ */
+import type { Subsystem } from "../../core/subsystem";
+export declare const componentsSubsystem: Subsystem;
+export type { ComponentsRecipeProps, ResolvedComponentClass, ComponentsRaw } from "./types";

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

@@ -0,0 +1,22 @@
+/**
+ * Components' `interpretRecipe` hook — the composition interpreter.
+ *
+ * A component variant carries cross-subsystem references (`colors: "solid.primary"`) that are
+ * NOT declarations (they're extracted separately as Model `references` pointers) plus an own
+ * `css` delta. This interpreter emits ONLY the own-delta declarations, each a format-neutral
+ * {@link Ref}. The delta is **literal-first**: a bare string / number value is a raw CSS literal
+ * → `{ value }`; a `ref("…")` / `{ ref: "…" }` marker is a token path → `{ ref }` (the adapter lowers
+ * it to `var(--…)` against the global token union). The
+ * referenced recipes' own states ride along on their shared classes (via the `references`
+ * pointers), so the component only emits its own delta + own states — which win at equal
+ * specificity by later source order.
+ */
+import type { InterpretedRecipeVariant } from "../../core/model";
+import type { NormalizedRecipeVariant } from "../../core/normalize";
+import type { RecipeInterpretContext } from "../../core/subsystem";
+import type { ComponentsRecipeProps } from "./types";
+/**
+ * Interpret one component variant into base + state/responsive override declarations from its
+ * `css` delta. Cross-subsystem references are handled by `extractComponentReferences`, not here.
+ */
+export declare const interpretComponentsRecipeVariant: (_variantName: string, variant: NormalizedRecipeVariant<ComponentsRecipeProps, string>, _ctx: RecipeInterpretContext) => InterpretedRecipeVariant<string>;

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

@@ -0,0 +1,46 @@
+/**
+ * Components (composition) subsystem types.
+ *
+ * A component recipe variant references other subsystems' recipes (`colors: "solid.primary"`,
+ * `layout: "padding.button-lg"`, …) and may add its own `css` delta (+ grouped `states` /
+ * `responsive`). It owns **no primitive properties** — the property pipeline never runs for it.
+ */
+import type { RecipeBlock } from "../../core/normalize";
+/**
+ * One value in a component `css` delta. **Literal-first**: a bare `string` is a raw CSS value
+ * (`display: "flex"`), a `number` is a literal, and a token **reference** uses `ref("colors.on-primary")`
+ * (the {@link ref} helper) or the JSON-safe object form `{ ref: "colors.on-primary" }` → `var(--…)`.
+ * (This differs from the sibling composition fields — `colors: "solid.primary"` — where a bare string is
+ * always a reference: those compose tokens, the `css` block is raw CSS.)
+ */
+export type CssDeltaValue = string | number | {
+    ref: string;
+};
+/** One component recipe variant: cross-subsystem references + an own `css` delta. */
+export type ComponentsRecipeProps = {
+    colors?: string;
+    typography?: string;
+    layout?: string;
+    effects?: string;
+    borders?: string;
+    css?: Record<string, CssDeltaValue>;
+    [subsystem: string]: string | Record<string, CssDeltaValue> | undefined;
+};
+/**
+ * The authored `raw.components` slice (§8a). **Closed** and recipes-only — components own no
+ * primitive properties (the property pipeline never runs); they contribute only composition
+ * recipes referencing other subsystems' recipes plus an own `css` delta. Authoring type only.
+ */
+export interface ComponentsRaw {
+    recipes?: RecipeBlock<ComponentsRecipeProps>;
+}
+/**
+ * The resolved class surface for one component variant — the referenced recipe classes (which
+ * carry their own `:hover` etc. on the shared class) followed by the component's own delta class.
+ * `className` is the space-joined list. Mirrors the OLD `ResolvedComponentClass` shape (`classes`
+ * renamed `classList`).
+ */
+export type ResolvedComponentClass = {
+    className: string;
+    classList: string[];
+};

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

@@ -0,0 +1,9 @@
+/**
+ * The effects subsystem — a "regular" subsystem with no property finalize hook (values
+ * pass straight through the shared normalize). Iterates `raw.effects` (skipping the
+ * reserved `recipes` key) and interprets recipes into token-path refs (incl. the `blur`
+ * compound as a `{ ref, wrap: "blur" }` ref). It grows a hook, never the spine.
+ */
+import type { Subsystem } from "../../core/subsystem";
+export declare const effectsSubsystem: Subsystem;
+export type { EffectsRaw, EffectsPropertyValue } from "./types";

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

@@ -0,0 +1,24 @@
+/**
+ * Effects' `interpretRecipe` hook — resolves recipe declarations to token-path Refs.
+ *
+ * An effects recipe prop names a **variant** of the matching property, but the recipe key
+ * differs from the token key (`boxShadow` → `shadow`, `transition` → `transitions`) — the
+ * resolve-key map bridges them. Each declaration lowers to a format-neutral {@link Ref}
+ * carrying the canonical token path (`effects.shadow.lg`, `effects.shadow` for the base) —
+ * **no `var(--…)` strings**; the CSS adapter maps the path to a `var(--…)` at render time.
+ *
+ * The `blur` compound is the notable reshape: the old `effects/recipes.ts` baked
+ * `filter: blur(var(--…))` as a `{ value }` literal that **embedded** `var()` — not format-
+ * neutral. Here it emits `{ ref: "effects.blur", wrap: "blur" }`; the adapter's `refToStyleValue`
+ * renders `ref.wrap` → `blur(var(--…))`, so the wrap lives in the adapter, not the Model.
+ */
+import type { InterpretedRecipeVariant } from "../../core/model";
+import type { NormalizedRecipeVariant } from "../../core/normalize";
+import type { RecipeInterpretContext } from "../../core/subsystem";
+import type { EffectsRecipeProps } from "./types";
+/**
+ * Interpret one effects 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 interpretEffectsRecipeVariant: (variantName: string, variant: NormalizedRecipeVariant<EffectsRecipeProps, string>, ctx: RecipeInterpretContext) => InterpretedRecipeVariant<string>;

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

@@ -0,0 +1,63 @@
+import type { PropertyValue, RecipeBlock } from "../../core/normalize";
+import type { ShadowInput, ShadowLayerInput, TransitionInput, TransitionPartInput } from "./utils";
+/**
+ * Effects' property + recipe types. A "regular" subsystem — plain property values
+ * (no palette-style synthesis). Ported from the old `subsystems/effects/types.ts`,
+ * trimmed to the normalize / recipe surface the clean-room pipeline needs.
+ */
+/**
+ * A structured object-leaf property (§15, structured-only per the 2026-07-16 amendment). The FLAT
+ * authoring shape: the leaf fields (`TLeaf`) sit at the property top level and ARE the (single-layer)
+ * base; `variants` / `responsive` / `modes` hold full leaf values (`TInput` = a flat leaf, an array
+ * of leaves for a multi-layer variant/mode, or the `"none"` keyword). **No `base` key** — the base is
+ * the top-level leaves (or `"none"` when none are authored); there is no multi-layer BASE. A bare
+ * `"none"` is also accepted (no shadow / no transition at all). Raw CSS strings are rejected at coerce.
+ */
+export type StructuredProperty<TInput, TLeaf> = "none" | (TLeaf & {
+    variants?: Record<string, TInput>;
+    responsive?: Array<{
+        breakpoint: string;
+        query?: "min" | "max" | "exact";
+        variant?: string;
+        target?: string;
+        orientation?: "landscape" | "portrait";
+    } & TLeaf>;
+    modes?: Record<string, TInput>;
+});
+/** Authored box-shadow property (§15) — structured single-layer base + structured variants/modes. */
+export type ShadowValue = StructuredProperty<ShadowInput, ShadowLayerInput>;
+/** Authored transition property (§15) — structured single-part base + structured variants/modes. */
+export type TransitionValue = StructuredProperty<TransitionInput, TransitionPartInput>;
+export type BlurValue = PropertyValue<number | string>;
+export type ZIndexValue = PropertyValue<number>;
+export type OpacityValue = PropertyValue<number>;
+/**
+ * An effects recipe declaration block. Each value names a **variant** of the matching
+ * effects property; the recipe prop key differs from the token key (`boxShadow` → `shadow`,
+ * `transition` → `transitions`) — the interpreter maps it via its resolve-key map. `blur` is
+ * a compound: it lowers to `filter: blur(var(--…))` via a `{ ref, wrap: "blur" }` ref.
+ */
+export type EffectsRecipeProps = {
+    boxShadow?: string;
+    opacity?: string;
+    blur?: string;
+    transition?: string;
+    zIndex?: string;
+    [property: string]: string | undefined;
+};
+/**
+ * An effects property value (§8a, §15). Effects properties span plain scalars (`blur`
+ * `number | string`, `opacity`/`zIndex` numbers) AND the structured object-leaf properties
+ * `shadow` / `transitions`. An **open** authoring union — the `EffectsRaw` index signature keys
+ * every property to it; runtime coercion (`effects/utils.ts`) validates the concrete shape per key.
+ */
+export type EffectsPropertyValue = PropertyValue<string | number> | ShadowValue | TransitionValue;
+/**
+ * The authored `raw.effects` slice (§8a). An **open** map: keys are effects property names
+ * (`shadow`, `blur`, `transitions`, …), each an {@link EffectsPropertyValue}; the reserved
+ * `recipes` key is a {@link RecipeBlock} of effects recipes. Authoring type only.
+ */
+export interface EffectsRaw {
+    recipes?: RecipeBlock<EffectsRecipeProps>;
+    [property: string]: EffectsPropertyValue | RecipeBlock<EffectsRecipeProps> | undefined;
+}

package/dist/subsystems/effects/utils.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Effects value coercion (§15) — parse/validate authored shadow / transition leaves into the
+ * canonical, **format-neutral** Model form.
+ *
+ * Modeled on `colors/utils.ts`: a single boundary that runs at normalize time (via the subsystem's
+ * `coerceValue`) and turns the ergonomic authoring shapes — a flat single leaf or an array of leaves
+ * — into ONE canonical representation the Model carries on `Ref.struct`:
+ *
+ * - **shadow** → {@link ShadowLayer}`[]` (always an array, even single-layer); `color` kept as its
+ *   `colors.*` token-path string (never an embedded `rgba()` — §15.1), resolved late by the adapter.
+ *   A translucent shadow references a translucent colour (an `alpha` colour variant — §13.3).
+ * - **transitions** → {@link TransitionPart}`[]`; `duration`/`delay` in ms.
+ *
+ * **Structured-only (§15.2, amended 2026-07-16):** raw CSS strings are REJECTED — the ONLY accepted
+ * string is the keyword `"none"` (no shadow / no transition). Every other string throws a path-labelled
+ * error. Serialization to CSS text stays in the adapter; this module holds structure, not format. Its
+ * only core dependency is the shared length parser (`parseLength`, §21) — so a pinned geometry string
+ * (`offsetY: "1px"`) is parsed by the same grammar every length uses, rather than a duplicate here.
+ */
+import type { ShadowLayer, TransitionPart } from "../../core/model";
+/** A single authored shadow layer (flat leaf object) — geometry as a bare number (deferred, resolved by
+ * the §21 unit pass) or a pinned length string (`"1px"`, `"0.5rem"`) + a `colors.*` color ref
+ * (translucency comes from an `alpha` colour variant, not a shadow field). */
+export type ShadowLayerInput = {
+    offsetX?: number | string;
+    offsetY?: number | string;
+    blur?: number | string;
+    spread?: number | string;
+    color?: string;
+    inset?: boolean;
+};
+/** An authored shadow value: a flat single layer, an array of layers, or the `"none"` keyword. */
+export type ShadowInput = "none" | ShadowLayerInput | ShadowLayerInput[];
+/** A single authored transition part — `property` (required) + ms durations + timing keyword. */
+export type TransitionPartInput = {
+    property?: string;
+    duration?: number;
+    timingFunction?: string;
+    delay?: number;
+};
+/** An authored transition value: a flat single part, an array of parts, or the `"none"` keyword. */
+export type TransitionInput = "none" | TransitionPartInput | TransitionPartInput[];
+/** The canonical Model form of a shadow value — an array of layers, or the `"none"` keyword. */
+export type ShadowCanonical = "none" | ShadowLayer[];
+/** The canonical Model form of a transition value — an array of parts, or the `"none"` keyword. */
+export type TransitionCanonical = "none" | TransitionPart[];
+/**
+ * Coerce an authored shadow value into its canonical Model form. A string passes through (escape
+ * hatch); a flat leaf becomes a one-element `ShadowLayer[]`; an array becomes a multi-layer
+ * `ShadowLayer[]`. `label` is the property path for friendly errors.
+ */
+export declare const coerceShadowValue: (input: ShadowInput, label?: string) => ShadowCanonical;
+/**
+ * Coerce an authored transition value into its canonical Model form. A string passes through; a flat
+ * part becomes a one-element `TransitionPart[]`; an array becomes a multi-part `TransitionPart[]`.
+ */
+export declare const coerceTransitionValue: (input: TransitionInput, label?: string) => TransitionCanonical;

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

@@ -0,0 +1,21 @@
+/**
+ * The globals subsystem (§9 — formerly `reset`).
+ *
+ * Owns **no primitive properties** and **no minted-class recipes** — it fills the Model with two
+ * kinds of selector-targeting rule-set:
+ *
+ *  - **preset layers** (`static` + default `defaults`) — `kind:"reset"`, literal/opportunistic
+ *    normalization the adapters render at specificity-0 (`:where(sel)`). Unchanged from `reset`.
+ *  - **themed elements** (`elements`) — `kind:"globals"`, one rule-set per selector, carrying base
+ *    declarations + `states`/`responsive` overrides + delta-only `variants`. The adapters render
+ *    these at a higher tier (bare `a { }`, variant `a.subtle` / nested `&.subtle`).
+ *
+ * Element rules reuse the shared recipe normalization (`normalizeRecipeGroup`) for the genuinely
+ * common part — flattening `states` + `responsive` into one `overrides` list — but stay *structural*
+ * (a base selector + a named-variant map), not §7A recipe-sibling classes: they're elements, not
+ * recipes. Their token refs resolve late in each adapter and are validated up-front in `createTheme`
+ * (`validateGlobalsRefs`), like `components`. It grows a hook, never the spine.
+ */
+import type { Subsystem } from "../../core/subsystem";
+export declare const globalsSubsystem: Subsystem;
+export type { GlobalsRaw, GlobalsPreset, GlobalsDeclValue, GlobalsDeclarations, GlobalsElement } from "./types";

package/dist/subsystems/globals/presets.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The globals preset library (§9, formerly §10.1 reset) — the single, format-neutral source for the
+ * static normalization rule-sets and the default `h1`–`h6` → type-scale map.
+ *
+ * These produce Model {@link RuleSet}s (declarations are `{ value }` literals for the static
+ * layer, `{ ref }` token paths for the default heading map), so every web adapter shares one
+ * source (à la `color-math`) and lowers them itself. No CSS strings here — the adapter wraps
+ * each `selector` in `:where(…)` (specificity-0) and orders reset ahead of recipes.
+ *
+ * Layers:
+ *  - **static** — literal-declaration rule-sets that strip UA opinions (box model, margins,
+ *    heading sizing, list markers, form typography, media block/max-width, anchor colour).
+ *  - **default headings** — themed rule-sets binding `h1`–`h6` to typography's ratio-generated
+ *    `fontSize` scale variants (`typography.fontSize.4xl` …). Opportunistic: the adapter drops a
+ *    heading whose scale step wasn't generated (a theme with a ratio-less `fontSize`).
+ */
+import type { RuleSetGroup } from "../../core/model";
+import type { GlobalsPreset } from "./types";
+/** The default `h1`–`h6` themed group — each binds `font-size` to `typography.fontSize.<step>`. */
+export declare const buildDefaultHeadingGroup: () => RuleSetGroup;
+/** The recommended default preset (what `refract init` scaffolds). */
+export declare const DEFAULT_GLOBALS_PRESET: Exclude<GlobalsPreset, false>;
+/** The known preset names — for validation / error messages. */
+export declare const GLOBALS_PRESET_NAMES: ReadonlyArray<Exclude<GlobalsPreset, false>>;
+/**
+ * Expand a preset name into its `{ static, defaults? }` rule-set groups. `false` yields no groups
+ * (elements-only). An unknown name throws (typo detection). The default heading group is included
+ * only when the preset opts into it (`preflight` / `reset`, not `normalize`).
+ */
+export declare const expandPreset: (preset: GlobalsPreset) => {
+    static?: RuleSetGroup;
+    defaults?: RuleSetGroup;
+};

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

@@ -0,0 +1,48 @@
+/**
+ * The globals subsystem's authoring types (§9).
+ *
+ * `globals` owns the bare-element layer: a **preset** (opinionated static normalization + a default
+ * `h1`–`h6` map bound to the type scale) plus **themed element rules** (`elements`) bound to raw
+ * selectors. An element rule is a recipe *item* (declarations + `states` / `responsive` / `variants`),
+ * not a two-level recipe group — the selector IS the leaf. Authoring type only; the subsystem lowers
+ * it to Model rule-sets (`kind:"reset"` for the preset layer, `kind:"globals"` for elements) that each
+ * web adapter renders.
+ */
+import type { RecipeVariantDefinition, GlobalsElementVariantModifier } from "../../core/normalize";
+/** The built-in normalization preset names. `false` disables the static + default layers (elements only). */
+export type GlobalsPreset = "preflight" | "normalize" | "reset" | false;
+/**
+ * One themed-element declaration value (§9) — components' `CssDeltaValue`, minus cross-subsystem
+ * composition refs. **Literal-first**: a bare `string` is a raw CSS value (`textDecoration: "underline"`),
+ * a `number` is a literal, and a token **reference** uses `ref("colors.link")` or the JSON-safe object
+ * form `{ ref: "colors.link" }` → `var(--…)`. Flat leaves bound to a selector, never the class-list
+ * composition of `components`.
+ */
+export type GlobalsDeclValue = string | number | {
+    ref: string;
+};
+/** The flat declaration map a globals element instantiates the recipe-item shape's `TProps` with. */
+export type GlobalsDeclarations = Record<string, GlobalsDeclValue>;
+/**
+ * One themed element rule (§9) — the recipe-item shape ({@link RecipeVariantDefinition}) instantiated
+ * with flat globals leaves: base declarations plus the three condition axes `states` / `responsive` /
+ * `variants`. There is **no `modes` axis** — light/dark rides the referenced token's own modes. Each
+ * `variants` entry is a delta-only modifier the adapters render as a higher-specificity variant of the
+ * element (CSS `a.subtle`, styled-components / SCSS nested `&.subtle`).
+ */
+export type GlobalsElement = RecipeVariantDefinition<GlobalsDeclarations, string, GlobalsElementVariantModifier<GlobalsDeclarations, string>>;
+/**
+ * The authored `rawTheme.globals` slice (§9).
+ *
+ * - `preset` — the normalization base (`"preflight" | "normalize" | "reset" | false`). The key is
+ *   `preset` (not `reset`) because a `reset: "reset"` collides with the `"reset"` value. There is **no
+ *   bare-string shorthand** — the one form is `globals: { preset }`. The preset expands the static
+ *   layer (+ a default `h1`–`h6` heading map for `preflight` / `reset`); it must be explicit for those
+ *   layers to emit, so a bare `{ elements }` (no `preset` key) emits only the themed element rules and
+ *   an `override({ globals: { elements } })` inherits the parent's preset.
+ * - `elements` — selector → themed element rule.
+ */
+export interface GlobalsRaw {
+    preset?: GlobalsPreset;
+    elements?: Record<string, GlobalsElement>;
+}

package/dist/subsystems/index.d.ts

@@ -0,0 +1,21 @@
+/** Subsystems: colors · typography · layout · effects · borders · animation · components · globals. Wired in Steps 1–4 / §10.2 / §14 / §9. */
+export { colorsSubsystem } from "./colors";
+/** Contrast audit (WCAG 2 + advisory APCA) — reads a built theme, reports/strict-throws. */
+export { audit } from "./colors";
+export type { AuditResult, AuditOptions, PairingScore, PairingKind, WcagLevel } from "./colors";
+export { typographySubsystem } from "./typography";
+export { layoutSubsystem } from "./layout";
+export { effectsSubsystem } from "./effects";
+export { bordersSubsystem } from "./borders";
+export { animationSubsystem } from "./animation";
+export { componentsSubsystem } from "./components";
+export { globalsSubsystem } from "./globals";
+/** Per-subsystem raw authoring-input types (§8a) — composed into `RawTheme`. */
+export type { ColorsRaw } from "./colors";
+export type { TypographyRaw, TypographyPropertyValue } from "./typography";
+export type { EffectsRaw, EffectsPropertyValue } from "./effects";
+export type { BordersRaw, BordersPropertyValue } from "./borders";
+export type { AnimationRaw } from "./animation";
+export type { LayoutRaw, ContainerRaw, ContainerVariantRaw } from "./layout";
+export type { ComponentsRaw } from "./components";
+export type { GlobalsRaw, GlobalsPreset, GlobalsDeclValue, GlobalsDeclarations, GlobalsElement } from "./globals";

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

@@ -0,0 +1,14 @@
+/**
+ * The layout subsystem — the biggest one, with three parts:
+ *  1. Regular property tokens (`spacing` / `gutters` / `aspectRatio`) — like typography/effects,
+ *     plus the forced `none` variant on spacing/gutters (`finalizeLayoutNormalization`).
+ *  2. Recipes (`padding` / `section`) — ordinary token-path recipes (`interpretRecipe`).
+ *  3. Structural generators (`columns` / `grids` / `stacks` / `container`) — emitted as native
+ *     Model rule-sets via the `buildStructural` hook (see `structural.ts`), with the columns/
+ *     container config knobs riding along as `configProperties` (Model `extraProperties`).
+ *
+ * It grows the spine's hooks (`interpretRecipe`, `buildStructural`), never the spine's control flow.
+ */
+import type { Subsystem } from "../../core/subsystem";
+export declare const layoutSubsystem: Subsystem;
+export type { LayoutRaw, ContainerRaw, ContainerVariantRaw } from "./types";

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

@@ -0,0 +1,35 @@
+/**
+ * Layout's `normalizeProperty` hook — numeric scale synthesis (§10.6) + the forced `none` variant.
+ *
+ * `spacing` / `gutters` / `sizes` can synthesize their variant ramp from a base + a curve, the same
+ * way colors generates tonal steps and typography the type scale:
+ *  - **geometric** (`ratio`) — `base × ratio^n`, `steps` an ordered name array (index = exponent);
+ *  - **linear** (`step`) — `step × n`, `steps` a name→multiplier map (the 4/8-pt grid).
+ *
+ * Each synthesized step is stored as a **derived** variant (`{ base, derive:{ ref, fn:"scaleStep",
+ * arg } }`) so the Model carries it as a re-resolving `Ref` — `override()` of the base re-synthesizes
+ * every step (mirror colors, NOT typography's frozen literals). A ramp entry inside a property's
+ * `responsive` list (D6) regenerates the WHOLE named scale at that breakpoint, expanding into one
+ * `target` override per step — the already-existing responsive channel, no new Model member.
+ *
+ * Synthesis is **opt-in + additive**: absent a `ratio`/`step`, behaviour is byte-identical to before
+ * (spacing/gutters still get the forced `none`; sizes/aspectRatio pass through). Authored `variants`
+ * always win over synthesized ones — the way sizes' semantic caps (`prose`) and pinned values
+ * (`full: "100%"`, no magnitude → never synthesized) coexist with the ramp.
+ */
+import type { NormalizedPropertyValue } from "../../core/normalize";
+import type { Literal } from "../../core/model";
+/**
+ * The `scaleStep` derivation fn (registered by the layout subsystem). Re-derives a synthesized step
+ * from its curve config: **geometric** `base × ratio^exp` (from the resolved base token, so an
+ * `override()` of the base rescales it), **linear** `step × mult` (a fixed grid, self-contained in
+ * `arg`). A responsive ramp step with an explicit breakpoint base carries it on `arg.base`, so it
+ * derives from its own breakpoint base (precedent: colors' appearance modes). Mirrors the way the
+ * derivation registry hands every fn `(resolvedValue, arg)`.
+ */
+export declare const scaleStep: (value: Literal, arg?: unknown) => Literal;
+/**
+ * @param propertyKey The layout property being normalized.
+ * @param normalized  The property after the shared property normalize pass.
+ */
+export declare const finalizeLayoutNormalization: (propertyKey: string, normalized: NormalizedPropertyValue<unknown>) => NormalizedPropertyValue<unknown>;