@theme-registry/refract 0.1.8 → 0.1.9

package/README.md

@@ -187,13 +187,24 @@ stylesheets by default, so the page is one self-contained file that survives bei
 { name: "css", adapter: createCssAdapter(), outDir: "dist/theme", preview: true }
 ```
 
-Token plates — colours, the type ramp, spacing, radii, shadows, breakpoints — render from the
-format-neutral token export, so **every** adapter gets them. Live recipe plates additionally need
-output a browser can load as-is, which today means CSS; an SCSS/styled-components/JSON target still
-renders every token and names every recipe, and says why it can't render them live. (For a live
-design-review page from an SC or SCSS theme, add a CSS target to the same config — same recipes,
-same core.) The page follows the target's `emit` mode, and gains a light/dark toggle when the theme
-declares modes plus frame-width buttons when it declares breakpoints. Off by default.
+It reads as a style guide, not a token dump: a 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 shown as a measure *and* as an applied inset, a **state matrix** per recipe, and a
+copy-on-click identifier beside every specimen. Sections appear only when the theme has tokens of
+that kind.
+
+Token plates render from the format-neutral token export, so **every** adapter gets them. Live
+recipe plates additionally need output a browser can load as-is, which today means CSS; an
+SCSS/styled-components/JSON target still renders every token and names every recipe, and says why it
+can't render them live. (For a live design-review page from an SC or SCSS theme, add a CSS target to
+the same config — same recipes, same core.)
+
+Three things only a compiler's specimen sheet can show: **states** side by side (a CSS pseudo-class
+can't be triggered from markup, so the adapter emits a parallel pinnable rule that is inlined into
+the page and never added to the stylesheet you ship), an **appearance-mode diff** of the tokens that
+actually carry an override, and **composition** broken into its parts — each class in a component's
+identity attributed to the recipe it came from. Bare elements themed by the `globals` subsystem get
+their own prose specimen, since they carry no class at all. Off by default.
 
 Its machine-facing sibling is `guide: true`, which writes an `llms.txt` + `manifest.json`
 consumption guide into the same folder.

package/dist/build/preview.d.ts

@@ -1,5 +1,6 @@
 /**
- * Human-facing preview (Node-only) — render a single `preview.html` specimen of a built theme.
+ * Human-facing preview (Node-only) — render a single `preview.html` **style-guide specimen** of a
+ * built theme.
  *
  * The audience-flipped sibling of `guide.ts`: that one writes `llms.txt` + `manifest.json` for a
  * downstream *agent*; this one writes a page a person opens, forwards, or hands a designer to answer
@@ -11,18 +12,28 @@
  *  - **Token plates (universal).** Rendered from the format-neutral DTCG export — the same document
  *    `guide` embeds — so they depend on nothing the adapter emitted. Every adapter, including a
  *    third-party one that has never heard of previews, gets these on day one. The walk is generic
- *    over `$type`, so a new subsystem's tokens show up without touching this file.
+ *    over `$type` with per-group specimen overrides, so a new subsystem's tokens still appear (in a
+ *    catch-all section) without touching this file.
  *
  *  - **Recipe plates (live).** Require the emitted artifacts to be browser-loadable as-is, which the
  *    adapter alone can answer — see {@link PreviewDescriptor}. Today that means CSS; SCSS needs
  *    compiling, styled-components emits JS modules, JSON has no rendered form. Those adapters say so
  *    in their own words and the page degrades to tokens-only rather than rendering unstyled boxes.
  *
+ * Two rules the layout is built on, both learned the hard way:
+ *
+ *  1. **The chrome is chromatically silent.** The theme owns every saturated pixel; the tool around
+ *     it is neutral, and specimen geometry uses a dedicated mid-tone (`--rfp-spec`) rather than the
+ *     nearest neutral to hand. Filling a swatch with the page ground makes it vanish the moment the
+ *     ground and the stage converge — which is exactly what happens in dark mode.
+ *  2. **Never assume the theme is light.** The emitted stylesheet is inlined, so a theme with a
+ *     `dark` mode restyles itself under the toggle; the chrome has to survive both, and the page
+ *     must not hard-code a light ground under it.
+ *
  * Distribution convention deliberately INVERTS `guide`'s: the page **inlines** its stylesheets by
  * default (`inline: false` opts out). `guide` is machine-facing and lives next to the code it
  * documents, so relative references are right there; a preview gets moved, attached, and forwarded,
- * and has to keep working. `inline: false` serves the dev loop, where the page should reflect a
- * rebuilt stylesheet on refresh.
+ * and has to keep working.
  */
 import type { ThemeModel } from "../core/model/model";
 import type { NormalizedEmit, PreviewDescriptor, UsageDescriptor } from "../core/ThemeAdapter";
@@ -36,15 +47,15 @@ export type PreviewConfig = {
      * reflects a rebuilt stylesheet on refresh.
      */
     readonly inline?: boolean;
-    /** Page heading + `<title>` (default `"<format> theme preview"`). */
+    /** Page heading + `<title>` (default the theme name, else `"<format> theme"`). */
     readonly title?: string;
 };
 export interface PreviewOptions extends PreviewConfig {
     /** The file names actually written for this target — the guard against referencing a missing artifact. */
     readonly files: readonly string[];
-    /** Emitted file contents by name, for inlining. A name missing here falls back to a `<link>`. */
+    /** Emitted file contents by name, for inlining + the byte counts in the masthead. */
     readonly contents?: Readonly<Record<string, string>>;
-    /** The normalized emit plan — reported in the header and used for layout semantics only. */
+    /** The normalized emit plan — reported in the masthead and used for layout semantics only. */
     readonly plan: NormalizedEmit;
 }
 export interface PreviewOutput {
@@ -58,16 +69,9 @@ export interface PreviewSource {
     readonly preview?: PreviewDescriptor;
     /** A DTCG document (from `toDTCG`) — the token-plate source. */
     readonly tokens: unknown;
-    /** The built model — supplies appearance modes and breakpoints for the page controls. */
+    /** The built model — supplies appearance modes, breakpoints, and the globals element selectors. */
     readonly model: ThemeModel;
 }
 /** Distinct appearance modes across every property's `modes` list, in first-appearance order. */
 export declare function collectModes(model: ThemeModel): string[];
-/**
- * Build the preview artifact. Pure — returns `filename → contents` for the build layer to write.
- *
- * The adapter's declared `stylesheets` are intersected with `options.files` (what was actually
- * written), so a descriptor that drifts from `emit()` degrades to tokens-only instead of producing a
- * page that silently references a file that isn't there.
- */
 export declare function buildPreview(source: PreviewSource, options: PreviewOptions): PreviewOutput;