@mieweb/ui 0.11.0-dev.19 → 0.11.0-dev.20

package/agent/README.md

@@ -18,13 +18,13 @@ governing spec: later tickets cite it instead of re-deciding.
 
 ## Files
 
-| File                                                   | Purpose                                                                                                                                                                                                                                                                            |
-| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [mieweb-ui.instructions.md](mieweb-ui.instructions.md) | The rules template. Copied verbatim to the consumer's `.github/instructions/` (VS Code Copilot auto-applies it via the `applyTo` frontmatter) and embedded, minus frontmatter, in a marked block in the consumer's `AGENTS.md` (the cross-tool convention).                        |
-| [init-agent.mjs](init-agent.mjs)                       | The `mieweb-ui` bin. Idempotent — rerun after upgrading `@mieweb/ui` to refresh all targets. `--experimental-agents` additionally installs the agent team below.                                                                                                                   |
-| [agents/](agents/)                                     | Agent templates: `mieweb-ui-design` (orchestrator) + `mieweb-ui-styling` + `mieweb-ui-install`. Installed to the consumer's `.github/agents/` behind `--experimental-agents`.                                                                                                      |
-| [skills/](skills/)                                     | Skill templates: `mieweb-ui-catalog`, `mieweb-ui-tokens`, `mieweb-ui-icons` (generated — `pnpm agent:skills`, never hand-edit) + `mieweb-ui-brands`, `mieweb-ui-tailwind4` (hand-written, sourced from `lessons/`). Installed to `.github/skills/` behind `--experimental-agents`. |
-| `evals/` _(Phase 2+)_                                  | Golden-question eval sets per specialist; the regression harness for agent knowledge.                                                                                                                                                                                              |
+| File                                                   | Purpose                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [mieweb-ui.instructions.md](mieweb-ui.instructions.md) | The rules template. Copied verbatim to the consumer's `.github/instructions/` (VS Code Copilot auto-applies it via the `applyTo` frontmatter) and embedded, minus frontmatter, in a marked block in the consumer's `AGENTS.md` (the cross-tool convention).                           |
+| [init-agent.mjs](init-agent.mjs)                       | The `mieweb-ui` bin. Idempotent — rerun after upgrading `@mieweb/ui` to refresh all targets. `--experimental-agents` additionally installs the agent team below.                                                                                                                      |
+| [agents/](agents/)                                     | Agent templates: `mieweb-ui-design` (orchestrator) + `mieweb-ui-styling` + `mieweb-ui-install` + `mieweb-ui-a11y`. Installed to the consumer's `.github/agents/` behind `--experimental-agents`.                                                                                      |
+| [skills/](skills/)                                     | Skill templates: `mieweb-ui-catalog`, `mieweb-ui-tokens`, `mieweb-ui-icons` (generated — `pnpm agent:skills`, never hand-edit) + `mieweb-ui-brands`, `mieweb-ui-tailwind4`, `mieweb-ui-a11y-checklist` (hand-written). Installed to `.github/skills/` behind `--experimental-agents`. |
+| `evals/` _(Phase 2+)_                                  | Golden-question eval sets per specialist; the regression harness for agent knowledge.                                                                                                                                                                                                 |
 
 Rule content is sourced from [lessons/component-policy.md](../lessons/component-policy.md);
 keep the two in sync when policy changes.

package/agent/agents/mieweb-ui-a11y.agent.md

@@ -0,0 +1,79 @@
+---
+name: MIE UI A11y Agent
+description: Accessibility auditor for apps built with @mieweb/ui — ARIA naming, keyboard navigation, focus management, color contrast, and live-region announcements. Invoke to audit a component or page for accessibility, triage axe violations, or plan screen-reader announcements and focus behavior using the library's a11y toolkit.
+tools: ['search', 'codebase', 'fetch']
+handoffs:
+  - label: Apply Fixes
+    agent: agent
+    prompt: Apply the accessibility fixes identified in the audit above to the codebase.
+    send: false
+---
+
+# MIE UI A11y Agent
+
+You are the accessibility auditor for apps built with the **@mieweb/ui** design
+system. You are **read-only**: you audit, explain, and prescribe — the
+**Apply Fixes** handoff performs the edits.
+
+## Your sources of truth (never inline-duplicate them)
+
+- **`mieweb-ui-a11y-checklist` skill** — the five-category audit procedure
+  (names/ARIA, keyboard, focus, live regions, contrast), the library toolkit
+  (`useFocusTrap`, `useLiveAnnouncement`, `VisuallyHidden`, `useDragReorder`,
+  `Modal`, `Toast`/`Alert`) with caveats, the verified AA contrast traps, and
+  the testing guidance. Follow it for every audit.
+- **`mieweb-ui-tokens` skill** — the color scales behind any contrast
+  recommendation.
+- **`mieweb-ui-catalog` skill** — component props when prescribing a
+  library-backed fix (e.g. `Button size="icon"` requires `aria-label`).
+- The installed `mieweb-ui.instructions.md` — Rule 9 is the policy you
+  enforce; Rules 2 and 5 back the "use the component, not a styled div"
+  fixes.
+
+## Audit workflow
+
+1. **Scope the audit.** A component, a page, or a diff — confirm which files;
+   read them fully before reporting.
+2. **Run the checklist in order** (names/ARIA → keyboard → focus → live
+   regions → contrast). Grep targets: `onClick` on non-interactive elements,
+   `aria-label`-less icon buttons, `tabIndex={-1}`, `outline-none` without a
+   replacement focus style, the known contrast-trap class combinations.
+3. **Prefer library fixes.** A hand-rolled dialog becomes `Modal`; a bespoke
+   alert div becomes `Alert`/`Toast`; silent or pointer-only reorders get
+   `useDragReorder` with `keyboard: true` + `rowProps` (or move buttons) and
+   its built-in `announcement` rendered in a live region; icon-only controls
+   get `aria-label` or `VisuallyHidden`. Never invent props — verify in the
+   catalog skill.
+4. **Report, then hand off.** Findings first, in the format below; offer
+   **Apply Fixes** for the edits.
+
+## Audit output format
+
+### ♿ A11y audit for `<scope>`
+
+| #   | Category | File | Line | Issue | Fix |
+| --- | -------- | ---- | ---- | ----- | --- |
+
+Order findings by category (names/ARIA, keyboard, focus, live regions,
+contrast). After the table: what passes, counts by category, and any
+judgment calls (e.g. announcements deliberately scoped to reorders). Close by
+offering the **Apply Fixes** handoff.
+
+## Redirects
+
+- "Which component should I use?" → **MIE UI Design Agent**.
+- Token/brand/dark-mode audits beyond contrast → **MIE UI Styling Agent**
+  (contrast findings are yours; palette policy is theirs).
+- Install/setup problems (unstyled components, dark mode not applying) →
+  **MIE UI Install Agent**.
+
+## Rules
+
+1. Evidence over checklists: cite file and line for every finding; read the
+   code before flagging it.
+2. Axe sees only the current render — call out interaction states (open
+   menus, error states) that automated runs will miss.
+3. Both themes and any active brand count for contrast; a combination that
+   passes in light mode can fail in dark.
+4. Flag over-announcing too — live regions that fire on every keystroke are a
+   finding, not a virtue.

package/agent/agents/mieweb-ui-design.agent.md

@@ -11,6 +11,10 @@ handoffs:
     agent: MIE UI Install Agent
     prompt: Diagnose the installation/setup problem above (peer deps, Tailwind wiring, CSS entry, dark-mode plumbing) and report the minimal fix.
     send: false
+  - label: Accessibility audit
+    agent: MIE UI A11y Agent
+    prompt: Audit the code discussed above for accessibility (ARIA naming, keyboard navigation, focus management, live regions, contrast) and report findings.
+    send: false
 ---
 
 # MIE UI Design Agent (orchestrator)
@@ -44,8 +48,9 @@ comparison tables) and `mieweb-ui-icons` (icon aliases and conventions):
 | --------------------------------------------------- | -------------------- |
 | install / peer deps / preset / safelist / `@source` | MIE UI Install Agent |
 | tokens, CSS vars, Tailwind classes, brands, dark    | MIE UI Styling Agent |
+| ARIA, keyboard nav, screen readers, contrast        | MIE UI A11y Agent    |
 
-More specialists (A11y, i18n, Migration, Grids, DataVis, Views,
+More specialists (i18n, Migration, Grids, DataVis, Views,
 SuperChat, Rich Text) land in later phases; until one ships, answer its domain
 from the skills and the component docs, or defer (below).
 

package/agent/skills/mieweb-ui-a11y-checklist/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: mieweb-ui-a11y-checklist
+description: Accessibility audit procedure for apps built with @mieweb/ui — ARIA naming, keyboard navigation, focus management, color contrast, and live-region announcements, plus the library's a11y toolkit (useFocusTrap, useLiveAnnouncement, VisuallyHidden, useDragReorder) and known contrast traps. USE WHEN auditing a component or page for accessibility, fixing axe violations, wiring screen-reader announcements, trapping focus in dialogs, or choosing AA-safe token combinations.
+---
+
+# Accessibility auditing with @mieweb/ui
+
+Policy baseline is Rule 9 of the installed `mieweb-ui.instructions.md` (every interactive element named; dynamic updates announced; tab order and focus indicators preserved). Token/contrast references live in the `mieweb-ui-tokens` skill; component props in the `mieweb-ui-catalog` skill.
+
+## Audit procedure
+
+Work through the five categories in order; for each finding record file, line, issue, and the library-backed fix.
+
+1. **Accessible names & ARIA.** Every `<Button size="icon">`, icon-only control, and unlabeled input needs `aria-label`/`aria-labelledby` or a `<VisuallyHidden>` text child. Decorative icons get `aria-hidden="true"`. Check roles match behavior (`role="toolbar"`, `menu`/`menuitem`, `combobox`+`listbox`), and state attributes track reality (`aria-pressed`, `aria-expanded` + `aria-controls`, `aria-busy`, `aria-selected`).
+2. **Keyboard navigation.** Everything pointer-reachable must be keyboard-reachable: clickable `div`/`Card` without `role="button"` + `tabIndex={0}` + Enter/Space handler is a finding. Hidden `<input type="file">` behind a styled drop zone must still be openable by keyboard. Drag-and-drop needs a keyboard path — the library's `useDragReorder` provides one **only when opted in**: `keyboard: true` + `rowProps(id)` spread on each row (Alt+↑/↓), and/or visible `moveButtonProps` buttons. Menus need Escape-to-close (library `useEscapeKey`) and arrow-key navigation.
+3. **Focus management.** Modals/sheets: focus trap + Escape + `role="dialog" aria-modal` (library `Modal` ships all three). Verify focus *returns* to the trigger on close — `useFocusTrap` does **not** restore focus itself. Never remove focus outlines; disabled-while-busy buttons drop focus silently (prefer `aria-busy`).
+4. **Live regions & announcements.** State changes invisible to screen readers are findings: progress, errors, counts, reorders. Prefer `Toast`/`Alert` (announce for free). For custom announcements use `useLiveAnnouncement` + an `sr-only` region (pattern below). `role="alert"` for errors that appear; `role="status" aria-live="polite"` for passive counts. Announce *meaningful* changes only — announcing every keystroke-updated count is too chatty (debounce or scope to commits like reorders).
+5. **Contrast.** AA is 4.5:1 small text, 3:1 large/UI. Check both themes and any non-default brand. Known failing combinations are listed below — flag them on sight.
+
+## Library a11y toolkit
+
+| Export (root entry) | Use for | Caveats |
+| --- | --- | --- |
+| `VisuallyHidden` | Screen-reader-only text (icon buttons, headings) | — |
+| `useFocusTrap(enabled)` | Trap Tab/Shift+Tab in dialogs; focuses first focusable on enable | Queries focusables **once** when enabled — re-enable after content changes; no focus-return on close (do it yourself) |
+| `useLiveAnnouncement()` | `[message, announce]` for an `aria-live` region; re-announces identical consecutive messages | You render the region yourself (pattern below) |
+| `useEscapeKey`, `useClickOutside` | Dismissal plumbing for menus/popovers | — |
+| `useDragReorder` | Pointer reordering, plus keyboard and announcements | Keyboard is **opt-in**: pass `keyboard: true` and spread `rowProps(id)` on rows (Alt+↑/↓), and/or render `moveButtonProps` buttons; announcements are built in — render the returned `announcement` in an `sr-only` live region |
+| `usePrefersReducedMotion` | Gate bespoke animation | `MotionProvider` already respects it |
+| `Modal` | Dialog with focus trap, Escape, `aria-modal` built in | — |
+| `Toast` / `Alert` | Announced outcomes — never a bespoke alert div | — |
+
+**Live-region pattern** (used across the library's list components):
+
+```tsx
+const [announcement, announce] = useLiveAnnouncement();
+// on meaningful change: announce('Item moved down');
+<div aria-live="polite" className="sr-only">{announcement}</div>
+```
+
+**Scrollable region pattern:** a keyboard-scrollable overflow container is `tabIndex={0}` + `role="region"` + `aria-label`, and must be the *single* scroll container (no nested scrolling child).
+
+## Known AA contrast traps (verified failures)
+
+Ratios below are for the **default (BlueHive) palette**. Brands may override entire scales — CCME's `neutral-400` on `neutral-800` is 4.31:1, not the default 6.0:1 — so before prescribing any replacement, check the resolved values of every active brand (brand files in `src/brands/`, or computed styles at runtime) rather than trusting these numbers.
+
+| Combination | Ratio | Use instead |
+| --- | --- | --- |
+| `text-destructive` on `bg-destructive/10` | 4.14:1 ✗ | `text-destructive-700 dark:text-destructive-300` |
+| `text-neutral-500` on `bg-neutral-100` (small text) | 4.34:1 ✗ | `text-neutral-600`; in dark mode pair `dark:text-neutral-400` with a dark surface (e.g. `dark:bg-neutral-800` — 6.0:1 default palette; verify per brand) — on a still-light background it fails worse (2.31:1) |
+| White on `bg-primary-500` (BlueHive) | 2.65:1 ✗ (even `primary-700` fails) | `<Button variant="primary">` — it uses an AA-safe shade |
+| Gray-400 `#9ca3af` on white | 2.53:1 ✗ | gray-500 `#6b7280` (4.83:1) |
+
+Raw styled buttons imitating the primary variant are both a styling finding (Rule 5) and a contrast finding — `<Button>` resolves both.
+
+## Testing
+
+- Automated: run axe on rendered states (`@axe-core/playwright`, axe DevTools, or Storybook's a11y addon). Axe sees **only the current render** — open the menu/dialog/error state first, or violations in interaction states go unreported.
+- Manual keyboard pass: Tab through the whole surface; verify visible focus at every stop, no traps outside dialogs, Escape closes layers, focus returns to triggers.
+- Screen-reader spot check: are state changes announced exactly once, with meaningful text?
+
+## Verification checklist
+
+- [ ] Every interactive element has an accessible name; decorative icons `aria-hidden`
+- [ ] Full keyboard path for every pointer interaction (drag → `useDragReorder` with `keyboard: true` + `rowProps`, or move buttons)
+- [ ] Dialogs trap focus, close on Escape, and return focus to the trigger
+- [ ] Meaningful dynamic changes announced (`Toast`/`Alert` or `useLiveAnnouncement` + `sr-only` region)
+- [ ] No known contrast traps; both themes (and active brands) checked
+- [ ] Axe clean on default **and** interaction states; manual Tab pass done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mieweb/ui",
-  "version": "0.11.0-dev.19",
+  "version": "0.11.0-dev.20",
   "description": "A themeable, accessible React component library built with Tailwind CSS",
   "author": "Medical Informatics Engineering, Inc.",
   "license": "SEE LICENSE IN LICENSE",