@neuravision/construct 2.1.1 → 2.1.2

package/components/tabs.css

@@ -30,19 +30,39 @@
   font-size: var(--ct-tabs-trigger-font-size);
   line-height: var(--ct-tabs-trigger-line-height);
   font-weight: var(--font-weight-medium);
+  text-decoration: none;
   cursor: pointer;
   transition: color var(--duration-fast) var(--easing-standard),
     background var(--duration-fast) var(--easing-standard);
 }
 
+/* Triggers may be rendered as <a> for router-driven tabs. Neutralize the
+   global link styling (underline + link colors) so anchor triggers read
+   identically to buttons — the active-tab signal is the indicator, never
+   an underline. Deliberately excludes :hover so the shared trigger hover
+   rule above keeps winning. */
+a.ct-tabs__trigger,
+a.ct-tabs__trigger:active {
+  color: var(--color-text-secondary);
+  text-decoration: none;
+}
+
 .ct-tabs__trigger::after {
   content: '';
   position: absolute;
   inset-inline: 0;
   inset-block-end: 0;
   height: var(--ct-tabs-indicator-size);
-  background: transparent;
-  transition: background var(--duration-fast) var(--easing-standard);
+  background: var(--ct-tabs-indicator-color);
+  /* The datum draws itself: the indicator grows from its origin on
+     activation instead of popping in. Collapsed to zero at rest. */
+  transform: scaleX(0);
+  transform-origin: 0 50%;
+  transition: transform var(--duration-fast) var(--easing-standard);
+}
+
+.ct-tabs__trigger:is(:dir(rtl))::after {
+  transform-origin: 100% 50%;
 }
 
 @media (hover: hover) {
@@ -65,7 +85,7 @@
 
 .ct-tabs__trigger[aria-selected='true']::after,
 .ct-tabs__trigger[data-state='active']::after {
-  background: var(--ct-tabs-indicator-color);
+  transform: scale(1);
 }
 
 .ct-tabs__trigger:disabled,
@@ -114,6 +134,13 @@
   inset-block: 0;
   width: var(--ct-tabs-indicator-size);
   height: auto;
+  /* Vertical tabs draw the indicator from the block start. */
+  transform: scaleY(0);
+  transform-origin: 50% 0;
+}
+
+.ct-tabs--vertical .ct-tabs__trigger:is([aria-selected='true'], [data-state='active'])::after {
+  transform: scale(1);
 }
 
 /* Pill variant */
@@ -139,9 +166,34 @@
   box-shadow: var(--shadow-sm);
 }
 
+/* Construct 44×44 target policy (WCAG 2.2 SC 2.5.5 is AAA) */
+
+@media (pointer: coarse) {
+  .ct-tabs__trigger {
+    min-block-size: 44px;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .ct-tabs__trigger,
   .ct-tabs__trigger::after {
     transition: none;
   }
 }
+
+@media (forced-colors: active) {
+  /* The active indicator is background-drawn and must survive forced
+     backgrounds. */
+  .ct-tabs__trigger[aria-selected='true']::after,
+  .ct-tabs__trigger[data-state='active']::after {
+    background: SelectedItem;
+    forced-color-adjust: none;
+  }
+
+  .ct-tabs--pill .ct-tabs__trigger[aria-selected='true'],
+  .ct-tabs--pill .ct-tabs__trigger[data-state='active'] {
+    background: SelectedItem;
+    color: SelectedItemText;
+    forced-color-adjust: none;
+  }
+}

package/components/toast.css

@@ -23,12 +23,21 @@
   box-shadow: var(--shadow-md);
   color: var(--color-text-primary);
   transition: opacity var(--duration-fast) var(--easing-standard),
-    transform var(--duration-fast) var(--easing-standard);
+    transform var(--duration-fast) var(--easing-standard),
+    visibility 0s linear 0s;
 }
 
+/* Delayed visibility (drawer.css pattern) removes the faded-out toast
+   from the accessibility tree and tab order once the fade completes;
+   reopening restores it instantly via the base transition. */
 .ct-toast[data-state='closed'] {
   opacity: 0;
   transform: translateY(8px);
+  visibility: hidden;
+  pointer-events: none;
+  transition: opacity var(--duration-fast) var(--easing-standard),
+    transform var(--duration-fast) var(--easing-standard),
+    visibility 0s linear var(--duration-fast);
 }
 
 .ct-toast__title {

package/components/toggle-group.css

@@ -24,11 +24,7 @@
   overflow-x: auto;
   overflow-y: hidden;
   -webkit-overflow-scrolling: touch;
-  scrollbar-width: none;
-}
-
-.ct-toggle-group::-webkit-scrollbar {
-  display: none;
+  scrollbar-width: thin;
 }
 
 /* ── Item ── */
@@ -194,3 +190,18 @@
     transition: none;
   }
 }
+
+/* ── Forced colors ── */
+
+@media (forced-colors: active) {
+  /* The pressed fill must survive forced backgrounds; the outlined
+     selectors match the specificity of that variant's override. */
+  .ct-toggle-group__item[aria-pressed='true'],
+  .ct-toggle-group__item[aria-checked='true'],
+  .ct-toggle-group--outlined .ct-toggle-group__item[aria-pressed='true'],
+  .ct-toggle-group--outlined .ct-toggle-group__item[aria-checked='true'] {
+    background: SelectedItem;
+    color: SelectedItemText;
+    forced-color-adjust: none;
+  }
+}

package/components/toolbar.css

@@ -15,7 +15,8 @@
   display: flex;
   align-items: center;
   gap: var(--ct-toolbar-gap);
-  height: var(--ct-toolbar-height);
+  /* min-height, not height: the bar must grow with text scaling. */
+  min-height: var(--ct-toolbar-height);
   padding: 0 var(--ct-toolbar-padding-x);
   background: var(--color-bg-elevated);
   border-bottom: var(--border-thin) solid var(--color-border-subtle);
@@ -153,8 +154,15 @@
   --ct-toolbar-actions-gap: var(--space-2);
 }
 
+/* WCAG 2.2 SC 2.5.8: dense padding alone cannot guarantee 24px links. */
+.ct-toolbar--dense .ct-toolbar__nav-link {
+  min-height: 24px;
+}
+
 /* ── Sticky ── */
 
+/* Consumers: set --ct-scroll-offset-top on :root (see foundations.css) so
+   scrolled-to content is not obscured behind the bar (WCAG 2.4.11). */
 .ct-toolbar--sticky {
   position: sticky;
   inset-block-start: 0;
@@ -213,6 +221,14 @@
   }
 }
 
+/* ── Construct 44×44 target policy (WCAG 2.2 SC 2.5.5 is AAA) ── */
+
+@media (pointer: coarse) {
+  .ct-toolbar__nav-link {
+    min-height: 44px;
+  }
+}
+
 /* ── Reduced Motion ── */
 
 @media (prefers-reduced-motion: reduce) {

package/components/tree.css

@@ -118,10 +118,25 @@
   border-radius: var(--ct-tree-toggle-radius);
   color: var(--ct-tree-toggle-color);
   cursor: pointer;
+  position: relative;
   transition: color var(--duration-fast) var(--easing-standard),
     background var(--duration-fast) var(--easing-standard);
 }
 
+/* WCAG 2.2 SC 2.5.8: the visual chevron stays 1rem; the pointer target
+   does not. The hit area overlaps the row, mirroring checkbox.css. */
+.ct-tree__toggle::before {
+  content: '';
+  position: absolute;
+  inset: calc((var(--ct-tree-toggle-size) - 24px) / 2);
+}
+
+@media (pointer: coarse) {
+  .ct-tree__toggle::before {
+    inset: calc((var(--ct-tree-toggle-size) - 44px) / 2);
+  }
+}
+
 @media (hover: hover) {
   .ct-tree__toggle:hover {
     color: var(--ct-tree-toggle-color-hover);
@@ -194,6 +209,13 @@
   --ct-tree-actions-opacity: 1;
 }
 
+/* Touch surfaces have no hover to reveal row actions — keep them visible. */
+@media (hover: none) {
+  .ct-tree {
+    --ct-tree-actions-opacity: 1;
+  }
+}
+
 /* ── Selection ── */
 
 .ct-tree__node[aria-selected='true'] > .ct-tree__row,
@@ -277,6 +299,14 @@
   background: var(--color-bg-elevated);
 }
 
+/* ── Construct 44×44 target policy (WCAG 2.2 SC 2.5.5 is AAA) ── */
+
+@media (pointer: coarse) {
+  .ct-tree__row {
+    min-height: 44px;
+  }
+}
+
 /* ── Reduced motion ── */
 
 @media (prefers-reduced-motion: reduce) {

package/docs/behaviors.md

@@ -15,18 +15,37 @@ Every factory validates its DOM contract, returns the existing controller when i
 
 | Factory | Behavior contract |
 | --- | --- |
-| `createModalController` | Dialog semantics, initial focus, focus trap, Escape/backdrop dismissal, nested overlay ordering, scroll lock, focus return |
+| `createModalController` | Dialog semantics, initial focus, focus trap, Escape/backdrop dismissal, nested overlay ordering, scroll lock, focus return, optional `inertBackground` |
 | `createDrawerController` | Modal drawer behavior with the same focus/dismissal invariants and toggle trigger support |
 | `createTabsController` | Roving tabindex, horizontal/vertical arrows, Home/End, automatic or manual activation |
-| `createToggleGroupController` | Single/multiple pressed state, roving tabindex, orientation-aware arrows, controlled programmatic value |
-| `createDropdownController` | ARIA menu button, first/last focus, arrows, Home/End, typeahead, outside/Escape dismissal, menu item selection |
-| `createSelectMenuController` | Button/listbox selection, active option, typeahead, keyboard opening and dismissal, value synchronization |
-| `createComboboxController` | Editable combobox, virtual listbox focus, optional local filtering, active descendant, announcements, selection |
+| `createToggleGroupController` | Single/multiple pressed state (`aria-pressed`, or `aria-checked` radio semantics for single groups authored with `role="radiogroup"`/`role="radio"`), roving tabindex, orientation-aware arrows, controlled programmatic value |
+| `createDropdownController` | ARIA menu button, first/last focus, arrows, Home/End, typeahead (open and closed), outside/Escape dismissal, menu item selection |
+| `createSelectMenuController` | Button/listbox selection, active option, typeahead, PageUp/PageDown, Tab commits the active option, keyboard opening and dismissal, value synchronization |
+| `createComboboxController` | Editable combobox, virtual listbox focus, optional local filtering, active descendant, Alt+Arrow open/close, IME-safe key handling, announcements, selection |
 | `createTooltipController` | Focus and hover timing, touch toggle, Escape/outside dismissal, described-by wiring |
 | `createPopoverController` | Non-modal popup disclosure, optional focus entry, hover/focus modes, outside/Escape dismissal, focus return |
 
 The package includes TypeScript declarations for options, callbacks, controller methods, and event-detail types.
 
+### What the caller still owns (accessible names and live regions)
+
+Controllers wire state attributes, but accessible names and announcement targets come from your markup. Missing ones are reported as console warnings in the browser:
+
+| Controller | You must provide |
+| --- | --- |
+| Modal / Drawer | `aria-labelledby` or `aria-label` on the dialog element |
+| Dropdown | `aria-label` or `aria-labelledby` on the `role="menu"` element |
+| Toggle group | `aria-label` or `aria-labelledby` on the group/radiogroup/toolbar root |
+| Select menu | A visible label or `aria-labelledby` for the trigger, and labels on options |
+| Combobox | A `<label>` for the input, an `aria-label` on the listbox, and a visually hidden live-region element passed as `options.status` — without it filter results are never announced |
+| Tooltip | A keyboard-focusable trigger (natively focusable or `tabindex="0"`) and text content in the tooltip element |
+| Popover | An accessible name when using `role="dialog"` content |
+
+### Documented deviations from APG
+
+- Select menu and dropdown arrow navigation wraps at the ends (APG select-only combobox specifies no wrap); wrapping matches Construct's menu behavior and is intentional.
+- Typing on a closed select menu commits the matching value immediately, mirroring native `<select>` on Windows, instead of opening the listbox first.
+
 ## Modal example
 
 ```html
@@ -64,6 +83,8 @@ controller.destroy();
 
 Buttons with `data-ct-dismiss` are discovered automatically. The caller still owns the accessible name through `aria-labelledby` or `aria-label` and owns the action performed after confirmation.
 
+Pass `inertBackground: true` to additionally set `inert` on the container's DOM siblings while the dialog is open — a belt-and-suspenders layer on top of `aria-modal` for legacy screen-reader virtual cursors. Content portaled into the DOM after opening (for example popup layers) is unaffected.
+
 ## Tabs example
 
 ```js

package/docs/guidelines.md

@@ -20,6 +20,7 @@ A consistent, accessible, professional design system for modern web applications
 ### Don't
 
 - Don't rely on color alone for status information without text or icons
+- Don't rely on hue alone to distinguish chart series — use direct labels, ordered legends, and the always-present data-table fallback; several series pairs are near-identical in luminance for color-blind users
 - Don't create custom controls without ARIA roles and keyboard support
 - Don't use fixed pixel layouts for content that can grow
 - Don't use low-contrast text or disabled states that are unreadable
@@ -28,7 +29,12 @@ A consistent, accessible, professional design system for modern web applications
 ## Accessibility Rules (Minimum)
 
 - **Visible Focus**: All interactive elements must have visible focus indication
-- **Labels**: Every form input must have a label (explicit `<label>` or `aria-label`)
+- **Labels**: Every form input must have a label. Prefer a visible `<label>`; use `aria-label` only when a visible label is impossible, and never let it differ from visible text (2.5.3 Label in Name — note that `aria-label` overrides an associated `<label>` when both are present)
+- **Headings**: Keep `h1`–`h6` in order without skipping levels, including inside cards, modals, and shells
+- **Landmarks**: Wrap navigation lists in `<nav>` (also inside `<aside>` sidebars), label repeated landmarks (`aria-label`), and provide a skip link to `main` (see `skip-link.css`)
+- **Truncation**: `nowrap` + ellipsis on essential text (titles, values, labels) needs a way to reach the full text — a tooltip, a wrapping variant, or full text elsewhere on the page
+- **Status colors**: Semantic color (toast, banner, alert, badge) must be paired with an icon or explicit wording; the tinted border alone is decorative and intentionally not contrast-gated
+- **Sticky chrome**: Products using `--sticky`/`--fixed` navbar, toolbar, or banner variants must set `--ct-scroll-offset-top`/`--ct-scroll-offset-bottom` on `:root` so focused elements are never scrolled underneath (2.4.11); the app shells set their own scroll padding automatically
 - **Keyboard Navigation**: Use the tested headless controller for supported composite widgets; framework adapters must implement the documented pattern for others such as Datepicker and Tree
 - **ARIA**: Use ARIA attributes only where semantic HTML isn't sufficient
 - **Links**: Links must be distinguishable without color alone (e.g., underline)
@@ -86,9 +92,10 @@ framework adapter with equivalent tested semantics; CSS state selectors alone do
 - **Backdrop**: Click closes drawer
 
 ### Tooltip
-- **Open**: On hover and focus
+- **Open**: On hover and keyboard focus (the trigger must be focusable)
 - **Close**: On blur and Esc
 - **Role**: `role="tooltip"` with `aria-describedby`
+- **Implementation**: The CSS `:hover`/`:focus-within` styles alone do not satisfy WCAG 1.4.13 — Esc dismissal and hover persistence require `createTooltipController` or an equivalent adapter
 
 ### Tree (`ct-tree`)
 
@@ -164,6 +171,27 @@ Use these attributes for state management:
 Never use `aria-disabled="true"` alone to block a native button: it announces state but does not suppress
 activation. Use the native `disabled` attribute whenever the HTML element supports it.
 
+## The Datum
+
+Construct's signature is one orange reference line — "the datum" — that marks what is focused, active,
+current, or the reference value. The grammar lives in `components/datum.css` (eyebrow, scale, frame,
+metrics), in active leading edges (list, sidebar, card, table rows), in the tab indicator and sorted
+column, and in the chart reference line. Its dimensions are component tokens (`--component-datum-*`).
+
+Rules that keep the signature strong and accessible:
+
+- **One datum per surface.** Orange marks exactly one thing per view region — the current, active, or
+  reference element. Never let two orange edges compete; if everything is highlighted, nothing is.
+- **Orange is never text.** Labels and values stay on `--color-text-*` neutrals; orange is carried by
+  non-text ticks, edges, rules, and lines.
+- **Edges are `--color-brand-accent`; meaning-bearing fills are `--color-brand-accent-strong`**
+  (validated ≥3:1 against muted/canvas/surface tracks per theme). A decorative rule may use plain
+  accent; anything that encodes a value (progress, chart reference) uses strong.
+- **The datum enters, it never pops.** State changes draw the edge in from its origin
+  (`--duration-fast` / `--easing-standard`); `prefers-reduced-motion` disables this globally.
+- **Forced colors re-encode edges as borders.** Inset box-shadow edges are dropped by forced colors —
+  every new edge needs a `SelectedItem` border fallback.
+
 ## Breakpoints & Media Queries
 
 Construct defines breakpoint tokens in `tokens/primitives.json`:

package/foundations.css

@@ -18,6 +18,12 @@
 html {
   height: 100%;
   text-size-adjust: 100%;
+  /* WCAG 2.4.11 Focus Not Obscured contract: sticky/fixed chrome (navbar,
+     toolbar, banner) does not know the document, so products publish its
+     height by setting --ct-scroll-offset-top/-bottom on :root/html. Scroll
+     operations then keep focused or anchored content clear of the bars. */
+  scroll-padding-block-start: var(--ct-scroll-offset-top, 0px);
+  scroll-padding-block-end: var(--ct-scroll-offset-bottom, 0px);
 }
 
 body {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuravision/construct",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Construct Design System - Accessible, token-based design system for modern web applications",
   "license": "MIT",
   "repository": {
@@ -33,8 +33,9 @@
     "audit": "npm audit --audit-level=high",
     "tokens:validate": "node scripts/validate-tokens.mjs",
     "tokens:test": "node scripts/test-token-pipeline.mjs",
+    "themes:validate": "node scripts/construct-theme.mjs --theme themes/walnut.theme.json --validate-only",
     "check": "npm run check:tokens && npm run check:standalone && npm run check:css && npm run check:exports && npm run check:version",
-    "check:tokens": "node scripts/build-tokens.mjs --check && npm run tokens:validate && npm run tokens:test",
+    "check:tokens": "node scripts/build-tokens.mjs --check && npm run tokens:validate && npm run tokens:test && npm run themes:validate",
     "check:standalone": "node scripts/build-standalone-components.mjs --check",
     "check:css": "node scripts/validate-css-vars.mjs",
     "check:exports": "node scripts/validate-package-exports.mjs",
@@ -78,7 +79,8 @@
       "default": "./tokens/tokens.js"
     },
     "./schemas/*.json": "./schemas/*.json",
-    "./schemas/examples/*.json": "./schemas/examples/*.json"
+    "./schemas/examples/*.json": "./schemas/examples/*.json",
+    "./themes/*.json": "./themes/*.json"
   },
   "files": [
     "foundations.css",
@@ -89,6 +91,8 @@
     "tokens/*.ts",
     "tokens/README.md",
     "schemas/**/*.json",
+    "themes/*.json",
+    "themes/README.md",
     "components/*.css",
     "components/README.md",
     "standalone/*.css",

package/schemas/components.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://neuravision.dev/construct/schemas/components.schema.json",
   "title": "Construct component token contract",
   "type": "object",
-  "required": ["button", "control", "card", "status", "metric", "meter"],
+  "required": ["button", "control", "card", "status", "metric", "meter", "datum"],
   "additionalProperties": false,
   "properties": {
     "button": {
@@ -87,6 +87,21 @@
         "radius": { "$ref": "#/$defs/token" },
         "track": { "$ref": "#/$defs/token" }
       }
+    },
+    "datum": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["edgeWidth", "tickWidth", "tickHeight", "originLength", "markSize", "scaleHeight", "scaleMinorStep", "scaleMajorStep"],
+      "properties": {
+        "edgeWidth": { "$ref": "#/$defs/token" },
+        "tickWidth": { "$ref": "#/$defs/token" },
+        "tickHeight": { "$ref": "#/$defs/token" },
+        "originLength": { "$ref": "#/$defs/token" },
+        "markSize": { "$ref": "#/$defs/token" },
+        "scaleHeight": { "$ref": "#/$defs/token" },
+        "scaleMinorStep": { "$ref": "#/$defs/token" },
+        "scaleMajorStep": { "$ref": "#/$defs/token" }
+      }
     }
   },
   "$defs": {

package/schemas/semantic.schema.json

@@ -27,7 +27,7 @@
         "brand": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["primary", "primaryHover", "primaryActive", "accent", "accentHover", "accentActive", "onAccent"],
+          "required": ["primary", "primaryHover", "primaryActive", "accent", "accentHover", "accentActive", "accentStrong", "onAccent"],
           "properties": {
             "primary": { "$ref": "#/$defs/token" },
             "primaryHover": { "$ref": "#/$defs/token" },
@@ -35,6 +35,7 @@
             "accent": { "$ref": "#/$defs/token" },
             "accentHover": { "$ref": "#/$defs/token" },
             "accentActive": { "$ref": "#/$defs/token" },
+            "accentStrong": { "$ref": "#/$defs/token" },
             "onAccent": { "$ref": "#/$defs/token" }
           }
         },

package/schemas/theme.schema.json

@@ -16,7 +16,7 @@
       "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
     },
     "extends": {
-      "enum": ["light", "dark", "high-contrast"]
+      "enum": ["light", "dark", "high-contrast", "high-contrast-dark"]
     },
     "selector": {
       "type": "string",

package/scripts/build-tokens.mjs

@@ -13,6 +13,7 @@ const sourcePaths = {
   semanticLight: path.join(tokensDir, 'semantic.light.json'),
   semanticDark: path.join(tokensDir, 'semantic.dark.json'),
   semanticHighContrast: path.join(tokensDir, 'semantic.high-contrast.json'),
+  semanticHighContrastDark: path.join(tokensDir, 'semantic.high-contrast-dark.json'),
   components: path.join(tokensDir, 'components.json'),
 };
 
@@ -23,7 +24,7 @@ const schemaPaths = {
   theme: path.join(schemasDir, 'theme.schema.json'),
 };
 
-const builtInThemeNames = new Set(['light', 'dark', 'high-contrast']);
+const builtInThemeNames = new Set(['light', 'dark', 'high-contrast', 'high-contrast-dark']);
 
 const defaultContrastPairs = [
   ...['primary', 'secondary', 'muted'].flatMap((text) =>
@@ -58,6 +59,40 @@ const defaultContrastPairs = [
     background: `semantic.color.stateSurface.${state}`,
     minRatio: 4.5,
   })),
+  ...['info', 'success', 'warning', 'danger'].flatMap((state) =>
+    ['canvas', 'surface', 'elevated'].map((background) => ({
+      name: `${state} text on ${background}`,
+      foreground: `semantic.color.stateText.${state}`,
+      background: `semantic.color.background.${background}`,
+      minRatio: 4.5,
+    }))
+  ),
+  ...['primary', 'secondary'].flatMap((text) =>
+    ['info', 'success', 'warning', 'danger'].map((state) => ({
+      name: `${text} text on ${state} surface`,
+      foreground: `semantic.color.text.${text}`,
+      background: `semantic.color.stateSurface.${state}`,
+      minRatio: 4.5,
+    }))
+  ),
+  ...['info', 'success', 'warning', 'danger'].map((state) => ({
+    name: `${state} fill on muted track`,
+    foreground: `semantic.color.state.${state}`,
+    background: 'semantic.color.background.muted',
+    minRatio: 3,
+  })),
+  ...['canvas', 'surface', 'muted'].map((background) => ({
+    name: `strong accent on ${background}`,
+    foreground: 'semantic.color.brand.accentStrong',
+    background: `semantic.color.background.${background}`,
+    minRatio: 3,
+  })),
+  ...['canvas', 'surface', 'elevated'].map((background) => ({
+    name: `strong border on ${background}`,
+    foreground: 'semantic.color.border.strong',
+    background: `semantic.color.background.${background}`,
+    minRatio: 3,
+  })),
   ...['info', 'success', 'warning', 'danger'].map((state) => ({
     name: `text on solid ${state}`,
     foreground: 'semantic.color.state.onSolid',
@@ -96,6 +131,12 @@ const defaultContrastPairs = [
     background: 'components.control.background',
     minRatio: 3,
   },
+  {
+    name: 'placeholder on control background',
+    foreground: 'components.control.placeholder',
+    background: 'components.control.background',
+    minRatio: 4.5,
+  },
 ];
 
 const fontFallbacks = {
@@ -533,9 +574,10 @@ const componentVarName = (tokenPath) =>
 const inferPrimitiveUnit = (tokenPath) => {
   const [group, subgroup] = tokenPath;
   if (group === 'font') {
-    if (subgroup === 'size' || subgroup === 'lineHeight' || subgroup === 'letterSpacing') {
-      return 'px';
-    }
+    /* Type scale in rem so user browser font-size preferences are honored
+       (1.4.4); source values stay authored in px and are divided by 16. */
+    if (subgroup === 'size' || subgroup === 'lineHeight') return 'rem';
+    if (subgroup === 'letterSpacing') return 'px';
     return '';
   }
   if (['space', 'radius', 'border', 'size', 'layout', 'breakpoint'].includes(group)) {
@@ -548,6 +590,7 @@ const inferPrimitiveUnit = (tokenPath) => {
 const formatPrimitiveValue = (tokenPath, value) => {
   if (typeof value === 'number') {
     const unit = inferPrimitiveUnit(tokenPath);
+    if (unit === 'rem') return `${Number((value / 16).toFixed(4))}rem`;
     return unit ? `${value}${unit}` : String(value);
   }
   if (tokenPath[0] === 'font' && tokenPath[1] === 'family') {
@@ -1035,6 +1078,7 @@ const buildTokens = (options) => {
   const semanticLightRaw = readJson(sourcePaths.semanticLight);
   const semanticDarkOverride = readJson(sourcePaths.semanticDark);
   const semanticHighContrastOverride = readJson(sourcePaths.semanticHighContrast);
+  const semanticHighContrastDarkOverride = readJson(sourcePaths.semanticHighContrastDark);
   const componentsRaw = readJson(sourcePaths.components);
 
   const schemas = Object.fromEntries(
@@ -1055,11 +1099,17 @@ const buildTokens = (options) => {
     semanticLightRaw,
     'tokens/semantic.high-contrast.json'
   );
+  assertKnownOverride(
+    semanticHighContrastDarkOverride,
+    semanticLightRaw,
+    'tokens/semantic.high-contrast-dark.json'
+  );
 
   const semanticBuiltInRaw = {
     light: semanticLightRaw,
     dark: mergeDeep(semanticLightRaw, semanticDarkOverride),
     'high-contrast': mergeDeep(semanticLightRaw, semanticHighContrastOverride),
+    'high-contrast-dark': mergeDeep(semanticLightRaw, semanticHighContrastDarkOverride),
   };
 
   for (const [name, semanticRaw] of Object.entries(semanticBuiltInRaw)) {
@@ -1112,6 +1162,17 @@ const buildTokens = (options) => {
       componentRaw: componentsRaw,
       ...buildThemeLayers('high-contrast', semanticBuiltInRaw['high-contrast'], componentsRaw),
     },
+    'high-contrast-dark': {
+      name: 'high-contrast-dark',
+      selector: '[data-theme="high-contrast-dark"]',
+      semanticRaw: semanticBuiltInRaw['high-contrast-dark'],
+      componentRaw: componentsRaw,
+      ...buildThemeLayers(
+        'high-contrast-dark',
+        semanticBuiltInRaw['high-contrast-dark'],
+        componentsRaw
+      ),
+    },
   };
 
   const customThemes = options.themes.map((themePath) => {
@@ -1178,6 +1239,10 @@ const buildTokens = (options) => {
   const highContrastSemanticEntries =
     builtInThemes['high-contrast'].semanticLayer.cssEntries;
   const highContrastComponentEntries = builtInThemes['high-contrast'].componentLayer.cssEntries;
+  const highContrastDarkSemanticEntries =
+    builtInThemes['high-contrast-dark'].semanticLayer.cssEntries;
+  const highContrastDarkComponentEntries =
+    builtInThemes['high-contrast-dark'].componentLayer.cssEntries;
 
   const primitiveEntries = primitiveLayer.cssEntries;
   const semanticEntries = lightTheme.semanticLayer.cssEntries;
@@ -1287,6 +1352,12 @@ const buildTokens = (options) => {
       highContrastSemanticEntries,
       highContrastComponentEntries
     ),
+    ...themeBlock(
+      builtInThemes['high-contrast-dark'].selector,
+      'high-contrast-dark',
+      highContrastDarkSemanticEntries,
+      highContrastDarkComponentEntries
+    ),
     ...customThemeBlocks,
     ...mediaBlock(
       '(prefers-color-scheme: dark)',
@@ -1302,12 +1373,23 @@ const buildTokens = (options) => {
       highContrastSemanticEntries,
       highContrastComponentEntries
     ),
+    /* Emitted after the light high-contrast block so it wins the cascade
+       when both prefers-contrast: more and a dark color scheme match —
+       dark-mode users asking for more contrast keep a dark UI. */
+    ...mediaBlock(
+      '(prefers-contrast: more) and (prefers-color-scheme: dark)',
+      ':root:not([data-theme])',
+      'high-contrast-dark (system)',
+      highContrastDarkSemanticEntries,
+      highContrastDarkComponentEntries
+    ),
   ];
 
   const semanticThemes = {};
   const componentThemes = {};
   for (const theme of allThemes) {
-    const exportName = theme.name === 'high-contrast' ? 'highContrast' : theme.name;
+    const exportNames = { 'high-contrast': 'highContrast', 'high-contrast-dark': 'highContrastDark' };
+    const exportName = exportNames[theme.name] ?? theme.name;
     semanticThemes[exportName] = theme.semanticLayer.resolved;
     componentThemes[exportName] = theme.componentLayer.resolved;
   }