@elastic/distillate 0.0.0 → 0.1.0

package/dist/var_invariant.d.ts

@@ -0,0 +1,25 @@
+/** A `var(...)` whose custom property is never declared in the same CSS text. */
+export interface VarInvariantViolation {
+    /** The undeclared custom property name (e.g. `--aui-color-bg`). */
+    readonly reference: string;
+    /** Surrounding CSS text for error reporting. */
+    readonly context: string;
+}
+/** Collects every custom property declared in a declaration position in `css`. */
+export declare const collectDeclaredCustomProperties: (css: string) => Set<string>;
+/** Collects all custom property names referenced inside `var(...)` calls in `css`. */
+export declare const collectReferencedCustomProperties: (css: string) => readonly string[];
+/**
+ * Returns all `var(...)` references whose custom property is never declared in `css`.
+ *
+ * @param css Full CSS text to scan.
+ */
+export declare const findVarRefViolations: (css: string) => readonly VarInvariantViolation[];
+/**
+ * Throws if any `var(...)` in `css` has no matching custom-property declaration.
+ *
+ * @param css Full CSS text to scan.
+ * @throws If any reference has no declaration in the same text.
+ */
+export declare const assertVarRefsHaveDeclarations: (css: string) => void;
+//# sourceMappingURL=var_invariant.d.ts.map

package/dist/var_invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"var_invariant.d.ts","sourceRoot":"","sources":["../src/var_invariant.ts"],"names":[],"mappings":"AAYA,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAyDD,kFAAkF;AAClF,eAAO,MAAM,+BAA+B,GAAI,KAAK,MAAM,KAAG,GAAG,CAAC,MAAM,CAUvE,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,iCAAiC,GAC5C,KAAK,MAAM,KACV,SAAS,MAAM,EAUjB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,KAAK,MAAM,KACV,SAAS,qBAAqB,EAgBhC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GAAI,KAAK,MAAM,KAAG,IAY3D,CAAC"}

package/dist/var_invariant.js

@@ -0,0 +1,108 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { isOpaque, scanCss } from './css_scan.js';
+const DECLARATION_RE = /(--[A-Za-z_][\w-]*)\s*:/g;
+const REFERENCE_RE = /var\(\s*(--[A-Za-z_][\w-]*)/g;
+const scan = (css) => {
+    const masked = [];
+    const blockAt = [];
+    for (const span of scanCss(css)) {
+        const blank = isOpaque(span);
+        for (let offset = 0; offset < span.text.length; offset += 1) {
+            masked.push(blank ? ' ' : (span.text[offset] ?? ''));
+            blockAt.push(span.block);
+        }
+    }
+    return { masked: masked.join(''), blockAt };
+};
+/**
+ * A custom property is declared where a declaration can start: inside a
+ * declarations block, as the first thing after `{` or `;`. A selector carrying
+ * a BEM-style modifier and a pseudo-class (`.button--active:hover`) matches the
+ * same characters and declares nothing.
+ */
+const isDeclarationStart = ({ masked, blockAt }, index) => {
+    if (blockAt[index] !== 'declarations') {
+        return false;
+    }
+    for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+        const char = masked[cursor];
+        if (char === undefined || !/\s/.test(char)) {
+            return char === '{' || char === ';';
+        }
+    }
+    return false;
+};
+/**
+ * `var` has to open a function token rather than end a longer identifier:
+ * `--expr:myvar(--x)` names some other function.
+ */
+const isFunctionTokenStart = (masked, index) => {
+    const before = masked[index - 1];
+    return before === undefined || !/[\w\\-]/.test(before);
+};
+/** Collects every custom property declared in a declaration position in `css`. */
+export const collectDeclaredCustomProperties = (css) => {
+    const scanned = scan(css);
+    const declared = new Set();
+    for (const match of scanned.masked.matchAll(DECLARATION_RE)) {
+        const name = match[1];
+        if (name && isDeclarationStart(scanned, match.index ?? 0)) {
+            declared.add(name);
+        }
+    }
+    return declared;
+};
+/** Collects all custom property names referenced inside `var(...)` calls in `css`. */
+export const collectReferencedCustomProperties = (css) => {
+    const { masked } = scan(css);
+    const names = [];
+    for (const match of masked.matchAll(REFERENCE_RE)) {
+        const name = match[1];
+        if (name && isFunctionTokenStart(masked, match.index ?? 0)) {
+            names.push(name);
+        }
+    }
+    return names;
+};
+/**
+ * Returns all `var(...)` references whose custom property is never declared in `css`.
+ *
+ * @param css Full CSS text to scan.
+ */
+export const findVarRefViolations = (css) => {
+    const { masked } = scan(css);
+    const declared = collectDeclaredCustomProperties(css);
+    const violations = [];
+    for (const match of masked.matchAll(REFERENCE_RE)) {
+        const ref = match[1];
+        const index = match.index ?? 0;
+        if (!ref || declared.has(ref) || !isFunctionTokenStart(masked, index)) {
+            continue;
+        }
+        violations.push({
+            reference: ref,
+            context: css.slice(Math.max(0, index - 40), index + ref.length + 8),
+        });
+    }
+    return violations;
+};
+/**
+ * Throws if any `var(...)` in `css` has no matching custom-property declaration.
+ *
+ * @param css Full CSS text to scan.
+ * @throws If any reference has no declaration in the same text.
+ */
+export const assertVarRefsHaveDeclarations = (css) => {
+    const violations = findVarRefViolations(css);
+    if (violations.length === 0) {
+        return;
+    }
+    const lines = violations.map(({ reference, context }) => `- ${reference} referenced near "${context.replace(/\s+/g, ' ')}"`);
+    throw new Error(`${violations.length} var(...) reference(s) without a matching declaration:\n${lines.join('\n')}`);
+};
+//# sourceMappingURL=var_invariant.js.map

package/dist/var_invariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"var_invariant.js","sourceRoot":"","sources":["../src/var_invariant.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport { type CssBlockKind, isOpaque, scanCss } from './css_scan';\n\nconst DECLARATION_RE = /(--[A-Za-z_][\\w-]*)\\s*:/g;\nconst REFERENCE_RE = /var\\(\\s*(--[A-Za-z_][\\w-]*)/g;\n\n/** A `var(...)` whose custom property is never declared in the same CSS text. */\nexport interface VarInvariantViolation {\n  /** The undeclared custom property name (e.g. `--aui-color-bg`). */\n  readonly reference: string;\n  /** Surrounding CSS text for error reporting. */\n  readonly context: string;\n}\n\ninterface ScannedCss {\n  /**\n   * `css` with comments, strings, `url(...)` tokens, and escapes blanked to\n   * spaces, positions preserved. A `var(` inside a string is text, a `;`\n   * inside an escape is part of a value, and neither should match here.\n   */\n  readonly masked: string;\n  /** The enclosing block kind at each character offset. */\n  readonly blockAt: readonly CssBlockKind[];\n}\n\nconst scan = (css: string): ScannedCss => {\n  const masked: string[] = [];\n  const blockAt: CssBlockKind[] = [];\n  for (const span of scanCss(css)) {\n    const blank = isOpaque(span);\n    for (let offset = 0; offset < span.text.length; offset += 1) {\n      masked.push(blank ? ' ' : (span.text[offset] ?? ''));\n      blockAt.push(span.block);\n    }\n  }\n  return { masked: masked.join(''), blockAt };\n};\n\n/**\n * A custom property is declared where a declaration can start: inside a\n * declarations block, as the first thing after `{` or `;`. A selector carrying\n * a BEM-style modifier and a pseudo-class (`.button--active:hover`) matches the\n * same characters and declares nothing.\n */\nconst isDeclarationStart = (\n  { masked, blockAt }: ScannedCss,\n  index: number\n): boolean => {\n  if (blockAt[index] !== 'declarations') {\n    return false;\n  }\n  for (let cursor = index - 1; cursor >= 0; cursor -= 1) {\n    const char = masked[cursor];\n    if (char === undefined || !/\\s/.test(char)) {\n      return char === '{' || char === ';';\n    }\n  }\n  return false;\n};\n\n/**\n * `var` has to open a function token rather than end a longer identifier:\n * `--expr:myvar(--x)` names some other function.\n */\nconst isFunctionTokenStart = (masked: string, index: number): boolean => {\n  const before = masked[index - 1];\n  return before === undefined || !/[\\w\\\\-]/.test(before);\n};\n\n/** Collects every custom property declared in a declaration position in `css`. */\nexport const collectDeclaredCustomProperties = (css: string): Set<string> => {\n  const scanned = scan(css);\n  const declared = new Set<string>();\n  for (const match of scanned.masked.matchAll(DECLARATION_RE)) {\n    const name = match[1];\n    if (name && isDeclarationStart(scanned, match.index ?? 0)) {\n      declared.add(name);\n    }\n  }\n  return declared;\n};\n\n/** Collects all custom property names referenced inside `var(...)` calls in `css`. */\nexport const collectReferencedCustomProperties = (\n  css: string\n): readonly string[] => {\n  const { masked } = scan(css);\n  const names: string[] = [];\n  for (const match of masked.matchAll(REFERENCE_RE)) {\n    const name = match[1];\n    if (name && isFunctionTokenStart(masked, match.index ?? 0)) {\n      names.push(name);\n    }\n  }\n  return names;\n};\n\n/**\n * Returns all `var(...)` references whose custom property is never declared in `css`.\n *\n * @param css Full CSS text to scan.\n */\nexport const findVarRefViolations = (\n  css: string\n): readonly VarInvariantViolation[] => {\n  const { masked } = scan(css);\n  const declared = collectDeclaredCustomProperties(css);\n  const violations: VarInvariantViolation[] = [];\n  for (const match of masked.matchAll(REFERENCE_RE)) {\n    const ref = match[1];\n    const index = match.index ?? 0;\n    if (!ref || declared.has(ref) || !isFunctionTokenStart(masked, index)) {\n      continue;\n    }\n    violations.push({\n      reference: ref,\n      context: css.slice(Math.max(0, index - 40), index + ref.length + 8),\n    });\n  }\n  return violations;\n};\n\n/**\n * Throws if any `var(...)` in `css` has no matching custom-property declaration.\n *\n * @param css Full CSS text to scan.\n * @throws If any reference has no declaration in the same text.\n */\nexport const assertVarRefsHaveDeclarations = (css: string): void => {\n  const violations = findVarRefViolations(css);\n  if (violations.length === 0) {\n    return;\n  }\n  const lines = violations.map(\n    ({ reference, context }) =>\n      `- ${reference} referenced near \"${context.replace(/\\s+/g, ' ')}\"`\n  );\n  throw new Error(\n    `${violations.length} var(...) reference(s) without a matching declaration:\\n${lines.join('\\n')}`\n  );\n};\n"]}

package/docs/concepts/authoring.md

@@ -0,0 +1,115 @@
+---
+navigation_title: Authoring
+description: Style modules, handles, nested templates, rules, media, and variants.
+---
+
+# Authoring
+
+A style module is a named group of entries. The factory runs once; the returned handles are static. The bind matches [quick start](../getting-started/quick-start.md).
+
+```ts
+import {
+  createDistillery,
+  cq,
+  lightDark,
+  rule,
+  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 callout = distillery.createStyleModule('callout', ({ css, decls, tokens }) => ({
+  root: css`
+    padding: ${tokens.gap};
+    color: ${tokens.colors.ink};
+    &:hover {
+      color: ${tokens.colors.accent};
+    }
+    @media (min-width: 600px) {
+      padding: 16px;
+    }
+  `, <1>
+  title: css`
+    font-weight: 600;
+  `,
+  tone: variants(
+    ['calm', 'loud'] as const,
+    (tone) =>
+      css`
+        outline-color: ${tone === 'calm' ? tokens.colors.surface : tokens.colors.accent};
+      `
+  ), <2>
+  hoverTitle: rule(
+    (h) => `${h.root}:hover ${h.title}`,
+    decls`
+      color: ${tokens.colors.accent};
+    `
+  ), <3>
+}));
+```
+
+1. Nested `&:hover` and `@media` stay on this handle and collect with it.
+2. Variant keys. `collector.use(callout)` skips these until you name `tone.loud`.
+3. Combines two handles. Auto-collects only when both `root` and `title` are live.
+
+What you get back is not a class name. A **handle** carries a `key`, a `readableName`, and the declarations the collector needs. The same handle can emit `.callout-root` or `.a` depending on the resolver.
+
+## Templates
+
+| Helper                            | Role                                                                                                                 |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `css`                             | Handle. Nested `&` and `@media` flatten into sibling rules. Also a top-level export.                                 |
+| `decls`                           | Declaration block for `rule(...)`. Also a top-level export.                                                          |
+| `rule(selector, decls, options?)` | Selector plus declarations. `auto` (default `true`) self-collects when every handle the selector reads is collected. |
+| `media(query, rules)`             | `@media` block.                                                                                                      |
+| `container(query, rules)`         | `@container` block. Same collector rank as `media`.                                                                  |
+| `variants(keys, factory)`         | One entry per key, marked `variant` so `collector.use(module)` skips it.                                             |
+| `mapDomain(keys, factory)`        | Same mapping as `variants`, with no collector side effect. Use it on non-CSS surfaces.                               |
+
+`@container` inside a `css` template is rejected; use the `container(...)` factory. `@supports` and `keyframes` are not supported. Object styles (`css({ color: 'red' })`) are not supported on the emotion entry.
+
+### When to reach for each helper
+
+**`css` with nesting** is the default. Nested `&` and `@media` blocks inside `css` are all part of that handle — they collect together and share its class name.
+
+**`rule`** is for selectors that combine two handles (`${h.root}:hover ${h.title}`). The key behaviour: `rule` records every handle the selector reads as a dependency, and only auto-collects when all of them are live. Use `{ auto: false }` to require an explicit `collector.use(ruleEntry)` instead of piggybacking on dependency collection.
+
+**`media` / `container`** as explicit factories wrap multiple handles in one block and collect independently. Prefer nesting `@media` inside `css` when a block is local to one handle. Reach for `media(...)` when the block spans multiple entries or needs to be toggled separately from them. The `container(...)` factory is always required for `@container` — it cannot be nested inside `css`.
+
+## Static after construction
+
+Anything that varies at runtime belongs on a CSS custom property (`vars`, theme tokens), not on a new template per render. Immutable modules are what makes dependency capture and reachability cheap.
+
+## Variants
+
+`collector.use(callout)` does not collect `callout.handles.tone.loud`. Name the variant you rendered:
+
+```ts
+const collector = distillery.artifactCollector('compact');
+collector.useHandles([callout.handles.root, callout.handles.tone.loud]);
+```
+
+`stylesheetCollector()` includes every variant because it calls `useAllEntries`.
+
+## Selector rules
+
+`hoverTitle` above records `root` and `title` as dependencies. Auto-collection fires only when every dependency is already collected — a `button + other` rule stays out until both handles are in.
+
+```ts
+rule((h) => `${h.button}:hover`, decls`color: red;`, { auto: false }); // requires collector.use(ruleEntry)
+```
+
+## Combining class names
+
+`combineClassNames(context, ...handles)` forwards to `context.resolveClassName`. In a React renderer, that context is the collector-backed resolver you pass down the tree. See [Integrate with a React renderer](../guides/react-renderer.md).

package/docs/concepts/collection.md

@@ -0,0 +1,66 @@
+---
+navigation_title: Reachability collection
+description: StylesCollector, use versus useHandles, theme-var reachability, and per-handle default narrowing.
+---
+
+# Reachability collection
+
+A `StylesCollector` is the set of entries that will ship. Class-name resolution collects as a side effect: the renderer names a handle, the handle's rules come along, and unread variables drop out.
+
+Prefer the distillery helpers over constructing a collector yourself:
+
+```ts
+const collector = distillery.artifactCollector('compact');
+collector.use(demo.handles.root); // only this handle ships
+const css = distillery.renderStyles(collector);
+```
+
+`artifactCollector` starts empty. `stylesheetCollector(names?)` defaults to `'readable'` and preloads every registered module via `useAllEntries`. Both accept an optional `{ warn }` so hosts can capture no-op-handle warnings when `createDistillery({ dev: true })`.
+
+## What each method collects
+
+| Method                  | Effect                                                                                                                                       |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `use(module)`           | Non-variant entries on the module. Variants stay out.                                                                                        |
+| `use(entry)`            | One handle, rule, or media block.                                                                                                            |
+| `useHandles(handles)`   | Those handles, then any `auto` rule or media-inner-rule whose selector deps are all present. Media blocks include only the live inner rules. |
+| `useAllEntries(module)` | Every entry, including variants. Used by the stylesheet target.                                                                              |
+| `useThemeVar(path)`     | Marks a theme token path reachable even if no collected declaration reads it.                                                                |
+
+Paths are slash-delimited (`colors/ink`), matching `themeVars` keys. There is no `StylesCollector.artifact(...)` static factory.
+
+## Strict selector deps
+
+A rule that reads two handles (`button + other`) does not auto-collect when only `button` is named. Nested `&:hover` on a handle auto-collects with that handle. A nested block on an uncollected handle is dropped from artifacts.
+
+## Theme-var reachability
+
+`renderThemeVars` emits a declaration for every path in `collectedThemeDeps`. Those paths come from tokens interpolated into collected declarations, default-marker value deps that survive [per-handle narrowing](#per-handle-default-narrowing), and explicit `useThemeVar(path)` calls.
+
+The emitted body CSS is not consulted. A collected path still ships if no remaining rule writes a textual `var(...)` for it. `useThemeVar` is the supported way to force a theme declaration that the body does not read.
+
+Named variations, media variations, and `{ alternates }` still render through `renderThemeVars`. They change which values and extra blocks are written for the already-collected paths; they do not decide reachability.
+
+## Per-handle default narrowing
+
+`reachableDefaults(handle, groupPath)` is the finest pruning layer. When a handle declaration contains a local-var default group (`${look}`), emission keeps only the keys that handle actually reads — plus keys read by any collected rule whose selector targets that handle.
+
+A default key that is declared but never referenced does not ship, and neither does its theme dep. `names module-local var groups with the environment prefix and prunes unreachable defaults` in `src/distillery.test.ts` is the executable spec.
+
+### Rule-level defaults emit every key
+
+`renderRule` has no host handle. Default markers on a rule (or a media-inner-rule) therefore emit **every** listed key, and `finalizeDeps` mirrors that by including all of them in the compact registry. Authors normally put `${group}` on handle declarations; if a rule ever carries a default marker, nothing inside that marker is pruned.
+
+## No-op handle pruning
+
+A handle is no-op when its declarations produce nothing **and** no rule targets it. With `createDistillery({ dev: true })`, Distillate warns once per such handle (process-wide) so the author can delete the empty template. Production stays silent: `dev` defaults to `false`. `{ warn }` on a collector overrides the sink; it does not turn warnings on. The single-copy guard always warns and is not gated by `dev`.
+
+Empty blocks never ship: `renderStyles` drops a handle or rule whose rendered body is blank, and a media block whose inner fragments are all blank.
+
+Dropping the class name itself happens only in `compact` mode. Readable names are stable, so a consumer stylesheet or test may scope on one. Compact names have no such contract, and no-op handles do not consume a compact slot. `useHandles` returns the retained handles so hosts can build the class string without changing `combineClassNames`.
+
+A handle is targeted when some rule, or some inner rule of an `@media` / `@container` block, reads it in a selector. `recordRuleDeps` fills that in for nested `&` rules too, so a handle with an empty self block and a real `& h2` stays. A nested block with no rules inside it (`@media (...) {}`) targets nothing and does not rescue its owner. A local-var marker counts as content, so marker-bearing handles are never pruned.
+
+## Resolvers
+
+`collector.createResolver()` snapshots the current handle and var keys. In compact mode, names are assigned from the **sorted** key set, so call it after collection is complete. `renderStyles(collector)` does that for you when you omit the resolver argument.

package/docs/concepts/distillery.md

@@ -0,0 +1,47 @@
+---
+navigation_title: The distillery
+description: Bind prefix and a theme tree with createDistillery.
+---
+
+# The distillery
+
+`createDistillery(options)` binds the engine to one component library. The returned object is destructure-safe (no `this`): `environment`, `tokens`, `themeVars`, `resolveValues`, `registry`, `dev`, `createStyleModule`, `primitiveStyles`, `artifactCollector`, `stylesheetCollector`, `renderStyles`, `createNameResolver`.
+
+```ts
+import { createDistillery, cq, lightDark } from '@elastic/distillate';
+
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme: {
+    colors: {
+      ink: lightDark('#111', '#eee'),
+    },
+    gap: cq('8px', '2cqi'),
+  },
+  sharedVars: ['vars/app/tone/foreground'],
+});
+```
+
+`environment` is the **resolved** environment: derived `themeVars` and `tokens`, plus `prefix` and `themeScope`. `distillery.tokens` aliases `environment.tokens`; `distillery.themeVars` aliases `environment.themeVars`. Input is `DistilleryOptions`.
+
+Each distillery owns a private `StyleRegistry`. Two libraries in one process should each call `createDistillery` with their own prefix so readable names cannot collide across brands. A second brand that can diverge structurally is a second distillery, not a [variation](../guides/theming.md#when-not-to-use-a-variation).
+
+## Options
+
+| Field        | Role                                                                                                                                             |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `prefix`     | CSS identifier segment used in `cssVarName(prefix, path)` readable custom properties.                                                            |
+| `themeScope` | Selector wrapping the emitted theme-variable block (`.eui-view`, `:host`, …).                                                                    |
+| `theme`      | Nested value tree. Strings and `lightDark` leaves become theme vars; `cq` / `scaleToken` leaves inline. Keys match `/^[A-Za-z_][A-Za-z0-9_]*$/`. |
+| `sharedVars` | Optional cross-module contextual-var paths. Names derive via `cssVarName`. Module-local `vars(...)` groups are not listed here.                  |
+| `variations` | Optional named value-only diffs of `theme`. Declaring a variation does not emit it. See [theming](../guides/theming.md).                         |
+| `dev`        | Optional. When `true`, collectors warn about no-op handles. Default `false`. Does not affect the single-copy guard.                              |
+
+`prefix` is validated at construction. Theme-tree keys that contain `-` throw. `themeVars` and `sharedVars` that hyphenate to the same readable custom-property name throw. `lightDark` values that are not CSS `<color>` throw. Named `variations` that introduce unknown paths or disagree on leaf kind throw.
+
+See [declare and select variations](../guides/theming.md) for render-time `flatten`, `scheme`, and `alternates`. `resolveValues(scheme, variation?)` returns the same tree as nested literal strings for a non-CSS surface; `renderStyles({ scheme })` emits the stylesheet with that scheme already chosen. See [read values outside CSS](../guides/non-css-surfaces.md).
+
+`primitiveStyles(name, factory)` is the same registry path as `createStyleModule`, with `factory` receiving `{ style, tokens }` instead of the full authoring API. Use it when a module only needs handles and tokens.
+
+See [environment reference](../reference/environment.md) for field-level types.

package/docs/concepts/index.md

@@ -0,0 +1,18 @@
+---
+navigation_title: Concepts
+description: Distillery, tokens, authoring, collection, naming, and the single-copy invariant.
+---
+
+# Concepts
+
+How Distillate turns tagged templates into CSS, in engine order: bind, author, collect, emit.
+
+- [The distillery](distillery.md) — `createDistillery` and `DistilleryOptions`
+- [Tokens and vars](tokens.md) — theme trees, `lightDark`, `cq`, `contextualVar`, `vars`
+- [Authoring](authoring.md) — modules, handles, `css`, `rule`, `media`, `variants`
+- [Reachability collection](collection.md) — `StylesCollector`
+- [Naming and output](naming-and-output.md) — the four-way matrix
+- [Ordering and specificity](ordering.md) — base rules before at-rules
+- [Single-copy invariant](single-copy.md) — one loaded copy of the package
+
+Named variations are a guide: [Declare and select variations](../guides/theming.md). Literal values for non-CSS surfaces: [Read values outside CSS](../guides/non-css-surfaces.md).

package/docs/concepts/naming-and-output.md

@@ -0,0 +1,123 @@
+---
+navigation_title: Naming and output
+description: Artifact versus stylesheet, compact versus readable, with a worked example per quadrant.
+---
+
+# Naming and output
+
+Two independent axes. **Target** is how much CSS you want. **Name mode** is how classes and custom properties are spelled.
+
+|                  | `readable`                                        | `compact`                                                      |
+| ---------------- | ------------------------------------------------- | -------------------------------------------------------------- |
+| **`stylesheet`** | Public sheet. `.demo-root`, `--eui-colors-ink`.   | Minified names for the full sheet. Unusual.                    |
+| **`artifact`**   | Readable names, tree-shaken to collected handles. | Minimal payload. `.a`, `--b`. HTML and CSS must ship together. |
+
+Empty declaration blocks never ship in any quadrant. In the two `compact` quadrants, a handle that is empty and untargeted is also dropped from collection, so it consumes no compact name and is omitted from `useHandles`'s return value. Readable collectors keep the class name so external selectors can still target it.
+
+Same module for every quadrant:
+
+```ts
+const demo = distillery.createStyleModule('demo', ({ css, tokens }) => ({
+  root: css`
+    color: ${tokens.colors.ink};
+    padding: ${tokens.gap};
+  `,
+  unused: css`
+    color: ${tokens.colors.accent};
+  `, <1>
+}));
+```
+
+1. Collected only by `stylesheetCollector()`. Artifact collectors that `use(root)` drop this handle and `--eui-colors-accent`.
+
+## Stylesheet + readable
+
+```ts
+distillery.renderStyles(distillery.stylesheetCollector());
+```
+
+Includes `unused`. Theme vars use `cssVarName(prefix, path)`:
+
+```css
+.eui-view {
+  --eui-colors-ink: light-dark(#111, #eee);
+  --eui-colors-accent: light-dark(#06c, #8cf);
+}
+.demo-root {
+  color: var(--eui-colors-ink);
+  padding: 8px;
+}
+.demo-unused {
+  color: var(--eui-colors-accent);
+}
+```
+
+Use this in an app that loads one CSS file and writes `class={handle.readableName}`.
+
+## Stylesheet + compact
+
+```ts
+distillery.renderStyles(distillery.stylesheetCollector('compact'));
+```
+
+Still every entry, but classes and compacted theme vars are short identifiers assigned from sorted keys. Only useful if the markup that refers to those classes was emitted with the same resolver.
+
+## Artifact + readable
+
+```ts
+const collector = distillery.artifactCollector('readable');
+collector.use(demo.handles.root);
+distillery.renderStyles(collector);
+```
+
+`unused` and `--eui-colors-accent` are gone. Class names stay stable:
+
+```css
+.eui-view {
+  --eui-colors-ink: light-dark(#111, #eee);
+}
+.demo-root {
+  color: var(--eui-colors-ink);
+  padding: 8px;
+}
+```
+
+## Artifact + compact
+
+```ts
+const collector = distillery.artifactCollector('compact');
+collector.use(demo.handles.root);
+distillery.renderStyles(collector);
+```
+
+```css
+.eui-view {
+  --a: light-dark(#111, #eee);
+}
+.a {
+  color: var(--a);
+  padding: 8px;
+}
+```
+
+This is the payload target: emails, SVG, exported HTML, agent replies. Compact names are **not** stable across different collected sets. Always emit HTML and CSS from the same collector/resolver pair.
+
+## Render options
+
+```ts
+distillery.renderStyles(collector, resolver, {
+  flatten: 'muted', <1>
+  alternates: [
+    { variation: 'muted', selector: '[data-eui-theme="muted"]' }, <2>
+  ],
+  themeValueOverrides: { 'colors/ink': '#000' }, <3>
+});
+```
+
+1. Flatten this variation into `themeScope`. Same declaration count as the base; values change. A media variation does not replace the primary block.
+2. Emit only this variation's diff under a selector the consuming page supplies.
+3. Replaces the light/dark pair with a single value. Wins over the flattened variation.
+
+Custom-property names always follow `cssVarName(prefix, path)`: `--${prefix}-${path}` with `/` joined on `-` and a leading `vars/` stripped.
+
+See [declare and select variations](../guides/theming.md).

package/docs/concepts/ordering.md

@@ -0,0 +1,61 @@
+---
+navigation_title: Ordering and specificity
+description: Base rules emit before every media and container block.
+---
+
+# Ordering and specificity
+
+`@media` and `@container` add no specificity. When a base rule and a conditional override target the same selector, **source order** decides the winner. Distillate therefore emits every non-conditional entry first, then every `@media` / `@container` block, globally — not per module.
+
+To override a base declaration at a breakpoint, put the override in `media(...)` or `container(...)` (or nest `@media` inside `css`). Do not rely on module registration order.
+
+```ts
+import {
+  createDistillery,
+  media,
+  rule,
+} from '@elastic/distillate';
+
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme: {},
+});
+
+distillery.createStyleModule('zebra', ({ css, decls }) => ({
+  root: css`
+    grid-template-columns: repeat(4, 1fr);
+  `,
+  responsive: media('(max-width: 620px)', [
+    rule(
+      (selectors) => `${selectors.root}`,
+      decls`
+        grid-template-columns: 1fr;
+      `
+    ),
+  ]),
+}));
+
+distillery.renderStyles(distillery.stylesheetCollector());
+```
+
+```css
+.zebra-root {
+  grid-template-columns: repeat(4, 1fr);
+}
+@media (max-width: 620px) {
+  .zebra-root {
+    grid-template-columns: 1fr;
+  }
+}
+```
+
+`container(...)` keeps `kind: 'media'` so it shares that rank. Nested `@media` inside `css` flattens to the same at-rule bucket.
+
+## Local var overlays
+
+`${group}` defaults and `${group.set()}` overrides have equal specificity when both classes are on the same element. Distillate emits every non-override entry first, then every `.set()` override, globally — not per handle name — so the stacked modifier wins.
+
+## Emotion composition
+
+Independent `css` calls have no guaranteed order relative to each other. `cx(a, b)` only joins class names; it does not order the stylesheet. To override, interpolate (`css\`${base} color: red;\``). The composed declarations re-target the composing class in source order (last wins).