@elastic/distillate 0.0.0 → 0.1.0

package/docs/getting-started/your-first-stylesheet.md

@@ -0,0 +1,57 @@
+---
+navigation_title: Your first stylesheet
+description: Register several handles and emit a readable sheet for an app.
+---
+
+# Your first stylesheet
+
+Use the **stylesheet** target when a host app will load one CSS file and refer to stable class names. Readable names are `${moduleName}-${path}`: `.panel-root`, `.panel-title`.
+
+This continues the [quick start](quick-start.md) environment (`colors.ink`, `colors.accent`, `colors.surface`, `gap`). The file below is complete on its own.
+
+```ts
+import { createDistillery, cq, lightDark } from '@elastic/distillate';
+
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme: {
+    colors: {
+      ink: lightDark('#111', '#eee'),
+      accent: lightDark('#06c', '#8cf'),
+      surface: lightDark('#fff', '#000'),
+    },
+    gap: cq('8px', '2cqi'),
+  },
+});
+
+const panel = distillery.createStyleModule('panel', ({ css, tokens }) => ({
+  root: css`
+    padding: ${tokens.gap};
+    background: ${tokens.colors.surface};
+  `,
+  title: css`
+    color: ${tokens.colors.ink};
+  `,
+}));
+
+const css = distillery.renderStyles(distillery.stylesheetCollector());
+```
+
+```css
+.eui-view {
+  --eui-colors-ink: light-dark(#111, #eee);
+  --eui-colors-surface: light-dark(#fff, #000);
+}
+.panel-root {
+  padding: 8px;
+  background: var(--eui-colors-surface);
+}
+.panel-title {
+  color: var(--eui-colors-ink);
+}
+```
+
+`stylesheetCollector()` preloads every registered module, including variants. Apply `panel.handles.root.readableName` (or `String(handle)` on an emotion wrapper) in markup. Readable stringification does **not** collect; it only works when the document's stylesheet also used readable names.
+
+For HTML that leaves the app with its CSS inlined, switch to [compact artifacts](../guides/compact-artifacts.md). For how names and targets combine, see [naming and output](../concepts/naming-and-output.md).

package/docs/guides/compact-artifacts.md

@@ -0,0 +1,87 @@
+---
+navigation_title: Ship a compact artifact
+description: Collect the handles a render reached and emit a self-contained CSS payload, with a measured size comparison.
+---
+
+# Ship a compact artifact
+
+Use this path when HTML and CSS leave the app together: an email, an SVG, a Slack message, an agent reply. Compact names are assigned from the collected key set, so they are not stable across renders. Emit markup and CSS from the same collector.
+
+The environment matches [quick start](../getting-started/quick-start.md). Every handle that appears on an element must be collected **and** resolved:
+
+```ts
+import {
+  createDistillery,
+  cq,
+  lightDark,
+  variants,
+} from '@elastic/distillate';
+
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme: {
+    colors: {
+      ink: lightDark('#111', '#eee'),
+      accent: lightDark('#06c', '#8cf'),
+      surface: lightDark('#fff', '#000'),
+    },
+    gap: cq('8px', '2cqi'),
+  },
+});
+
+const panel = distillery.createStyleModule('panel', ({ css, tokens }) => ({
+  root: css`
+    padding: ${tokens.gap};
+    background: ${tokens.colors.surface};
+  `,
+  tone: variants(
+    ['calm', 'loud'] as const,
+    (tone) =>
+      css`
+        outline-color: ${tone === 'calm' ? tokens.colors.surface : tokens.colors.accent};
+      `
+  ),
+}));
+
+const collector = distillery.artifactCollector('compact');
+const used = [panel.handles.root, panel.handles.tone.loud]; // include the variant; use(panel) skips it
+const retained = collector.useHandles(used);
+
+const resolver = collector.createResolver(); // after collection; compact ids depend on the full set
+const className = retained
+  .map((handle) => resolver.className(handle.key, handle.readableName))
+  .join(' ');
+const css = distillery.renderStyles(collector, resolver);
+```
+
+`useHandles` auto-collects nested `&:hover` and `media(...)` / `container(...)` inner rules whose selector deps are met.
+
+## Two-pass render
+
+Compact class names depend on the **full** collected set. If you print class names during the walk that collects handles, you will mint names too early.
+
+1. Walk the tree. For every style you would apply, `collector.useHandles([...])`. Do not read compact names yet.
+2. `const resolver = collector.createResolver()`.
+3. Walk again (or serialize from a recorded list). Write `resolver.className(handle.key, handle.readableName)` only for handles `useHandles` retained.
+4. `distillery.renderStyles(collector, resolver)` and inline the CSS.
+
+A readable artifact (`artifactCollector('readable')`) can skip the second pass because `handle.readableName` does not depend on the collected set. Compact is cheaper on the wire; readable is easier to debug.
+
+## How much smaller
+
+[`docs/examples/06-payload.ts`](https://github.com/elastic/distillate/blob/main/docs/examples/06-payload.ts) authors one module with unused variants and handles, then emits the full readable stylesheet and a compact artifact from a single `root` + `tone.calm` render. The example returns both strings and their UTF-8 byte lengths. In this fixture the compact artifact is about a quarter of the stylesheet. The test asserts it stays under 40% — shaking plus compact names, which is the payload that actually ships.
+
+The playground CSS pane shows the same comparison live: full stylesheet versus compact artifact, with byte counts visible without switching tabs.
+
+## What is pruned
+
+- Unnamed variant entries
+- Handles the walk never named
+- Empty untargeted handles (no-op templates). `useHandles` omits them from its return value; resolve only that list.
+- Local-var defaults that no collected declaration reads. Per-handle, `reachableDefaults` keeps only keys referenced by that handle or by a collected rule whose selector targets it. Rule-level default markers have no host handle and emit every listed key. See [reachability collection](../concepts/collection.md).
+- Theme tokens whose paths were never collected (not interpolated into a collected declaration, not a surviving default-marker value dep, and not marked with `useThemeVar`). A collected path still emits even if the body does not textually contain `var(...)`.
+
+`injectGlobal` styles are **not** in an artifact unless you `collector.use(module)` each `globalModules()` entry. Call `stylesheet()` / `stylesheetCollector()` when globals should always ship.
+
+A React host that does both passes for you is in [Integrate with a React renderer](react-renderer.md).

package/docs/guides/emotion-migration.md

@@ -0,0 +1,60 @@
+---
+navigation_title: Migrate from Emotion
+description: Adopt createEmotion without rewriting every call site.
+---
+
+# Migrate from Emotion
+
+`@elastic/distillate/emotion` is an `@emotion/css`-shaped surface over a distillery: `css`, `cx`, `injectGlobal`, `stylesheet`, `globalModules`. Nested `&` and `@media` use stylis, so existing templates keep their meaning.
+
+```ts
+import { createEmotion, createDomSink } from '@elastic/distillate/emotion';
+
+const sink = createDomSink({ document });
+const { css, cx, injectGlobal } = createEmotion(distillery, { sink });
+```
+
+## What maps
+
+| Emotion             | Distillate                                                                         |
+| ------------------- | ---------------------------------------------------------------------------------- |
+| `css\`...\``        | `css\`...\`` — returns a handle that stringifies to the readable class.            |
+| `cx(...)`           | `cx(...)` — strings, numbers, falsy, arrays, maps, handles.                        |
+| `injectGlobal`      | `injectGlobal` — registered as a module; ships in `stylesheet()`.                  |
+| `<style>` injection | `createDomSink` — one element, rewritten on each registration, one flush per turn. |
+
+## What does not map
+
+| Emotion                                  | Status                                                                      |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| `css({ color: 'red' })`                  | Rejected. Tagged templates only.                                            |
+| `keyframes`                              | Rejected.                                                                   |
+| `@supports` / `@container` in `css`      | Rejected. Use `container(...)` from the root entry.                         |
+| `styled.*` / `@emotion/react` `css` prop | Out of scope.                                                               |
+| Runtime template values                  | Styles are static after first construction. Put variation on CSS variables. |
+
+## Two ways to use a handle
+
+`String(css\`...\`)`is the readable class name and **does not collect**. Use it only against a readable stylesheet (the DOM sink or`stylesheet()`).
+
+The same value passed through `resolveClassName` / `collector.useHandles` participates in compact artifact emission. SSR: render `stylesheet()` on the server; content hashes make client and server class names agree.
+
+## Composition
+
+Do not rely on declaration order across separate `css` calls. Interpolate:
+
+```ts
+const base = css`
+  color: red;
+`;
+const ext = css`
+  ${base} <1>
+  color: blue;
+`;
+```
+
+1. Compose by interpolation. Both declarations land on `ext`'s class; later wins.
+
+## Mix with native modules
+
+`cx` accepts native `StyleHandle` values and uses their `readableName`. A host can migrate file by file: new modules through `createStyleModule`, remaining call sites through `createEmotion` on the same distillery.

package/docs/guides/index.md

@@ -0,0 +1,17 @@
+---
+navigation_title: Guides
+description: When to use Distillate, theming, non-CSS surfaces, compact artifacts, React, Emotion migration, testing, and name collisions.
+---
+
+# Guides
+
+Task-oriented pages. Concepts live under [Concepts](../concepts/index.md).
+
+- [Distillate vs CSS-in-JS](vs-emotion.md) — when Distillate is the right tool
+- [Declare and select variations](theming.md) — named diffs, `{ flatten }`, `{ alternates }`
+- [Read values outside CSS](non-css-surfaces.md) — literal theme values for SVG and other non-CSS surfaces
+- [Ship a compact artifact](compact-artifacts.md) — tree-shaken CSS for HTML that leaves the app
+- [Integrate with a React renderer](react-renderer.md) — collect handles while rendering
+- [Migrate from Emotion](emotion-migration.md) — `createEmotion` over the same registry
+- [Test the var invariant](var-invariant.md) — every `var(...)` has a declaration
+- [Avoid readable-name collisions](name-collisions.md) — hyphen-joined names must be unique

package/docs/guides/name-collisions.md

@@ -0,0 +1,37 @@
+---
+navigation_title: Avoid readable-name collisions
+description: Hyphen-joined class and variable names must be unique across the registry.
+---
+
+# Avoid readable-name collisions
+
+Readable class names join path segments with hyphens: module `card` plus handle `header/title` becomes `card-header-title`. Module `card-header` plus handle `title` becomes the same string. Distillate throws at `createStyleModule` rather than emit two rules for one class.
+
+```ts
+distillery.createStyleModule('card', ({ css, tokens }) => ({
+  header: {
+    title: css`
+      color: ${tokens.colors.ink};
+    `,
+  },
+})); <1>
+distillery.createStyleModule('card-header', ({ css, tokens }) => ({
+  title: css`
+    color: ${tokens.colors.accent};
+  `,
+})); <2>
+```
+
+1. Readable name: `card-header-title`.
+2. Same readable name. Throws at `createStyleModule`.
+
+Local vars join `--${prefix}-${module}-${group}-${key}` via `cssVarName`. These also throw:
+
+- Two `vars` groups in one module that hyphen-join to the same property (`look` + `bg` vs `lo` + `ok-bg` is fine; `b-c`/`d` vs `b`/`c-d` is not).
+- A local var that hyphenates to the same property as a theme or shared path (`chip` + `look`/`bg` vs theme path `chip/look/bg`).
+- A theme path and a shared path that hyphenate to the same property (`colors/ink` vs `vars/colors/ink`).
+- A theme-tree key that contains `-` (`colors-ink`). Hyphens are rejected so path segments reverse uniquely.
+
+Compact mode is path-keyed and unaffected. Identifier segments (`prefix`, module names, group names, keys) must match `[A-Za-z_][A-Za-z0-9_-]*`. Hyphens are allowed so emotion modules named `css-${hash}` stay legal — they are also why collisions are possible.
+
+Pick one nesting convention per library (flat handle names, or nested objects, not both colliding) and keep `prefix` short and unique.

package/docs/guides/non-css-surfaces.md

@@ -0,0 +1,73 @@
+---
+navigation_title: Read values outside CSS
+description: Resolve theme literals, or emit a stylesheet with one scheme already chosen, for surfaces that cannot use CSS custom properties or `light-dark()`.
+---
+
+# Read values outside CSS
+
+`tokens` stringify to `var(--x)`. That is the right shape for CSS. A headless SVG or PNG rasterizer has no custom-property engine, so it needs the nested literal strings `createDistillery` already computed. A target that consumes the stylesheet itself but has no color scheme to resolve `light-dark()` against — an image or PDF backend, email HTML, an older browser — needs the same values written into the theme block.
+
+`resolveValues(scheme, variation?)` walks the original theme tree: `lightDark` and string leaves come from `themeVars` for that scheme, `cq` / `ScaleToken` leaves become `.value`. Named variations apply the same diffs `renderStyles({ flatten })` would. Resolution is lazy; unused variations are not precomputed.
+
+```ts
+import { createDistillery, cq, lightDark, mapDomain } from '@elastic/distillate';
+
+const theme = {
+  colors: {
+    ink: lightDark('#111', '#eee'),
+    accent: lightDark('#06c', '#8cf'),
+  },
+  type: {
+    size: {
+      s: '12px',
+      m: '16px',
+    },
+  },
+  gap: cq('8px', '2cqi'),
+} as const;
+
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme,
+  variations: {
+    muted: { colors: { accent: '#0077cc' } },
+  },
+});
+
+const light = distillery.resolveValues('light');
+light.colors.ink; // '#111'
+light.type.size.m; // '16px'
+light.gap; // '8px'
+
+const mutedDark = distillery.resolveValues('dark', 'muted');
+mutedDark.colors.accent; // '#0077cc'
+```
+
+## Emit a single-scheme stylesheet
+
+When the consumer still wants CSS — the React tree plus the emitted sheet — pass `{ scheme: 'light' | 'dark' }` to `renderStyles`. Differing `lightDark` leaves emit that scheme's literal instead of `light-dark(...)`.
+
+```ts
+distillery.renderStyles(collector, undefined, { scheme: 'light' });
+// --eui-colors-ink:#111  (not light-dark(#111,#eee))
+
+distillery.renderStyles(collector, undefined, {
+  scheme: 'light',
+  flatten: 'muted',
+});
+// --eui-colors-accent:#0077cc  (the variation, not the base)
+```
+
+`scheme` reads the `ThemeVarDefinition` each var-block already selected, so it composes with `{ flatten }` and `{ alternates }`. `themeValueOverrides` still wins. A variation that differs from the base only on the unselected side still emits its diff; under `scheme` that declaration can equal the primary block. Combining `scheme` with `alternates` is allowed: `scheme` describes the target, not the content.
+
+`resolveThemeValues(theme, themeVars, scheme, variation?)` is the same walk when you already have the tree and registry and do not want to go through the distillery.
+
+The engine does not strip units. `'16px'` stays `'16px'`; a renderer that wants a number parses the string. `.cq` stays on the `ScaleToken` in `theme` / `tokens` if the surface needs the container-relative form.
+
+`mapDomain` is the non-CSS half of `variants()`: map an enum to a value with no collector side effect. `variants()` calls it, then marks each value so `collector.use(module)` skips it.
+
+```ts
+const sizes = ['s', 'm'] as const;
+const typeSize = mapDomain(sizes, (size) => light.type.size[size]);
+```

package/docs/guides/react-renderer.md

@@ -0,0 +1,158 @@
+---
+navigation_title: Integrate with a React renderer
+description: Collect handles while rendering, then emit class names and CSS.
+---
+
+# Integrate with a React renderer
+
+Distillate does not ship a React runtime. A host renderer owns the class-name context and decides when to collect.
+
+## Readable stylesheet (app)
+
+Register modules at module-eval time. Emit one stylesheet (build step or `createDomSink`) and put `handle.readableName` on `className`. No collector is required at render time:
+
+```tsx
+import { createDistillery, cq, lightDark } from '@elastic/distillate';
+import type { ReactNode } from 'react';
+
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme: {
+    colors: { ink: lightDark('#111', '#eee') },
+    gap: cq('8px', '2cqi'),
+  },
+});
+
+const { handles } = distillery.createStyleModule('button', ({ css, tokens }) => ({
+  root: css`
+    color: ${tokens.colors.ink};
+  `,
+}));
+
+export const Button = ({ children }: { children: ReactNode }) => (
+  <button className={handles.root.readableName}>{children}</button>
+);
+
+// writeFileSync(
+//   'dist/styles.css', 
+//   distillery.renderStyles(distillery.stylesheetCollector())
+// );
+```
+
+## Compact artifact (export / email / SVG)
+
+Collection has to observe the tree. Compact names depend on the full collected set, so render twice: once to `useHandles`, once to write class names. `combineClassNames` is the component-facing API so views never mention the collector.
+
+Reuse the distillery and `button` module from above. The extra pieces are a context, views that call `combineClassNames`, and a two-pass helper. Imports in the next snippet cover the rest of this section.
+
+### Pass a class-name context
+
+Both render passes implement this shape. Views only ever see `resolveClassName`:
+
+```tsx
+import {
+  combineClassNames,
+  type Distillery,
+  type StyleHandle,
+  type StylesModule,
+} from '@elastic/distillate';
+import { createContext, useContext, type ReactElement, type ReactNode } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+interface StyleContextValue {
+  resolveClassName: (...handles: StyleHandle[]) => string;
+}
+
+const StyleContext = createContext<StyleContextValue | null>(null);
+
+const useStyleContext = (): StyleContextValue => {
+  const value = useContext(StyleContext);
+  if (!value) {
+    throw new Error('StyleContext is missing.');
+  }
+  return value;
+};
+```
+
+### Views call `combineClassNames`
+
+Same `handles.root` as the app button. Swap `readableName` for the context:
+
+```tsx
+const Button = ({ children }: { children: ReactNode }) => {
+  const ctx = useStyleContext();
+  return <button className={combineClassNames(ctx, handles.root)}>{children}</button>;
+};
+```
+
+Pass every handle the element should wear: `combineClassNames(ctx, handles.root, other.handles.title)`.
+
+### Render twice
+
+The first pass must finish before any class name is printed. `createResolver()` assigns compact names from the collected set; reading them earlier mints names too soon. Leave `globals` empty unless you have `injectGlobal` styles (next section).
+
+```tsx
+export const renderArtifact = (
+  tree: ReactElement,
+  distillery: Distillery,
+  globals: readonly StylesModule[] = []
+): { html: string; css: string } => {
+  const collector = distillery.artifactCollector('compact');
+  for (const module of globals) {
+    collector.use(module);
+  }
+
+  // Pass 1: record handles. Compact names are not assigned yet.
+  const collecting: StyleContextValue = {
+    resolveClassName: (...handles) => {
+      collector.useHandles(handles);
+      return '';
+    },
+  };
+
+  renderToStaticMarkup(
+    <StyleContext.Provider value={collecting}>{tree}</StyleContext.Provider>
+  );
+
+  const resolver = collector.createResolver();
+
+  // Pass 2: write class names now that the collected set is complete.
+  const emitting: StyleContextValue = {
+    resolveClassName: (...handles) =>
+      collector
+        .useHandles(handles)
+        .map((handle) => resolver.className(handle.key, handle.readableName))
+        .join(' '),
+  };
+
+  const html = renderToStaticMarkup(
+    <StyleContext.Provider value={emitting}>{tree}</StyleContext.Provider>
+  );
+  return { html, css: distillery.renderStyles(collector, resolver) };
+};
+
+renderArtifact(<Button>Hello</Button>, distillery);
+```
+
+A readable artifact (`artifactCollector('readable')`) can skip the emitting pass because `handle.readableName` does not depend on the collected set. See [Ship a compact artifact](compact-artifacts.md).
+
+### Include `injectGlobal` styles
+
+Globals from `injectGlobal` are separate modules. They are not implied by collecting handles; pass `globalModules()` into the helper when they should ship with the artifact:
+
+```tsx
+import { createEmotion } from '@elastic/distillate/emotion';
+
+const { injectGlobal, globalModules } = createEmotion(distillery);
+
+injectGlobal`
+  html {
+    color-scheme: light dark;
+  }
+`;
+
+renderArtifact(<Button>Hello</Button>, distillery, globalModules());
+```
+
+Do not mix a compact stylesheet with markup that used `readableName`. The DOM will carry `.button-root` while the `<style>` contains `.a`.

package/docs/guides/theming.md

@@ -0,0 +1,107 @@
+---
+navigation_title: Declare and select variations
+description: Named variations, render-time flatten and alternates, and when not to use a variation.
+---
+
+# Declare and select variations
+
+`theme` is the default tree you ship. If you only ship one brand, that brand is `theme`, not a variation.
+
+`variations` are named, value-only diffs of that same tree. Declaring one does not emit it. Name it at `renderStyles` with `{ flatten }` or `{ alternates }` so unused variations cost nothing.
+
+## Declare
+
+Named variations cannot introduce new paths. They do not chain: each is resolved against the base, not against another variation. `media` is the query only (`'(prefers-contrast: more)'`), not `@media (...)`.
+
+```ts
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme: {
+    colors: {
+      ink: lightDark('#111', '#eee'),
+      accent: lightDark('#06c', '#8cf'),
+    },
+    gap: cq('8px', '2cqi'),
+  },
+  variations: {
+    muted: {
+      colors: { accent: '#0077cc' }, // flatten with { flatten: 'muted' }
+    },
+    highContrast: {
+      media: '(prefers-contrast: more)',
+      variation: {
+        colors: { ink: lightDark('#000', '#fff') },
+      },
+    },
+  },
+});
+```
+
+A selector is the consuming page's DOM contract, so it is supplied per render rather than on the variation.
+
+`cq()` / `ScaleToken` leaves inline at authoring time and cannot change in a variation. Spacing authored with `cq('8px', '2cqi')` is fixed; a `dense` variation that tried to swap `cq('4px', '1cqi')` throws. Making density selectable means authoring that size as a string leaf so it becomes a theme var, and giving up inlining.
+
+## Select
+
+Base only is the default, and byte-for-byte what a distillery without `variations` emits:
+
+```ts
+distillery.renderStyles(collector);
+```
+
+Flatten one non-media variation into `themeScope`. Same declaration count as the base; values change:
+
+```ts
+distillery.renderStyles(collector, undefined, { flatten: 'muted' });
+```
+
+`{ scheme: 'light' | 'dark' }` is the same idea for the built-in color scheme: emit one side's literal instead of `light-dark(...)`. It applies to every emitted block, including `alternates`. See [read values outside CSS](non-css-surfaces.md).
+
+```ts
+distillery.renderStyles(collector, undefined, { scheme: 'light' });
+```
+
+Runtime switching: the base fills `themeScope`, each alternate emits only its diff:
+
+```ts
+distillery.renderStyles(collector, undefined, {
+  alternates: [
+    { variation: 'muted', selector: '[data-eui-theme="muted"]' },
+  ],
+});
+```
+
+Independent paths compose through the cascade. Flatten `muted` and list `highContrast` as an alternate:
+
+```ts
+distillery.renderStyles(collector, undefined, {
+  flatten: 'muted',
+  alternates: [{ variation: 'highContrast' }],
+});
+```
+
+That writes muted values into `themeScope`, then the high-contrast diff (computed against the base, not against muted) inside `@media (prefers-contrast: more)`. Colliding paths do not merge: the media block's value wins inside the query. A combined variation is only needed if the high-contrast values themselves depend on which flattenable variation is selected.
+
+`:host` composes as `:host(selector)`. Media variations may omit `selector`; the diffs wrap in `@media`. Flattening a media variation does **not** replace the primary block: the base still fills `themeScope`, and the diffs wrap in `@media`. That is byte-identical to listing the same name in `alternates`.
+
+`themeValueOverrides` still apply per render for values known only at request time. They win over both `flatten` and `scheme`. Declared variations are for values known when the distillery is created. A non-CSS consumer that needs those declared values calls `distillery.resolveValues(scheme, variation?)`; that walk does not apply `themeValueOverrides`. A CSS-consuming surface that cannot resolve `light-dark()` uses `renderStyles({ scheme })` instead. See [read values outside CSS](non-css-surfaces.md).
+
+## What a variation cannot do
+
+A variation changes values for token paths that are already collected. It never changes which declarations exist. A structural response to `prefers-contrast` — replacing `box-shadow` with a border, hiding a decorative rule — belongs in the module via [`media()`](../concepts/authoring.md):
+
+```ts
+media('(prefers-contrast: more)', [
+  rule(
+    (h) => h.root,
+    decls`box-shadow: none; border: 1px solid ${tokens.colors.ink};`
+  ),
+]);
+```
+
+## When not to use a variation
+
+Anything that can diverge structurally over time — a second brand, a second product — is a second distillery with its own base tree. One distillery per library keeps registries private; see [the distillery](../concepts/distillery.md).
+
+The engine will not stop you from growing `theme` with paths that exist only so one variation can touch them. That is token feature-flagging. If a difference needs new paths or different leaf kinds, it is not a variation.

package/docs/guides/var-invariant.md

@@ -0,0 +1,24 @@
+---
+navigation_title: Test the var invariant
+description: Assert every var() in emitted CSS has a matching declaration.
+---
+
+# Test the var invariant
+
+A compact payload that references `--missing` will look fine in development if the host app's sheet happens to declare it, then break in email or SVG. `@elastic/distillate/testing` scans CSS text and reports `var(...)` names that are never declared in the same string.
+
+```ts
+import {
+  assertVarRefsHaveDeclarations,
+  findVarRefViolations,
+} from '@elastic/distillate/testing';
+
+const css = distillery.renderStyles(collector);
+assertVarRefsHaveDeclarations(css); // throws with surrounding context
+```
+
+`findVarRefViolations` returns `{ reference, context }[]` when the assertion should not throw.
+
+The scanner is whitespace-tolerant (`var( --x )`) and ignores strings, comments, and function names that merely end in `var`. A BEM selector like `.button--active:hover` is not a declaration of `--active`.
+
+This entry reaches no third-party package. Run it against both compact artifacts and readable stylesheets; the helper does not care which names you used.