command-code 1.25.0 → 1.26.0

package/CHANGELOG.md

@@ -1,10 +1,20 @@
 # command-code
 
+## 1.26.0
+
+### Minor Changes
+
+feat(design): add accessibility discipline and shared finding severity to the bundled /design skill
+
+### Patch Changes
+
+- feat: default ZDR mode vision to MiMo V2.5 instead of Kimi K2.5
+
 ## 1.25.0
 
 ### Patch Changes
 
-- feat: add GLM-5.3 
+- feat: add GLM-5.3
 
 ## 1.24.0
 

package/dist/bundled/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-description: "Design partner for frontend interfaces. One command covers every visual discipline: color, typography, layout, motion, interaction, responsive behavior, voice, surface, review, and refinement."
+description: "Design partner for frontend interfaces. One command covers every visual discipline: color, typography, layout, motion, interaction, accessibility, responsive behavior, voice, surface, review, and refinement."
 ---
 
 # Design
@@ -29,6 +29,8 @@ These modes report findings only. Fixes happen when the user runs `/design redes
 
 No design changes. No fixing. No calling other modes. Just reports.
 
+All three use the shared severity scale, evidence bar, findings table, and verdict in [references/severity.md](references/severity.md). A finding without a severity, a location, and a concrete **After** is an observation, not a finding — the fix modes cannot consume it.
+
 ## Bare `/design` routing
 
 When the user runs `/design` with no tool and no freeform prompt, I do not show the table. I route immediately and act.
@@ -43,7 +45,7 @@ If interface code exists, I check `.commandcode/design/` for any of:
 - `review-report.md`
 - `smell-report.md`
 
-**If a report exists**, the interface has already been audited. I read it, identify the highest-severity findings, and choose `redesign`, `relayout`, or `refine` — whichever addresses what the report flags most critically. I apply those changes to real files now.
+**If a report exists**, the interface has already been audited. I read it, identify the highest-severity findings, and choose `redesign`, `relayout`, `a11y`, or `refine` — whichever addresses what the report flags most critically. I apply those changes to real files now. When the report contains an escalation trigger from [references/severity.md](references/severity.md), that is what I fix first, ahead of any visual finding.
 
 **If no report exists**, the interface has not been diagnosed yet. I run an audit first, then act on the findings in the same pass. I do not stop after writing the report.
 
@@ -53,7 +55,7 @@ I pick the audit tool that fits:
 - `checkup` — for a fast vitals scan with traffic-light scores
 - `review` — for a thorough critique with scoring and a section-by-section walkthrough
 
-After the audit I write the report to `.commandcode/design/`, then immediately apply the most critical fixes via `redesign`, `relayout`, or `refine`. The report is the diagnostic. The design change is the treatment. I do not deliver one without the other.
+After the audit I write the report to `.commandcode/design/`, then immediately apply the most critical fixes via `redesign`, `relayout`, `a11y`, or `refine`. The report is the diagnostic. The design change is the treatment. I do not deliver one without the other.
 
 ## Composition comes from work
 
@@ -133,7 +135,7 @@ I prioritize confirmed blockers, high-severity issues, repeated smell patterns,
 
 I do not merely mention the report. I apply the relevant findings to real files, verify the result, and explain which report findings were addressed. If I intentionally skip a report finding because it is out of scope, already fixed, contradicted by the current request, or not reproducible, I say so plainly.
 
-Report-producing modes (`review`, `checkup`, and `smell`) create the required markdown and HTML report artifacts. Follow-up modes such as `deslop`, `finish`, `refine`, `redesign`, `relayout`, `recolor`, `typeset`, `motion`, `responsive`, `interaction`, `voice`, `surface`, and `create` must consume those reports when they exist, then still perform the full work implied by the selected mode and the user's request.
+Report-producing modes (`review`, `checkup`, and `smell`) create the required markdown and HTML report artifacts, using the severity scale and findings format in [references/severity.md](references/severity.md). Follow-up modes such as `deslop`, `finish`, `refine`, `redesign`, `relayout`, `recolor`, `typeset`, `motion`, `responsive`, `interaction`, `a11y`, `voice`, `surface`, and `create` must consume those reports when they exist, then still perform the full work implied by the selected mode and the user's request.
 
 ## Blank project behavior
 
@@ -192,6 +194,7 @@ The HTML file becomes the working canvas. All subsequent design work builds on t
 | `recolor [target]` | Systems | Build a color system: palette, roles, contrast, state color | [references/color.md](references/color.md) |
 | `motion [target]` | Systems | Add a page-wide motion system, then tune existing motion | [references/motion.md](references/motion.md) |
 | `interaction [target]` | Systems | Add missing behavior, states, affordances, feedback, targets | [references/interaction.md](references/interaction.md) |
+| `a11y [target]` | Systems | Repair the access system: focus, keyboard path, semantics, names, forms, announcements, hit areas, zoom | [references/accessibility.md](references/accessibility.md) |
 | `relayout [target]` | Compose | Change the structural composition, not just spacing | [references/relayout.md](references/relayout.md) |
 | `responsive [target]` | Compose | Recompose across screens, devices, input modes, contexts | [references/responsive.md](references/responsive.md) |
 | `redesign [target]` | Build | Complete visual transformation of existing interface | [references/redesign.md](references/redesign.md) |
@@ -205,6 +208,8 @@ The HTML file becomes the working canvas. All subsequent design work builds on t
 Discipline references, available to any tool:
 
 - [references/color.md](references/color.md), [references/layout.md](references/layout.md), [references/border.md](references/border.md), [references/shadow.md](references/shadow.md), [references/motion.md](references/motion.md), [references/interaction.md](references/interaction.md), [references/responsive.md](references/responsive.md), [references/writing.md](references/writing.md)
+- [references/accessibility.md](references/accessibility.md) for focus, keyboard, ARIA, forms, live regions, hit areas, zoom (`a11y`) — required reading for any mode that touches a control, a form, an overlay, or motion
+- [references/severity.md](references/severity.md) for the shared severity scale, escalation triggers, findings table, and verdict used by every report mode
 - [references/smell.md](references/smell.md) for the AI-tells catalog
 - [references/voice.md](references/voice.md) for marketing, landing, portfolio surfaces (`voice`)
 - [references/surface.md](references/surface.md) for app UI, dashboards, tools (`surface`)
@@ -340,6 +345,21 @@ Words are interface. Bad copy breaks experiences faster than bad color.
 - **Sentence case everywhere.** "Save changes" not "Save Changes".
 - **Strip filler.** Restated headings, marketing preamble, and transition sentences add noise. Cut anything that exists to fill space.
 
+### Access is the Floor
+
+This is not a checklist I run once the design is done. It is the ground every other discipline stands on, and most of it costs nothing as long as I stop fighting the platform: the browser already gives buttons a keyboard, already reads a real label aloud, already draws a focus ring until someone writes a rule to erase it.
+
+- **Native first, ARIA last.** `<button>` for actions, `<a href>` for navigation, never `<div onClick>`. No ARIA is better than bad ARIA — a screen reader trusts my roles, so a wrong role is worse than none. A role is a promise of a full keyboard model.
+- **Walk it twice before judging.** Once with the keyboard only: every flow must complete without a mouse. Once as a screen-reader user: does each control announce a name, a role, and its state?
+- **`:focus-visible`, never bare `:focus`,** and never `outline: none` without a verified replacement.
+- **Two legal `tabindex` values:** `0` and `-1`. A positive value hijacks the tab order for the whole page; the DOM order is what needs fixing.
+- **Modals trap and restore.** `inert` on the background, focus moved in on open, focus returned to the trigger on close.
+- **Placeholders are never labels,** and submit is never disabled until the form is valid — a disabled action hides the thing that must be fixed.
+- **Never color alone.** Every state carried by color also carries an icon, text, or shape.
+- **It has to survive 200% zoom and reflow at 320px.** Fixed heights on text containers are what break first.
+
+These eight failures are `HIGH` on sight in any report, never averaged down because the surface is minor. The full list and the mechanics behind each rule: [references/accessibility.md](references/accessibility.md) and [references/severity.md](references/severity.md).
+
 ### The Smell Test
 
 If a stranger can look at the design for two seconds and say "AI made that" without hesitation, it has failed. The fix is rarely a single edit — it is almost always a category reflex. If the palette, layout, and type choice are all predictable from the industry alone — SaaS in cream and purple, developer tool in dark terminal mono, fintech in navy serif, health app in white and teal — rework the scene sentence and color strategy until none of those answers fit.

package/dist/bundled/design/references/accessibility.md

@@ -0,0 +1,404 @@
+# Accessibility: `/design a11y`
+
+This is not a checklist I run once the design is done. It is the ground the design stands on, and most of it costs nothing as long as I stop fighting the platform: the browser already gives buttons a keyboard, already reads a real label aloud, already draws a focus ring until someone writes a rule to erase it.
+
+A design that only works for a sighted mouse user is a sketch, not a design.
+
+---
+
+## Pre-execution checklist
+
+Before proceeding, check for existing reports in the `.commandcode/design/` directory. Look for these files:
+
+- `checkup-report.md`
+- `review-report.md`
+- `smell-report.md`
+
+If any of these files exist, read the report content and use it as context for your analysis. Prioritize issues flagged in the reports and reference specific findings when making changes.
+
+If no reports are found, proceed with the task normally.
+
+---
+
+## Access Follows Composition
+
+The work pattern decides which access failures hurt most.
+
+Monitor screens fail when alerts are color-only, live updates never announce, or an operator cannot acknowledge without a mouse.
+
+Operate screens fail when direct manipulation has no keyboard equivalent, focus is lost after a command, or a drag handle is the only path.
+
+Compare screens fail when table structure is faked with divs, sort controls have no state, or numbers are unreadable at zoom.
+
+Configure screens fail when labels are placeholders, errors are a red border, or the submit button is disabled until the user guesses what is wrong.
+
+Learn screens fail when headings are picked for their size, reading order jumps, or media autoplays.
+
+Decide screens fail when the one action is an unlabeled icon, or the whole pitch is an image with no alt text.
+
+Explore screens fail when filters are unreachable, results never announce their count, or hover is the only way to see anything.
+
+---
+
+## Access Bar
+
+`/design a11y` repairs the access system. It is not an `aria-label` sprinkle.
+
+At minimum, I inspect and repair: focus visibility, the complete keyboard path, semantic elements, accessible names, landmark and heading structure, form labels and error announcement, live regions, hit areas, alt text, reduced motion, and behavior at 200% zoom and 320px width.
+
+I make two passes before I judge anything. Pass one, the mouse is off the table — if a task cannot be finished on the keyboard, it is not finished. Pass two, I listen instead of look: every control has to say what it is called, what kind of thing it is, and what state it is in.
+
+Adding one `aria-label` is not an accessibility pass unless the user asked for that one fix.
+
+---
+
+## Native First, ARIA Last
+
+The first rule of ARIA is: don't use ARIA. If a native element with the semantics and behavior I need exists, I use it.
+
+| Element | Use for | What it gives me free |
+|---|---|---|
+| `<a href>` | Navigation, anything that changes the URL | Cmd/Ctrl/middle-click, right-click to copy, Enter |
+| `<button>` | Actions: submit, toggle, open, delete | Focus, Enter *and* Space, form semantics |
+| `<div onClick>` | Nothing at all | Nothing — it is styled text that happens to run code |
+
+No ARIA is better than bad ARIA. A screen reader trusts my roles, so a wrong role is worse than none. A role is a promise: `role="tab"` promises the full tab keyboard model, and I have to deliver it.
+
+The five rules I do not break:
+
+1. Use the native element when one exists.
+2. Don't change native semantics unless I truly have to.
+3. Every interactive ARIA control is keyboard-operable.
+4. Nothing that can hold focus may be erased with `role="presentation"` or `aria-hidden="true"`.
+5. Nothing interactive ships without a name.
+
+The rule runs both directions. Anything that reads as pressable has to be pressable — and anything that is not has to stop dressing like it. Give a status badge the same shape as the buttons around it and users will keep clicking it, forever, getting nothing back.
+
+---
+
+## Focus Is Architecture
+
+I style `:focus-visible`, never bare `:focus`. The browser shows `:focus-visible` for keyboard and assistive tech but suppresses it for mouse clicks, where focus is already obvious.
+
+I prefer the browser's own ring, because it adapts to platform and forced-color settings without me predicting every background:
+
+```css
+/* Best: keep the browser ring, give it breathing room */
+:focus-visible {
+  outline-offset: 2px;
+}
+
+/* Custom ring when the design requires one: use the project's verified token */
+:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+```
+
+A bare `outline: 2px solid` renders `currentColor`, which is not automatically safe — the ring may cross colors unrelated to the text's own background. Before I ship a custom ring I inspect the whole perimeter against every adjacent color it crosses: component fills, page surfaces, images, gradients, hover and selected states. At least a `2px` solid perimeter, or an equivalent visible area.
+
+`outline: none` and `focus:outline-none` without a verified replacement are hostile. In `forced-colors: active` I keep the default color adjustment or use a system color such as `Highlight`; I never freeze the authored color with `forced-color-adjust: none` unless the control stays perceivable.
+
+`:focus-within` groups the ring on a wrapper when an inner input takes focus — a search box with an icon inside the border.
+
+---
+
+## The Keyboard Path
+
+Every pointer interaction needs a keyboard path. `tabindex` has exactly two legal values:
+
+- `tabindex="0"` — puts a custom control into the tab order it should already have been in. Only for things the platform does not focus on its own.
+- `tabindex="-1"` — reachable from script, skipped by Tab. This is for the heading I throw focus at after a route change, the modal shell, and the inactive members of a roving group.
+- Anything positive — no. One positive value reorders the entire page around itself, and the actual problem is always the DOM order, so that is what I go fix.
+
+Composite widgets occupy one Tab stop and use roving tabindex: the active item is `0`, every other is `-1`, and arrow keys move both focus and the `0`.
+
+| Widget | Keys |
+|---|---|
+| Dialog | Tab/Shift+Tab cycle inside and wrap; Escape closes |
+| Tabs | Arrows move between tabs and wrap; Tab exits to the panel; Home/End jump to the ends |
+| Menu button | Enter/Space/ArrowDown opens on the first item; ArrowUp opens on the last; Escape closes and refocuses the button |
+| Disclosure / accordion | The header itself is a `<button aria-expanded>`, toggled by Enter or Space |
+| Combobox | ArrowDown opens and moves in; Enter accepts; Escape closes and returns to the input |
+| Listbox / radio group | Arrows move selection; one Tab stop for the whole group |
+
+Three rules hold everywhere. Escape unwinds one layer at a time, newest first — the tooltip goes before the menu it sits in, and the menu goes before the dialog holding both. Arrows travel *inside* a widget while Tab travels *between* them. And Enter submits from a focused input, except in a `<textarea>`, where it owes the user a newline and Cmd/Ctrl+Enter does the submitting.
+
+A tab set has to decide what an arrow key means. If the panels are cheap to render, arrowing onto a tab can open it outright. If switching costs a fetch or a heavy re-render, arrowing only moves focus and the user confirms with Enter or Space — otherwise skimming the row fires off every panel on the way past.
+
+---
+
+## Trap and Restore
+
+A modal has to hold focus inside itself. The cheapest way to get that is `inert` on whatever sits behind the dialog: one attribute, and the background stops being tabbable and stops existing for assistive tech at the same time.
+
+```js
+// On open
+appContent.inert = true;
+(dialog.querySelector("[autofocus]") ??
+  dialog.querySelector("button, [href], input, select, textarea"))?.focus();
+
+// On close
+appContent.inert = false;
+trigger?.focus(); // always return focus to what opened it
+```
+
+Native `<dialog>` with `showModal()` gives me the trap, the inert background, and Escape handling for free, so I prefer it. A custom overlay that cannot use `<dialog>` needs `role="dialog"`, `aria-modal="true"`, and an accessible name via `aria-labelledby` pointing at its heading.
+
+Either way: on open, focus the first focusable element — but for a destructive confirmation, focus the *least* destructive action. On close, return focus to the trigger; if the trigger is gone, move focus to the nearest logical container. Add `overscroll-behavior: contain` so scrolling inside never scrolls the page behind it.
+
+**Client-side navigation** changes the screen and tells nobody. The page never reloads, so focus stays wherever it was and a screen reader announces nothing at all. I do that work by hand: retitle the document for wherever the user has landed, then throw focus at the new view's `<h1>` — `tabindex="-1"` makes it a legal target — or at `<main>` if there is no heading. Going back or forward restores the old scroll position; going somewhere new starts at the top.
+
+---
+
+## Accessible Names
+
+When several naming sources compete, the winner is decided in this order: `aria-labelledby`, then `aria-label`, then whatever the platform derives (`<label>`, text content, `alt`), and `title` only if nothing else exists.
+
+I reach for visible text or `aria-labelledby` first. `aria-label` is a string nobody can see, which means it quietly falls out of step with the interface it describes, and translation tooling treats it unevenly.
+
+```tsx
+// Name from visible text, icon hidden
+<button>
+  <TrashIcon aria-hidden="true" /> Delete
+</button>
+
+// Icon-only, explicit name
+<button aria-label="Delete">
+  <TrashIcon aria-hidden="true" />
+</button>
+```
+
+Whatever the user can read on the control has to be contained in the name the control reports. Label a button "Send" on screen and `"Submit message"` underneath, and someone driving the interface by voice says "click Send" and nothing happens.
+
+Brand names, code tokens, and identifiers get `translate="no"`, so machine translation leaves them alone instead of mangling them.
+
+| Mistake | Why it fails |
+|---|---|
+| `aria-label` on a plain `<div>` or `<span>` | Names on role-less, non-interactive elements are ignored |
+| `<button role="button">` | Redundant role: noise, no benefit |
+| `aria-hidden="true"` on or above a focusable element | A Tab stop that does not exist for screen readers |
+| `aria-labelledby`/`aria-describedby` aimed at an ID that isn't there | Fails without a warning: the control ends up nameless |
+| `role="menu"` on site navigation | `menu` promises app-style arrow keys; site nav is `<nav>` with a list |
+
+---
+
+## Structure Is Navigation
+
+There is exactly one primary `<main>` on the page. The other structural elements — `<header>`, `<nav>`, `<aside>`, `<footer>` — become the waypoints a screen-reader user jumps between, so when two of the same kind exist I name them apart: `<nav aria-label="Primary">` next to `<nav aria-label="Breadcrumbs">`.
+
+Headings describe their sections and form a coherent outline. One page-level `<h1>` with properly nested levels is the recommended default. Headings are structure, not styling — I pick the level semantically and set the visual size in CSS, never the reverse.
+
+When repeated navigation or chrome precedes the content, the first focusable element is a skip link:
+
+```css
+.skip-link { position: absolute; inset-inline-start: -999px; }
+.skip-link:focus { inset-inline-start: 16px; top: 16px; }
+```
+
+In-page anchor targets get `scroll-margin-top` so a sticky header does not swallow them. `<title>` matches the current context, most specific first: `Billing · Settings · Acme`.
+
+---
+
+## Forms
+
+The label has to be wired to the field, not merely near it: `<label for>` aimed at the input's `id`, or a `<label>` wrapped around it. Placeholder text does not qualify. It vanishes at the first keystroke — exactly when the user most needs to remember what they are filling in — and it usually fails contrast on the way out.
+
+Label and field are one target, not two. If the words "Send me updates" do not toggle the checkbox, there is a dead strip between them, and I close it.
+
+The complete error pattern:
+
+```html
+<label for="email">Email</label>
+<input id="email" type="email" autocomplete="email"
+       aria-invalid="true" aria-describedby="email-error" />
+<p id="email-error">Enter a valid email address.</p>
+```
+
+- `aria-invalid="true"` goes on while the field is wrong and comes back off the moment it is right.
+- `aria-describedby` ties the field to the message beneath it, so the two are read as one thing rather than as an orphaned sentence.
+- Errors render inline next to their field with text or an icon. A red border alone is color-only and fails.
+- Submitting a broken form throws focus at the first thing that failed. I do not need to announce it separately; landing there says it.
+- I do not disable submit until the form is valid. A disabled action hides what must be fixed. I keep it enabled until the request starts, then disable it with a spinner **while keeping the original label** — the label is what tells assistive tech which button is busy.
+- I accept free text and validate after; I never filter characters as the user types. I trim before validating, because autocomplete and text expansion add trailing spaces.
+
+`autocomplete` with a meaningful `name` fills a form in one tap and is a WCAG requirement for fields about the user:
+
+| Field | `autocomplete` |
+|---|---|
+| Name | `name`, or `given-name` / `family-name` |
+| Email / phone | `email` / `tel` |
+| Address | `street-address`, `address-line1`, `postal-code`, `country` |
+| Card | `cc-number`, `cc-exp`, `cc-csc`, `cc-name` |
+| Login | `username`, `current-password` |
+| Signup / reset | `new-password` |
+| 2FA code | `one-time-code` |
+
+Correct `type` and `inputmode` pick the right mobile keyboard: `type="email"` / `url` / `tel`; `type="text" inputmode="numeric"` for OTP, PIN, and card numbers (keeps text semantics, no spinner); `type="text" inputmode="decimal"` for money; `type="number"` only for a true numeric quantity. `spellcheck="false"` on emails, codes, and usernames.
+
+I never block paste — users paste passwords and one-time codes — and I stay compatible with password managers: a real `<form>`, correct `autocomplete`, no fake inputs.
+
+**Disabled states.** Native `disabled` supplies the platform's complete behavior: out of the tab order, no activation, `:disabled` styling, excluded from submission. `aria-disabled="true"` only *announces* the state — it changes nothing else. I use it only when keeping the control discoverable is intentional, and then I block pointer and keyboard activation in code, style the state explicitly, and say nearby why the action is unavailable. Never both attributes on one element.
+
+---
+
+## Announcing Change
+
+I take the first of these that fits and stop there:
+
+1. **Focus already goes there** — an opening modal, the first broken field. The movement carries the message; adding anything else means saying it twice.
+2. **It belongs to one control** — a field's error, a character count. `aria-describedby` on that control.
+3. **It belongs to no control and can wait** — a toast, "Saved", a result count, a loading update. A polite region, `role="status"`.
+4. **It belongs to no control and cannot wait** — the form failed as a whole, the session is about to expire. `role="alert"`.
+
+For repeated polite updates I keep a stable empty region in the DOM and change its text; inserting a new polite region together with its content is announced inconsistently.
+
+```tsx
+<div role="status" className="sr-only">{statusMessage}</div>
+```
+
+Polite is the default and `assertive` is the exception, because reaching for `assertive` by habit is how a live region goes from helpful to hostile: it cuts off whatever sentence the user was in the middle of. I keep each message short and able to stand alone, since `aria-atomic` reads the entire region again every time any of it changes. And a toast never steals focus — it speaks from where it is, and the user keeps their hands where they were.
+
+The canonical visually-hidden pattern (Tailwind ships it as `sr-only`):
+
+```css
+.sr-only {
+  position: absolute;
+  width: 1px; height: 1px;
+  padding: 0; margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+The box is `1px`, not `0`, because a few screen readers walk straight past anything with no size. And this is the one job `display: none` and `visibility: hidden` cannot do: they do not hide the text visually, they delete it from the accessibility tree along with everything else.
+
+---
+
+## Alt Text by Purpose
+
+I choose alt by what the image *does*, not by what it looks like.
+
+| Purpose | Alt | Example |
+|---|---|---|
+| Decorative or redundant with adjacent text | `alt=""`, empty but present | Logo beside the company name in text |
+| Informative | The meaning it adds | `alt="Ticket QR code"` |
+| Functional (the image is the control) | The action or destination | Search icon → `alt="Search"`, not `alt="magnifying glass"` |
+| Image of text | The exact text (better: use real text) | `alt="50% off everything"` |
+| Complex (chart, diagram) | Short summary, full data nearby | `alt="Revenue by quarter, described below"` |
+
+Leaving `alt` off entirely is the worst of the options — with nothing to read, screen readers fall back to announcing the file name.
+
+**SVG:** decorative gets `aria-hidden="true"` and `focusable="false"`. Meaningful inline SVG gets `role="img"` plus `aria-label`. Prerecorded video needs captions, audio needs transcripts, nothing autoplays with sound, controls always render.
+
+---
+
+## Hit Areas
+
+What the user sees is allowed to be tiny. What the user has to hit is not.
+
+| Standard | Minimum |
+|---|---|
+| WCAG 2.5.8 (AA) | 24×24px — the hard floor |
+| WCAG 2.5.5 (AAA) | 44×44px |
+| Apple HIG | 44×44pt |
+| Material | 48×48dp |
+
+I treat 44px as the target for touch and 40px as a useful desktop size when density permits. Smaller controls are not automatic failures — I check the spacing, equivalent-control, inline, user-agent, and essential exceptions first. Under the spacing exception, an undersized target passes if a 24px circle centered on it does not intersect another target's circle; in the simple case, 20px targets need a 4px gap.
+
+```css
+/* Expand without changing the visual size — on the label or button, never the input */
+.checkbox-label { position: relative; width: 20px; height: 20px; }
+.checkbox-label::after {
+  content: "";
+  position: absolute;
+  top: 50%; left: 50%;
+  transform: translate(-50%, -50%);
+  width: 44px; height: 44px;
+}
+```
+
+When the element can afford real box size I skip the pseudo-element and let the box be the target (`min-width: 44px; min-height: 44px; display: inline-grid; place-items: center`) — the browser then gets the real geometry for scrolling and gestures.
+
+**Collision rule:** two interactive elements never have overlapping hit areas. If an extended area would collide, I shrink it to the largest size that does not.
+
+`touch-action: manipulation` removes the double-tap-to-zoom delay. `-webkit-tap-highlight-color` matches the design instead of flashing gray.
+
+---
+
+## Motion, Zoom, and Reflow
+
+Motion is opt-in, not chased with overrides:
+
+```css
+.card { /* static */ }
+@media (prefers-reduced-motion: no-preference) {
+  .card { transition: transform 200ms ease-out; }
+}
+```
+
+Inheriting a codebase too far gone to invert, I fall back to a blanket override — but I set durations to `0.01ms` instead of `none`. Zero means the browser never fires `transitionend` or `animationend`, and any script waiting on one of those events sits there forever.
+
+The preference asks for less motion, not none. What it is protecting against is vestibular upset, not the interface answering the user:
+
+| Cut it | Swap it | Leave it alone |
+|---|---|---|
+| Parallax | Anything that slides, scales, or zooms → a plain opacity crossfade | Spinners and progress indicators |
+| Video, GIFs, and looping decoration that start themselves | Smooth scrolling → jump straight there | State that changes instantly: hover color, the focus ring |
+| Spinning, and anything travelling a long way across the screen | Carousels that rotate on their own → hand them over paused | The short confirmation that a press registered |
+
+Independent of the preference: anything that moves, blinks, or updates automatically for more than 5 seconds needs a visible pause control — muted looping hero video included. Auto-dismissing toasts are for low-stakes confirmations only; anything carrying an action or an error stays until dismissed. Never put the only path to an action inside a timed element — that is data loss on a schedule.
+
+**Zoom:** all content and functionality survives 200% zoom, and the page reflows at 320px width with vertical scrolling only. Genuinely two-dimensional content (tables, maps, code blocks) scrolls inside its own container. Fixed heights are what break under zoom — `min-height` on anything containing text, and let containers grow.
+
+**rem vs px:** I respect how the codebase is set up and never introduce mixed units into someone else's system. Where I do have the choice: `rem` for `font-size`, text container `max-width`, media-query breakpoints, and spacing that should scale with text; `px` for borders, focus outline width and offset, shadow details, and fixed decorations. Breakpoints are where it matters most — at a larger base font size, a `rem` query switches to the mobile layout when the text needs it and a `px` query does not.
+
+---
+
+## Never Color Alone
+
+Status needs a redundant cue: an icon, text, or an underline alongside the color. Red-and-green as the only difference between two states is a failure for roughly one in twelve men.
+
+Contrast is measured between a foreground and the background it actually renders against. I identify which requirement applies, measure the rendered pair, and report the pair, its measured value, and the threshold it misses. Thresholds and the OKLCH remediation method live in [color.md](color.md#contrast-mechanics).
+
+---
+
+## What I Refuse
+
+- `outline: none` with no verified replacement
+- Calling one `aria-label` an accessibility pass
+- `<div onClick>` where a `<button>` or `<a href>` belongs
+- Placeholder used as the only label
+- Positive `tabindex` to fix a focus order the DOM should fix
+- Submit disabled until the form is valid
+- `assertive` live regions for routine toasts
+- `aria-hidden="true"` on a focusable element
+- Functional icon alt that describes the picture instead of the action
+- A modal that traps nothing and returns focus nowhere
+- Motion or autoplay that ignores `prefers-reduced-motion`
+- Fixed heights on text containers that clip at 200% zoom
+- Hover as the only way to reach a feature
+- Reporting a color contrast failure by repainting the brand without being asked
+
+---
+
+## How I Know Access Works
+
+- The primary task completes with the keyboard alone, start to finish
+- Focus is visible on every interactive element and never disappears
+- Every control announces a name, a role, and its state
+- Overlays trap focus, close on Escape, and return focus to the trigger
+- Every input has a real label, the right `type`, and useful `autocomplete`
+- Errors announce, sit beside their field, and say how to recover
+- No state is carried by color alone
+- Every hit area clears the floor and none of them overlap
+- Motion respects `prefers-reduced-motion` and nothing autoplays without a pause
+- The page works at 200% zoom and reflows at 320px without horizontal scrolling
+- I verified these by walking the interface, not by reading the CSS
+
+STRICT RULE — NEVER BREAK THIS
+Do not create report.md, any kind of report, summary, analysis file,
+or extra documentation. This applies every time this file is used.
+Generate no reports unless explicitly asked.

package/dist/bundled/design/references/border.md

@@ -74,6 +74,10 @@ Product UI usually wants tighter corners. Brand surfaces can be softer. Data-hea
 
 I keep inner elements visually nested. Inner radius should feel smaller than outer radius. If nested corners fight, the surface looks careless.
 
+The math is concentric: **outer radius = inner radius + the padding between them.** A card with `8px` padding around a `12px`-radius child wants a `20px` radius, not another `12px`. Mismatched radii on closely nested surfaces is the single most common reason an interface feels subtly off.
+
+The rule applies while the layers are visually nested. Past roughly `24px` of padding they read as separate surfaces, and each radius is chosen on its own rather than forced through the formula. An established component token beats the formula when the layers are independent or the padding is deliberately asymmetric.
+
 ---
 
 ## Focus Rings
@@ -84,6 +88,8 @@ It must be visible, offset enough to avoid clipping, shaped to match the element
 
 If a component cannot use a normal outline, I still provide a clear ring or halo that survives nearby colors.
 
+I style `:focus-visible`, not bare `:focus`, so keyboard users get the ring and mouse users usually do not. Where the design allows it, the browser's own indicator with `outline-offset: 2px` is the strongest choice, because it adapts to platform and forced-color settings without me predicting every background. A custom ring uses the project's focus token and gets checked against every color its perimeter crosses. Full mechanics, including forced-colors behavior: [accessibility.md](accessibility.md#focus-is-architecture).
+
 ---
 
 ## Dividers

package/dist/bundled/design/references/checkup.md

@@ -114,6 +114,8 @@ For every critical issue, I write the prescription in my working answer:
 
 I do not bury the next move in a report. The user should know the practical fix immediately.
 
+Prescriptions carry a severity, a `path/to/file:line` location, and a concrete replacement, per [severity.md](severity.md). Any escalation trigger in that file makes the Accessibility vital `Critical` on sight — no keyboard path, no visible focus, meaning carried by color alone, motion ignoring `prefers-reduced-motion`, or content unreachable at 320px or 200% zoom. A checkup does not average those away because the other five vitals look healthy.
+
 ---
 
 ## Report Boundary

package/dist/bundled/design/references/color.md

@@ -121,6 +121,73 @@ I never let color carry meaning alone. State needs shape, label, icon, position,
 
 ---
 
+## Contrast Mechanics
+
+Contrast is always measured between a **foreground** and the **background it actually renders against** — usually the nearest parent's background, not the page's.
+
+**Report, don't repaint.** When a pair fails, I report the pair, its measured value, and the threshold it misses. A project's colors are a design decision; I change them when the user asks, or when the mode I am running is a fix mode.
+
+APCA is the default because it is perceptually accurate and pairs naturally with OKLCH. Lc is signed — positive is dark-on-light, negative is light-on-dark — so I compare absolute values.
+
+| Content | APCA minimum | Preferred |
+|---|---|---|
+| Body text (blocks and columns) | Lc 75 | Lc 90 |
+| Non-body text (labels, headlines) | Lc 60 | Lc 75 |
+| Large text (≥36px) | Lc 45 | Lc 60 |
+| UI components, placeholder, disabled | Lc 30 | — |
+
+WCAG 2 still governs a formal conformance claim: 4.5:1 AA and 7:1 AAA for normal text, 3:1 AA for large text (≥24px, or ≥18.5px bold) and for UI components and graphical objects.
+
+**Fixing in OKLCH.** Lightness is the clearest first lever. I move L and preserve C and H where I can, then remeasure the rendered pair:
+
+```css
+/* Failing: too little lightness distance (Lc ≈ 50) */
+color: oklch(0.65 0.08 250);
+background: oklch(0.95 0.02 250);
+
+/* Fixed: darken the foreground, C and H unchanged (Lc ≈ 90) */
+color: oklch(0.3 0.08 250);
+background: oklch(0.95 0.02 250);
+```
+
+Mid-lightness backgrounds cap what is achievable: on a background at L 0.75, even pure black text reaches only about Lc 60. Body text needs a background near one of the extremes.
+
+Quick gaps for body text: on a light background (L > 0.9) the foreground wants L below 0.35; on a dark background (L < 0.25) the foreground wants L above 0.9. The gap is asymmetric because APCA is polarity-aware.
+
+The light/dark crossover sits at **L 0.73** — higher than intuition suggests. Between 0.6 and 0.73 a background already looks light, but white text still scores meaningfully better than black.
+
+---
+
+## OKLCH Mechanics
+
+`oklch(L C H)` or `oklch(L C H / alpha)`. L is 0–1 and perceptually uniform. C is 0 to about 0.4 and its maximum depends on both L and H. H is 0–360. Alpha uses slash syntax, never commas. Three decimals for L and C, and `-0` is written `0`.
+
+**The gamut is irregular.** At L 0.5 in sRGB, purple (H ≈ 285) reaches C ≈ 0.29, red-orange C ≈ 0.20, and cyan (H ≈ 195) only C ≈ 0.09. The peak hue moves with lightness. If chroma exceeds the maximum for its L and H, the color clips — I reduce C and hold L and H.
+
+```css
+.accent { color: oklch(0.7 0.2 150); }          /* sRGB-safe */
+
+@media (color-gamut: p3) {
+  .accent { color: oklch(0.7 0.3 150); }        /* wider gamut enhancement */
+}
+```
+
+**Palette scales** run 50 (lightest) to 950 (darkest); 11 steps matches Tailwind, 9 is a leaner default. I clamp lightness to [0.05, 0.95] — pure black and pure white carry zero chroma — distribute L evenly, then clamp chroma *per step* to a percentage of that step's maximum. High-chroma base colors come out less chromatic at the ends. That is correct.
+
+**Multi-hue palettes share the same L and the same chroma *percentage*, not the same absolute C.** Same L guarantees equal perceived brightness; same percentage guarantees equal vividness relative to each hue's own ceiling:
+
+```css
+--blue-500:  oklch(0.623 0.141 250);  /* 80% of max 0.176 */
+--green-500: oklch(0.623 0.157 145);  /* 80% of max 0.196 */
+--red-500:   oklch(0.623 0.202 25);   /* 80% of max 0.253 */
+```
+
+**Hue drift** is how I diagnose an inherited HSL ramp: convert each step to OKLCH and compare H. More than 10° of spread across the scale is visible drift — `hsl(240, 80%, 20%)` and `hsl(240, 80%, 90%)` land ~16° apart, which is why the light end of a blue ramp goes purple.
+
+**Respect the existing notation.** I do not convert a hex or RGB token system to OKLCH because this file was loaded. A consistent hex system beats a second color representation introduced for one isolated fix. I convert when the task *is* a color-system pass. In Tailwind v4 the `@theme` block takes OKLCH values directly, and the `/50` opacity modifier compiles to slash-alpha.
+
+---
+
 ## The Grey Test
 
 I mentally strip every hue to gray. The hierarchy must survive.
@@ -135,6 +202,8 @@ Dark mode is a second theme. It is not light mode with the lights off.
 
 Depth comes from surface lightness, not heavy shadow. Accents lose a little chroma so they do not glow. Borders become subtle light, often with a trace of brand hue. Light text needs careful weight because it reads heavier and brighter than dark text.
 
+I start by swapping the semantic roles, then tune the dark values independently. I do not mechanically reverse every palette step: equal OKLCH steps do not guarantee that every foreground/background pair keeps its contrast when the polarity flips. Every pair gets rechecked in both appearances.
+
 ---
 
 ## Domain Default Trap