@theme-registry/refract 0.1.8 → 0.1.9

package/dist/core/ThemeAdapter.d.ts

@@ -195,6 +195,39 @@ export interface PreviewDescriptor {
     readonly unavailable?: string;
     /** Caveats worth surfacing on the page even when rendering does work (e.g. "`variables: false` — …"). */
     readonly notes?: readonly string[];
+    /**
+     * A token path → the name the emitted output gives it (`colors.brand` → `--dt-colors-brand`).
+     * Shown beside each value, so a reader can go straight from the specimen to the thing they type.
+     * Return `undefined` for a path that mints no name.
+     */
+    readonly tokenName?: (path: string) => string | undefined;
+    /**
+     * The states a recipe actually declares (`["hover", "focus", "disabled"]`), so the page can render
+     * a state matrix instead of one at-rest specimen. Only states that also answer to
+     * {@link statePinClass} are rendered — a state nobody can pin can't be shown at rest.
+     */
+    readonly states?: (recipe: UsageRecipe) => readonly string[];
+    /**
+     * The class that forces `state` to render at rest. CSS states are pseudo-classes (`:hover`) and
+     * attribute selectors (`[disabled]`) that markup cannot switch on, so the adapter emits a parallel
+     * pinnable rule (see {@link statePinCss}) and names its class here.
+     */
+    readonly statePinClass?: (state: string) => string | undefined;
+    /**
+     * Extra stylesheet the page inlines to make {@link statePinClass} work. Kept out of the emitted
+     * theme on purpose: these rules exist only to drive a specimen sheet and must never reach a
+     * consumer's bundle.
+     */
+    readonly statePinCss?: string;
+    /**
+     * A composed recipe's identity broken into its parts — each emitted class plus the recipe address
+     * it came from (`undefined` ⇒ this rule-set's own delta). Rendering the joined string without
+     * saying why it's two classes reads as a bug.
+     */
+    readonly composition?: (recipe: UsageRecipe) => ReadonlyArray<{
+        readonly className: string;
+        readonly from?: string;
+    }> | undefined;
 }
 /** The Model-derived context bound alongside the Model. */
 export interface RenderContext<TBreakpoint extends string = string> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theme-registry/refract",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "The framework-agnostic, format-neutral theme compiler core — build a ThemeModel from a RawTheme, then lower it with any adapter package (CSS, SCSS, JSON, styled-components).",
   "author": {
     "name": "Petyo Stoyanov",

package/skills/build-config/SKILL.md

@@ -85,11 +85,22 @@ every token and lists every recipe by its real identity, and states why it can't
 If a user wants a live design-review page from an SC or SCSS theme, tell them to **add a CSS target
 to the same config** — same recipes through the same core, so it's a faithful specimen.
 
-The page follows the target's `emit` mode (variables load before styles in `split`; plates group by
+The page is a **style guide**, not a token dump: sticky section rail, colour families as contiguous
+ladders with live WCAG contrast readouts on each `text` pairing, the type ramp set in its own sizes,
+spacing as a measure *and* an applied inset (there is no `padding` token — spacing IS the padding
+scale), a **state matrix** per recipe, an **appearance-mode diff** of the tokens that actually carry
+an override, **composition** broken into its parts, and a prose specimen for the bare elements the
+`globals` subsystem themes. Sections appear only when the theme has tokens of that kind.
+
+It follows the target's `emit` mode (variables load before styles in `split`; plates group by
 subsystem or by component file), gains a light/dark toggle when the theme declares `modes`, and
 frame-width buttons when it declares `breakpoints`. A theme with **no recipes** (e.g. straight out of
 `refract create`) renders its tokens and says explicitly that recipes are missing.
 
+**State rules never reach the shipped stylesheet.** A CSS pseudo-class can't be triggered from
+markup, so the adapter emits parallel pinnable rules (`.cls.rfp-s-hover`) that are inlined into
+`preview.html` only. If a user asks why those classes aren't in `theme.css`, that's why.
+
 ## Dark-mode strategy (differs by target)
 
 - **CSS / SCSS / JSON** — dark rides the *referenced token's own `modes`* (see **theme-foundations**);