@elastic/distillate 0.0.0 → 0.1.0

package/docs/guides/vs-emotion.md

@@ -0,0 +1,61 @@
+---
+navigation_title: Distillate vs CSS-in-JS
+description: When to use Distillate over Emotion, CSS Modules, static extraction, or Tailwind.
+---
+
+# Distillate vs CSS-in-JS
+
+Distillate is a **component library authoring** tool. Emotion, CSS Modules, Tailwind, and vanilla-extract are primarily **application** tools. The audiences overlap, but the core problems differ.
+
+## The positioning
+
+Use Distillate when you need **both a public stylesheet and compact self-contained artifact payloads** from the same authored source — and the library must carry no design opinions of its own.
+
+Use Emotion (or similar) when you are styling an **application directly** and have no need to export tree-shaken CSS alongside HTML.
+
+## Distillate vs Emotion
+
+Emotion generates class names at runtime by hashing template content and injecting `<style>` elements. Distillate records declarations once at module-construction time and emits CSS on demand through a collector.
+
+| | Emotion | Distillate |
+| --- | --- | --- |
+| Primary audience | Application developers | Component library authors |
+| Style authoring | `css\`...\`` at render time | `createStyleModule` once at module load |
+| Runtime variation | New template → new class | CSS custom properties (`vars`, theme tokens) |
+| Output modes | DOM injection | Stylesheet or compact artifact |
+| Tree-shaking | No — all styles inject eagerly | Artifact collector drops unreached entries |
+| Typed tokens | No | `lightDark`, `cq`, `vars` |
+| Object styles | `css({ color: 'red' })` | Not supported |
+| Keyframes | `keyframes\`...\`` | Not supported |
+| `styled.*` | Yes (`@emotion/styled`) | No |
+| Bundle constraint | Works in any bundle | One copy per runtime required |
+
+The `@elastic/distillate/emotion` entry point is a drop-in surface (`css` / `cx` / `injectGlobal`) over the same registry. It lets you keep existing call sites while gaining the collector and artifact-export path. See [Migrate from Emotion](emotion-migration.md).
+
+## When to use Distillate
+
+- You ship a component library that exports **both** a loadable stylesheet (for apps) and self-contained HTML payloads (emails, AI reply cards, SVG renders, exported reports).
+- You want typed design-token references (`tokens.colors.ink`) with pruning — unused tokens drop out of artifact CSS.
+- You need the same styles in two name modes: human-readable for development, short-identifier compact when HTML and CSS travel together.
+- You want to assert at test time that every `var(--...)` in emitted CSS has a matching declaration (`assertVarRefsHaveDeclarations`).
+
+## When not to use Distillate
+
+- **You need per-render dynamic class names.** Modules are static after construction. Put variation on CSS custom properties, not new templates per render.
+- **You are building an application, not a library.** Distillate's artifact-export path has no value when styles never leave the host app.
+- **You rely on `styled.*`, keyframes, `@supports`, or object styles.** These are unsupported.
+- **Your bundle cannot guarantee a single copy at runtime.** See [Single-copy invariant](../concepts/single-copy.md). For plugin-host architectures (Kibana-style), the platform must expose Distillate as a shared dependency.
+
+## Distillate vs CSS Modules
+
+CSS Modules scope class names per file with a bundler plugin. They do not tree-shake unused declarations, have no typed token system, and cannot emit compact payloads. Choose CSS Modules for simple scoped styles in an application; choose Distillate for a library that needs typed tokens and artifact export.
+
+## Distillate vs static extraction (Linaria / vanilla-extract)
+
+Static extraction tools run at build time and produce real CSS files with zero runtime cost. The tradeoff: they cannot follow an actual render to determine which handles were reached. Distillate's artifact collection is a **runtime** side effect of resolving class names, which is the correct model when the emitted CSS must exactly match the rendered HTML tree.
+
+Vanilla-extract offers typed token support similar to `createThemeContract`. Choose vanilla-extract if build-time extraction is a hard requirement or if runtime is forbidden (edge/serverless cold-start sensitive). Choose Distillate if artifact export or runtime reachability collection is required.
+
+## Distillate vs Tailwind
+
+Tailwind generates utility classes from a predefined scale. Distillate emits authored property blocks from tagged templates. They are not competing tools — a library can use Distillate internally while a host application uses Tailwind. The key difference: Tailwind cannot produce a compact, tree-shaken CSS payload tied to a specific render tree.

package/docs/index.md

@@ -0,0 +1,73 @@
+---
+navigation_title: Distillate
+description: Theme-agnostic CSS style engine with typed authoring, reachability collection, and readable or compact output.
+---
+
+# Distillate
+
+{{pkg}} is a CSS style engine for component libraries. You author styles once, against your own tokens. The engine emits a public stylesheet with stable names, or a tree-shaken compact payload for HTML that leaves the app.
+
+One runtime dependency, for `emotion`-style syntax: [stylis](https://github.com/thysultan/stylis.js) 4.4.0. No brand is baked in.
+
+```ts
+import { createDistillery, cq, lightDark } from '@elastic/distillate';
+
+const distillery = createDistillery({
+  prefix: 'eui',
+  themeScope: '.eui-view',
+  theme: {
+    colors: { ink: lightDark('#111', '#eee') }, // theme variable
+    gap: cq('8px', '2cqi'), // inlines as `8px`
+  },
+});
+
+const demo = distillery.createStyleModule('demo', ({ css, tokens }) => ({
+  root: css`
+    color: ${tokens.colors.ink};
+    padding: ${tokens.gap};
+  `,
+}));
+
+distillery.renderStyles(distillery.stylesheetCollector()); // default readable classes: `.demo-root`
+
+const collector = distillery.artifactCollector('compact'); // compact classes and vars: `.a`, `--a`
+collector.use(demo.handles.root);
+distillery.renderStyles(collector);
+```
+
+## How it works
+
+1. **Bind.** `createDistillery` takes a prefix and a nested theme tree; it derives `tokens` and `themeVars`.
+2. **Author.** Tagged templates (`css`, `rule`, `media`, `variants`) record every token and var they touch.
+3. **Collect.** A `StylesCollector` keeps the entries a render actually reached. Unused variants and unread custom properties drop out.
+4. **Emit.** `renderStyles` writes CSS in readable or compact names, for a full stylesheet or a single artifact.
+
+```mermaid
+flowchart LR
+    Env[DistilleryEnvironment] --> Distillery[createDistillery]
+    Distillery --> Modules[Style modules]
+    Modules --> Collector[StylesCollector]
+    Collector --> CSS[renderStyles]
+```
+
+## Why Distillate
+
+Distillate is for **component library authors** who need the same authored styles to work two ways: a public stylesheet with stable names for host applications, and a compact self-contained CSS payload for HTML that leaves the app (emails, AI reply cards, SVG renders, exported reports).
+
+- **Two outputs from one source.** Readable names for apps; compact names for payloads where HTML and CSS travel together.
+- **Reachability, not static analysis.** Collection runs during a real render — class-name resolution is the side effect that builds the collected set. Unused entries and unread theme tokens drop out automatically.
+- **Your tokens.** `tokens` is the tree you passed in. The engine never invents a palette.
+- **Emotion-shaped opt-in.** `@elastic/distillate/emotion` is `css` / `cx` / `injectGlobal` over the same registry for incremental adoption.
+- **Testable CSS.** `@elastic/distillate/testing` asserts every `var(...)` has a matching declaration.
+
+See [Distillate vs CSS-in-JS](guides/vs-emotion.md) for a side-by-side comparison with Emotion, CSS Modules, vanilla-extract, and Tailwind.
+
+## Next
+
+- [Install](getting-started/installation.md) and [quick start](getting-started/quick-start.md)
+- [The output matrix](concepts/naming-and-output.md)
+- [Declare and select variations](guides/theming.md)
+- [Read values outside CSS](guides/non-css-surfaces.md)
+- [Integrate with a React renderer](guides/react-renderer.md)
+- [Playground](https://elastic.github.io/distillate/playground/)
+- [API reference](reference/index.md)

package/docs/logo.svg

@@ -0,0 +1,7 @@
+<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M25 31H16V10C16 5.02923 20.0292 1 25 1V31Z" fill="#F04E98"/>
+<path d="M1 16C1 24.2846 7.71538 31 16 31L16 16L1 16Z" fill="#1BA9F5"/>
+<path d="M31 25C31 21.6863 28.3137 19 25 19C21.6863 19 19 21.6863 19 25C19 28.3137 21.6863 31 25 31C28.3137 31 31 28.3137 31 25Z" fill="#00BFB3"/>
+<path d="M25 31C21.6863 31 19 28.3137 19 25C19 21.6863 21.6863 19 25 19V31Z" fill="#FF957D"/>
+<path d="M8 14C11.3137 14 14 11.3137 14 8C14 4.68629 11.3137 2 8 2C4.68629 2 2 4.68629 2 8C2 11.3137 4.68629 14 8 14Z" fill="#FEC514"/>
+</svg>

package/docs/playground/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Distillate playground</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/docs/playground/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@elastic/distillate-playground",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "monaco-editor": "^0.56.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "sucrase": "^3.35.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "@vitejs/plugin-react": "^4.7.0",
+    "vite": "^6.3.6",
+    "vitest": "^4.1.11"
+  }
+}

package/docs/playground/src/app/app.tsx

@@ -0,0 +1,109 @@
+/*
+ * 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 { type ReactNode, useEffect, useState } from 'react';
+
+import { defaultSnippet, snippetById } from '../examples/snippets';
+import {
+  type CompileError,
+  compilePlayground,
+  type CompileSuccess,
+  type PlaygroundMode,
+} from '../lib/compile';
+import { ui } from '../setup/chrome';
+
+import { CssPanel } from './css_panel';
+import { EditorPanel } from './editor_panel';
+import { PreviewPanel } from './preview_panel';
+import { TokensPanel } from './tokens_panel';
+import type { CssTab, PreviewTheme } from './types';
+
+const COMPILE_DEBOUNCE_MS = 150;
+const { handles: h } = ui;
+
+export const App = (): ReactNode => {
+  const [mode, setMode] = useState<PlaygroundMode>('emotion');
+  const [theme, setTheme] = useState<PreviewTheme>('light');
+  const [cssTab, setCssTab] = useState<CssTab>('readable');
+  const [snippetId, setSnippetId] = useState(defaultSnippet.id);
+  const [sources, setSources] = useState<Record<PlaygroundMode, string>>(
+    () => ({ ...defaultSnippet.source })
+  );
+  const [display, setDisplay] = useState<CompileSuccess | null>(null);
+  const [error, setError] = useState<CompileError | null>(null);
+
+  const source = sources[mode];
+
+  const onSourceChange = (next: string): void =>
+    setSources((current) => ({ ...current, [mode]: next }));
+
+  const onSnippetChange = (id: string): void => {
+    const snippet = snippetById(id);
+    if (!snippet) {
+      return;
+    }
+    setSnippetId(snippet.id);
+    setSources({ ...snippet.source });
+  };
+
+  const onReset = (): void => {
+    const snippet = snippetById(snippetId);
+    if (!snippet) {
+      return;
+    }
+    onSourceChange(snippet.source[mode]);
+  };
+
+  useEffect(() => {
+    const timer = window.setTimeout(() => {
+      const result = compilePlayground(source, mode);
+      if (result.ok) {
+        setDisplay(result);
+        setError(null);
+      } else {
+        setError(result.error);
+      }
+    }, COMPILE_DEBOUNCE_MS);
+    return () => window.clearTimeout(timer);
+  }, [source, mode]);
+
+  const onModeChange = (next: PlaygroundMode): void => setMode(next);
+
+  return (
+    <div className={h.shell.readableName}>
+      <header className={h.top.readableName}>
+        <a className={h.brand.readableName} href="../">
+          Distillate
+        </a>
+        <h1>Playground</h1>
+      </header>
+      <div className={h.layout.readableName}>
+        <div className={h.dockSource.readableName}>
+          <EditorPanel
+            {...{
+              mode,
+              snippetId,
+              source,
+              onModeChange,
+              onReset,
+              onSnippetChange,
+              onSourceChange,
+            }}
+          />
+          <TokensPanel {...{ theme }} />
+        </div>
+        <div className={h.dockOutput.readableName}>
+          <PreviewPanel
+            {...{ display, error, theme }}
+            onThemeChange={setTheme}
+          />
+          <CssPanel {...{ cssTab, display }} onCssTabChange={setCssTab} />
+        </div>
+      </div>
+    </div>
+  );
+};

package/docs/playground/src/app/css_panel.tsx

@@ -0,0 +1,119 @@
+/*
+ * 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 { lazy, type ReactNode, Suspense, useMemo } from 'react';
+
+import type { CompileSuccess } from '../lib/compile';
+import { formatCss } from '../lib/format_css';
+import { cx, ui } from '../setup/chrome';
+
+import type { CssTab } from './types';
+
+const { handles: h } = ui;
+
+const MonacoCssEditor = lazy(async () => {
+  const { MonacoCssEditor: Editor } = await import('./monaco_css_editor');
+  return { default: Editor };
+});
+
+export interface CssPanelProps {
+  readonly display: CompileSuccess | null;
+  readonly cssTab: CssTab;
+  readonly onCssTabChange: (tab: CssTab) => void;
+}
+
+const cssForTab = (display: CompileSuccess | null, cssTab: CssTab): string => {
+  if (!display) {
+    return '';
+  }
+  if (cssTab === 'readable') {
+    return display.readableCss;
+  }
+  if (cssTab === 'compact') {
+    return display.compactCss;
+  }
+  return display.artifactCss;
+};
+
+const formatBytes = (bytes: number): string =>
+  `${bytes.toLocaleString('en-US')} B`;
+
+const savedLabel = (display: CompileSuccess): string => {
+  const { stylesheetBytes, artifactBytes } = display;
+  if (stylesheetBytes === 0) {
+    return '0% smaller';
+  }
+  const pct = Math.round((1 - artifactBytes / stylesheetBytes) * 100);
+  if (pct === 0) {
+    return 'same size';
+  }
+  if (pct < 0) {
+    return `${Math.abs(pct)}% larger`;
+  }
+  return `${pct}% smaller`;
+};
+
+export const CssPanel = ({
+  display,
+  cssTab,
+  onCssTabChange,
+}: CssPanelProps): ReactNode => {
+  const cssText = cssForTab(display, cssTab);
+  const formatted = useMemo(() => formatCss(cssText), [cssText]);
+  const value = formatted || '/* No CSS emitted yet. */';
+
+  return (
+    <section className={cx(h.panel, h.dockCss)}>
+      <div className={h.toolbar.readableName}>
+        <h2>Generated CSS</h2>
+        <div
+          className={h.segmented.readableName}
+          role="group"
+          aria-label="CSS output">
+          <button
+            type="button"
+            aria-pressed={cssTab === 'readable'}
+            onClick={() => onCssTabChange('readable')}>
+            Readable
+          </button>
+          <button
+            type="button"
+            aria-pressed={cssTab === 'compact'}
+            onClick={() => onCssTabChange('compact')}>
+            Compact
+          </button>
+          <button
+            type="button"
+            aria-pressed={cssTab === 'artifact'}
+            onClick={() => onCssTabChange('artifact')}>
+            Artifact
+          </button>
+        </div>
+      </div>
+      {display ? (
+        <p className={h.cssStats.readableName}>
+          <span>Full stylesheet {formatBytes(display.stylesheetBytes)}</span>
+          <span aria-hidden="true">·</span>
+          <span>Compact artifact {formatBytes(display.artifactBytes)}</span>
+          <span aria-hidden="true">·</span>
+          <span>{savedLabel(display)}</span>
+          <a href="../guides/compact-artifacts">How this is measured</a>
+        </p>
+      ) : null}
+      <Suspense
+        fallback={
+          <div
+            className={h.cssOut.readableName}
+            data-pg-monaco=""
+            aria-busy="true"
+          />
+        }>
+        <MonacoCssEditor {...{ value }} />
+      </Suspense>
+    </section>
+  );
+};

package/docs/playground/src/app/editor_panel.tsx

@@ -0,0 +1,87 @@
+/*
+ * 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 { type ChangeEvent, lazy, type ReactNode, Suspense } from 'react';
+
+import { snippetCatalog } from '../examples/snippets';
+import type { PlaygroundMode } from '../lib/compile';
+import { cx, ui } from '../setup/chrome';
+
+const { handles: h } = ui;
+
+const MonacoSourceEditor = lazy(async () => {
+  const { MonacoSourceEditor: Editor } = await import('./monaco_source_editor');
+  return { default: Editor };
+});
+
+export interface EditorPanelProps {
+  readonly mode: PlaygroundMode;
+  readonly snippetId: string;
+  readonly source: string;
+  readonly onModeChange: (mode: PlaygroundMode) => void;
+  readonly onReset: () => void;
+  readonly onSnippetChange: (id: string) => void;
+  readonly onSourceChange: (source: string) => void;
+}
+
+export const EditorPanel = ({
+  mode,
+  snippetId,
+  source,
+  onModeChange,
+  onReset,
+  onSnippetChange,
+  onSourceChange,
+}: EditorPanelProps): ReactNode => {
+  return (
+    <section className={cx(h.panel, h.editor)}>
+      <div className={h.toolbar.readableName}>
+        <div
+          className={h.segmented.readableName}
+          role="group"
+          aria-label="Authoring mode">
+          <button
+            type="button"
+            aria-pressed={mode === 'emotion'}
+            onClick={() => onModeChange('emotion')}>
+            Emotion css
+          </button>
+          <button
+            type="button"
+            aria-pressed={mode === 'native'}
+            onClick={() => onModeChange('native')}>
+            Native module
+          </button>
+        </div>
+        <label className={h.snippetSelect.readableName}>
+          <span>Example</span>
+          <select
+            value={snippetId}
+            aria-label="Example"
+            onChange={(event: ChangeEvent<HTMLSelectElement>) => {
+              onSnippetChange(event.target.value);
+            }}>
+            {snippetCatalog.map((snippet) => (
+              <option key={snippet.id} value={snippet.id}>
+                {snippet.label}
+              </option>
+            ))}
+          </select>
+        </label>
+        <button
+          type="button"
+          className={h.ghost.readableName}
+          onClick={onReset}>
+          Reset
+        </button>
+      </div>
+      <Suspense fallback={<div data-pg-monaco="" aria-busy="true" />}>
+        <MonacoSourceEditor {...{ mode, source, onSourceChange }} />
+      </Suspense>
+    </section>
+  );
+};

package/docs/playground/src/app/index.ts

@@ -0,0 +1,8 @@
+/*
+ * 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.
+ */
+
+export { App } from './app';

package/docs/playground/src/app/monaco_css_editor.tsx

@@ -0,0 +1,84 @@
+/*
+ * 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 'monaco-editor/languages/definitions/css/register.js';
+
+import { type ReactNode, useEffect, useRef } from 'react';
+import { editor, Uri } from 'monaco-editor/editor.js';
+
+import { ui } from '../setup/chrome';
+import { CSS_THEME, ensureMonaco } from '../setup/monaco_env';
+
+const { handles: h } = ui;
+
+const MODEL_URI = 'file:///playground.css';
+
+interface MonacoCssEditorProps {
+  readonly value: string;
+}
+
+export const MonacoCssEditor = ({ value }: MonacoCssEditorProps): ReactNode => {
+  const hostRef = useRef<HTMLDivElement>(null);
+  const editorRef = useRef<editor.IStandaloneCodeEditor | null>(null);
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) {
+      return;
+    }
+    const initialValue = value;
+    ensureMonaco();
+    const uri = Uri.parse(MODEL_URI);
+    const existing = editor.getModel(uri);
+    const model = existing ?? editor.createModel(initialValue, 'css', uri);
+    if (existing && existing.getValue() !== initialValue) {
+      existing.setValue(initialValue);
+    }
+    const instance = editor.create(host, {
+      model,
+      theme: CSS_THEME,
+      readOnly: true,
+      domReadOnly: true,
+      automaticLayout: true,
+      minimap: { enabled: false },
+      fontSize: 13,
+      fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, monospace',
+      lineHeight: 20,
+      tabSize: 2,
+      insertSpaces: true,
+      scrollBeyondLastLine: false,
+      wordWrap: 'on',
+      padding: { top: 12, bottom: 12 },
+      fixedOverflowWidgets: true,
+      ariaLabel: 'Generated CSS',
+      renderLineHighlight: 'none',
+      overviewRulerLanes: 0,
+      hideCursorInOverviewRuler: true,
+      contextmenu: false,
+      links: false,
+      scrollbar: { verticalScrollbarSize: 10, horizontalScrollbarSize: 10 },
+    });
+    editorRef.current = instance;
+    return () => {
+      instance.dispose();
+      editorRef.current = null;
+      model.dispose();
+    };
+  }, []);
+
+  useEffect(() => {
+    const instance = editorRef.current;
+    if (!instance || instance.getValue() === value) {
+      return;
+    }
+    instance.setValue(value);
+  }, [value]);
+
+  return (
+    <div ref={hostRef} className={h.cssOut.readableName} data-pg-monaco="" />
+  );
+};