@wildo-ai/saas-frontend-lib 1.1.9 → 1.1.11

package/dist/esm/core/ui/themes/default.theme.js

@@ -1,5 +1,12 @@
 import { DividerVariant, InteractiveVariant, SurfaceVariant, FormControlVariant, IndicatorVariant, SelectableVariant, TypographyVariant, SKELETON_NEUTRAL_TINT, } from '@wildo-ai/presets-components-models';
 import { DEFAULT_CHART_STYLE_PRESET } from '../chart-style-defaults.js';
+import { FOCUS_INDICATOR_CLASSES, FocusIndicatorShape } from './focus-indicator.js';
+/*
+ * The design rules the comments below explain (surfaces paint with surface tokens, elevation never decreases,
+ * badges use the subtle pair, motion uses tokens, …) are CHECKED, not only written down: `checkThemeContract` in
+ * `@wildo-ai/presets-components-models` runs them over this theme and every named one (#2356). Change a rule
+ * there, with its reason, rather than here.
+ */
 // ============================================================
 // Helper
 // ============================================================
@@ -46,6 +53,8 @@ const MOTION = {
     formControl: "transition-[color,border-color,box-shadow] duration-[var(--motion-duration-fast)] ease-[var(--motion-easing-default)] motion-reduce:transition-none",
     /** Selectable items: bg, color, border on state change */
     selectable: "transition-[background-color,color,border-color] duration-[var(--motion-duration-fast)] ease-[var(--motion-easing-default)] motion-reduce:transition-none",
+    /** A segmented control's thumb: its fill, label and the edge + shadow that raise it (box-shadow) on selection. */
+    segment: "transition-[background-color,color,box-shadow] duration-[var(--motion-duration-fast)] ease-[var(--motion-easing-default)] motion-reduce:transition-none",
     /** Sidebar: width/height collapse */
     sidebarCollapse: "transition-[width,height,padding] duration-[var(--motion-duration-normal)] ease-[var(--motion-easing-default)] motion-reduce:transition-none",
     /** Enter animation for overlays/surfaces (fade + zoom) */
@@ -81,32 +90,40 @@ const interactiveSizes = {
     "icon-sm": "size-7 pointer-coarse:min-h-9 pointer-coarse:min-w-9",
 };
 const interactiveDisabled = "disabled:pointer-events-none disabled:opacity-[var(--opacity-disabled)] aria-disabled:cursor-not-allowed aria-disabled:opacity-[var(--opacity-disabled)]";
-const interactiveInvalid = "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive";
+const interactiveInvalid = "aria-invalid:border-destructive aria-invalid:focus-visible:outline-destructive";
 // ============================================================
-// Focus-ring constants — single source of truth
-// for the keyboard-focus indicators used by INTERACTIVE, FORM_CONTROL,
-// SELECTABLE, and INDICATOR recipes. Shape mirrors the global
-// `.focus-ring-offset` / `.focus-ring-inset` Tailwind utilities exposed
-// in `index.css`; the recipes use raw classes (rather than the @apply
-// utility) because some variants pair the ring with a coloured border.
+// Focus — the framework CONTRACT (`focus-indicator.ts`), dressed by this theme.
+//
+// Geometry is not this theme's to choose: every recipe below takes one of the
+// contract's shapes, and the colour comes from the palette's `--ring`. What the
+// default theme adds is the field's border turning to the ring colour under the
+// outline, as every named theme does. Buttons no longer repaint their border to
+// the ring colour — that, plus a painted offset gap, is what drew two parallel
+// lines around every focused control.
 // ============================================================
-/** Standard 2px offset ring + matching border-ring (most controls). */
-const FOCUS_RING_OFFSET_WITH_BORDER = "focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background";
-/** Standard 2px offset ring with NO border-ring change (filled / accent). */
-const FOCUS_RING_OFFSET = "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background";
-/** Compact 2px ring used by indicator badges and selectable items. */
-const FOCUS_RING_COMPACT = "focus-visible:ring-2 focus-visible:ring-ring";
+/** A standalone control: outline outside the box, transparent 1px gap. */
+const FOCUS_OFFSET = FOCUS_INDICATOR_CLASSES[FocusIndicatorShape.OFFSET];
+/** An item packed or clipped in a container (tabs, sidebar items, pills, segments); a selected one carries a band inside the outline. */
+const FOCUS_INSET = FOCUS_INDICATOR_CLASSES[FocusIndicatorShape.INSET];
+/**
+ * A text field: the contract's FIELD edge (2px, drawn inside the border, covering it), with the border
+ * itself turned to the ring colour beneath it. An invalid field stays red while focused, from the contract.
+ *
+ * No halo outside the field: a soft `ring-4 ring-ring/15` once sat there, and beside a solid edge it
+ * read as a second line around every field. None of the named themes carries one.
+ */
+const FOCUS_FIELD = `${FOCUS_INDICATOR_CLASSES[FocusIndicatorShape.FIELD]} focus-visible:border-ring`;
 const interactive = {
     [InteractiveVariant.PRIMARY]: recipe({
         // T2 tactile: a hairline edge (`border-primary/50`) + `shadow-sm` give the
         // button real elevation, and the press (`active:translate-y-px active:shadow-none`)
         // reads as a physical push. `MOTION.interactive` already transitions transform,
         // so the press animates for free.
-        base: "bg-primary text-primary-foreground rounded-lg border border-primary/50 shadow-sm font-medium text-sm cursor-pointer",
+        base: "bg-primary [--focus-band:var(--color-primary-foreground)] text-primary-foreground rounded-lg border border-primary/50 shadow-sm font-medium text-sm cursor-pointer",
         states: {
             hover: "hover:bg-primary/90",
             active: "active:bg-primary/80 active:shadow-none active:translate-y-px",
-            focus: FOCUS_RING_OFFSET_WITH_BORDER,
+            focus: FOCUS_OFFSET,
             disabled: interactiveDisabled,
             invalid: interactiveInvalid,
         },
@@ -151,11 +168,10 @@ const interactive = {
         states: {
             hover: "hover:border-destructive hover:bg-destructive/10 dark:hover:bg-destructive/20",
             active: "active:bg-destructive/15 dark:active:bg-destructive/25 active:translate-y-px",
-            // FOCUS_RING_OFFSET, not ..._WITH_BORDER: that constant repaints the border to `ring`, which
-            // for every other bordered variant is harmless because their border is decorative. Here the
-            // border IS the danger cue, so swapping it out would strip the warning from a keyboard user at
-            // the exact moment they are about to press the thing.
-            focus: FOCUS_RING_OFFSET,
+            // The contract's OFFSET shape draws outside the box and never touches the border. That matters
+            // more here than anywhere: the border IS the danger cue, and the old `border-ring` repaint swapped
+            // it for the ring colour at the exact moment a keyboard user was about to press the thing.
+            focus: FOCUS_OFFSET,
             highlighted: "focus:bg-destructive/10 dark:focus:bg-destructive/20 focus:text-destructive",
             disabled: interactiveDisabled,
             invalid: interactiveInvalid,
@@ -177,7 +193,7 @@ const interactive = {
         states: {
             hover: "hover:bg-accent hover:text-accent-foreground dark:hover:bg-input/50 dark:hover:text-foreground",
             active: "active:bg-accent/80 active:shadow-none active:translate-y-px",
-            focus: FOCUS_RING_OFFSET_WITH_BORDER,
+            focus: FOCUS_OFFSET,
             /*
              * SELECTED IS NOT HOVER. It used to be the same two classes as `hover`, so a segmented
              * control could not say which segment was chosen while the pointer was anywhere on it —
@@ -212,7 +228,7 @@ const interactive = {
         states: {
             hover: "hover:bg-secondary/80",
             active: "active:bg-secondary/70 active:translate-y-px",
-            focus: FOCUS_RING_OFFSET_WITH_BORDER,
+            focus: FOCUS_OFFSET,
             disabled: interactiveDisabled,
             invalid: interactiveInvalid,
         },
@@ -224,7 +240,7 @@ const interactive = {
         states: {
             hover: "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
             active: "active:bg-accent/80",
-            focus: FOCUS_RING_OFFSET_WITH_BORDER,
+            focus: FOCUS_OFFSET,
             /*
              * SELECTED IS NOT HOVER. It used to be the same two classes as `hover`, so a segmented
              * control could not say which segment was chosen while the pointer was anywhere on it —
@@ -261,7 +277,7 @@ const interactive = {
         states: {
             hover: "hover:underline",
             active: "active:text-primary/80",
-            focus: FOCUS_RING_OFFSET_WITH_BORDER,
+            focus: FOCUS_OFFSET,
             disabled: interactiveDisabled,
             invalid: interactiveInvalid,
         },
@@ -280,17 +296,17 @@ const interactive = {
         // (`--accent-gradient-{from,via,to}`) so tenants can rebrand the ACCENT
         // recipe without forking a theme. Defaults preserve the historical
         // violet/blue/pink visual.
-        base: 'relative bg-primary text-primary-foreground font-semibold rounded-lg shadow-xs before:absolute before:inset-0 before:rounded-[inherit] before:p-[1px] before:bg-[length:200%_200%] before:bg-gradient-to-r before:from-accent-gradient-from before:via-accent-gradient-via before:to-accent-gradient-to before:animate-[gradient-rotate_3s_ease_infinite] motion-reduce:before:animate-none before:-z-10 before:blur-[2px] shadow-[0_0_15px_color-mix(in_oklch,var(--primary)_20%,transparent)] text-sm cursor-pointer',
+        base: 'relative bg-primary [--focus-band:var(--color-primary-foreground)] text-primary-foreground font-semibold rounded-lg shadow-xs before:absolute before:inset-0 before:rounded-[inherit] before:p-[1px] before:bg-[length:200%_200%] before:bg-gradient-to-r before:from-accent-gradient-from before:via-accent-gradient-via before:to-accent-gradient-to before:animate-[gradient-rotate_var(--motion-duration-ambient)_ease_infinite] motion-reduce:before:animate-none before:-z-10 before:blur-[2px] shadow-[0_0_15px_color-mix(in_oklch,var(--primary)_20%,transparent)] text-sm cursor-pointer',
         states: {
             hover: 'hover:shadow-[0_0_25px_color-mix(in_oklch,var(--primary)_35%,transparent)]',
             active: 'active:scale-[0.98]',
-            focus: FOCUS_RING_OFFSET,
+            focus: FOCUS_OFFSET,
             disabled: interactiveDisabled,
             invalid: interactiveInvalid,
         },
         sizes: interactiveSizes,
         motion: {
-            transition: 'transition-[shadow,transform] duration-[var(--motion-duration-fast)] ease-[var(--motion-easing-default)] motion-reduce:transition-none',
+            transition: 'transition-[box-shadow,transform] duration-[var(--motion-duration-fast)] ease-[var(--motion-easing-default)] motion-reduce:transition-none',
         },
     }),
 };
@@ -357,6 +373,10 @@ const surface = {
         // opt-in via policy config.
         base: "bg-surface-raised text-surface-raised-foreground",
     }),
+    // Fact tile: the inset tint at 60% on a hairline, radius-lg — quieter than a CARD, so a grid of them stays one set of facts.
+    [SurfaceVariant.TILE]: recipe({
+        base: "bg-surface-inset/60 text-surface-inset-foreground border border-border rounded-lg",
+    }),
     [SurfaceVariant.TRANSIENT]: recipe({
         // Toast/snackbar: compact floating card, visually between RAISED and OVERLAY.
         base: "bg-surface-overlay text-surface-overlay-foreground rounded-lg border shadow-md",
@@ -382,9 +402,9 @@ const formControl = {
          */
         base: "border-border-strong dark:bg-surface-inset/30 rounded-lg border bg-transparent shadow-xs text-base md:text-sm placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground",
         states: {
-            focus: FOCUS_RING_OFFSET_WITH_BORDER,
+            focus: FOCUS_FIELD,
             disabled: "disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-[var(--opacity-disabled)]",
-            invalid: "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+            invalid: `aria-invalid:border-destructive`,
         },
         sizes: {
             md: "h-9 px-3 py-1 pointer-coarse:min-h-11",
@@ -406,9 +426,9 @@ const formControl = {
          */
         base: "bg-muted rounded-t-lg rounded-b-none border-0 border-b border-border-strong text-base md:text-sm placeholder:text-muted-foreground",
         states: {
-            focus: FOCUS_RING_OFFSET,
+            focus: FOCUS_FIELD,
             disabled: "disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-[var(--opacity-disabled)]",
-            invalid: "aria-invalid:ring-destructive/20 aria-invalid:border-destructive",
+            invalid: `aria-invalid:border-destructive`,
         },
         sizes: {
             md: "h-9 px-3 py-1 pointer-coarse:min-h-11",
@@ -420,34 +440,42 @@ const formControl = {
     [FormControlVariant.UNDERLINED]: recipe({
         base: "bg-transparent border-0 border-b border-border-strong rounded-none text-base md:text-sm placeholder:text-muted-foreground",
         states: {
-            focus: "focus-visible:border-ring focus-visible:border-b-2",
+            /*
+             * The contract's FIELD edge, not a thicker rule. `border-b-2` grew the box by a pixel on focus
+             * (every line below the field jumped) and drew one 2px line — less than the 2px perimeter the
+             * focus-appearance criterion sizes an indicator against. The outline lands on the box instead,
+             * shifts nothing, and is kept by forced-colors mode.
+             */
+            focus: FOCUS_FIELD,
             disabled: "disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-[var(--opacity-disabled)]",
-            invalid: "aria-invalid:border-destructive",
+            invalid: `aria-invalid:border-destructive`,
         },
+        // px-1, not px-0: the FIELD focus edge is drawn INSIDE the box (2px on this 1px border; it was 4px when
+        // this padding was set), and with no inline padding it covered the first glyph and the caret.
         sizes: {
-            md: "h-9 px-0 py-1 pointer-coarse:min-h-11",
-            sm: "h-8 px-0 py-1 text-sm pointer-coarse:min-h-11",
-            lg: "h-10 px-0 py-2 pointer-coarse:min-h-11",
+            md: "h-9 px-1 py-1 pointer-coarse:min-h-11",
+            sm: "h-8 px-1 py-1 text-sm pointer-coarse:min-h-11",
+            lg: "h-10 px-1 py-2 pointer-coarse:min-h-11",
         },
         motion: { transition: "transition-[border-color] duration-[var(--motion-duration-fast)] ease-[var(--motion-easing-default)] motion-reduce:transition-none" },
     }),
     [FormControlVariant.CHECKBOX]: recipe({
         base: "border-border-strong dark:bg-input/30 border shadow-xs",
         states: {
-            focus: FOCUS_RING_OFFSET_WITH_BORDER,
+            focus: FOCUS_OFFSET,
             selected: "data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=checked]:border-primary dark:data-[state=checked]:bg-primary",
             disabled: "disabled:cursor-not-allowed disabled:opacity-[var(--opacity-disabled)]",
-            invalid: "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+            invalid: "aria-invalid:border-destructive aria-invalid:focus-visible:outline-destructive",
         },
         motion: { transition: "transition-[color,box-shadow] duration-[var(--motion-duration-fast)] ease-[var(--motion-easing-default)] motion-reduce:transition-none" },
     }),
     [FormControlVariant.SWITCH]: recipe({
         base: "data-[state=unchecked]:bg-input dark:data-[state=unchecked]:bg-input/80 border border-transparent shadow-xs",
         states: {
-            focus: FOCUS_RING_OFFSET_WITH_BORDER,
+            focus: FOCUS_OFFSET,
             selected: "data-[state=checked]:bg-primary",
             disabled: "disabled:cursor-not-allowed disabled:opacity-[var(--opacity-disabled)]",
-            invalid: "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+            invalid: "aria-invalid:border-destructive aria-invalid:focus-visible:outline-destructive",
         },
         motion: { transition: "transition-[background-color,border-color,box-shadow] duration-[var(--motion-duration-fast)] ease-[var(--motion-easing-default)] motion-reduce:transition-none" },
     }),
@@ -458,7 +486,7 @@ const formControl = {
 const indicatorShared = {
     states: {
         hover: "[a&]:hover:opacity-[var(--opacity-hover)]",
-        focus: `focus-visible:border-ring ${FOCUS_RING_COMPACT}`,
+        focus: FOCUS_OFFSET,
         invalid: interactiveInvalid,
     },
     // `attention` = the theme-owned notification pulse (applied by NotificationIndicator
@@ -481,6 +509,10 @@ const indicatorShared = {
 // tenant can override any pair via `DesignSystemToken.*_SUBTLE(_FOREGROUND)`.
 // The border stays on the palette base (`border-{status}/25`, `/30` for warning
 // where the base is lighter) so it tracks the same hue.
+//
+// PILL shape (`rounded-full`, 2026-09-30): a status is a state, not a box of text, and the pill is
+// what lets a leading tone dot (`<Badge dot>`) sit inside it without looking like a bullet in a
+// rectangle. The hairline stays: it is what separates a NEUTRAL pill from an inset or tile fill.
 const indicator = {
     [IndicatorVariant.NEUTRAL]: recipe({
         // Tonal like the other four: `bg-neutral-subtle` mirrors the muted tint, but
@@ -488,40 +520,45 @@ const indicator = {
         // WCAG-AA on that tint. Previously `text-muted-foreground` (tuned for the page
         // background, not the raised muted tint) rendered a washed-out, sub-AA grey
         // chip for every `default`/`secondary`/`outline` enum value.
-        base: "bg-neutral-subtle text-neutral-subtle-foreground border-border rounded-md border px-2 py-0.5 text-xs font-medium",
+        base: "bg-neutral-subtle text-neutral-subtle-foreground border-border rounded-full border px-2 py-0.5 text-xs font-medium",
         ...indicatorShared,
     }),
     [IndicatorVariant.INFO]: recipe({
-        base: "bg-info-subtle text-info-subtle-foreground border-info/25 rounded-md border px-2 py-0.5 text-xs font-medium",
+        base: "bg-info-subtle text-info-subtle-foreground border-info/25 rounded-full border px-2 py-0.5 text-xs font-medium",
         ...indicatorShared,
     }),
     [IndicatorVariant.SUCCESS]: recipe({
-        base: "bg-success-subtle text-success-subtle-foreground border-success/25 rounded-md border px-2 py-0.5 text-xs font-medium",
+        base: "bg-success-subtle text-success-subtle-foreground border-success/25 rounded-full border px-2 py-0.5 text-xs font-medium",
         ...indicatorShared,
     }),
     [IndicatorVariant.WARNING]: recipe({
-        base: "bg-warning-subtle text-warning-subtle-foreground border-warning/30 rounded-md border px-2 py-0.5 text-xs font-medium",
+        base: "bg-warning-subtle text-warning-subtle-foreground border-warning/30 rounded-full border px-2 py-0.5 text-xs font-medium",
         ...indicatorShared,
     }),
     [IndicatorVariant.ERROR]: recipe({
-        base: "bg-destructive-subtle text-destructive-subtle-foreground border-destructive/25 rounded-md border px-2 py-0.5 text-xs font-medium",
+        base: "bg-destructive-subtle text-destructive-subtle-foreground border-destructive/25 rounded-full border px-2 py-0.5 text-xs font-medium",
         ...indicatorShared,
     }),
 };
 // ============================================================
 // SELECTABLE — Tabs, sidebar active items, toggles
 // ============================================================
+// Bases carry `outline-none`, not `outline-hidden`: the latter is a transparent outline that
+// forced-colors mode repaints, so every tab and sidebar item was boxed whether focused or not. The
+// focus contract (FOCUS_INSET) restores an outline on `:focus-visible`, which is the only box wanted.
 const selectable = {
     [SelectableVariant.FILLED]: recipe({
-        base: "rounded-md text-sm outline-hidden ring-surface-sunken-border",
+        base: "rounded-md text-sm outline-none",
         states: {
             hover: "hover:bg-surface-sunken-accent hover:text-surface-sunken-foreground",
-            focus: "focus-visible:ring-2",
+            // INSET, coloured by `--ring`. This was a ring in `surface-sunken-border` — the sidebar's own
+            // border colour, about 1.1:1 on the sidebar — so keyboard focus in the navigation was invisible.
+            focus: FOCUS_INSET,
             active: "active:bg-surface-sunken-accent active:text-surface-sunken-foreground",
             // `font-semibold` (not medium): the selected item is the "you are here"
             // anchor — WEIGHT carries the emphasis instead of a primary tint, and
             // medium is too close to the regular weight to read at sidebar sizes.
-            selected: "data-[active=true]:bg-surface-sunken-accent data-[active=true]:font-semibold data-[active=true]:text-surface-sunken-foreground data-[state=active]:bg-surface-sunken-accent data-[state=active]:text-surface-sunken-foreground",
+            selected: "data-[active=true]:bg-surface-sunken-accent data-[active=true]:font-semibold data-[active=true]:text-surface-sunken-foreground data-[state=active]:bg-surface-sunken-accent data-[state=active]:font-semibold data-[state=active]:text-surface-sunken-foreground",
             disabled: "disabled:pointer-events-none disabled:opacity-[var(--opacity-disabled)] aria-disabled:pointer-events-none aria-disabled:opacity-[var(--opacity-disabled)]",
         },
         sizes: {
@@ -532,10 +569,12 @@ const selectable = {
         motion: { transition: MOTION.selectable },
     }),
     [SelectableVariant.UNDERLINE]: recipe({
-        base: "rounded-none border-b-2 border-transparent text-sm outline-hidden",
+        // Top corners rounded, bottom square: the underline still runs straight, and the INSET focus
+        // outline reads as a soft tab shape instead of a hard box drawn over the strip's rule.
+        base: "rounded-t-md rounded-b-none border-b-2 border-transparent text-sm outline-none",
         states: {
             hover: "hover:text-foreground",
-            focus: FOCUS_RING_COMPACT,
+            focus: FOCUS_INSET,
             selected: "data-[state=active]:border-primary data-[state=active]:text-foreground",
             disabled: "disabled:pointer-events-none disabled:opacity-[var(--opacity-disabled)]",
         },
@@ -547,11 +586,11 @@ const selectable = {
         motion: { transition: MOTION.selectable },
     }),
     [SelectableVariant.PILL]: recipe({
-        base: "rounded-full text-sm outline-hidden",
+        base: "rounded-full text-sm outline-none",
         states: {
             hover: "hover:bg-accent hover:text-accent-foreground",
-            focus: FOCUS_RING_COMPACT,
-            selected: "data-[state=active]:bg-primary data-[state=active]:text-primary-foreground",
+            focus: FOCUS_INSET,
+            selected: "data-[state=active]:bg-primary data-[state=active]:[--focus-band:var(--color-primary-foreground)] data-[state=active]:text-primary-foreground",
             disabled: "disabled:pointer-events-none disabled:opacity-[var(--opacity-disabled)]",
         },
         sizes: {
@@ -562,10 +601,10 @@ const selectable = {
         motion: { transition: MOTION.selectable },
     }),
     [SelectableVariant.INDICATOR]: recipe({
-        base: "rounded-md text-sm outline-hidden",
+        base: "rounded-md text-sm outline-none",
         states: {
             hover: "hover:bg-surface-sunken-accent hover:text-surface-sunken-foreground",
-            focus: FOCUS_RING_COMPACT,
+            focus: FOCUS_INSET,
             // Same weight semantics as FILLED: selected = semibold (see note there).
             selected: "data-[active=true]:border-s-2 data-[active=true]:border-surface-sunken-primary data-[active=true]:font-semibold data-[active=true]:text-surface-sunken-foreground",
             disabled: "disabled:pointer-events-none disabled:opacity-[var(--opacity-disabled)]",
@@ -577,6 +616,47 @@ const selectable = {
         },
         motion: { transition: MOTION.selectable },
     }),
+    [SelectableVariant.SEGMENT]: recipe({
+        // One option inside a segmented control's recessed track. The toggle group paints the track with
+        // `surface.inset`; the options are borderless on it, so the row reads as one control.
+        base: "rounded-md text-sm font-medium text-muted-foreground outline-none",
+        states: {
+            hover: "hover:text-foreground",
+            focus: FOCUS_INSET,
+            // The selected option is a raised thumb. Its EDGE is the state's 3:1 cue (WCAG 2.2 SC 1.4.11) against
+            // both the track and the thumb's own fill. It is muted-foreground, which the palette contract owes
+            // 4.5:1 on surface-inset and surface-raised. border-strong was tried first and measured 2.95:1 against
+            // the track on the default palette (2.86:1 cozy). The raised fill and the shadow alone are about 1.1:1.
+            selected: "data-[state=on]:bg-surface-raised data-[state=on]:text-surface-raised-foreground data-[state=on]:shadow-xs data-[state=on]:ring-1 data-[state=on]:ring-inset data-[state=on]:ring-muted-foreground",
+            disabled: "disabled:pointer-events-none disabled:opacity-[var(--opacity-disabled)]",
+        },
+        // A thumb two pixels short of the control height, so the track (2px padding) lines up with a
+        // button and a field of the same size.
+        sizes: {
+            sm: "h-7 px-2.5 text-sm",
+            md: "h-8 px-3 text-sm",
+            lg: "h-9 px-4 text-sm",
+        },
+        motion: { transition: MOTION.segment },
+    }),
+    [SelectableVariant.CHIP]: recipe({
+        // A filter chip among others, separated by a gap: a standalone control, so OFFSET focus.
+        base: "rounded-full border border-border text-muted-foreground font-medium outline-none",
+        states: {
+            hover: "hover:bg-accent hover:text-accent-foreground",
+            focus: FOCUS_OFFSET,
+            // A tint and a brand-coloured edge, and the toggle group's check mark in the label's ink. The
+            // label stays foreground: primary as text on its own tint is not legible on every palette.
+            selected: "data-[state=on]:border-primary/50 data-[state=on]:bg-primary/10 data-[state=on]:text-foreground",
+            disabled: "disabled:pointer-events-none disabled:opacity-[var(--opacity-disabled)]",
+        },
+        sizes: {
+            sm: "h-7 px-3 text-xs",
+            md: "h-8 px-3.5 text-sm",
+            lg: "h-9 px-4 text-sm",
+        },
+        motion: { transition: MOTION.selectable },
+    }),
 };
 // ============================================================
 // OVERLAY_BACKDROP — Dialog/Sheet background overlay
@@ -655,9 +735,21 @@ const typography = {
         base: "text-muted-foreground text-sm",
         sizes: { sm: "text-xs", md: "text-sm" },
     }),
+    // The label voice of a record: 11px mono capitals, tracked, in the third ink level. Paired with the
+    // DATA voice below it reads as "name of the fact" against "the fact" — the hierarchy the Focal Plane
+    // mock carries and that a 10px sans eyebrow at 0.025em was too faint and too tight to hold (2026-09-30).
     [TypographyVariant.EYEBROW]: recipe({
-        base: "text-foreground-subtle text-2xs font-medium uppercase tracking-wide",
-        sizes: { sm: "text-2xs", md: "text-xs" },
+        base: "text-foreground-subtle font-mono text-[0.6875rem] font-medium uppercase tracking-[0.06em] leading-tight",
+        sizes: { sm: "text-2xs", md: "text-[0.6875rem]" },
+    }),
+    // One step below the h3 size and medium weight: the title of a record or collection, sharing its line with that record's actions.
+    [TypographyVariant.RESOURCE_TITLE]: recipe({
+        base: "text-lg font-medium leading-snug tracking-tight text-foreground",
+    }),
+    // Data voice: mono tabular figures one step under the 14px body, which is where mono reads the same size as sans.
+    [TypographyVariant.DATA]: recipe({
+        base: "text-foreground font-mono text-[0.8125rem] tabular-nums tracking-tight",
+        sizes: { sm: "text-xs", md: "text-[0.8125rem]", lg: "text-sm" },
     }),
     [TypographyVariant.CODE]: recipe({
         base: "font-mono text-sm bg-muted rounded px-1 py-0.5",
@@ -675,7 +767,7 @@ const typography = {
 export const defaultTheme = {
     id: 'default',
     name: 'Default',
-    description: 'Clean modern SaaS, derived from shadcn/ui (NOT Material Design 3). Soft shadow ladder (xs/sm/md/lg); radius ladder control lg(8) · popover lg · card/dialog xl(12); accessible focus rings; fast/default motion tokens. Tonal status badges (tinted bg + AA-contrast text + hairline, light & dark) instead of solid fills. Tactile buttons (hairline edge + shadow-sm + active press) on the elevated variants.',
+    description: 'Clean modern SaaS, derived from shadcn/ui (NOT Material Design 3). Soft shadow ladder (xs/sm/md/lg); radius ladder control lg(8) · popover lg · card/dialog xl(12); focus drawn with the framework outline contract (plus a soft halo on text fields); fast/default motion tokens. Tonal status badges (tinted bg + AA-contrast text + hairline, light & dark) instead of solid fills. Tactile buttons (hairline edge + shadow-sm + active press) on the elevated variants.',
     // spacing: omitted — uses application-level defaults (see DesignSystemToken.SPACING_*)
     interactive,
     surface,