twico-ui 1.42.0 → 1.43.0

package/llms.txt

@@ -234,6 +234,8 @@ Props:
 - `type` — `"button" | "submit" | "reset"` · default `"button"` — Native button type — use "submit" to submit a surrounding form.
 - `disabled` — `boolean` · default `false` — Disables the control — no interaction and a dimmed appearance.
 - `autoFocus` — `boolean` · default `false` — Focus the element automatically when it mounts.
+- `id` — `string` — Id applied to <button>, handy for labels and aria wiring.
+- `style` — `React.CSSProperties` — Inline styles merged onto <button> after the component's own.
 
 ```jsx
 import { Button } from "twico-ui";
@@ -268,6 +270,8 @@ Props:
 - `type` — `"button" | "submit" | "reset"` · default `"button"` — Native button type — use "submit" to submit a surrounding form.
 - `disabled` — `boolean` · default `false` — Disables the control — no interaction and a dimmed appearance.
 - `autoFocus` — `boolean` · default `false` — Focus the element automatically when it mounts.
+- `id` — `string` — Id applied to <button>, handy for labels and aria wiring.
+- `style` — `React.CSSProperties` — Inline styles merged onto <button> after the component's own.
 
 ```jsx
 import { IconButton } from "twico-ui";
@@ -424,7 +428,7 @@ Divider is a thin separator rule that visually splits content, either horizontal
 Props:
 - `orientation` — `"horizontal" | "vertical"` · default `"horizontal"` — Direction of the separator rule, either horizontal (default) to split stacked content or vertical for inline items.
 - `inset` — `boolean` · default `false` — Indents the start of a horizontal rule to align it with inset content like list item text.
-- `align` — `"left" | "center" | "right" | "start" | "end"` · default `"center"` — Label alignment when children are provided; logical start/end now accepted and map to left/right (additive — existing left/center/right unchanged).
+- `align` — `"left" | "center" | "right" | "start" | "end"` · default `"center"` — Label alignment when children are provided; prefer the logical "start"/"end" so the label mirrors under dir="rtl" ("left"/"right" still accepted).
 - `children` — `React.ReactNode` — Optional label text rendered within the rule, such as "OR", to break content with a caption.
 
 ```jsx
@@ -523,7 +527,7 @@ Heading (h1–h6) with consistent token typography. Use it instead of bare headi
 Props:
 - `level` — `1 | 2 | 3 | 4 | 5 | 6` · default `2` — Chooses which h1-h6 tag renders and its default token size, keeping document hierarchy and typography consistent.
 - `size` — `string` — Overrides the font-size token suffix (e.g. "3xl") to decouple visual scale from the semantic heading level.
-- `align` — `string` — Sets the CSS text-align value, letting you left-align, center, or right-align the heading text.
+- `align` — `string` — Sets the CSS text-align value; prefer the logical "start"/"end" over "left"/"right" so the heading mirrors under dir="rtl".
 - `as` — `ElementType` — Renders a different tag while preserving the level's size, useful when semantics and visual weight should differ.
 - `sx` — `Sx` — Style escape hatch: flat CSS goes inline (wins over base); nested selectors/at-rules like "&:hover" or "@media …" compile to a scoped stylesheet.
 
@@ -544,7 +548,7 @@ Props:
 - `size` — `"xs" | "sm" | "base" | "lg" | "xl"` · default `"base"` — Picks the font-size token from xs to xl, scaling the body text to fit its context, base by default.
 - `tone` — `"default" | "muted" | "subtle" | "primary" | "success" | "warning" | "danger" | "info" | "neutral"` · default `"default"` — Sets the text color — neutral roles (default, muted, subtle) plus the six semantic color intents.
 - `weight` — `string` — Sets the font-weight token suffix like semibold to adjust how heavy the text appears.
-- `align` — `string` — Sets the text-align value, controlling whether the text reads left, center, right, or justified.
+- `align` — `string` — Sets the text-align value: "start", "center", "end" or "justify" — prefer the logical start/end so the text mirrors under dir="rtl".
 - `as` — `ElementType` · default `"p"` — Chooses the element or tag rendered, defaulting to p so you can swap in span or other tags.
 - `sx` — `Sx` — Style escape hatch: flat CSS goes inline (wins over base); nested selectors/at-rules like "&:hover" or "@media …" compile to a scoped stylesheet.
 
@@ -581,6 +585,7 @@ Props:
 - `readOnly` — `boolean` · default `false` — Makes the field non-editable while still focusable/selectable.
 - `required` — `boolean` · default `false` — Marks the field required for native form validation.
 - `autoComplete` — `string` — Browser autocomplete hint (e.g. "email", "off").
+- `style` — `React.CSSProperties` — Inline styles merged onto <input> after the component's own.
 
 ```jsx
 import { Checkbox } from "twico-ui";
@@ -665,6 +670,8 @@ Props:
 - `name` — `string` — Form field name submitted with the value.
 - `readOnly` — `boolean` · default `false` — Makes the field non-editable while still focusable/selectable.
 - `autoComplete` — `string` — Browser autocomplete hint (e.g. "email", "off").
+- `id` — `string` — Id applied to <input>, handy for labels and aria wiring.
+- `style` — `React.CSSProperties` — Inline styles merged onto <input> after the component's own.
 
 ```jsx
 import { Combobox } from "twico-ui";
@@ -715,6 +722,8 @@ Props:
 - `disabled` — `boolean` · default `false` — Disables the control — no interaction and a dimmed appearance.
 - `readOnly` — `boolean` · default `false` — Makes the field non-editable while still focusable/selectable.
 - `autoComplete` — `string` — Browser autocomplete hint (e.g. "email", "off").
+- `id` — `string` — Id applied to <input>, handy for labels and aria wiring.
+- `style` — `React.CSSProperties` — Inline styles merged onto <input> after the component's own.
 
 ```jsx
 import { Currency } from "twico-ui";
@@ -753,6 +762,8 @@ Props:
 - `disabled` — `boolean` · default `false` — Disables the control — no interaction and a dimmed appearance.
 - `readOnly` — `boolean` · default `false` — Makes the field non-editable while still focusable/selectable.
 - `autoComplete` — `string` — Browser autocomplete hint (e.g. "email", "off").
+- `id` — `string` — Id applied to <input>, handy for labels and aria wiring.
+- `style` — `React.CSSProperties` — Inline styles merged onto <input> after the component's own.
 
 ```jsx
 import { CurrencyField } from "twico-ui";
@@ -1030,6 +1041,8 @@ Props:
 - `disabled` — `boolean` · default `false` — Disables the control — no interaction and a dimmed appearance.
 - `readOnly` — `boolean` · default `false` — Makes the field non-editable while still focusable/selectable.
 - `autoComplete` — `string` — Browser autocomplete hint (e.g. "email", "off").
+- `id` — `string` — Id applied to <input>, handy for labels and aria wiring.
+- `style` — `React.CSSProperties` — Inline styles merged onto <input> after the component's own.
 
 ```jsx
 import { Input } from "twico-ui";
@@ -1079,6 +1092,8 @@ Props:
 - `name` — `string` — Form field name submitted with the value.
 - `readOnly` — `boolean` · default `false` — Makes the field non-editable while still focusable/selectable.
 - `autoComplete` — `string` — Browser autocomplete hint (e.g. "email", "off").
+- `id` — `string` — Id applied to <input>, handy for labels and aria wiring.
+- `style` — `React.CSSProperties` — Inline styles merged onto <input> after the component's own.
 
 ```jsx
 import { MultiSelect } from "twico-ui";
@@ -1119,6 +1134,8 @@ Props:
 - `readOnly` — `boolean` · default `false` — Makes the field non-editable while still focusable/selectable.
 - `required` — `boolean` · default `false` — Marks the field required for native form validation.
 - `autoComplete` — `string` — Browser autocomplete hint (e.g. "email", "off").
+- `id` — `string` — Id applied to <input>, handy for labels and aria wiring.
+- `style` — `React.CSSProperties` — Inline styles merged onto <input> after the component's own.
 
 ```jsx
 import { Radio } from "twico-ui";
@@ -1169,7 +1186,7 @@ const [r, setR] = React.useState(0);
 
 #### Select
 
-A custom select that replaces the native browser dropdown with a rounded, keyboard-navigable popover, supporting grouped options and two-line (title + subtitle) options. Use it when you need a styled single-select with optional in-popover search, grouping, or descriptions.
+A custom select that replaces the native browser dropdown with a rounded, keyboard-navigable popover, supporting grouped options and two-line (title + subtitle) options. Use it when you need a styled single-select with optional in-popover search, grouping, or descriptions. Its trigger is exposed as the WAI-ARIA select-only combobox (role="combobox" with aria-haspopup="listbox"), as MUI's Select also is, so query it by the combobox role rather than by button — and give it a label, since that role takes its name from the label rather than from the selected value.
 
 `import { Select } from "twico-ui"`
 
@@ -1288,6 +1305,8 @@ Props:
 - `readOnly` — `boolean` · default `false` — Makes the field non-editable while still focusable/selectable.
 - `required` — `boolean` · default `false` — Marks the field required for native form validation.
 - `autoComplete` — `string` — Browser autocomplete hint (e.g. "email", "off").
+- `id` — `string` — Id applied to <input>, handy for labels and aria wiring.
+- `style` — `React.CSSProperties` — Inline styles merged onto <input> after the component's own.
 
 ```jsx
 import { Switch } from "twico-ui";
@@ -1326,6 +1345,8 @@ Props:
 - `rows` — `number` — Visible number of text rows.
 - `disabled` — `boolean` · default `false` — Disables the control — no interaction and a dimmed appearance.
 - `readOnly` — `boolean` · default `false` — Makes the field non-editable while still focusable/selectable.
+- `id` — `string` — Id applied to <textarea>, handy for labels and aria wiring.
+- `style` — `React.CSSProperties` — Inline styles merged onto <textarea> after the component's own.
 
 ```jsx
 import { Textarea } from "twico-ui";
@@ -2671,6 +2692,8 @@ Props:
 - `open` — `string[]` — Controlled open panel values; pair with onOpenChange. When set, internal state is bypassed and defaultOpen is ignored.
 - `onOpenChange` — `(values: string[]) => void` — Called with the next open values whenever a panel trigger is toggled (fires in both controlled and uncontrolled modes).
 - `headingLevel` — `1 | 2 | 3 | 4 | 5 | 6` · default `3` — Heading level wrapping each trigger button (document-outline semantics).
+- `mountOnOpen` — `boolean` · default `false` — Render each panel's content only after its first open, then keep it mounted - cuts the DOM and hook cost of a page full of collapsed panels.
+- `unmountOnClose` — `boolean` · default `false` — Also unmount a panel's content when it closes, waiting out the collapse animation first. Implies mountOnOpen.
 
 ```jsx
 import { Accordion } from "twico-ui";
@@ -2741,7 +2764,7 @@ Props:
 import { Navbar } from "twico-ui";
 
 <Navbar
-  brand={<>Twico <span style={{ color: "var(--color-primary)" }}>UI</span></>}
+  brand={<>Twico <span style={{ color: "var(--color-primary-subtle-fg)" }}>UI</span></>}
   links={[
     { label: "Dashboard", active: true },
     { label: "Projects" },
@@ -2779,7 +2802,7 @@ const MailIcon = () => (<svg width="18" height="18" viewBox="0 0 24 24" fill="no
 const CogIcon = () => (<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round"><circle cx="12" cy="12" r="3" /><path d="M12 3v3M12 18v3M3 12h3M18 12h3" /></svg>);
 
 <Sidebar
-  brand={<>Twico <span style={{ color: "var(--color-primary)" }}>UI</span></>}
+  brand={<>Twico <span style={{ color: "var(--color-primary-subtle-fg)" }}>UI</span></>}
   items={[
     { section: "Main" },
     { label: "Dashboard", icon: <HomeIcon />, active: true },
@@ -3018,7 +3041,7 @@ Menu is a portaled dropdown menu that takes a clickable trigger and an array of
 `import { Menu } from "twico-ui"`
 
 Props:
-- `trigger` — `React.ReactNode` · **required** — Defines the clickable element that opens the menu, typically a Button or IconButton the dropdown anchors to.
+- `trigger` — `React.ReactNode` · **required** — Defines the clickable element that opens the menu, typically a Button or IconButton the dropdown anchors to. Pass a single focusable control (a Button/IconButton): the element is cloned to carry tabIndex/aria-expanded, which are only valid on a control, and wrapping the real button to overlay a badge gives two tab stops - put the decoration outside. A wrapping Tooltip goes outside this component.
 - `items` — `MenuItemDef[]` · **required** — Lists the menu entries, where each can be an action item, a separator, or a section heading.
 - `align` — `"start" | "end"` · default `"start"` — Aligns the menu horizontally to the trigger's start or end edge so it sits flush in tight layouts; defaults to start.
 - `header` — `React.ReactNode` — Renders an optional rich node above the items, handy for surfacing user info or context at the top of the menu.
@@ -3050,7 +3073,7 @@ Popover is a click-triggered floating panel anchored to a trigger element, rende
 `import { Popover } from "twico-ui"`
 
 Props:
-- `trigger` — `React.ReactNode` · **required** — The clickable element the panel anchors to; clicking it toggles the popover open and closed.
+- `trigger` — `React.ReactNode` · **required** — The clickable element the panel anchors to; clicking it toggles the popover open and closed. Pass a single focusable control (a Button/IconButton): the element is cloned to carry tabIndex/aria-expanded, which are only valid on a control, and wrapping the real button to overlay a badge gives two tab stops - put the decoration outside. A wrapping Tooltip goes outside this component.
 - `title` — `React.ReactNode` — Optional bold heading rendered at the top of the panel to introduce its interactive content.
 - `placement` — `"top" | "bottom" | "left" | "right"` · default `"bottom"` — Which side of the trigger the panel opens toward (top, bottom, left, or right), auto-flipping near viewport edges.
 - `align` — `"start" | "center" | "end"` · default `"center"` — Cross-axis alignment (start, center, or end) of the panel relative to the trigger for top and bottom placements.
@@ -3384,10 +3407,10 @@ export function useKeyPress( key: string | string[], handler: (event: KeyboardEv
 
 ### useLocalStorage
 
-State persisted to localStorage (JSON-serialized), SSR-safe.
+State persisted to localStorage (JSON-serialized), SSR-safe: returns `initialValue` on the server AND on the first client render, then reads storage in a layout effect before paint (#466).
 
 ```ts
-export function useLocalStorage<T>( key: string, initialValue: T ): [T, (value: T | ((prev: T) => T)) => void];
+export function useLocalStorage<T>( key: string, initialValue: T, options?: UseLocalStorageOptions ): [T, (value: T | ((prev: T) => T)) => void];
 ```
 
 ### useCopyToClipboard
@@ -3432,10 +3455,10 @@ export function useTimeout(callback: () => void, delay: number | null): void;
 
 ### useWindowSize
 
-The current window dimensions (0×0 on the server).
+The current window dimensions. 0×0 on the server AND on the first client render, then measured in a layout effect before paint (#466) — so hydration never mismatches.
 
 ```ts
-export function useWindowSize(): { width: number; height: number };
+export function useWindowSize(options?: UseWindowSizeOptions): { width: number; height: number };
 ```
 
 ### useHover

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twico-ui",
-  "version": "1.42.0",
+  "version": "1.43.0",
   "description": "Twico UI — a free, modern, themeable React + Tailwind-friendly component library. 61 components with dark mode, motion, and accessibility built in.",
   "license": "MIT",
   "author": "Twico UI",
@@ -78,6 +78,8 @@
     "build": "tsup",
     "build:css": "node scripts/build-css.mjs",
     "build:css:check": "node scripts/build-css.mjs --check",
+    "build:fonts": "node scripts/build-fonts.mjs",
+    "build:fonts:check": "node scripts/build-fonts.mjs --check",
     "verify:palette": "node scripts/verify-palette.mjs",
     "gen:llms": "node scripts/gen-llms.mjs",
     "gen:llms:check": "node scripts/gen-llms.mjs --check",
@@ -108,7 +110,7 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.1",
-    "@size-limit/preset-small-lib": "^13.0.3",
+    "@size-limit/preset-small-lib": "^14.0.0",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.6.3",
@@ -117,10 +119,11 @@
     "jsdom": "^30.0.1",
     "lucide-react": "^1.31.0",
     "semantic-release": "^25.0.9",
-    "size-limit": "^13.0.3",
+    "size-limit": "^14.0.0",
     "tsup": "^8.3.5",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.0",
+    "wawoff2": "^2.0.1"
   },
   "size-limit": [
     {

package/styles/twico-ui.css

@@ -13,11 +13,13 @@
    Twico UI — Webfonts (self-hosted, OFL licensed)
    Plus Jakarta Sans (UI) + JetBrains Mono (code).
    Variable fonts: one file covers weights 200–800.
+   #450: shipped as WOFF2 - brotli-compressed inside the container, so the saving no longer
+   depends on the host compressing font/ttf. Generated by `npm run build:fonts` (committed).
    ============================================================ */
 
 @font-face {
   font-family: "Plus Jakarta Sans";
-  src: url("./fonts/PlusJakartaSans-Variable.ttf") format("truetype-variations");
+  src: url("./fonts/PlusJakartaSans-Variable.woff2") format("woff2");
   font-weight: 200 800;
   font-style: normal;
   font-display: swap;
@@ -25,7 +27,7 @@
 
 @font-face {
   font-family: "Plus Jakarta Sans";
-  src: url("./fonts/PlusJakartaSans-Italic-Variable.ttf") format("truetype-variations");
+  src: url("./fonts/PlusJakartaSans-Italic-Variable.woff2") format("woff2");
   font-weight: 200 800;
   font-style: italic;
   font-display: swap;
@@ -33,7 +35,7 @@
 
 @font-face {
   font-family: "JetBrains Mono";
-  src: url("./fonts/JetBrainsMono-Variable.ttf") format("truetype-variations");
+  src: url("./fonts/JetBrainsMono-Variable.woff2") format("woff2");
   font-weight: 100 800;
   font-style: normal;
   font-display: swap;
@@ -152,16 +154,38 @@
   /* Borders & dividers */
   --color-border:         var(--slate-200);
   --color-border-strong:  var(--slate-300);
+  /* #454: the unchecked boundary of Checkbox/Radio/Switch is the ONLY indication the control
+     exists, so SC 1.4.11 requires 3:1 against the surface. border-strong is 1.49:1. This step
+     clears it in both themes (4.76:1 on white, 6.96:1 on the dark surface) without touching
+     card/divider borders. */
+  --color-control-border: var(--slate-500);
+  /* #454 (review): a Switch track is NOT the same problem as a checkbox border. Its white thumb is
+     what identifies the control - except in light mode, where a white thumb on a white surface is
+     invisible and the track has to carry it. So light needs a dark track (4.76:1 on the surface, and
+     4.76:1 against the thumb)... */
+  --color-control-track: var(--slate-500);
+  /* #454 (review): the OFF thumb, deliberately STATIC in both themes (like --color-chart-on-fill).
+     It used to be --_accent-fg, i.e. the tone's ON-state ink - which is designed to sit on the tone
+     FILL, not on a neutral track. For five of the six tones that ink is near-black (success #052e1d,
+     info sky-950, warning amber-950, danger's dark variant, and neutral = --color-surface), so on the
+     dark track nothing in the control cleared 3:1 and an unchecked success Switch simply vanished -
+     the very SC 1.4.11 failure #454 was filed for, reintroduced for 5/6 tones while fixing primary.
+     A fixed light thumb resolves against BOTH tracks (4.76:1 on slate-500, 10.35:1 on slate-700) for
+     every tone, and the ON state keeps --_accent-fg, which is token-paired with its own fill. */
+  --color-control-thumb: #ffffff;
   --color-divider:        var(--slate-200);
 
   /* Text */
   --color-text:           var(--slate-900);
   --color-text-muted:     var(--slate-600);
-  --color-text-subtle:    var(--slate-400);
+  --color-text-subtle:    var(--slate-500);
   --color-text-inverted:  #ffffff;
 
   /* Data labels painted ON coloured chart marks (pie/donut slices, treemap tiles,
-     funnel stages). The mark fills are fixed -500 primitives that DON'T flip with
+     funnel stages). #455 made the mark fills theme-aware (--color-chart-1..7), but these two stay
+     static on purpose: the fills still span a wide lightness range in BOTH themes, so a theme-aware
+     label colour would wash out on the light ones and invert on the dark ones. Historically the
+     comment here said the fills were fixed -500 primitives that DON'T flip with
      theme, so these must stay static too (they are intentionally NOT re-declared in
      .dark): a light fill + a translucent dark halo — applied via `paint-order:
      stroke` — keeps the text legible on any slice colour, including light ones like
@@ -186,26 +210,51 @@
   --color-success:        var(--emerald-600);
   --color-success-fg:     #ffffff;
   --color-success-subtle:    var(--emerald-50);
-  --color-success-subtle-fg: var(--emerald-600);
+  --color-success-subtle-fg: var(--emerald-700);
 
   /* Warning */
   --color-warning:        var(--amber-500);
   --color-warning-fg:     var(--amber-950); /* dark ink on amber-500 = 6.97:1 (white was 2.15:1) */
   --color-warning-subtle:    var(--amber-50);
-  --color-warning-subtle-fg: var(--amber-600);
+  --color-warning-subtle-fg: var(--amber-700);
 
   /* Danger */
   --color-danger:         var(--rose-500);
   --color-danger-hover:   var(--rose-600);
   --color-danger-fg:      #ffffff;
   --color-danger-subtle:     var(--rose-50);
-  --color-danger-subtle-fg:  var(--rose-600);
+  --color-danger-subtle-fg:  var(--rose-700);
 
   /* Info */
   --color-info:           var(--sky-500);
   --color-info-fg:        var(--sky-950); /* dark ink on sky-500 (white was 2.77:1) */
   --color-info-subtle:       var(--sky-50);
-  --color-info-subtle-fg:    var(--sky-600);
+  --color-info-subtle-fg:    var(--sky-700);
+
+  /* #455: GRAPHIC tone colours — for a fill or stroke that is itself the information (a Progress
+     bar, a Toast edge stripe, a status icon). SC 1.4.11 wants 3:1 for those, and the light-mode
+     tone colours miss it: amber-500 is 1.96:1 on surface-sunken and sky-500 2.53:1. These steps
+     clear 3:1 on BOTH --color-surface (#fff) and --color-surface-sunken (slate-100) with margin
+     — 4.1:1 at worst — and keep the five tones at a consistent lightness so a tone switch does
+     not change the weight of the control. Use the plain tone for fills that carry text on top
+     (they are paired with --color-*-fg); use these when the colour stands alone. */
+  --color-primary-graphic: var(--brand-500);    /* 4.47 / 4.08 — unchanged, listed for symmetry */
+  --color-success-graphic: var(--emerald-700);  /* 5.48 / 5.01 */
+  --color-warning-graphic: var(--amber-700);    /* 5.02 / 4.58 */
+  --color-danger-graphic:  var(--rose-600);     /* 4.70 / 4.29 */
+  --color-info-graphic:    var(--sky-600);      /* 4.10 / 3.74 */
+
+  /* #455: the chart series ramp. Was seven primitives inlined in _chart.js, where slots 1 and 6
+     were BOTH indigo-500 (--brand-500 aliases it) — two series rendered identically, 1.00:1. As
+     tokens they also flip per theme, so a series fill is never below 3:1 on its own surface:
+     light bottoms out at 4.08:1, and the closest pair is 23.8 ΔE76 apart. */
+  --color-chart-1: var(--indigo-500);
+  --color-chart-2: var(--sky-700);
+  --color-chart-3: var(--emerald-700);
+  --color-chart-4: var(--amber-700);
+  --color-chart-5: var(--rose-600);
+  --color-chart-6: var(--indigo-900);
+  --color-chart-7: var(--slate-500);
 }
 
 /* ============================================================
@@ -224,11 +273,19 @@
 
   --color-border:         #25324a;
   --color-border-strong:  var(--slate-700);
+  --color-control-border: var(--slate-400);
+  /* ...while dark must go the OTHER way: on a dark surface the white thumb already reads at 10.35:1
+     against this track and ~14:1 against the surface, so the control is unmistakable, and lightening
+     the track to match --color-control-border would have dropped thumb-vs-track to 2.56:1 - trading
+     one 1.4.11 failure for another. On/off is carried by thumb POSITION, so SC 1.4.1 is satisfied
+     without colour either way. */
+  --color-control-track: var(--slate-700);
+  --color-control-thumb: #ffffff;   /* static: see the :root note */
   --color-divider:        #1c2840;
 
   --color-text:           var(--slate-50);
   --color-text-muted:     var(--slate-300);
-  --color-text-subtle:    var(--slate-500);
+  --color-text-subtle:    var(--slate-400);
   --color-text-inverted:  var(--slate-900);
 
   --color-primary:         var(--brand-500);
@@ -261,6 +318,33 @@
   --color-info-fg:        #04212f;
   --color-info-subtle:       rgb(14 165 233 / 0.15);
   --color-info-subtle-fg:    var(--sky-400);
+
+  /* #455: dark already clears 3:1 for every tone on slate-900 (6.4:1 and up), so these are the tone
+     values themselves - but written as PRIMITIVES, not as var(--color-warning).
+     #455 (review): aliasing the tone here while light named a primitive made the family behave
+     differently per theme - a consumer overriding --color-warning saw the Progress bar follow in dark
+     and not in light. Naming primitives in both scopes puts -graphic on exactly the same footing as
+     -fg / -subtle / -subtle-fg / -border: one more member of the per-tone derivative family that a
+     re-skin overrides together (which is what the docs-site Theme builder demonstrates). */
+  --color-primary-graphic: var(--brand-500);
+  --color-success-graphic: var(--emerald-500);
+  --color-warning-graphic: var(--amber-500);
+  --color-danger-graphic:  var(--rose-500);
+  --color-info-graphic:    var(--sky-500);
+
+  /* #455: dark keeps the ORIGINAL 500 steps. Dark mode never had the contrast problem (3.07:1 at
+     worst against surface-raised, 6.4:1+ on the surface itself), and the on-slice data labels in
+     PieChart/DonutChart/Treemap/FunnelChart are a static white fill + dark halo tuned against these
+     exact fills (see docs/charts.md) - lightening them would weaken that for no gain. Only slot 6
+     changes, from the indigo-500 that duplicated slot 1 to indigo-300: 25.7 ΔE76 from slot 1, and a
+     white-on-slice ratio in line with the amber-500 slice the label design already handles. */
+  --color-chart-1: var(--indigo-500);
+  --color-chart-2: var(--sky-500);
+  --color-chart-3: var(--emerald-500);
+  --color-chart-4: var(--amber-500);
+  --color-chart-5: var(--rose-500);
+  --color-chart-6: var(--indigo-300);
+  --color-chart-7: var(--slate-500);
 }
 
 /* ===== tokens/typography.css ===== */
@@ -552,7 +636,7 @@ h1, h2, h3, h4, h5, h6 {
 p { margin: 0; }
 
 a {
-  color: var(--color-primary);
+  color: var(--color-primary-subtle-fg);
   text-decoration: none;
   transition: color var(--duration-fast) var(--ease-standard);
 }