@handamade/psi-tokens 0.20.0 → 0.21.0

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/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/dialog.js

@@ -10,4 +10,7 @@ export const dialogVars = {
     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.js

@@ -5,5 +5,10 @@ export const fieldVars = {
     "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/menu.js

@@ -16,4 +16,6 @@ export const menuVars = {
     "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)",
 };

package/dist/components/menu.vars.css

@@ -11,5 +11,6 @@
     --psi-menu-item-fg-danger: var(--psi-fg-danger);
     --psi-menu-item-fg-disabled: var(--psi-fg-quaternary);
     --psi-menu-separator-border: var(--psi-border-faint);
+    --psi-menu-focus-ring: var(--psi-border-focus);
   }
 }

package/dist/components/nav-tree.d.ts

@@ -0,0 +1,12 @@
+/** NavTree component tokens (--psi-nav-tree-*) — D88. Pure indirection onto the
+ * semantic layer (same posture as menu.ts and tabs.ts), so every key resolves
+ * under a `data-psi-theme="dark"` sidebar inside a light page: component
+ * tokens are declared under `:where(:root, [data-psi-theme])`.
+ *
+ * No new contrast pairs: wcagAAPairs already gates fgPrimary and fgSecondary
+ * on bgPrimary and on fillNeutral1-6 in every theme, dark included, which
+ * covers the item text on the sidebar, on the hover surface (neutral3) and on
+ * the current surface (neutral4). `indicator` and `focus-ring` are non-text
+ * accents and `radius` is geometry; none carries a gated pair, so the pinned
+ * pair count does not move. */
+export declare const navTreeVars: Record<string, string>;

package/dist/components/nav-tree.js

@@ -0,0 +1,26 @@
+/** NavTree component tokens (--psi-nav-tree-*) — D88. Pure indirection onto the
+ * semantic layer (same posture as menu.ts and tabs.ts), so every key resolves
+ * under a `data-psi-theme="dark"` sidebar inside a light page: component
+ * tokens are declared under `:where(:root, [data-psi-theme])`.
+ *
+ * No new contrast pairs: wcagAAPairs already gates fgPrimary and fgSecondary
+ * on bgPrimary and on fillNeutral1-6 in every theme, dark included, which
+ * covers the item text on the sidebar, on the hover surface (neutral3) and on
+ * the current surface (neutral4). `indicator` and `focus-ring` are non-text
+ * accents and `radius` is geometry; none carries a gated pair, so the pinned
+ * pair count does not move. */
+export const navTreeVars = {
+    "item-fg": "var(--psi-fg-secondary)",
+    "item-fg-current": "var(--psi-fg-primary)",
+    "item-bg-hover": "var(--psi-fill-neutral3)",
+    "item-bg-current": "var(--psi-fill-neutral4)",
+    // The inline-start bar on the current item: weight and surface carry the
+    // state too, so colour is never the only signal.
+    indicator: "var(--psi-fill-accent)",
+    // A group's button reads like its items, one step quieter than the current.
+    "group-fg": "var(--psi-fg-secondary)",
+    // Alias of the control radius dial: a CSS Module may bind only its own
+    // component prefix, and the radius lives outside it.
+    radius: "var(--psi-control-radius)",
+    "focus-ring": "var(--psi-border-focus)",
+};

package/dist/components/nav-tree.vars.css

@@ -0,0 +1,12 @@
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-nav-tree-item-fg: var(--psi-fg-secondary);
+    --psi-nav-tree-item-fg-current: var(--psi-fg-primary);
+    --psi-nav-tree-item-bg-hover: var(--psi-fill-neutral3);
+    --psi-nav-tree-item-bg-current: var(--psi-fill-neutral4);
+    --psi-nav-tree-indicator: var(--psi-fill-accent);
+    --psi-nav-tree-group-fg: var(--psi-fg-secondary);
+    --psi-nav-tree-radius: var(--psi-control-radius);
+    --psi-nav-tree-focus-ring: var(--psi-border-focus);
+  }
+}

package/dist/components/navbar.js

@@ -8,4 +8,7 @@ export const navbarVars = {
     "link-fg": "var(--psi-fg-secondary)",
     "link-fg-hover": "var(--psi-fg-primary)",
     "focus-ring": "var(--psi-border-focus)",
+    // D88 — the side padding of a fluid row; the same gutter .psi-container pads
+    // with, reachable from the CSS Module only through a navbar token.
+    gutter: "var(--psi-gutter)",
 };

package/dist/components/navbar.vars.css

@@ -7,5 +7,6 @@
     --psi-navbar-link-fg: var(--psi-fg-secondary);
     --psi-navbar-link-fg-hover: var(--psi-fg-primary);
     --psi-navbar-focus-ring: var(--psi-border-focus);
+    --psi-navbar-gutter: var(--psi-gutter);
   }
 }

package/dist/components/navtree.d.ts

@@ -0,0 +1,12 @@
+/** NavTree component tokens (--psi-navtree-*) — D88. Pure indirection onto the
+ * semantic layer (same posture as menu.ts and tabs.ts), so every key resolves
+ * under a `data-psi-theme="dark"` sidebar inside a light page: component
+ * tokens are declared under `:where(:root, [data-psi-theme])`.
+ *
+ * No new contrast pairs: wcagAAPairs already gates fgPrimary and fgSecondary
+ * on bgPrimary and on fillNeutral1-6 in every theme, dark included, which
+ * covers the item text on the sidebar, on the hover surface (neutral3) and on
+ * the current surface (neutral4). `indicator` and `focus-ring` are non-text
+ * accents and `radius` is geometry; none carries a gated pair, so the pinned
+ * pair count does not move. */
+export declare const navtreeVars: Record<string, string>;

package/dist/components/navtree.js

@@ -0,0 +1,26 @@
+/** NavTree component tokens (--psi-navtree-*) — D88. Pure indirection onto the
+ * semantic layer (same posture as menu.ts and tabs.ts), so every key resolves
+ * under a `data-psi-theme="dark"` sidebar inside a light page: component
+ * tokens are declared under `:where(:root, [data-psi-theme])`.
+ *
+ * No new contrast pairs: wcagAAPairs already gates fgPrimary and fgSecondary
+ * on bgPrimary and on fillNeutral1-6 in every theme, dark included, which
+ * covers the item text on the sidebar, on the hover surface (neutral3) and on
+ * the current surface (neutral4). `indicator` and `focus-ring` are non-text
+ * accents and `radius` is geometry; none carries a gated pair, so the pinned
+ * pair count does not move. */
+export const navtreeVars = {
+    "item-fg": "var(--psi-fg-secondary)",
+    "item-fg-current": "var(--psi-fg-primary)",
+    "item-bg-hover": "var(--psi-fill-neutral3)",
+    "item-bg-current": "var(--psi-fill-neutral4)",
+    // The inline-start bar on the current item: weight and surface carry the
+    // state too, so colour is never the only signal.
+    indicator: "var(--psi-fill-accent)",
+    // A group's button reads like its items, one step quieter than the current.
+    "group-fg": "var(--psi-fg-secondary)",
+    // Alias of the control radius dial: a CSS Module may bind only its own
+    // component prefix, and the radius lives outside it.
+    radius: "var(--psi-control-radius)",
+    "focus-ring": "var(--psi-border-focus)",
+};

package/dist/components/navtree.vars.css

@@ -0,0 +1,12 @@
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-navtree-item-fg: var(--psi-fg-secondary);
+    --psi-navtree-item-fg-current: var(--psi-fg-primary);
+    --psi-navtree-item-bg-hover: var(--psi-fill-neutral3);
+    --psi-navtree-item-bg-current: var(--psi-fill-neutral4);
+    --psi-navtree-indicator: var(--psi-fill-accent);
+    --psi-navtree-group-fg: var(--psi-fg-secondary);
+    --psi-navtree-radius: var(--psi-control-radius);
+    --psi-navtree-focus-ring: var(--psi-border-focus);
+  }
+}

package/dist/components/registry.js

@@ -1,6 +1,12 @@
 // Component var registry (D81: moved out of scripts/build.ts) — the D46 scope
 // gate reads it, in Psi's own build and in a consumer's theme build alike.
+import { bannerVars } from "./banner.js";
+import { inlineAlertVars } from "./inline-alert.js";
 import { buttonVars } from "./button.js";
+import { skeletonVars } from "./skeleton.js";
+import { skipLinkVars } from "./skip-link.js";
+import { navTreeVars } from "./nav-tree.js";
+import { appShellVars } from "./app-shell.js";
 import { inputVars } from "./input.js";
 import { selectVars } from "./select.js";
 import { surfaceVars } from "./surface.js";
@@ -22,6 +28,8 @@ import { tabsVars } from "./tabs.js";
 import { fieldVars } from "./field.js";
 import { descriptionListVars } from "./description-list.js";
 export const componentVars = {
+    "app-shell": appShellVars,
+    banner: bannerVars,
     button: buttonVars,
     card: cardVars,
     checkbox: checkboxVars,
@@ -29,11 +37,15 @@ export const componentVars = {
     dialog: dialogVars,
     field: fieldVars,
     input: inputVars,
+    "inline-alert": inlineAlertVars,
     media: mediaVars,
     menu: menuVars,
     navbar: navbarVars,
     panel: panelVars,
     select: selectVars,
+    skeleton: skeletonVars,
+    "nav-tree": navTreeVars,
+    "skip-link": skipLinkVars,
     surface: surfaceVars,
     switch: switchVars,
     table: tableVars,

package/dist/components/skeleton.d.ts

@@ -0,0 +1,4 @@
+/** Skeleton component tokens (--psi-skeleton-*) — D86. Pure indirection, same
+ * posture as banner.ts. A placeholder carries no text, so there is no
+ * foreground pair to gate; it is a quiet neutral shape. */
+export declare const skeletonVars: Record<string, string>;

package/dist/components/skeleton.js

@@ -0,0 +1,7 @@
+/** Skeleton component tokens (--psi-skeleton-*) — D86. Pure indirection, same
+ * posture as banner.ts. A placeholder carries no text, so there is no
+ * foreground pair to gate; it is a quiet neutral shape. */
+export const skeletonVars = {
+    bg: "var(--psi-fill-neutral4)",
+    radius: "var(--psi-radius-4)",
+};

package/dist/components/skeleton.vars.css

@@ -0,0 +1,6 @@
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-skeleton-bg: var(--psi-fill-neutral4);
+    --psi-skeleton-radius: var(--psi-radius-4);
+  }
+}

package/dist/components/skip-link.d.ts

@@ -0,0 +1,6 @@
+/** SkipLink component tokens (--psi-skip-link-*) — D88. Pure indirection onto
+ * the shared surface and focus tokens (same posture as menu.ts and
+ * navbar.ts): the link shows only when focused, on a surface, so a brand
+ * retuning --psi-surface-* gets it for free. radius rides the control radius
+ * dial, as Button's does, so the link matches the controls around it. */
+export declare const skipLinkVars: Record<string, string>;

package/dist/components/skip-link.js

@@ -0,0 +1,12 @@
+/** SkipLink component tokens (--psi-skip-link-*) — D88. Pure indirection onto
+ * the shared surface and focus tokens (same posture as menu.ts and
+ * navbar.ts): the link shows only when focused, on a surface, so a brand
+ * retuning --psi-surface-* gets it for free. radius rides the control radius
+ * dial, as Button's does, so the link matches the controls around it. */
+export const skipLinkVars = {
+    bg: "var(--psi-surface-bg)",
+    fg: "var(--psi-fg-primary)",
+    border: "var(--psi-surface-border)",
+    radius: "var(--psi-control-radius)",
+    "focus-ring": "var(--psi-border-focus)",
+};

package/dist/components/skip-link.vars.css

@@ -0,0 +1,9 @@
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-skip-link-bg: var(--psi-surface-bg);
+    --psi-skip-link-fg: var(--psi-fg-primary);
+    --psi-skip-link-border: var(--psi-surface-border);
+    --psi-skip-link-radius: var(--psi-control-radius);
+    --psi-skip-link-focus-ring: var(--psi-border-focus);
+  }
+}

package/dist/components/skiplink.d.ts

@@ -0,0 +1,6 @@
+/** SkipLink component tokens (--psi-skiplink-*) — D88. Pure indirection onto
+ * the shared surface and focus tokens (same posture as menu.ts and
+ * navbar.ts): the link shows only when focused, on a surface, so a brand
+ * retuning --psi-surface-* gets it for free. radius rides the control radius
+ * dial, as Button's does, so the link matches the controls around it. */
+export declare const skiplinkVars: Record<string, string>;

package/dist/components/skiplink.js

@@ -0,0 +1,12 @@
+/** SkipLink component tokens (--psi-skiplink-*) — D88. Pure indirection onto
+ * the shared surface and focus tokens (same posture as menu.ts and
+ * navbar.ts): the link shows only when focused, on a surface, so a brand
+ * retuning --psi-surface-* gets it for free. radius rides the control radius
+ * dial, as Button's does, so the link matches the controls around it. */
+export const skiplinkVars = {
+    bg: "var(--psi-surface-bg)",
+    fg: "var(--psi-fg-primary)",
+    border: "var(--psi-surface-border)",
+    radius: "var(--psi-control-radius)",
+    "focus-ring": "var(--psi-border-focus)",
+};

package/dist/components/skiplink.vars.css

@@ -0,0 +1,9 @@
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-skiplink-bg: var(--psi-surface-bg);
+    --psi-skiplink-fg: var(--psi-fg-primary);
+    --psi-skiplink-border: var(--psi-surface-border);
+    --psi-skiplink-radius: var(--psi-control-radius);
+    --psi-skiplink-focus-ring: var(--psi-border-focus);
+  }
+}

package/dist/components.css

@@ -1,3 +1,26 @@
+@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);
+  }
+}
+
+@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);
+  }
+}
+
 @layer psi.components {
   :where(:root, [data-psi-theme]) {
     --psi-button-accent-bg: var(--psi-fill-accent);
@@ -123,6 +146,7 @@
     --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);
   }
 }
 
@@ -132,6 +156,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);
   }
 }
@@ -161,6 +186,25 @@
   }
 }
 
+@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);
+  }
+}
+
 @layer psi.components {
   :where(:root, [data-psi-theme]) {
     --psi-media-tint: none;
@@ -180,6 +224,7 @@
     --psi-menu-item-fg-danger: var(--psi-fg-danger);
     --psi-menu-item-fg-disabled: var(--psi-fg-quaternary);
     --psi-menu-separator-border: var(--psi-border-faint);
+    --psi-menu-focus-ring: var(--psi-border-focus);
   }
 }
 
@@ -192,6 +237,7 @@
     --psi-navbar-link-fg: var(--psi-fg-secondary);
     --psi-navbar-link-fg-hover: var(--psi-fg-primary);
     --psi-navbar-focus-ring: var(--psi-border-focus);
+    --psi-navbar-gutter: var(--psi-gutter);
   }
 }
 
@@ -238,6 +284,36 @@
   }
 }
 
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-skeleton-bg: var(--psi-fill-neutral4);
+    --psi-skeleton-radius: var(--psi-radius-4);
+  }
+}
+
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-nav-tree-item-fg: var(--psi-fg-secondary);
+    --psi-nav-tree-item-fg-current: var(--psi-fg-primary);
+    --psi-nav-tree-item-bg-hover: var(--psi-fill-neutral3);
+    --psi-nav-tree-item-bg-current: var(--psi-fill-neutral4);
+    --psi-nav-tree-indicator: var(--psi-fill-accent);
+    --psi-nav-tree-group-fg: var(--psi-fg-secondary);
+    --psi-nav-tree-radius: var(--psi-control-radius);
+    --psi-nav-tree-focus-ring: var(--psi-border-focus);
+  }
+}
+
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-skip-link-bg: var(--psi-surface-bg);
+    --psi-skip-link-fg: var(--psi-fg-primary);
+    --psi-skip-link-border: var(--psi-surface-border);
+    --psi-skip-link-radius: var(--psi-control-radius);
+    --psi-skip-link-focus-ring: var(--psi-border-focus);
+  }
+}
+
 @layer psi.components {
   :where(:root, [data-psi-theme]) {
     --psi-surface-bg: var(--psi-bg-secondary);

package/dist/contrast-matrix.js

@@ -108,6 +108,14 @@ export const wcagAAPairs = [
     // the fgAccent/fillTintAccent pair above: a selected row keeps ordinary
     // body text, it does not recolor it to the accent.
     { fg: "fgPrimary", bg: "fillTintAccent", minRatio: 4.5 },
+    // Body text on the status tints (D86): Banner and InlineAlert set their
+    // title and body in fgPrimary on fill-tint-{success,warning,danger}. The
+    // tints are 12–15% of the status foreground over the canvas, so every
+    // shipped theme clears this by a wide margin; it is gated because a
+    // consumer theme built with psi-theme (D81) is held to the same matrix.
+    { fg: "fgPrimary", bg: "fillTintSuccess", minRatio: 4.5 },
+    { fg: "fgPrimary", bg: "fillTintWarning", minRatio: 4.5 },
+    { fg: "fgPrimary", bg: "fillTintDanger", minRatio: 4.5 },
     // Toast's status icon on the elevated surface (D64/D65). The three pairs
     // above gate these foregrounds on bgPrimary; --psi-surface-bg — what Toast,
     // Menu and Dialog all alias — resolves to bgSecondary, which was ungated for

package/dist/dsl/validator.js

@@ -85,7 +85,7 @@ export function validateScopeConsistency(themes) {
 }
 // Both gates resolve --psi-* names scale-first, so a semantic token whose
 // kebab name starts with a scale-family prefix would be silently shadowed.
-const SCALE_FAMILY_PREFIX = /^(space|size|radius|text|font|duration|ease|z)-/;
+const SCALE_FAMILY_PREFIX = /^(space|size|radius|text|font|duration|ease|z|focus-ring)-/;
 /** D46 follow-up (HAN-21): reject semantic token kebab names that a
  * scale-family lookup would shadow before the semantic lookup runs. */
 export function validateNoScalePrefixShadow(kebabNames) {

package/dist/dtcg/acme.json

@@ -155,7 +155,8 @@
         "$extensions": {
           "psi": {
             "scopes": [
-              "text"
+              "text",
+              "border"
             ]
           }
         }
@@ -167,7 +168,8 @@
         "$extensions": {
           "psi": {
             "scopes": [
-              "text"
+              "text",
+              "border"
             ]
           }
         }
@@ -607,6 +609,20 @@
         "$type": "dimension",
         "$value": "1.5rem"
       }
+    },
+    "focusRing": {
+      "width": {
+        "$type": "dimension",
+        "$value": "2px"
+      },
+      "offset": {
+        "$type": "dimension",
+        "$value": "2px"
+      },
+      "offsetInset": {
+        "$type": "dimension",
+        "$value": "-2px"
+      }
     }
   },
   "typography": {

package/dist/dtcg/dark.json

@@ -155,7 +155,8 @@
         "$extensions": {
           "psi": {
             "scopes": [
-              "text"
+              "text",
+              "border"
             ]
           }
         }
@@ -167,7 +168,8 @@
         "$extensions": {
           "psi": {
             "scopes": [
-              "text"
+              "text",
+              "border"
             ]
           }
         }
@@ -607,6 +609,20 @@
         "$type": "dimension",
         "$value": "1.5rem"
       }
+    },
+    "focusRing": {
+      "width": {
+        "$type": "dimension",
+        "$value": "2px"
+      },
+      "offset": {
+        "$type": "dimension",
+        "$value": "2px"
+      },
+      "offsetInset": {
+        "$type": "dimension",
+        "$value": "-2px"
+      }
     }
   },
   "typography": {

package/dist/dtcg/ember.json

@@ -155,7 +155,8 @@
         "$extensions": {
           "psi": {
             "scopes": [
-              "text"
+              "text",
+              "border"
             ]
           }
         }
@@ -167,7 +168,8 @@
         "$extensions": {
           "psi": {
             "scopes": [
-              "text"
+              "text",
+              "border"
             ]
           }
         }
@@ -607,6 +609,20 @@
         "$type": "dimension",
         "$value": "1.5rem"
       }
+    },
+    "focusRing": {
+      "width": {
+        "$type": "dimension",
+        "$value": "2px"
+      },
+      "offset": {
+        "$type": "dimension",
+        "$value": "2px"
+      },
+      "offsetInset": {
+        "$type": "dimension",
+        "$value": "-2px"
+      }
     }
   },
   "typography": {

package/dist/dtcg/light.json

@@ -155,7 +155,8 @@
         "$extensions": {
           "psi": {
             "scopes": [
-              "text"
+              "text",
+              "border"
             ]
           }
         }
@@ -167,7 +168,8 @@
         "$extensions": {
           "psi": {
             "scopes": [
-              "text"
+              "text",
+              "border"
             ]
           }
         }
@@ -607,6 +609,20 @@
         "$type": "dimension",
         "$value": "1.5rem"
       }
+    },
+    "focusRing": {
+      "width": {
+        "$type": "dimension",
+        "$value": "2px"
+      },
+      "offset": {
+        "$type": "dimension",
+        "$value": "2px"
+      },
+      "offsetInset": {
+        "$type": "dimension",
+        "$value": "-2px"
+      }
     }
   },
   "typography": {

package/dist/guidance.json

@@ -54,14 +54,14 @@
     "Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.",
     "--psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).",
     "Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.",
-    "Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field).",
+    "Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"end\" of Fields (D87).",
     "Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group."
   ],
   "states": {
     "hover": "L - 0.04",
     "active": "L - 0.08",
     "disabled": "element opacity 0.4 (keeps hue)",
-    "focus": "2px ring var(--psi-{component}-focus-ring)"
+    "focus": "outline: var(--psi-focus-ring-width) solid var(--psi-{component}-focus-ring) on :focus-visible, at --psi-focus-ring-offset (outside) or --psi-focus-ring-offset-inset (inside) — D82"
   },
   "typographyDefaults": {
     "body": "16-24-regular",

package/dist/resolved/acme.json

@@ -157,7 +157,8 @@
       "hex": "#007048",
       "formula": "slot(success) → L set(0.48), C cap(0.1086)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgWarning": {
@@ -170,7 +171,8 @@
       "hex": "#775800",
       "formula": "slot(warning) → L set(0.48), C cap(0.0984)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgDanger": {
@@ -574,6 +576,11 @@
         "tooltip": 1100
       }
     },
+    "focusRing": {
+      "width": 2,
+      "offset": 2,
+      "offsetInset": -2
+    },
     "scopes": {
       "space": [
         "gap"

package/dist/resolved/dark.json

@@ -157,7 +157,8 @@
       "hex": "#00cf77",
       "formula": "slot(success) → L set(0.75), C cap(0.23)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgWarning": {
@@ -170,7 +171,8 @@
       "hex": "#e79d00",
       "formula": "slot(warning) → L set(0.75), C cap(0.1582)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgDanger": {
@@ -574,6 +576,11 @@
         "tooltip": 1100
       }
     },
+    "focusRing": {
+      "width": 2,
+      "offset": 2,
+      "offsetInset": -2
+    },
     "scopes": {
       "space": [
         "gap"

package/dist/resolved/ember.json

@@ -157,7 +157,8 @@
       "hex": "#00cf77",
       "formula": "slot(success) → L set(0.75), C cap(0.23)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgWarning": {
@@ -170,7 +171,8 @@
       "hex": "#e79d00",
       "formula": "slot(warning) → L set(0.75), C cap(0.1582)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgDanger": {
@@ -574,6 +576,11 @@
         "tooltip": 1100
       }
     },
+    "focusRing": {
+      "width": 2,
+      "offset": 2,
+      "offsetInset": -2
+    },
     "scopes": {
       "space": [
         "gap"

package/dist/resolved/light.json

@@ -157,7 +157,8 @@
       "hex": "#00703e",
       "formula": "slot(success) → L set(0.48), C cap(0.1187)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgWarning": {
@@ -170,7 +171,8 @@
       "hex": "#7e5400",
       "formula": "slot(warning) → L set(0.48), C cap(0.1013)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgDanger": {
@@ -574,6 +576,11 @@
         "tooltip": 1100
       }
     },
+    "focusRing": {
+      "width": 2,
+      "offset": 2,
+      "offsetInset": -2
+    },
     "scopes": {
       "space": [
         "gap"

package/dist/scope-map.json

@@ -107,10 +107,12 @@
       "text"
     ],
     "fg-success": [
-      "text"
+      "text",
+      "border"
     ],
     "fg-warning": [
-      "text"
+      "text",
+      "border"
     ],
     "fg-danger": [
       "text",
@@ -191,6 +193,39 @@
     ]
   },
   "component": {
+    "app-shell-sidebar-bg": [
+      "surface"
+    ],
+    "app-shell-sidebar-fg": [
+      "text"
+    ],
+    "banner-bg-neutral": [
+      "surface"
+    ],
+    "banner-bg-success": [
+      "surface"
+    ],
+    "banner-bg-warning": [
+      "surface"
+    ],
+    "banner-bg-danger": [
+      "surface"
+    ],
+    "banner-fg": [
+      "text"
+    ],
+    "banner-icon-fg-neutral": [
+      "text"
+    ],
+    "banner-icon-fg-success": [
+      "text"
+    ],
+    "banner-icon-fg-warning": [
+      "text"
+    ],
+    "banner-icon-fg-danger": [
+      "text"
+    ],
     "button-accent-bg": [
       "surface"
     ],
@@ -341,6 +376,9 @@
     "field-marker-fg": [
       "text"
     ],
+    "field-required-text-fg": [
+      "text"
+    ],
     "input-bg": [
       "surface"
     ],
@@ -356,6 +394,45 @@
     "input-border-error": [
       "border"
     ],
+    "inline-alert-bg-neutral": [
+      "surface"
+    ],
+    "inline-alert-bg-success": [
+      "surface"
+    ],
+    "inline-alert-bg-warning": [
+      "surface"
+    ],
+    "inline-alert-bg-danger": [
+      "surface"
+    ],
+    "inline-alert-fg": [
+      "text"
+    ],
+    "inline-alert-icon-fg-neutral": [
+      "text"
+    ],
+    "inline-alert-icon-fg-success": [
+      "text"
+    ],
+    "inline-alert-icon-fg-warning": [
+      "text"
+    ],
+    "inline-alert-icon-fg-danger": [
+      "text"
+    ],
+    "inline-alert-border-neutral": [
+      "border"
+    ],
+    "inline-alert-border-success": [
+      "border"
+    ],
+    "inline-alert-border-warning": [
+      "border"
+    ],
+    "inline-alert-border-danger": [
+      "border"
+    ],
     "menu-bg": [
       "surface"
     ],
@@ -422,6 +499,33 @@
     "select-chevron-fg": [
       "text"
     ],
+    "skeleton-bg": [
+      "surface"
+    ],
+    "nav-tree-item-fg": [
+      "text"
+    ],
+    "nav-tree-item-fg-current": [
+      "text"
+    ],
+    "nav-tree-item-bg-hover": [
+      "surface"
+    ],
+    "nav-tree-item-bg-current": [
+      "surface"
+    ],
+    "nav-tree-group-fg": [
+      "text"
+    ],
+    "skip-link-bg": [
+      "surface"
+    ],
+    "skip-link-fg": [
+      "text"
+    ],
+    "skip-link-border": [
+      "border"
+    ],
     "surface-bg": [
       "surface"
     ],

package/dist/themes/dark.js

@@ -17,8 +17,8 @@ export const darkTheme = {
     // tokens were already clamping to, so rendered hex is unchanged. fgSuccess
     // keeps the loose cap: emerald at l 0.75 is already in-gamut.
     fgAccent: token({ from: slot.accent, l: set(0.75), c: cap(0.1286), scopes: ["text"] }),
-    fgSuccess: token({ from: slot.success, l: set(0.75), c: cap(0.23), scopes: ["text"] }),
-    fgWarning: token({ from: slot.warning, l: set(0.75), c: cap(0.1582), scopes: ["text"] }),
+    fgSuccess: token({ from: slot.success, l: set(0.75), c: cap(0.23), scopes: ["text", "border"] }),
+    fgWarning: token({ from: slot.warning, l: set(0.75), c: cap(0.1582), scopes: ["text", "border"] }),
     fgDanger: token({ from: slot.danger, l: set(0.75), c: cap(0.1505), scopes: ["text", "border"] }),
     fillNeutral1: token({ from: slot.ink, l: set(0.18), c: set(0.012), scopes: ["surface"] }),
     fillNeutral2: token({ from: slot.ink, l: set(0.2), c: set(0.015), scopes: ["surface"] }),

package/dist/themes/light.js

@@ -16,8 +16,10 @@ export const lightTheme = {
     fgAccent: token({ from: slot.accent, l: set(0.48), c: cap(0.23), scopes: ["text"] }),
     // D39: status-fg caps lowered to each hue's in-gamut max at l 0.48 — the
     // values these tokens were already clamping to, so rendered hex is unchanged.
-    fgSuccess: token({ from: slot.success, l: set(0.48), c: cap(0.1187), scopes: ["text"] }),
-    fgWarning: token({ from: slot.warning, l: set(0.48), c: cap(0.1013), scopes: ["text"] }),
+    // text + border on all three status foregrounds: fgDanger for Input's error
+    // border (D46), fgSuccess and fgWarning for InlineAlert's (D86).
+    fgSuccess: token({ from: slot.success, l: set(0.48), c: cap(0.1187), scopes: ["text", "border"] }),
+    fgWarning: token({ from: slot.warning, l: set(0.48), c: cap(0.1013), scopes: ["text", "border"] }),
     fgDanger: token({ from: slot.danger, l: set(0.48), c: cap(0.1946), scopes: ["text", "border"] }),
     fillNeutral1: token({ from: slot.canvas, l: delta(+0.016), c: delta(-0.001), scopes: ["surface"] }),
     fillNeutral2: token({ from: slot.canvas, scopes: ["surface"] }),

package/llms.txt

@@ -26,6 +26,11 @@ OKLCH formula-based design tokens. Code is the source of truth; all artifacts ge
 - --psi-z-sticky (1), --psi-z-nav (100), --psi-z-overlay (1000), --psi-z-tooltip (1100). sticky is for elements that stack within their own local scroll container (e.g. a sticky table header), not above page chrome.
 - Breakpoints (sm 560 / md 960) are build-time constants (D31), not CSS vars: `import { breakpoints } from "@handamade/psi-tokens/types"` for any @media-driven JS/CSS-in-JS.
 
+## Focus ring (--psi-focus-ring-*)
+- One ring for every focusable part (D82): `outline: var(--psi-focus-ring-width) solid <colour>` on `:focus-visible`, never on `:focus`, never a literal width or offset.
+- --psi-focus-ring-width (2px). --psi-focus-ring-offset (2px) draws the ring outside the control. --psi-focus-ring-offset-inset (-2px) draws it inside, for a control whose outside ring would be clipped or would land on a neighbour: a text field, a tab, a menu item, a row in a list, a panel against the viewport edge.
+- The colour is the component's own --psi-{component}-focus-ring in component CSS, and --psi-border-focus in app CSS. The three geometry tokens are independent px values, so an override on any sub-tree takes effect there; the inset offset is not derived from the width, so override both together.
+
 ## Typography: display, serif, mono
 - Fluid display tier: --psi-display-{min}-{max}-{weight} (e.g. --psi-display-56-128-black), clamp-based and pixel-true at both endpoints; pair with the matching .psi-display-* utility class for tracking/uppercase.
 - Serif and mono are first-class combo roles alongside sans: --psi-text-serif-{size}-{lh}-{weight} and --psi-text-mono-{size}-{lh}-{weight}, same naming shape as the sans scale.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handamade/psi-tokens",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "license": "MIT",
   "type": "module",
   "exports": {