@mlola-ui/engine 1.0.2 → 1.0.3

package/build.mjs

@@ -7,6 +7,7 @@ import { renderCatalogCss } from "./src/library-recipes.mjs";
 import { renderSpecSchema } from "./src/spec.mjs";
 import { renderThemeCss, renderThemeManifest } from "./src/theme.mjs";
 import {
+  renderAccessibilityCss,
   renderDtcg,
   renderFoundationsCss,
   renderMaterialsCss,
@@ -28,6 +29,7 @@ const layers = {
   "materials.css": renderMaterialsCss(),
   "recipes.css": renderRecipesCss(),
   "motion.css": renderMotionCss(),
+  "accessibility.css": renderAccessibilityCss(),
 };
 
 const layerOrder = "mlola.tokens, mlola.foundations, mlola.materials, mlola.recipes, mlola.motion, mlola.accessibility";
@@ -41,6 +43,7 @@ const aggregate = `/* Generated by @mlola-ui/engine. React and Tailwind are not
 @import "./materials.css" layer(mlola.materials);
 @import "./recipes.css" layer(mlola.recipes);
 @import "./motion.css" layer(mlola.motion);
+@import "./accessibility.css" layer(mlola.accessibility);
 `;
 
 const dtcg = `${JSON.stringify(renderDtcg(), null, 2)}\n`;

package/generated/accessibility.css

@@ -0,0 +1,9 @@
+/* Accessibility layer: last in the cascade, so these guarantees hold over any recipe. */
+/* On a touch screen, a text field smaller than 16px makes iOS zoom the page
+   when it takes focus, and the page stays zoomed after. Every field that
+   takes typing is at least 16px there; everything else keeps its size. */
+@media (pointer: coarse) {
+  :is(input:not([type="checkbox"], [type="radio"], [type="range"], [type="color"], [type="file"], [type="submit"], [type="button"], [type="reset"], [type="image"], [type="hidden"]), textarea, select, [contenteditable]:not([contenteditable="false"])) {
+    font-size: max(1rem, 1em);
+  }
+}

package/generated/agents.md

@@ -9,7 +9,7 @@ Generated from the source of truth. Do not edit by hand.
 - **Style through the classes below, never through invented ones.** A class
   that is not in this document does not exist. (Mlola Pro's classes are in the
   guide that comes with Pro source.)
-- **Behaviour is optional and framework-free.** `@mlola-ui/behavior` attaches
+- **Behavior is optional and framework-free.** `@mlola-ui/behavior` attaches
   to markup you already rendered. It never renders anything itself, so it works
   with React, Svelte, Vue, Rails, a Go template or a static file.
 - **Native controls stay native.** Checkbox and radio are real `<input>`
@@ -45,9 +45,93 @@ Set `data-theme` and `data-mode` on any ancestor. Nothing else changes.
 `data-mode` is `light` or `dark`.
 
 A project defines its own theme in one file, `mlola.theme.json`, which
-overrides fonts, colours, geometry, the spacing and type scale, and any
+overrides fonts, colors, geometry, the spacing and type scale, and any
 custom property through `extend`. See `mlola.theme.example.json`.
 
+## Tokens
+
+Every value a design needs is a token. Read them with `var()`; never write
+a color, a size from outside the scales, a shadow or a duration by hand.
+Values change with the theme and the mode, the names never do.
+
+- **Planes and ink.** Backgrounds, surfaces, the three levels of text, borders.
+  `--ml-background` `--ml-background-subtle` `--ml-surface` `--ml-surface-elevated` `--ml-text` `--ml-text-muted` `--ml-text-faint` `--ml-border` `--ml-border-subtle`
+- **Color roles.** Each role is a fill with its `-foreground`, a `-text` for text and marks on the page, and (primary) a `-subtle` tint.
+  `--ml-primary` `--ml-primary-foreground` `--ml-primary-text` `--ml-primary-subtle` `--ml-success` `--ml-success-foreground` `--ml-success-text` `--ml-warning` `--ml-warning-foreground` `--ml-warning-text` `--ml-danger` `--ml-danger-foreground` `--ml-danger-text` `--ml-info` `--ml-info-foreground` `--ml-info-text`
+- **Charts.** A categorical palette for series, 3:1 on the surface. Never a status.
+  `--ml-chart-1` `--ml-chart-2` `--ml-chart-3` `--ml-chart-4` `--ml-chart-5` `--ml-chart-6`
+- **Interaction and light.** Focus, hover and pressed fills, tracks, the veil behind overlays, light and knobs.
+  `--ml-focus` `--ml-primary-hover` `--ml-fill-hover` `--ml-fill-active` `--ml-track` `--ml-control-border` `--ml-ring` `--ml-scrim` `--ml-highlight` `--ml-knob` `--ml-knob-shadow` `--ml-sheen`
+- **Spacing.** The only spacing: gaps, padding, margins, offsets.
+  `--ml-space-px` `--ml-space-0-5` `--ml-space-1` `--ml-space-1-5` `--ml-space-2` `--ml-space-2-5` `--ml-space-3` `--ml-space-3-5` `--ml-space-4` `--ml-space-4-5` `--ml-space-5` `--ml-space-6` `--ml-space-7` `--ml-space-8` `--ml-space-9` `--ml-space-10` `--ml-space-12` `--ml-space-14` `--ml-space-16`
+- **Type.** The only type sizes, line heights, families and weights.
+  `--ml-type-2xs` `--ml-type-xs` `--ml-type-sm` `--ml-type-base` `--ml-type-md` `--ml-type-lg` `--ml-type-xl` `--ml-type-2xl` `--ml-leading-tight` `--ml-leading-snug` `--ml-leading-normal` `--ml-font-sans` `--ml-font-display` `--ml-font-mono` `--ml-display-weight` `--ml-body-leading` `--ml-tracking`
+- **Density.** Control heights, panel padding, the touch target.
+  `--ml-control-sm` `--ml-control-md` `--ml-control-lg` `--ml-panel-padding` `--ml-target-min`
+- **Shape.** Corner radii by the size of the thing, and the border weight.
+  `--ml-radius-xs` `--ml-radius-sm` `--ml-radius-md` `--ml-radius-lg` `--ml-radius-pill` `--ml-border-width`
+- **Depth and material.** Elevation, and the material a floating surface is made of.
+  `--ml-texture-opacity` `--ml-material` `--ml-surface-alpha` `--ml-surface-blur` `--ml-surface-grain` `--ml-surface-highlight` `--ml-shadow-xs` `--ml-shadow-sm` `--ml-shadow-md` `--ml-shadow-lg` `--ml-shadow-xl` `--ml-shadow-tint`
+- **Motion.** Every transition and entrance.
+  `--ml-duration-fast` `--ml-duration-normal` `--ml-duration-slow` `--ml-duration-reveal` `--ml-ease-standard` `--ml-ease-spring` `--ml-ease-bounce`
+- **Layers.** The one stacking order.
+  `--ml-layer-raised` `--ml-layer-sticky` `--ml-layer-header` `--ml-layer-dropdown` `--ml-layer-overlay` `--ml-layer-modal` `--ml-layer-popover` `--ml-layer-toast` `--ml-layer-tooltip` `--ml-layer-top`
+- **Icons.** The theme's icon channel.
+  `--ml-icon-stroke`
+
+## Designing new UI in the Mlola language
+
+When the elements above do not cover what you need, build it the way they are
+built, and it will look like it belongs.
+
+1. **Compose first.** Reach for a component, then a layout primitive, and
+   write CSS only for what neither covers. Put it in a layer of your own,
+   declared before `mlola.accessibility` so the accessibility guarantees
+   still win:
+   `@layer mlola.tokens, mlola.foundations, mlola.materials, mlola.recipes, mlola.motion, app, mlola.accessibility;`
+2. **Name what it is, not how it looks.** One class per element role, with
+   your own prefix (not `ml-`, so a later Mlola element never collides).
+   State and variant go in `data-*` and `aria-*`, never in a second class.
+   Reuse the shared words: `data-tone` is `neutral primary info success
+   warning danger`; `data-size` is `xs sm md lg xl`; work that went
+   wrong is `error`.
+3. **Color by role, never by value.** Planes are `background`,
+   `background-subtle`, `surface`, `surface-elevated`. Ink is `text`,
+   `text-muted`, `text-faint`. A colored fill (`primary`, `danger`, …)
+   always carries its `-foreground`. Colored text, icons, lines and status
+   marks on the page use the `-text` role: fills are only kept 1.5:1 from the
+   page, enough for an area, not for meaning. Series use `chart-1`…`chart-6`.
+4. **Measure with the scales.** Spacing from `--ml-space-*`, type from
+   `--ml-type-*` with `--ml-leading-*`, control heights from
+   `--ml-control-*`, panel padding from `--ml-panel-padding`. A `clamp()`
+   between two steps is fine; a value invented between them is not.
+5. **Shape and depth come from the theme.** Radii by the size of the thing
+   (`xs` a tag, `sm` a small control, `md` a control or card, `lg` a panel
+   or dialog, `pill`). Elevation from `--ml-shadow-*`; a floating surface
+   also takes the material: `--ml-surface-alpha`, `--ml-surface-blur`,
+   `--ml-surface-highlight`.
+6. **Move with the theme.** Durations from `--ml-duration-*`, easing from
+   `--ml-ease-*`. Reduced motion is handled by the engine.
+7. **Stack with the layers.** `--ml-layer-*`, never a raw z-index above 9.
+8. **Keep it usable by hand.** Never remove an outline without a
+   `:focus-visible` style in its place. Targets are at least 24px; a smaller
+   control adds `data-hit="expand"` for touch. Text is never under
+   `--ml-type-2xs`.
+9. **Leave the theme alone.** `data-theme` and `data-mode` belong to the
+   engine; never set them for a component's own meaning, and never style a
+   theme or mode by name. If something must differ by theme, it is a token.
+
+## Composition primitives
+
+Compose pages from these before writing layout CSS: sections, stacks,
+clusters, grids, headings, forms, stats. They read the same tokens as every
+component, so a page built from them themes with the rest.
+
+`.ml-actions` `.ml-brand` `.ml-brand-mark` `.ml-brand-name` `.ml-chart` `.ml-chart-bar` `.ml-chart-bars` `.ml-chart-heading` `.ml-cluster` `.ml-definition-list` `.ml-display` `.ml-divider` `.ml-empty-state` `.ml-eyebrow` `.ml-filter-chip` `.ml-filter-group` `.ml-fine-print` `.ml-form` `.ml-form-message` `.ml-form-options` `.ml-grid` `.ml-heading` `.ml-icon-chip` `.ml-inline-form` `.ml-inline-form-field` `.ml-label` `.ml-lede` `.ml-link` `.ml-page-shell` `.ml-person` `.ml-person-copy` `.ml-positive` `.ml-price` `.ml-required-mark` `.ml-section` `.ml-section-description` `.ml-section-header` `.ml-section-header-centered` `.ml-section-muted` `.ml-section-shell` `.ml-stack` `.ml-stat` `.ml-stat-card` `.ml-stat-grid` `.ml-stat-list` `.ml-stat-meta` `.ml-stat-value` `.ml-text-primary` `.ml-value`
+
+- `.ml-link` — A glyph inside a link flows with the text instead of breaking the line.
+- `.ml-page-shell` — A full page: header, main and footer stacked on the page background.
+
 ## Elements and their attributes
 
 Emit these classes and attributes from any language and the visuals are
@@ -198,11 +282,11 @@ correct. This table is read out of the stylesheet, so it is never stale.
 | `.ml-toggle-button` | `data-state` | `on` |
 | `.ml-tooltip` | `data-side` | `bottom`, `left`, `right`, `top` |
 | `.ml-tour-button` | `data-primary` | _presence only_ |
-| `.ml-tour-card` | `data-centred` | _presence only_ |
+| `.ml-tour-card` | `data-centered` | _presence only_ |
 | `.ml-tour-dot` | `data-active` | _presence only_ |
 | `.ml-tour-scrim` | `data-spotlight` | _presence only_ |
 
-## Behaviour
+## Behavior
 
 ### accordion
 
@@ -316,7 +400,7 @@ A short label shown on hover or focus.
   - <kbd>Escape</kbd>: Hide the tooltip.
 - State changes:
   - On pointer enter or focus the trigger, set visible to after the delay.
-  - On pointer leave or blur, set hidden to immediately, cancelling any pending delay.
+  - On pointer leave or blur, set hidden to immediately, canceling any pending delay.
 - Note: Never put essential information or interactive content in a tooltip.
 
 ### toast
@@ -365,5 +449,5 @@ A single value chosen from a range.
 
 Prefer emitting less. A plain `<button class="ml-button">` is correct; a
 button with a variant this document does not list is not. When a component
-needs behaviour, mark its root with `data-ml="<behaviour name>"` and let the
+needs behavior, mark its root with `data-ml="<behavior name>"` and let the
 runtime attach, rather than writing event handlers that guess at the contract.

package/generated/assets.json

@@ -8,7 +8,7 @@
       "summary": "currentColor SVG glyphs. Size and stroke follow the active theme unless a prop overrides them.",
       "props": {
         "size": "number or CSS length. Defaults to var(--mlola-glyph-size, 1.125rem).",
-        "strokeWidth": "number or CSS length. Defaults to var(--mlola-glyph-stroke, 1.75).",
+        "strokeWidth": "number or CSS length. Defaults to the theme's --ml-icon-stroke; --mlola-glyph-stroke overrides it.",
         "opticalSize": "small | default | large",
         "animate": "boolean, honours prefers-reduced-motion",
         "title": "gives the glyph an accessible name; without it the glyph is decorative"
@@ -1059,7 +1059,7 @@
     {
       "id": "3d",
       "label": "3D assets",
-      "summary": "glTF models with a poster still. Materials are named by theme role, so a Mlola viewer paints them in the active theme; any other viewer shows their own colours.",
+      "summary": "glTF models with a poster still. Materials are named by theme role, so a Mlola viewer paints them in the active theme; any other viewer shows their own colors.",
       "items": [
         {
           "id": "blocks",

package/generated/contract.json

@@ -591,7 +591,7 @@
         "data-primary": []
       },
       "ml-tour-card": {
-        "data-centred": []
+        "data-centered": []
       },
       "ml-tour-dot": {
         "data-active": []
@@ -1067,7 +1067,7 @@
         {
           "on": "pointer leave or blur",
           "set": "hidden",
-          "to": "immediately, cancelling any pending delay"
+          "to": "immediately, canceling any pending delay"
         }
       ],
       "notes": "Never put essential information or interactive content in a tooltip."

package/generated/foundations.css

@@ -113,10 +113,27 @@ h3 {
   opacity: .5;
 }
 
+/* Room for a fingertip on text fields, which grow with their content.
+   Buttons keep the shape their recipe draws: stretching a round or square
+   control only distorts it. Small ones widen their target invisibly instead
+   (see [data-hit] below), and every other button already clears the 24px
+   minimum of WCAG 2.5.8. */
 @media (pointer:coarse) {
-  :where(button,[role="button"],input:not([type="hidden"]),select,textarea) {
+  :where(input:not([type="hidden"],[type="checkbox"],[type="radio"],[type="range"],[type="color"],[type="file"],[type="submit"],[type="button"],[type="reset"],[type="image"]),select,textarea):where(:not([data-shape="inline"])) {
     min-height: var(--ml-target-min);
   }
+
+  /* A control drawn smaller than a fingertip keeps its look and gains an
+     invisible target around it. */
+  :where([data-hit="expand"]) {
+    position: relative;
+  }
+
+  :where([data-hit="expand"])::after {
+    position: absolute;
+    inset: min(-0.375rem, calc((var(--ml-target-min) - 100%) / -2));
+    content: "";
+  }
 }
 
 @media (prefers-reduced-transparency:reduce) {
@@ -139,7 +156,7 @@ h3 {
     forced-color-adjust: auto;
   }
 
-  /* Box-shadow rings vanish in forced colours; the system highlight stands in. */
+  /* Box-shadow rings vanish in forced colors; the system highlight stands in. */
   :focus-visible {
     outline: 2px solid Highlight!important;
     outline-offset: 2px!important;

package/generated/mlola.css

@@ -8,3 +8,4 @@
 @import "./materials.css" layer(mlola.materials);
 @import "./recipes.css" layer(mlola.recipes);
 @import "./motion.css" layer(mlola.motion);
+@import "./accessibility.css" layer(mlola.accessibility);

package/generated/recipes.css

@@ -559,7 +559,7 @@
   border-radius: var(--ml-radius-xs);
   background: transparent;
   color: var(--ml-text);
-  text-align: left;
+  text-align: start;
   font-size: var(--ml-type-base);
   font-weight: 500;
   cursor: pointer;
@@ -822,7 +822,7 @@
   transition: opacity var(--ml-duration-fast) var(--ml-ease-standard), transform var(--ml-duration-normal) var(--ml-ease-standard);
 }
 
-/* A solid mark in the tone, centred on the first line of text. */
+/* A solid mark in the tone, centered on the first line of text. */
 .ml-alert-icon {
   position: relative;
   display: inline-grid;
@@ -1302,7 +1302,7 @@
   font-size: var(--ml-type-sm);
 }
 
-/* Tone picks the colour role; variant decides how it is worn. */
+/* Tone picks the color role; variant decides how it is worn. */
 .ml-badge[data-tone="primary"] {
   --ml-badge-tone: var(--ml-primary);
   --ml-badge-text: var(--ml-primary-text);
@@ -1492,7 +1492,7 @@
 }
 
 /* A toggle button that is on reads as filled ink, so its state is visible
-   without relying on colour alone. */
+   without relying on color alone. */
 .ml-button[data-variant="secondary"][aria-pressed="true"],
 .ml-button[data-variant="subtle"][aria-pressed="true"],
 .ml-button[data-variant="outline"][aria-pressed="true"] {
@@ -1579,7 +1579,7 @@
   width: .875rem;
   height: .875rem;
   border: 1.5px solid currentColor;
-  border-right-color: transparent;
+  border-inline-end-color: transparent;
   border-radius: 50%;
   animation: ml-spin .7s linear infinite;
 }
@@ -1596,7 +1596,7 @@
 }
 
 /* A shortcut inside a filled button takes the button's own ink: an outline
-   of the text colour, no fill of its own, so it reads on any variant. */
+   of the text color, no fill of its own, so it reads on any variant. */
 .ml-button .ml-kbd {
   border-color: color-mix(in oklab, currentColor 40%, transparent);
   background: transparent;
@@ -1608,6 +1608,9 @@
 .ml-calendar {
   --ml-calendar-day: 2.25rem;
   display: inline-grid;
+  /* One column no wider than the calendar, so two months wrap into a stack
+     when the space is narrower than both side by side. */
+  grid-template-columns: minmax(0, 1fr);
   width: max-content;
   max-width: 100%;
   color: var(--ml-text);
@@ -1835,7 +1838,7 @@
   position: absolute;
   inset: 0;
   pointer-events: none;
-  background: linear-gradient(135deg,oklch(1 0 0/.18),transparent 46%,oklch(0 0 0/.05));
+  background: var(--ml-sheen);
 }
 
 .ml-card-header {
@@ -2188,6 +2191,7 @@
   position: relative;
   height: 9.5rem;
   border-radius: var(--ml-radius-md);
+  /* audit-allow: color.literal — this is the color model itself: value falls to black, saturation to white. */
   background: linear-gradient(to top, #000, transparent), linear-gradient(to right, #fff, transparent), var(--ml-color-hue);
   cursor: crosshair;
   outline: none;
@@ -2235,16 +2239,16 @@
   position: absolute;
   width: 1rem;
   height: 1rem;
-  border: 2.5px solid #fff;
+  border: 2.5px solid var(--ml-knob);
   border-radius: 50%;
-  box-shadow: 0 0 0 1px rgb(0 0 0 / 0.25), 0 1px 4px rgb(0 0 0 / 0.3);
+  box-shadow: var(--ml-knob-shadow);
   pointer-events: none;
   translate: -50% -50%;
 }
 
 .ml-color-picker-area:focus-visible > .ml-color-picker-thumb,
 .ml-color-picker-track:focus-visible > .ml-color-picker-thumb {
-  box-shadow: 0 0 0 2px var(--ml-focus), 0 1px 4px rgb(0 0 0 / 0.3);
+  box-shadow: 0 0 0 2px var(--ml-focus), 0 1px 4px var(--ml-shadow-tint);
 }
 
 .ml-color-picker-row {
@@ -2455,7 +2459,8 @@
 .ml-combobox-list {
   display: grid;
   gap: var(--ml-space-0-5);
-  max-height: 16rem;
+  /* Never taller than the visible room beside the field (set when it opens). */
+  max-height: min(16rem, var(--ml-combobox-room, 16rem));
   margin: 0;
   padding: 0;
   overflow-y: auto;
@@ -2569,6 +2574,7 @@
   flex: 1;
   min-width: 0;
   border: 0;
+  /* audit-allow: focus.removed — the search field is the open dialog's only field; its caret shows focus. */
   outline: none;
   background: transparent;
   color: var(--ml-text);
@@ -2688,6 +2694,7 @@
   border-radius: var(--ml-radius-lg);
   box-shadow: var(--ml-surface-highlight), var(--ml-shadow-lg);
   color: var(--ml-text);
+  /* audit-allow: focus.removed — a menu container, focused only by script (tabindex -1); its items carry the focus style. */
   outline: none;
   background-color: color-mix(in oklab, var(--ml-surface-elevated) var(--ml-surface-alpha), transparent);
   background-image: var(--ml-surface-grain);
@@ -2981,7 +2988,7 @@
   color: var(--ml-text);
   font-size: var(--ml-type-sm);
   font-weight: 400;
-  text-align: left;
+  text-align: start;
   text-decoration: none;
   cursor: pointer;
 }
@@ -3271,6 +3278,7 @@
 /* components/input */
 .ml-input-field {
   display: grid;
+  grid-template-columns: minmax(0, 1fr);
   gap: var(--ml-space-1-5);
   width: 100%;
 }
@@ -3646,12 +3654,16 @@
 /* components/otp-input */
 .ml-otp {
   display: flex;
+  max-width: 100%;
   align-items: center;
   gap: var(--ml-space-2);
 }
 
+/* Boxes give a little way on the narrowest phones instead of running past the edge. */
 .ml-otp-box {
+  flex: 0 1 var(--ml-control-lg);
   width: var(--ml-control-lg);
+  min-width: 2rem;
   height: calc(var(--ml-control-lg) * 1.15);
   padding: 0;
   border: var(--ml-border-width) solid var(--ml-border);
@@ -3682,6 +3694,7 @@
 }
 
 .ml-otp-separator {
+  flex: none;
   width: var(--ml-space-2);
   height: 2px;
   border-radius: var(--ml-radius-pill);
@@ -3816,7 +3829,7 @@
 }
 
 .ml-priority-icon[data-priority="urgent"] {
-  color: var(--ml-danger);
+  color: var(--ml-danger-text);
 }
 
 .ml-priority-icon[data-priority="high"] {
@@ -4404,7 +4417,7 @@
   border-radius: var(--ml-radius-md);
   box-shadow: var(--ml-shadow-xs);
   cursor: pointer;
-  text-align: left;
+  text-align: start;
   transition: border-color var(--ml-duration-fast),box-shadow var(--ml-duration-fast);
 }
 
@@ -4439,7 +4452,7 @@
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  text-align: left;
+  text-align: start;
 }
 
 .ml-select-chips {
@@ -4528,6 +4541,7 @@
   border-radius: var(--ml-radius-sm);
   background: transparent;
   font-size: var(--ml-type-sm);
+  /* audit-allow: focus.removed — the search field inside an open listbox; its caret shows focus. */
   outline: none;
 }
 
@@ -4567,7 +4581,7 @@
   background: transparent;
   color: var(--ml-text);
   font-size: var(--ml-type-sm);
-  text-align: left;
+  text-align: start;
   cursor: pointer;
 }
 
@@ -4822,7 +4836,7 @@
 }
 
 /* Each line is one line box of the surrounding text: a bar about the height
-   of lowercase letters, centred in 1lh. */
+   of lowercase letters, centered in 1lh. */
 .ml-skeleton-line {
   height: 0.62em;
   margin-block: calc((1lh - 0.62em) / 2);
@@ -4948,7 +4962,7 @@
   height: var(--ml-space-4);
   border: var(--ml-border-width) solid color-mix(in oklab,var(--ml-primary) 45%,var(--ml-border));
   border-radius: 50%;
-  background: oklch(1 0 0);
+  background: var(--ml-knob);
   box-shadow: var(--ml-shadow-sm);
   transform: translate(-50%,-50%);
   cursor: grab;
@@ -4968,7 +4982,7 @@
 }
 
 /* components/status-icon */
-/* Colour carries the stage; the glyph carries it without colour too. */
+/* Color carries the stage; the glyph carries it without color too. */
 .ml-status-icon {
   --ml-status-mark: var(--ml-surface);
   flex: none;
@@ -4981,14 +4995,16 @@
 }
 
 .ml-status-icon[data-status="in-progress"] {
-  color: var(--ml-warning);
+  color: var(--ml-warning-text);
 }
 
 .ml-status-icon[data-status="in-review"] {
-  color: var(--ml-success);
+  color: var(--ml-success-text);
 }
 
+/* Done is a filled disc carrying its check in the foreground: a fill and its pair. */
 .ml-status-icon[data-status="done"] {
+  /* audit-allow: color.role — the disc is a fill; its mark takes --ml-primary-foreground. */
   color: var(--ml-primary);
   --ml-status-mark: var(--ml-primary-foreground);
 }
@@ -5029,7 +5045,7 @@
 }
 
 /* Horizontal: the connector is a flex item after the step, level with the
-   marker's centre, and fills once the step is done. */
+   marker's center, and fills once the step is done. */
 .ml-stepper[data-orientation="horizontal"] .ml-stepper-step:not(:last-child)::after {
   min-width: var(--ml-space-4);
   height: 2px;
@@ -5216,7 +5232,7 @@ button.ml-stepper-target:focus-visible {
 .ml-table {
   width: 100%;
   border-collapse: collapse;
-  text-align: left;
+  text-align: start;
   font-size: var(--ml-type-sm);
 }
 
@@ -5256,7 +5272,7 @@ button.ml-stepper-target:focus-visible {
 .ml-table [data-align="right"],
 .ml-table [data-align="end"],
 .ml-table [data-numeric] {
-  text-align: right;
+  text-align: end;
   font-variant-numeric: tabular-nums;
 }
 
@@ -5315,7 +5331,7 @@ button.ml-stepper-target:focus-visible {
   padding: var(--ml-space-3) var(--ml-space-4);
   color: var(--ml-text-muted);
   font-size: var(--ml-type-xs);
-  text-align: left;
+  text-align: start;
 }
 
 .ml-table-footer {
@@ -5351,6 +5367,7 @@ button.ml-stepper-target:focus-visible {
 /* components/tabs */
 .ml-tabs {
   display: grid;
+  grid-template-columns: minmax(0, 1fr);
   gap: var(--ml-space-4);
   width: 100%;
 }
@@ -5745,7 +5762,7 @@ button.ml-stepper-target:focus-visible {
 
 /* components/timeline */
 /* A rail of markers and a column of text. Each item draws the segment of
-   rail below its own marker, so the line always runs through the centres,
+   rail below its own marker, so the line always runs through the centers,
    whatever each item holds, and fills in as the sequence progresses. */
 .ml-timeline {
   --ml-timeline-marker: 1.5rem;
@@ -5874,7 +5891,7 @@ button.ml-stepper-target:focus-visible {
   min-width: 0;
 }
 
-/* The heading row is as tall as the marker, so a one-line title sits on its centre. */
+/* The heading row is as tall as the marker, so a one-line title sits on its center. */
 .ml-timeline-heading {
   display: flex;
   flex-wrap: wrap;
@@ -6208,7 +6225,7 @@ button.ml-stepper-target:focus-visible {
   width: 1rem;
   height: 1rem;
   border-radius: 50%;
-  background: oklch(1 0 0);
+  background: var(--ml-knob);
   box-shadow: var(--ml-shadow-sm);
   pointer-events: none;
   transition: transform var(--ml-duration-normal) var(--ml-ease-spring);
@@ -6373,11 +6390,12 @@ button.ml-stepper-target:focus-visible {
   background: var(--ml-surface-elevated);
   box-shadow: var(--ml-shadow-xl);
   color: var(--ml-text);
+  /* audit-allow: focus.removed — the tour card is focused by script (tabindex -1); its buttons carry the focus style. */
   outline: none;
   animation: ml-pop-in var(--ml-duration-fast) var(--ml-ease-spring);
 }
 
-.ml-tour-card[data-centred] {
+.ml-tour-card[data-centered] {
   top: 50%;
   left: 50%;
   translate: -50% -50%;

package/generated/theme-spec.schema.json

@@ -96,7 +96,7 @@
       "properties": {
         "primary": {
           "type": "string",
-          "description": "Seed for the primary colour, oklch() or hex. Lightness is adjusted to meet contrast."
+          "description": "Seed for the primary color, oklch() or hex. Lightness is adjusted to meet contrast."
         },
         "primaryDark": {
           "type": [

package/generated/tokens.css

@@ -91,6 +91,7 @@
   --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.0304), 0 4.103px 13.32px -2px oklch(0 0 0 / 0.0608);
   --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0266), 0 8.206px 23.68px -4px oklch(0 0 0 / 0.076);
   --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0228), 0 15.044px 41.44px -8px oklch(0 0 0 / 0.095);
+  --ml-shadow-tint: oklch(0 0 0 / 0.0608);
   --ml-background: oklch(1 0 0);
   --ml-background-subtle: oklch(0.968 0.006 286);
   --ml-surface: oklch(1 0 0);
@@ -130,6 +131,10 @@
   --ml-control-border: var(--ml-text-faint);
   --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
   --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
 :root[data-mode="dark"],
@@ -172,6 +177,7 @@
   --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.079), 0 4.103px 13.32px -2px oklch(0 0 0 / 0.1581);
   --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0692), 0 8.206px 23.68px -4px oklch(0 0 0 / 0.1976);
   --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0593), 0 15.044px 41.44px -8px oklch(0 0 0 / 0.247);
+  --ml-shadow-tint: oklch(0 0 0 / 0.1581);
   --ml-focus: var(--ml-primary-text);
   --ml-primary-hover: color-mix(in oklab, var(--ml-primary) 88%, var(--ml-background));
   --ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent);
@@ -180,6 +186,10 @@
   --ml-control-border: var(--ml-text-faint);
   --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
   --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
 @supports (transition-timing-function: linear(0, 1)) {
@@ -239,6 +249,7 @@
   --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.0485), 0 6.378px 24.692px -2px oklch(0 0 0 / 0.0971);
   --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0425), 0 12.756px 43.898px -4px oklch(0 0 0 / 0.1213);
   --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0364), 0 23.387px 76.821px -8px oklch(0 0 0 / 0.1517);
+  --ml-shadow-tint: oklch(0 0 0 / 0.0971);
   --ml-background: oklch(0.972 0.016 80);
   --ml-background-subtle: oklch(0.94 0.02 80);
   --ml-surface: oklch(0.989 0.01 80);
@@ -278,6 +289,10 @@
   --ml-control-border: var(--ml-text-faint);
   --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
   --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
 :root[data-theme="atelier"][data-mode="dark"],
@@ -319,6 +334,7 @@
   --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.1262), 0 6.378px 24.692px -2px oklch(0 0 0 / 0.2524);
   --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.1104), 0 12.756px 43.898px -4px oklch(0 0 0 / 0.3155);
   --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0946), 0 23.387px 76.821px -8px oklch(0 0 0 / 0.3944);
+  --ml-shadow-tint: oklch(0 0 0 / 0.2524);
   --ml-focus: var(--ml-primary-text);
   --ml-primary-hover: color-mix(in oklab, var(--ml-primary) 88%, var(--ml-background));
   --ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent);
@@ -327,6 +343,10 @@
   --ml-control-border: var(--ml-text-faint);
   --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
   --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
 @supports (transition-timing-function: linear(0, 1)) {
@@ -385,6 +405,7 @@
   --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.0306), 0 3.828px 13.331px -2px oklch(0 0 0 / 0.0612);
   --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0268), 0 7.655px 23.699px -4px oklch(0 0 0 / 0.0764);
   --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0229), 0 14.034px 41.474px -8px oklch(0 0 0 / 0.0956);
+  --ml-shadow-tint: oklch(0 0 0 / 0.0612);
   --ml-background: oklch(0.994 0.003 240);
   --ml-background-subtle: oklch(0.962 0.006 240);
   --ml-surface: oklch(0.997 0.001 240);
@@ -424,6 +445,10 @@
   --ml-control-border: var(--ml-text-faint);
   --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
   --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
 :root[data-theme="machined"][data-mode="dark"],
@@ -465,6 +490,7 @@
   --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.0795), 0 3.828px 13.331px -2px oklch(0 0 0 / 0.159);
   --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0696), 0 7.655px 23.699px -4px oklch(0 0 0 / 0.1988);
   --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0596), 0 14.034px 41.474px -8px oklch(0 0 0 / 0.2485);
+  --ml-shadow-tint: oklch(0 0 0 / 0.159);
   --ml-focus: var(--ml-primary-text);
   --ml-primary-hover: color-mix(in oklab, var(--ml-primary) 88%, var(--ml-background));
   --ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent);
@@ -473,6 +499,10 @@
   --ml-control-border: var(--ml-text-faint);
   --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
   --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
 @supports (transition-timing-function: linear(0, 1)) {
@@ -531,6 +561,7 @@
   --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.0593), 0 9.818px 32.195px -2px oklch(0 0 0 / 0.1186);
   --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0519), 0 19.636px 57.235px -4px oklch(0 0 0 / 0.1483);
   --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0445), 0 35.999px 100.162px -8px oklch(0 0 0 / 0.1854);
+  --ml-shadow-tint: oklch(0 0 0 / 0.1186);
   --ml-background: oklch(0.986 0.007 260);
   --ml-background-subtle: oklch(0.954 0.022 260);
   --ml-surface: oklch(0.995 0.002 260);
@@ -570,6 +601,10 @@
   --ml-control-border: var(--ml-text-faint);
   --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
   --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
 :root[data-theme="aerogel"][data-mode="dark"],
@@ -611,6 +646,7 @@
   --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.1542), 0 9.818px 32.195px -2px oklch(0 0 0 / 0.3084);
   --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.1349), 0 19.636px 57.235px -4px oklch(0 0 0 / 0.3855);
   --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.1157), 0 35.999px 100.162px -8px oklch(0 0 0 / 0.4819);
+  --ml-shadow-tint: oklch(0 0 0 / 0.3084);
   --ml-focus: var(--ml-primary-text);
   --ml-primary-hover: color-mix(in oklab, var(--ml-primary) 88%, var(--ml-background));
   --ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent);
@@ -619,6 +655,10 @@
   --ml-control-border: var(--ml-text-faint);
   --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
   --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
 @supports (transition-timing-function: linear(0, 1)) {
@@ -677,6 +717,7 @@
   --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.0407), 0 4.887px 19.58px -2px oklch(0 0 0 / 0.0815);
   --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0356), 0 9.775px 34.81px -4px oklch(0 0 0 / 0.1018);
   --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0305), 0 17.92px 60.917px -8px oklch(0 0 0 / 0.1273);
+  --ml-shadow-tint: oklch(0 0 0 / 0.0815);
   --ml-background: oklch(0.969 0.018 135);
   --ml-background-subtle: oklch(0.937 0.023 135);
   --ml-surface: oklch(0.988 0.011 135);
@@ -716,6 +757,10 @@
   --ml-control-border: var(--ml-text-faint);
   --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
   --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
 :root[data-theme="nordic"][data-mode="dark"],
@@ -757,6 +802,7 @@
   --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.1059), 0 4.887px 19.58px -2px oklch(0 0 0 / 0.2118);
   --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0927), 0 9.775px 34.81px -4px oklch(0 0 0 / 0.2647);
   --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0794), 0 17.92px 60.917px -8px oklch(0 0 0 / 0.3309);
+  --ml-shadow-tint: oklch(0 0 0 / 0.2118);
   --ml-focus: var(--ml-primary-text);
   --ml-primary-hover: color-mix(in oklab, var(--ml-primary) 88%, var(--ml-background));
   --ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent);
@@ -765,6 +811,10 @@
   --ml-control-border: var(--ml-text-faint);
   --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
   --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
 @supports (transition-timing-function: linear(0, 1)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlola-ui/engine",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Framework-free CSS, spring easings, and the machine-readable contract for Mlola UI",
   "type": "module",
   "sideEffects": [
@@ -19,6 +19,7 @@
     "./materials.css": "./generated/materials.css",
     "./recipes.css": "./generated/recipes.css",
     "./motion.css": "./generated/motion.css",
+    "./accessibility.css": "./generated/accessibility.css",
     "./tokens.json": "./generated/tokens.json",
     "./manifest.json": "./generated/manifest.json"
   },

package/src/behavior-spec.mjs

@@ -7,7 +7,7 @@
  * packages/behavior, and by the audit that proves the two agree.
  *
  * Components built on native form controls are deliberately absent: checkbox
- * and radio are real inputs, so the browser already owns their behaviour and
+ * and radio are real inputs, so the browser already owns their behavior and
  * nothing here can rot. Only the indeterminate flag on a checkbox needs script,
  * because HTML exposes it as a property rather than an attribute.
  */
@@ -216,7 +216,7 @@ export const behaviors = {
     keyboard: [{ keys: ["Escape"], does: "Hide the tooltip." }],
     transitions: [
       { on: "pointer enter or focus the trigger", set: "visible", to: "after the delay" },
-      { on: "pointer leave or blur", set: "hidden", to: "immediately, cancelling any pending delay" },
+      { on: "pointer leave or blur", set: "hidden", to: "immediately, canceling any pending delay" },
     ],
     notes: "Never put essential information or interactive content in a tooltip.",
   },

package/src/color.mjs

@@ -1,7 +1,7 @@
 /**
- * Colour math the engine can rely on, in the browser or in Node.
+ * Color math the engine can rely on, in the browser or in Node.
  *
- * Everything is OKLCH in and OKLCH out. A colour outside sRGB is brought into
+ * Everything is OKLCH in and OKLCH out. A color outside sRGB is brought into
  * gamut by reducing chroma at a fixed lightness and hue, the same strategy CSS
  * Color 4 uses, so the value the engine measures is the value the browser
  * paints. Contrast follows WCAG 2.2.
@@ -53,7 +53,7 @@ function srgbToOklch([r, g, b]) {
   return { L, C, H };
 }
 
-/** Linear sRGB for an OKLCH colour, not clamped. */
+/** Linear sRGB for an OKLCH color, not clamped. */
 function toLinear({ L, C, H }) {
   const radians = (H * Math.PI) / 180;
   const a = C * Math.cos(radians);
@@ -71,7 +71,7 @@ function toLinear({ L, C, H }) {
 const EPSILON = 1e-5;
 const inGamut = (color) => toLinear(color).every((channel) => channel >= -EPSILON && channel <= 1 + EPSILON);
 
-/** Reduce chroma until the colour fits sRGB. Lightness and hue are kept. */
+/** Reduce chroma until the color fits sRGB. Lightness and hue are kept. */
 export function toGamut(color) {
   const L = clamp(color.L, 0, 1);
   const candidate = { ...color, L };
@@ -86,7 +86,7 @@ export function toGamut(color) {
   return { ...candidate, C: low };
 }
 
-/** Gamma-encoded sRGB in 0..1, for an in-gamut colour. */
+/** Gamma-encoded sRGB in 0..1, for an in-gamut color. */
 export function toSrgb(color) {
   return toLinear(toGamut(color)).map((channel) => clamp(encode(clamp(channel, 0, 1)), 0, 1));
 }
@@ -106,7 +106,7 @@ function composite(top, bottom) {
   return { ...srgbToOklch(mixed), alpha: 1 };
 }
 
-/** WCAG 2.2 contrast ratio. Accepts colour strings or parsed colours. */
+/** WCAG 2.2 contrast ratio. Accepts color strings or parsed colors. */
 export function contrast(foreground, background) {
   const fg = typeof foreground === "string" ? parseColor(foreground) : foreground;
   const bg = typeof background === "string" ? parseColor(background) : background;
@@ -117,7 +117,7 @@ export function contrast(foreground, background) {
   return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
 }
 
-/** Serialise an OKLCH colour, gamut-mapped, at stable precision. */
+/** Serialise an OKLCH color, gamut-mapped, at stable precision. */
 export function formatColor(color) {
   const mapped = toGamut(color);
   const chroma = round(mapped.C, 3);

package/src/config.mjs

@@ -100,7 +100,7 @@ const canonicalMeta = {
 };
 
 /**
- * Canonical themes in the shape the rest of the build reads: the normalised
+ * Canonical themes in the shape the rest of the build reads: the normalized
  * spec, its vector as an ordered array, and the descriptive copy.
  */
 export const profiles = Object.fromEntries(

package/src/contract.mjs

@@ -10,7 +10,7 @@ import { behaviors } from "./behavior-spec.mjs";
  * library actually renders. Any renderer in any language that emits these
  * classes and attributes gets the correct visuals.
  *
- * The behaviour half — which attribute flips on which event, and the keyboard
+ * The behavior half — which attribute flips on which event, and the keyboard
  * map — cannot be read out of CSS, so it is authored in behavior-spec.mjs and
  * audited against this derived data.
  */

package/src/contrast.mjs

@@ -1,5 +1,5 @@
 /**
- * Colour math for the accessibility gate.
+ * Color math for the accessibility gate.
  *
  * The palettes are curated by hand, so "meets WCAG AA" has to be a measured
  * fact rather than a comment. This converts the engine's OKLCH tokens to sRGB,
@@ -44,7 +44,7 @@ export function oklchToSrgb({ L, C, H }) {
   });
 }
 
-/** Composite a possibly translucent colour over an opaque backdrop. */
+/** Composite a possibly translucent color over an opaque backdrop. */
 function composite([top, alpha], [bottom]) {
   return top.map((channel, index) => channel * alpha + bottom[index] * (1 - alpha));
 }

package/src/declarations.mjs

@@ -35,6 +35,8 @@ export function shadowDeclarations(derived, gain = 1) {
     `--ml-shadow-md: 0 1px 2px ${alpha(0.4)}, 0 ${px(y * 0.6)} ${px(blur * 0.9)} -2px ${alpha(0.8)}`,
     `--ml-shadow-lg: 0 2px 4px ${alpha(0.35)}, 0 ${px(y * 1.2)} ${px(blur * 1.6)} -4px ${alpha(1)}`,
     `--ml-shadow-xl: 0 4px 8px ${alpha(0.3)}, 0 ${px(y * 2.2)} ${px(blur * 2.8)} -8px ${alpha(1.25)}`,
+    // The contact shadow's color alone, for shapes a box-shadow cannot follow (filter: drop-shadow).
+    `--ml-shadow-tint: ${alpha(0.8)}`,
   ];
 }
 
@@ -113,7 +115,7 @@ export function themeDeclarations(spec) {
  */
 export const PALETTE_DERIVED = [
   "--ml-focus: var(--ml-primary-text)",
-  // Hover and pressed fills move a colour toward the page, so they lighten in
+  // Hover and pressed fills move a color toward the page, so they lighten in
   // light mode and darken in dark mode without a second palette.
   "--ml-primary-hover: color-mix(in oklab, var(--ml-primary) 88%, var(--ml-background))",
   "--ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent)",
@@ -128,4 +130,16 @@ export const PALETTE_DERIVED = [
   // it carries the theme's tint, and more opaque the darker the page, so it
   // reads as a light veil by day and still separates layers at night.
   "--ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28))",
+  // Pure light: a specular glint, the lit side of an orb. Light in both modes,
+  // as light is.
+  "--ml-highlight: oklch(1 0 0)",
+  // The thumb of a switch or slider. It stays light on any track and in dark
+  // mode, like a physical control; a theme may give it another finish.
+  "--ml-knob: var(--ml-highlight)",
+  // A knob that must read over any color at all (a color picker's handle)
+  // carries its own edge: a hairline and a small drop.
+  "--ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3)",
+  // The sheen of a specular surface: light from the top left, a little shade
+  // in the far corner.
+  "--ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05))",
 ];

package/src/library-recipes.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
  * Assemble the library's stylesheets from the CSS files their owners keep.
  *
  * Each component carries its own `<name>.css` next to its source, so a
- * component's markup, behaviour and styling are reviewed and copied together.
+ * component's markup, behavior and styling are reviewed and copied together.
  * The engine only concatenates them, in a stable order, into the published
  * layers:
  *

package/src/palette.mjs

@@ -4,23 +4,23 @@ import { contrast, formatColor, parseColor, solveLightness } from "./color.mjs";
  * Palettes are derived, not curated.
  *
  * A spec gives a primary seed and the tint of the neutrals; this module builds
- * every colour token for light and dark mode from them. Each text or fill
+ * every color token for light and dark mode from them. Each text or fill
  * pairing is solved to a WCAG target instead of being picked and then tested,
  * so any seed a person or a model supplies produces an accessible palette.
  *
  * Roles, so a token is never asked to do two jobs:
  *   - `primary`, `success`, ... are fills; their `-foreground` sits on them.
- *   - `primary-text` is the brand colour solved for text on the page (links,
+ *   - `primary-text` is the brand color solved for text on the page (links,
  *     focus rings). A vivid yellow stays a yellow button; its links go darker.
- *   - `success-text`, `danger-text`, ... are the status colours for text on
- *     the page, which a fill colour usually cannot be in both modes.
+ *   - `success-text`, `danger-text`, ... are the status colors for text on
+ *     the page, which a fill color usually cannot be in both modes.
  */
 
 /** WCAG thresholds with a small margin, so rounding never drops below them. */
 export const TARGETS = {
   text: 17,
   textDark: 17.5,
-  // Coloured text is solved with headroom, so it still clears AA on the
+  // Colored text is solved with headroom, so it still clears AA on the
   // hover fills and ~15% tints the library draws under it.
   body: 5.3,
   // Every text role is readable text. Faint is the quietest level, not a
@@ -42,7 +42,7 @@ function hardestBackground(foreground, neutrals) {
   );
 }
 
-/** Solve a text colour against every page background it may sit on. */
+/** Solve a text color against every page background it may sit on. */
 function solveText(color, neutrals, target, direction) {
   let solved = solveLightness(color, neutrals.background, target, direction);
   solved = solveLightness(solved, hardestBackground(solved, neutrals), target, direction);
@@ -130,17 +130,17 @@ function primaryFor(spec, mode, neutrals) {
   let fill = { L: seed.L, C: seed.C, H: seed.H };
   if (mode === "dark" && !spec.color.primaryDark) {
     // Without an explicit night seed, a near-black brand inverts to near-white
-    // and a deep brand colour is lifted, so neither sinks into the page.
+    // and a deep brand color is lifted, so neither sinks into the page.
     fill = isAchromatic(seed)
       ? { L: neutrals.text.L, C: seed.C, H: seed.H }
       : { L: Math.max(seed.L, 0.62), C: seed.C, H: seed.H };
   }
-  // A fill keeps the brand's colour; it only has to stand apart from the page
+  // A fill keeps the brand's color; it only has to stand apart from the page
   // and carry its own label. Text contrast is primary-text's job.
   if (contrast(fill, neutrals.background) < TARGETS.separation) {
     fill = solveLightness(fill, neutrals.background, TARGETS.separation, mode === "light" ? "darker" : "lighter");
   }
-  // WCAG 2's ratio favours dark ink on mid-tone saturated colours, but eyes read
+  // WCAG 2's ratio favours dark ink on mid-tone saturated colors, but eyes read
   // white on a violet, blue or red far better. In light mode a chromatic,
   // non-warm brand darkens a little (at most 0.12 L) so white clears the
   // target; yellows and oranges keep dark ink, as convention expects.
@@ -172,7 +172,7 @@ function statusFor(name, mode, neutrals) {
 }
 
 /**
- * Six categorical colours for charts, apart from the status roles so a series
+ * Six categorical colors for charts, apart from the status roles so a series
  * never reads as "good" or "bad" by accident. The first follows the brand's
  * hue (blue for a monochrome brand); the rest are the hues furthest from those
  * already taken, so neighbours never share a family. Each is solved to 3:1

package/src/render.mjs

@@ -105,6 +105,10 @@ export function renderMotionCss() {
   return `/* Motion and accessibility layer. */\n${readEngineCss("motion")}`;
 }
 
+export function renderAccessibilityCss() {
+  return `/* Accessibility layer: last in the cascade, so these guarantees hold over any recipe. */\n${readEngineCss("accessibility")}`;
+}
+
 export function renderDtcg() {
   const dtcgColor = (value) => {
     const match = value.match(/^oklch\(([\d.]+)\s+([\d.]+)\s+([\d.]+)(?:\s*\/\s*([\d.]+))?\)$/);

package/src/spec.mjs

@@ -11,7 +11,7 @@ import { parseColor } from "./color.mjs";
  *
  * Every field is one atomic decision, so it can be answered by one typed
  * question: a channel is a score on an ordered scale, a material or a font set
- * is a choice among named options, a colour is either given or chosen from a
+ * is a choice among named options, a color is either given or chosen from a
  * hue family.
  *
  * Deliberate choices, because this has to survive a decade:
@@ -47,7 +47,7 @@ export const MATERIALS = {
   anodized: "Opaque surfaces with a machined top highlight.",
 };
 
-/** Hue families a colour can be chosen from, as OKLCH hue angles. */
+/** Hue families a color can be chosen from, as OKLCH hue angles. */
 export const HUE_FAMILIES = {
   red: 25,
   orange: 50,
@@ -202,7 +202,7 @@ export function resolveFonts(fonts) {
 }
 
 /**
- * Normalise any theme input into a complete spec. Never throws: a partial
+ * Normalize any theme input into a complete spec. Never throws: a partial
  * theme inherits the rest from `base`, which defaults to a neutral spec.
  *
  * Also reads the pre-1.0 theme file shape (`theme` for the vector, `inherit`,
@@ -246,9 +246,9 @@ export function validateSpec(input) {
     const value = input.vector?.[channel];
     if (typeof value !== "number" || value < 0 || value > 1) problems.push(`vector.${channel} must be a number from 0 to 1.`);
   }
-  if (!parseColor(input.color?.primary)) problems.push("color.primary must be an oklch() or hex colour.");
+  if (!parseColor(input.color?.primary)) problems.push("color.primary must be an oklch() or hex color.");
   if (input.color?.primaryDark != null && !parseColor(input.color.primaryDark)) {
-    problems.push("color.primaryDark must be an oklch() or hex colour, or null.");
+    problems.push("color.primaryDark must be an oklch() or hex color, or null.");
   }
   const neutral = input.color?.neutral;
   if (!neutral || typeof neutral.hue !== "number" || typeof neutral.chroma !== "number" || neutral.chroma < 0 || neutral.chroma > 0.06) {
@@ -295,7 +295,7 @@ export function renderSpecSchema() {
       color: {
         type: "object",
         properties: {
-          primary: { type: "string", description: "Seed for the primary colour, oklch() or hex. Lightness is adjusted to meet contrast." },
+          primary: { type: "string", description: "Seed for the primary color, oklch() or hex. Lightness is adjusted to meet contrast." },
           primaryDark: { type: ["string", "null"], description: "Optional different seed for dark mode." },
           neutral: { ...tint, description: "Tint of the page and surfaces." },
           ink: { anyOf: [tint, { type: "null" }], description: "Tint of text and dark-mode surfaces. Defaults to neutral." },

package/src/theme-css.mjs

@@ -27,7 +27,7 @@ function selectorList(spec, { root, aliases }, dark) {
 }
 
 /**
- * Render a normalised spec as a self-contained stylesheet.
+ * Render a normalized spec as a self-contained stylesheet.
  *
  * `root` also applies the theme to `:root`, which only the default theme
  * does. `aliases` are further `data-theme` names for the same theme, such as