@handamade/psi-tokens 0.19.0 → 0.21.0

package/README.md

@@ -51,6 +51,24 @@ const { filename, source, registration } = serializeCustomerTheme(pair); // cust
 - `deriveTheme` solves both members of the pair independently to WCAG AA by binary-searching lightness; it never returns a below-AA theme, because it throws instead of returning one if the solver can't clear the matrix.
 - `serializeCustomerTheme` emits `customers/<name>.ts` source in the CLI's own layout (`pnpm new-theme`'s `Palette` + `SlotMap`), extended to a pair: two `SlotMap`s (light and dark) and, unlike the CLI's override-free scaffold, the solved `ThemeDef` overrides each member needs to clear AA — the same kind of hand-tuned correction `acmeOverrides` carries in `customers/acme.ts`, but derived rather than hand-tuned.
 
+## Building a theme outside this repo
+
+`@handamade/psi-tokens/theme` (D81) builds a gated theme from a definition the consumer keeps in its own repository, so a client brand never has to ship in this package:
+
+```ts
+import { buildThemeCss, ThemeGateError } from "@handamade/psi-tokens/theme";
+
+const { css, warnings } = buildThemeCss("acme-portal", {
+  palette: { /* anchors */ },
+  slots: { ink, canvas, accent, success, warning, danger },
+  base: "light",            // or "dark" — e.g. a dark sidebar sub-tree
+});
+```
+
+The definition has the same shape as a `customers/<name>.ts` theme. It passes the same gates as Psi's shipped themes, which run the same code (`src/theme/gate.ts`): a WCAG AA contrast failure or a D46 scope violation throws `ThemeGateError`, naming every failure. The CSS is scoped to `[data-psi-theme="<name>"]`; load it after `base.css` and set the attribute on any element.
+
+From a build script: `psi-theme <definition.mjs|.ts> --name <name> [--out <file.css>]`, where the definition module default-exports the theme. Exit codes: 0 built, 1 refused by a gate, 2 usage error.
+
 ## Machine-readable artifacts
 
 For AI and tooling, see [llms.txt](./llms.txt):
@@ -58,6 +76,7 @@ For AI and tooling, see [llms.txt](./llms.txt):
 - `dist/guidance.json` — Variant intent, usage rules, state derivation
 - `dist/dtcg/{theme}.json` — W3C DTCG format export
 - `dist/components/{name}.vars.css` — Component-specific token declarations
+- `dist/theme/`, `dist/cli/psi-theme.js` — Compiled `./theme` subpath and the `psi-theme` bin (D81)
 - `dist/generate/` — Compiled `./generate` subpath (`parsePrompt`, `deriveTheme`, `serializeCustomerTheme`, and lower-level helpers)
 
 ## Note

package/dist/base.css

@@ -85,6 +85,9 @@
     --psi-z-nav: 100;
     --psi-z-overlay: 1000;
     --psi-z-tooltip: 1100;
+    --psi-focus-ring-width: 2px;
+    --psi-focus-ring-offset: 2px;
+    --psi-focus-ring-offset-inset: -2px;
 
     --psi-font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
     --psi-font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;

package/dist/cli/psi-theme.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function run(argv: readonly string[]): Promise<number>;

package/dist/cli/psi-theme.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// D81 — psi-theme <definition> --name <name> [--out <file>]
+// The definition is an ES module whose default export is a CustomerTheme.
+// Exit codes: 0 built · 1 refused by a gate or invalid · 2 usage error.
+import { writeFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { pathToFileURL } from "node:url";
+import { buildThemeCss } from "../theme/index.js";
+const USAGE = "usage: psi-theme <definition-module> --name <theme-name> [--out <file.css>]";
+export async function run(argv) {
+    const args = [...argv];
+    const take = (flag) => {
+        const i = args.indexOf(flag);
+        if (i === -1)
+            return undefined;
+        const value = args[i + 1];
+        args.splice(i, 2);
+        return value;
+    };
+    const name = take("--name");
+    const out = take("--out");
+    const definition = args[0];
+    if (!definition || !name || args.length !== 1) {
+        console.error(USAGE);
+        return 2;
+    }
+    let theme;
+    try {
+        const mod = (await import(pathToFileURL(resolvePath(definition)).href));
+        if (!mod.default)
+            throw new Error(`${definition} has no default export`);
+        theme = mod.default;
+    }
+    catch (e) {
+        console.error(`psi-theme: cannot load ${definition}: ${e.message}`);
+        return 2;
+    }
+    try {
+        const { css, warnings } = buildThemeCss(name, theme);
+        for (const w of warnings)
+            console.warn(`psi-theme: gamut warning [${name}] ${w}`);
+        if (out)
+            writeFileSync(out, css);
+        else
+            process.stdout.write(css);
+        return 0;
+    }
+    catch (e) {
+        console.error(`psi-theme: ${e.message}`);
+        return 1;
+    }
+}
+// Run when executed as a program, not when imported by a test.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    run(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/dist/components/app-shell.d.ts

@@ -0,0 +1,16 @@
+/** AppShell component tokens (--psi-app-shell-*) — D88.
+ *
+ * sidebar-width is a deliberate default for the sidebar column of the frame.
+ * 16rem is a standalone literal, matching --psi-toolbar-control-width: no
+ * shared scale reaches this range (sizeScale tops at 48, spacingScale at 144,
+ * both for heights and gaps, not column widths). The header's height stays
+ * --psi-navbar-height: the NavBar owns it.
+ *
+ * sidebar-bg, sidebar-fg and focus-ring alias the semantic layer, so under a
+ * `data-psi-theme="dark"` sidebar inside a light page they re-resolve dark
+ * (component tokens are declared under `:where(:root, [data-psi-theme])`).
+ * The theme paints no background of its own: the sidebar paints sidebar-bg.
+ *
+ * No contrast pair added: fgPrimary on bgPrimary is already gated in every
+ * theme, dark included, and the pinned pair count does not move. */
+export declare const appShellVars: Record<string, string>;

package/dist/components/app-shell.js

@@ -0,0 +1,21 @@
+/** AppShell component tokens (--psi-app-shell-*) — D88.
+ *
+ * sidebar-width is a deliberate default for the sidebar column of the frame.
+ * 16rem is a standalone literal, matching --psi-toolbar-control-width: no
+ * shared scale reaches this range (sizeScale tops at 48, spacingScale at 144,
+ * both for heights and gaps, not column widths). The header's height stays
+ * --psi-navbar-height: the NavBar owns it.
+ *
+ * sidebar-bg, sidebar-fg and focus-ring alias the semantic layer, so under a
+ * `data-psi-theme="dark"` sidebar inside a light page they re-resolve dark
+ * (component tokens are declared under `:where(:root, [data-psi-theme])`).
+ * The theme paints no background of its own: the sidebar paints sidebar-bg.
+ *
+ * No contrast pair added: fgPrimary on bgPrimary is already gated in every
+ * theme, dark included, and the pinned pair count does not move. */
+export const appShellVars = {
+    "sidebar-width": "16rem",
+    "sidebar-bg": "var(--psi-bg-primary)",
+    "sidebar-fg": "var(--psi-fg-primary)",
+    "focus-ring": "var(--psi-border-focus)",
+};

package/dist/components/app-shell.vars.css

@@ -0,0 +1,8 @@
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-app-shell-sidebar-width: 16rem;
+    --psi-app-shell-sidebar-bg: var(--psi-bg-primary);
+    --psi-app-shell-sidebar-fg: var(--psi-fg-primary);
+    --psi-app-shell-focus-ring: var(--psi-border-focus);
+  }
+}

package/dist/components/banner.d.ts

@@ -0,0 +1,11 @@
+/** Banner component tokens (--psi-banner-*) — D86. Pure indirection, same
+ * posture as toast.ts (D64) and table.ts (D62).
+ *
+ * Unlike Toast, a Banner is a tinted surface: it spans the page edge to edge
+ * and is meant to be seen, so the variant tints the whole strip. Neutral sits
+ * on fillNeutral3, the status variants on the fillTint* family.
+ *
+ * The body text is fgPrimary on all four surfaces; fgPrimary on each
+ * fillTint* is gated at 4.5 in contrast-matrix.ts (D86). The icon foregrounds
+ * are not text and ride the status-foreground pairs already gated there. */
+export declare const bannerVars: Record<string, string>;

package/dist/components/banner.js

@@ -0,0 +1,21 @@
+/** Banner component tokens (--psi-banner-*) — D86. Pure indirection, same
+ * posture as toast.ts (D64) and table.ts (D62).
+ *
+ * Unlike Toast, a Banner is a tinted surface: it spans the page edge to edge
+ * and is meant to be seen, so the variant tints the whole strip. Neutral sits
+ * on fillNeutral3, the status variants on the fillTint* family.
+ *
+ * The body text is fgPrimary on all four surfaces; fgPrimary on each
+ * fillTint* is gated at 4.5 in contrast-matrix.ts (D86). The icon foregrounds
+ * are not text and ride the status-foreground pairs already gated there. */
+export const bannerVars = {
+    "bg-neutral": "var(--psi-fill-neutral3)",
+    "bg-success": "var(--psi-fill-tint-success)",
+    "bg-warning": "var(--psi-fill-tint-warning)",
+    "bg-danger": "var(--psi-fill-tint-danger)",
+    fg: "var(--psi-fg-primary)",
+    "icon-fg-neutral": "var(--psi-fg-secondary)",
+    "icon-fg-success": "var(--psi-fg-success)",
+    "icon-fg-warning": "var(--psi-fg-warning)",
+    "icon-fg-danger": "var(--psi-fg-danger)",
+};

package/dist/components/banner.vars.css

@@ -0,0 +1,13 @@
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-banner-bg-neutral: var(--psi-fill-neutral3);
+    --psi-banner-bg-success: var(--psi-fill-tint-success);
+    --psi-banner-bg-warning: var(--psi-fill-tint-warning);
+    --psi-banner-bg-danger: var(--psi-fill-tint-danger);
+    --psi-banner-fg: var(--psi-fg-primary);
+    --psi-banner-icon-fg-neutral: var(--psi-fg-secondary);
+    --psi-banner-icon-fg-success: var(--psi-fg-success);
+    --psi-banner-icon-fg-warning: var(--psi-fg-warning);
+    --psi-banner-icon-fg-danger: var(--psi-fg-danger);
+  }
+}

package/dist/components/button.d.ts

@@ -0,0 +1,7 @@
+/** Button component variants */
+export declare const BUTTON_VARIANTS: readonly ["accent", "accent-subtle", "neutral", "neutral-subtle", "ghost", "danger", "danger-subtle", "outline"];
+export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
+/** Button component tokens (--psi-button-*). Values may reference semantic
+ * tokens and the component's own tokens; hover/active derive from the
+ * component's own bg so one override retunes all states (principle 3). */
+export declare const buttonVars: Record<string, string>;

package/dist/components/button.js

@@ -0,0 +1,76 @@
+/** Button component variants */
+export const BUTTON_VARIANTS = [
+    "accent",
+    "accent-subtle",
+    "neutral",
+    "neutral-subtle",
+    "ghost",
+    "danger",
+    "danger-subtle",
+    "outline",
+];
+/** Button component tokens (--psi-button-*). Values may reference semantic
+ * tokens and the component's own tokens; hover/active derive from the
+ * component's own bg so one override retunes all states (principle 3). */
+export const buttonVars = {
+    "accent-bg": "var(--psi-fill-accent)",
+    "accent-bg-hover": "oklch(from var(--psi-button-accent-bg) calc(l - 0.04) c h)",
+    "accent-bg-active": "oklch(from var(--psi-button-accent-bg) calc(l - 0.08) c h)",
+    "accent-fg": "var(--psi-fg-on-accent)",
+    "accent-subtle-bg": "var(--psi-fill-tint-accent)",
+    "accent-subtle-bg-hover": "oklch(from var(--psi-button-accent-subtle-bg) l c h / 0.18)",
+    "accent-subtle-bg-active": "oklch(from var(--psi-button-accent-subtle-bg) l c h / 0.24)",
+    "accent-subtle-fg": "var(--psi-fg-accent)",
+    "neutral-bg": "var(--psi-fill-neutral3)",
+    "neutral-bg-hover": "oklch(from var(--psi-button-neutral-bg) calc(l - 0.04) c h)",
+    "neutral-bg-active": "oklch(from var(--psi-button-neutral-bg) calc(l - 0.08) c h)",
+    "neutral-fg": "var(--psi-fg-primary)",
+    "neutral-subtle-bg": "var(--psi-fill-neutral1)",
+    "neutral-subtle-bg-hover": "oklch(from var(--psi-button-neutral-subtle-bg) calc(l - 0.04) c h)",
+    "neutral-subtle-bg-active": "oklch(from var(--psi-button-neutral-subtle-bg) calc(l - 0.08) c h)",
+    "neutral-subtle-fg": "var(--psi-fg-primary)",
+    "ghost-bg": "transparent",
+    "ghost-bg-hover": "var(--psi-fill-neutral3)",
+    "ghost-bg-active": "var(--psi-fill-neutral4)",
+    "ghost-fg": "var(--psi-fg-primary)",
+    "danger-bg": "var(--psi-fill-danger)",
+    "danger-bg-hover": "oklch(from var(--psi-button-danger-bg) calc(l - 0.04) c h)",
+    "danger-bg-active": "oklch(from var(--psi-button-danger-bg) calc(l - 0.08) c h)",
+    "danger-fg": "var(--psi-fg-static-white)",
+    "danger-subtle-bg": "var(--psi-fill-tint-danger)",
+    "danger-subtle-bg-hover": "oklch(from var(--psi-button-danger-subtle-bg) l c h / 0.18)",
+    "danger-subtle-bg-active": "oklch(from var(--psi-button-danger-subtle-bg) l c h / 0.24)",
+    "danger-subtle-fg": "var(--psi-fg-danger)",
+    "outline-bg": "transparent",
+    "outline-bg-hover": "var(--psi-fill-accent)",
+    "outline-bg-active": "oklch(from var(--psi-fill-accent) calc(l - 0.04) c h)",
+    "outline-fg": "var(--psi-fg-primary)",
+    // Hover fills accent; label follows the accent variant's binding (fgOnAccent,
+    // D37) — the literal "canvas label" fails AA in default light/dark.
+    "outline-fg-hover": "var(--psi-button-accent-fg)",
+    "outline-border": "var(--psi-border-strong)",
+    "focus-ring": "var(--psi-border-focus)",
+    // ── Shape (D56) — size-invariant; IconButton binds this too ──
+    radius: "var(--psi-control-radius)",
+    // ── Size ramp (D54) — label ramp; IconButton binds -height for both axes ──
+    "24-height": "var(--psi-control-24-height)",
+    "32-height": "var(--psi-control-32-height)",
+    "40-height": "var(--psi-control-40-height)",
+    "48-height": "var(--psi-control-48-height)",
+    "24-padding-inline": "var(--psi-control-24-padding-inline)",
+    "32-padding-inline": "var(--psi-control-32-padding-inline)",
+    "40-padding-inline": "var(--psi-control-40-padding-inline)",
+    "48-padding-inline": "var(--psi-control-48-padding-inline)",
+    "24-padding-inline-icon": "var(--psi-control-24-padding-inline-icon)",
+    "32-padding-inline-icon": "var(--psi-control-32-padding-inline-icon)",
+    "40-padding-inline-icon": "var(--psi-control-40-padding-inline-icon)",
+    "48-padding-inline-icon": "var(--psi-control-48-padding-inline-icon)",
+    "24-gap": "var(--psi-control-24-gap)",
+    "32-gap": "var(--psi-control-32-gap)",
+    "40-gap": "var(--psi-control-40-gap)",
+    "48-gap": "var(--psi-control-48-gap)",
+    "24-font": "var(--psi-control-24-font)",
+    "32-font": "var(--psi-control-32-font)",
+    "40-font": "var(--psi-control-40-font)",
+    "48-font": "var(--psi-control-48-font)",
+};

package/dist/components/card.d.ts

@@ -0,0 +1,2 @@
+/** Card component tokens (--psi-card-*). Layout shell, not a link (WS5). */
+export declare const cardVars: Record<string, string>;

package/dist/components/card.js

@@ -0,0 +1,7 @@
+/** Card component tokens (--psi-card-*). Layout shell, not a link (WS5). */
+export const cardVars = {
+    border: "var(--psi-border-faint)",
+    bg: "transparent",
+    gap: "var(--psi-space-16)",
+    radius: "var(--psi-radius-8)",
+};

package/dist/components/checkbox.d.ts

@@ -0,0 +1,2 @@
+/** Checkbox component tokens (--psi-checkbox-*). */
+export declare const checkboxVars: Record<string, string>;

package/dist/components/checkbox.js

@@ -0,0 +1,13 @@
+/** Checkbox component tokens (--psi-checkbox-*). */
+export const checkboxVars = {
+    fg: "var(--psi-fg-primary)",
+    "box-bg": "var(--psi-bg-primary)",
+    "box-border": "var(--psi-border-neutral)",
+    "box-bg-checked": "var(--psi-fill-accent)",
+    "box-border-checked": "var(--psi-fill-accent)",
+    // D56: tracks a sharper theme down, never rounder than radius-4 — the box
+    // is ~16px, so the 8px control default would read as a circle.
+    "box-radius": "min(var(--psi-control-radius), var(--psi-radius-4))",
+    "check-fg": "var(--psi-fg-on-accent)",
+    "focus-ring": "var(--psi-border-focus)",
+};

package/dist/components/control.d.ts

@@ -0,0 +1,21 @@
+/** Shared sized-control ramp (--psi-control-*) — D54/D55. A token-only family
+ * with no component behind it, same posture as surface.ts (D51): Button,
+ * IconButton, Input and Select alias it and nothing binds it directly (the
+ * psi/component-tokens-only stylelint rule makes that a lint error).
+ *
+ * Height and gap are shared across roles. Padding and font fork: a centred
+ * label wants more air than a left-aligned value, and labels are medium
+ * while values are regular. Input and Select both bind the value ramp, so
+ * they cannot diverge from each other — that is the point of the family.
+ *
+ * The icon inset is the label ramp minus the text inset, derived so a
+ * text-only control renders pixel-identical to pre-D54 output:
+ *
+ *   size | p (icon side) | text inset | raw gap | icon side | icon-text | text side
+ *     24 |       6       |     2      |    2    |     6     |     4     |     8
+ *     32 |       8       |     4      |    4    |     8     |     8     |    12
+ *     40 |      12       |     4      |    4    |    12     |     8     |    16
+ *     48 |      16       |     4      |    4    |    16     |     8     |    20
+ *
+ * The emitted padding-inline-icon and gap tokens are the effective columns. */
+export declare const controlVars: Record<string, string>;

package/dist/components/control.js

@@ -0,0 +1,59 @@
+/** Shared sized-control ramp (--psi-control-*) — D54/D55. A token-only family
+ * with no component behind it, same posture as surface.ts (D51): Button,
+ * IconButton, Input and Select alias it and nothing binds it directly (the
+ * psi/component-tokens-only stylelint rule makes that a lint error).
+ *
+ * Height and gap are shared across roles. Padding and font fork: a centred
+ * label wants more air than a left-aligned value, and labels are medium
+ * while values are regular. Input and Select both bind the value ramp, so
+ * they cannot diverge from each other — that is the point of the family.
+ *
+ * The icon inset is the label ramp minus the text inset, derived so a
+ * text-only control renders pixel-identical to pre-D54 output:
+ *
+ *   size | p (icon side) | text inset | raw gap | icon side | icon-text | text side
+ *     24 |       6       |     2      |    2    |     6     |     4     |     8
+ *     32 |       8       |     4      |    4    |     8     |     8     |    12
+ *     40 |      12       |     4      |    4    |    12     |     8     |    16
+ *     48 |      16       |     4      |    4    |    16     |     8     |    20
+ *
+ * The emitted padding-inline-icon and gap tokens are the effective columns. */
+export const controlVars = {
+    // ── Shared across roles ────────────────────────────────────────
+    "24-height": "var(--psi-size-24)",
+    "32-height": "var(--psi-size-32)",
+    "40-height": "var(--psi-size-40)",
+    "48-height": "var(--psi-size-48)",
+    "24-gap": "var(--psi-space-4)",
+    "32-gap": "var(--psi-space-8)",
+    "40-gap": "var(--psi-space-8)",
+    "48-gap": "var(--psi-space-8)",
+    // ── Label ramp (Button, IconButton) ────────────────────────────
+    "24-padding-inline": "var(--psi-space-8)",
+    "32-padding-inline": "var(--psi-space-12)",
+    "40-padding-inline": "var(--psi-space-16)",
+    "48-padding-inline": "var(--psi-space-20)",
+    "24-padding-inline-icon": "var(--psi-space-6)",
+    "32-padding-inline-icon": "var(--psi-space-8)",
+    "40-padding-inline-icon": "var(--psi-space-12)",
+    "48-padding-inline-icon": "var(--psi-space-16)",
+    "24-font": "var(--psi-text-12-16-medium)",
+    "32-font": "var(--psi-text-14-20-medium)",
+    "40-font": "var(--psi-text-16-24-medium)",
+    "48-font": "var(--psi-text-18-28-medium)",
+    // ── Value ramp (Input, Select) ─────────────────────────────────
+    "value-24-padding-inline": "var(--psi-space-8)",
+    "value-32-padding-inline": "var(--psi-space-8)",
+    "value-40-padding-inline": "var(--psi-space-12)",
+    "value-48-padding-inline": "var(--psi-space-16)",
+    "value-24-font": "var(--psi-text-12-16-regular)",
+    "value-32-font": "var(--psi-text-14-20-regular)",
+    "value-40-font": "var(--psi-text-16-24-regular)",
+    "value-48-font": "var(--psi-text-18-28-regular)",
+    // ── Size-invariant ─────────────────────────────────────────────
+    // Radius does not ride the size ramp: border-radius sits on each
+    // component's base rule, not in its .size{n} blocks, and all four sizes
+    // resolve to radius-8 today. One dial keeps it that way and gives a theme
+    // a single control-shape override (D56).
+    radius: "var(--psi-radius-8)",
+};

package/dist/components/description-list.d.ts

@@ -0,0 +1,8 @@
+/** DescriptionList component tokens (--psi-description-list-*) — D70. Pure
+ * indirection onto the semantic foreground family; exists because component
+ * CSS may only bind its own family (psi/component-tokens-only).
+ *
+ * Colour only. Spacing comes from the global --psi-space-* scale, which the
+ * scope gate already allows component CSS to bind directly, so aliasing it
+ * here would add a layer that buys nothing. */
+export declare const descriptionListVars: Record<string, string>;

package/dist/components/description-list.js

@@ -0,0 +1,13 @@
+/** DescriptionList component tokens (--psi-description-list-*) — D70. Pure
+ * indirection onto the semantic foreground family; exists because component
+ * CSS may only bind its own family (psi/component-tokens-only).
+ *
+ * Colour only. Spacing comes from the global --psi-space-* scale, which the
+ * scope gate already allows component CSS to bind directly, so aliasing it
+ * here would add a layer that buys nothing. */
+export const descriptionListVars = {
+    /** The <dt>. Secondary by design: the value is the content, the term is its label. */
+    "term-fg": "var(--psi-fg-secondary)",
+    /** The <dd>. */
+    "value-fg": "var(--psi-fg-primary)",
+};

package/dist/components/dialog.d.ts

@@ -0,0 +1,6 @@
+/** Dialog component tokens (--psi-dialog-*). Elevated surface — binds the
+ * shared --psi-surface-* family (D51); backdrop reuses the heavy scrim the
+ * NavBar glass treatment uses (D50). `fg` binds the panel's body foreground
+ * so the native <dialog> UA stylesheet's `color: CanvasText` never leaks
+ * through on dark themes (VR catch). */
+export declare const dialogVars: Record<string, string>;

package/dist/components/dialog.js

@@ -0,0 +1,16 @@
+/** Dialog component tokens (--psi-dialog-*). Elevated surface — binds the
+ * shared --psi-surface-* family (D51); backdrop reuses the heavy scrim the
+ * NavBar glass treatment uses (D50). `fg` binds the panel's body foreground
+ * so the native <dialog> UA stylesheet's `color: CanvasText` never leaks
+ * through on dark themes (VR catch). */
+export const dialogVars = {
+    bg: "var(--psi-surface-bg)",
+    border: "var(--psi-surface-border)",
+    radius: "var(--psi-surface-radius)",
+    backdrop: "var(--psi-scrim-heavy)",
+    fg: "var(--psi-fg-primary)",
+    "title-fg": "var(--psi-fg-primary)",
+    // D82 — the ring on the <dialog> and on a drawer's scrolling panel, which
+    // are tab stops themselves; the controls inside carry their own.
+    "focus-ring": "var(--psi-border-focus)",
+};

package/dist/components/dialog.vars.css

@@ -6,5 +6,6 @@
     --psi-dialog-backdrop: var(--psi-scrim-heavy);
     --psi-dialog-fg: var(--psi-fg-primary);
     --psi-dialog-title-fg: var(--psi-fg-primary);
+    --psi-dialog-focus-ring: var(--psi-border-focus);
   }
 }

package/dist/components/field.d.ts

@@ -0,0 +1,3 @@
+/** Field component tokens (--psi-field-*). Label/message/error colors alias
+ * gated semantic fg tokens; gap is the label→control→message grid gap (D49). */
+export declare const fieldVars: Record<string, string>;

package/dist/components/field.js

@@ -0,0 +1,14 @@
+/** Field component tokens (--psi-field-*). Label/message/error colors alias
+ * gated semantic fg tokens; gap is the label→control→message grid gap (D49). */
+export const fieldVars = {
+    "label-fg": "var(--psi-fg-secondary)",
+    "message-fg": "var(--psi-fg-tertiary)",
+    "error-fg": "var(--psi-fg-danger)",
+    "marker-fg": "var(--psi-fg-danger)",
+    // D84: the word a required label shows instead of the asterisk. The label's
+    // own colour — gated at 4.5 on every surface — not marker-fg, which would
+    // make every required label read as an error, and not fg-tertiary, the one
+    // foreground the contrast matrix does not gate.
+    "required-text-fg": "var(--psi-fg-secondary)",
+    gap: "var(--psi-space-6)",
+};

package/dist/components/field.vars.css

@@ -4,6 +4,7 @@
     --psi-field-message-fg: var(--psi-fg-tertiary);
     --psi-field-error-fg: var(--psi-fg-danger);
     --psi-field-marker-fg: var(--psi-fg-danger);
+    --psi-field-required-text-fg: var(--psi-fg-secondary);
     --psi-field-gap: var(--psi-space-6);
   }
 }

package/dist/components/inline-alert.d.ts

@@ -0,0 +1,12 @@
+/** InlineAlert component tokens (--psi-inline-alert-*) — D86. Pure
+ * indirection, same posture as banner.ts.
+ *
+ * The same tinted surface as Banner, but it sits inside content, so it adds a
+ * 1px border in the variant's colour and a radius. Neutral sits on
+ * fillNeutral3 with borderNeutral; the status variants draw the border from
+ * the status foreground (fgSuccess and fgWarning carry the `border` scope
+ * since D86, so the D46 scope gate accepts these bindings).
+ *
+ * The body text is fgPrimary on all four surfaces; fgPrimary on each
+ * fillTint* is gated at 4.5 in contrast-matrix.ts (D86). */
+export declare const inlineAlertVars: Record<string, string>;

package/dist/components/inline-alert.js

@@ -0,0 +1,27 @@
+/** InlineAlert component tokens (--psi-inline-alert-*) — D86. Pure
+ * indirection, same posture as banner.ts.
+ *
+ * The same tinted surface as Banner, but it sits inside content, so it adds a
+ * 1px border in the variant's colour and a radius. Neutral sits on
+ * fillNeutral3 with borderNeutral; the status variants draw the border from
+ * the status foreground (fgSuccess and fgWarning carry the `border` scope
+ * since D86, so the D46 scope gate accepts these bindings).
+ *
+ * The body text is fgPrimary on all four surfaces; fgPrimary on each
+ * fillTint* is gated at 4.5 in contrast-matrix.ts (D86). */
+export const inlineAlertVars = {
+    "bg-neutral": "var(--psi-fill-neutral3)",
+    "bg-success": "var(--psi-fill-tint-success)",
+    "bg-warning": "var(--psi-fill-tint-warning)",
+    "bg-danger": "var(--psi-fill-tint-danger)",
+    fg: "var(--psi-fg-primary)",
+    "icon-fg-neutral": "var(--psi-fg-secondary)",
+    "icon-fg-success": "var(--psi-fg-success)",
+    "icon-fg-warning": "var(--psi-fg-warning)",
+    "icon-fg-danger": "var(--psi-fg-danger)",
+    "border-neutral": "var(--psi-border-neutral)",
+    "border-success": "var(--psi-fg-success)",
+    "border-warning": "var(--psi-fg-warning)",
+    "border-danger": "var(--psi-fg-danger)",
+    radius: "var(--psi-radius-8)",
+};

package/dist/components/inline-alert.vars.css

@@ -0,0 +1,18 @@
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-inline-alert-bg-neutral: var(--psi-fill-neutral3);
+    --psi-inline-alert-bg-success: var(--psi-fill-tint-success);
+    --psi-inline-alert-bg-warning: var(--psi-fill-tint-warning);
+    --psi-inline-alert-bg-danger: var(--psi-fill-tint-danger);
+    --psi-inline-alert-fg: var(--psi-fg-primary);
+    --psi-inline-alert-icon-fg-neutral: var(--psi-fg-secondary);
+    --psi-inline-alert-icon-fg-success: var(--psi-fg-success);
+    --psi-inline-alert-icon-fg-warning: var(--psi-fg-warning);
+    --psi-inline-alert-icon-fg-danger: var(--psi-fg-danger);
+    --psi-inline-alert-border-neutral: var(--psi-border-neutral);
+    --psi-inline-alert-border-success: var(--psi-fg-success);
+    --psi-inline-alert-border-warning: var(--psi-fg-warning);
+    --psi-inline-alert-border-danger: var(--psi-fg-danger);
+    --psi-inline-alert-radius: var(--psi-radius-8);
+  }
+}

package/dist/components/input.d.ts

@@ -0,0 +1,2 @@
+/** Input component tokens (--psi-input-*). */
+export declare const inputVars: Record<string, string>;

package/dist/components/input.js

@@ -0,0 +1,25 @@
+/** Input component tokens (--psi-input-*). */
+export const inputVars = {
+    bg: "var(--psi-bg-primary)",
+    fg: "var(--psi-fg-primary)",
+    placeholder: "var(--psi-fg-tertiary)",
+    border: "var(--psi-border-neutral)",
+    "border-hover": "var(--psi-border-strong)",
+    "border-error": "var(--psi-fg-danger)",
+    "focus-ring": "var(--psi-border-focus)",
+    // ── Shape (D56) ──
+    radius: "var(--psi-control-radius)",
+    // ── Size ramp (D54) — value ramp, shared with Select ──
+    "24-height": "var(--psi-control-24-height)",
+    "32-height": "var(--psi-control-32-height)",
+    "40-height": "var(--psi-control-40-height)",
+    "48-height": "var(--psi-control-48-height)",
+    "24-padding-inline": "var(--psi-control-value-24-padding-inline)",
+    "32-padding-inline": "var(--psi-control-value-32-padding-inline)",
+    "40-padding-inline": "var(--psi-control-value-40-padding-inline)",
+    "48-padding-inline": "var(--psi-control-value-48-padding-inline)",
+    "24-font": "var(--psi-control-value-24-font)",
+    "32-font": "var(--psi-control-value-32-font)",
+    "40-font": "var(--psi-control-value-40-font)",
+    "48-font": "var(--psi-control-value-48-font)",
+};

package/dist/components/media.d.ts

@@ -0,0 +1,3 @@
+/** Media treatment tokens (D35). --psi-media-tint is a brand-defined filter
+ * chain; the .psi-media-tint utility applies it with hover reveal. */
+export declare const mediaVars: Record<string, string>;

package/dist/components/media.js

@@ -0,0 +1,5 @@
+/** Media treatment tokens (D35). --psi-media-tint is a brand-defined filter
+ * chain; the .psi-media-tint utility applies it with hover reveal. */
+export const mediaVars = {
+    tint: "none",
+};

package/dist/components/menu.d.ts

@@ -0,0 +1,7 @@
+/** Menu component tokens (--psi-menu-*) — D53. Container is pure indirection
+ * onto the shared surface family (same posture as panel.ts and dialog.ts);
+ * item states reuse Button's ghost recipe rather than introducing anchors, so
+ * a brand retuning --psi-surface-* gets Menu for free. item-fg-disabled binds
+ * --psi-fg-quaternary (not the plan's --psi-fg-muted, which does not exist);
+ * fg-quaternary is the lowest-contrast foreground available in the theme. */
+export declare const menuVars: Record<string, string>;

package/dist/components/menu.js

@@ -0,0 +1,21 @@
+/** Menu component tokens (--psi-menu-*) — D53. Container is pure indirection
+ * onto the shared surface family (same posture as panel.ts and dialog.ts);
+ * item states reuse Button's ghost recipe rather than introducing anchors, so
+ * a brand retuning --psi-surface-* gets Menu for free. item-fg-disabled binds
+ * --psi-fg-quaternary (not the plan's --psi-fg-muted, which does not exist);
+ * fg-quaternary is the lowest-contrast foreground available in the theme. */
+export const menuVars = {
+    bg: "var(--psi-surface-bg)",
+    border: "var(--psi-surface-border)",
+    radius: "var(--psi-surface-radius)",
+    fg: "var(--psi-fg-primary)",
+    "item-bg": "transparent",
+    "item-bg-hover": "var(--psi-fill-neutral3)",
+    "item-bg-active": "var(--psi-fill-neutral4)",
+    "item-fg": "var(--psi-fg-primary)",
+    "item-fg-danger": "var(--psi-fg-danger)",
+    "item-fg-disabled": "var(--psi-fg-quaternary)",
+    "separator-border": "var(--psi-border-faint)",
+    // D82 — the ring on a focused item; until then the browser drew its own.
+    "focus-ring": "var(--psi-border-focus)",
+};