@mieweb/ui 0.11.0-dev.37 → 0.11.0-dev.39

package/agent/README.md

@@ -22,7 +22,7 @@ governing spec: later tickets cite it instead of re-deciding.
 | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [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` + `mieweb-ui-i18n`. Installed to the consumer's `.github/agents/` behind `--experimental-agents`.                                                                                               |
+| [agents/](agents/)                                     | Agent templates: `mieweb-ui-design` (orchestrator) + `mieweb-ui-styling` + `mieweb-ui-install` + `mieweb-ui-a11y` + `mieweb-ui-i18n` + `mieweb-ui-migration`. 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`, `mieweb-ui-i18n-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.                                                                                                                                                                                                                             |
 

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

@@ -19,6 +19,10 @@ handoffs:
     agent: MIE UI i18n Agent
     prompt: Audit the code discussed above for internationalization and RTL compliance (string externalization, locale-bundle completeness, Intl formatting, logical properties) and report findings.
     send: false
+  - label: Migration/compliance audit
+    agent: MIE UI Migration Agent
+    prompt: Audit the code discussed above for @mieweb/ui compliance (raw HTML elements, custom modal/card/badge patterns, hand-rolled icons, CSS foundation) and report findings with a prioritized replacement plan.
+    send: false
 ---
 
 # MIE UI Design Agent (orchestrator)
@@ -48,14 +52,16 @@ comparison tables) and `mieweb-ui-icons` (icon aliases and conventions):
 
 ## Route to specialists
 
-| Question is about…                                  | Delegate to          |
-| --------------------------------------------------- | -------------------- |
-| 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    |
-| translations, locale bundles, Intl formats, RTL     | MIE UI i18n Agent    |
+| Question is about…                                   | Delegate to            |
+| ---------------------------------------------------- | ---------------------- |
+| install / peer deps / preset / safelist / `@source`  | MIE UI Install Agent   |
+| wiring headless modules (ViewSet, SuperChat) to data | 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      |
+| translations, locale bundles, Intl formats, RTL      | MIE UI i18n Agent      |
+| migrating code to @mieweb/ui, raw-HTML compliance    | MIE UI Migration Agent |
 
-More specialists (Migration, Grids, DataVis, Views,
+More specialists (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/agents/mieweb-ui-install.agent.md

@@ -51,11 +51,13 @@ diagnose from evidence, then report a minimal fix — you do not edit files
 
 ## Peer-dependency triage
 
-`react`/`react-dom` are the only required peers. Everything else is optional
-and entry-scoped — before telling anyone to install a package, check whether
-they actually import the entry that needs it (catalog skill table). Under
-pnpm, remind consumers that peers are not hoisted; required peers belong in
-the app's own `package.json`.
+Required peers: `react`/`react-dom` (>=18) **and** the five `@kerebron/*`
+runtime packages (`editor`, `editor-kits`, `extension-basic-editor`,
+`extension-menu`, `wasm`) — the main-barrel `Textarea` rides the Kerebron
+engine. Everything else is optional and entry-scoped — before telling anyone
+to install a package, check whether they actually import the entry that needs
+it (catalog skill table). Under pnpm, remind consumers that peers are not
+hoisted; required peers belong in the app's own `package.json`.
 
 ## Redirects
 

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

@@ -0,0 +1,144 @@
+---
+name: MIE UI Migration Agent
+description: Migration and compliance auditor for bringing codebases onto @mieweb/ui — raw-HTML-to-component pattern enforcement (badge spans, card divs, raw buttons, tables to DataVis NITRO), hand-rolled SVG to lucide-react, CSS foundation checks, and legacy-framework migration planning (Meteor/Blaze to React). Invoke to audit a file, page, or project for @mieweb/ui compliance or to plan a migration.
+tools: ['search', 'codebase', 'fetch']
+handoffs:
+  - label: Apply Fixes
+    agent: agent
+    prompt: Apply the @mieweb/ui compliance fixes identified in the audit above — replace the flagged raw elements and patterns with the prescribed @mieweb/ui components, preserving existing functionality and event handlers.
+    send: false
+---
+
+# MIE UI Migration Agent
+
+You are the migration and compliance auditor for the **@mieweb/ui** design
+system. You bring legacy code into compliance: every UI element must use a
+`@mieweb/ui` component when one exists — no raw `<button>`, `<input>`,
+`<select>`, `<table>`, `<textarea>`, or custom modal/card/badge markup. You
+are **read-only**: you audit, plan, and prescribe — the **Apply Fixes**
+handoff performs the edits.
+
+## Your sources of truth (never inline-duplicate them)
+
+- **`mieweb-ui-catalog` skill** — the component inventory and selection
+  guidance; every replacement you prescribe must exist there. It is the
+  raw-element → component mapping (`<button>` → `Button`, card divs →
+  `Card`/`CardContent`, badge spans → `Badge`, modal divs → `Modal`, …).
+- **`mieweb-ui-tailwind4` skill** — the CSS foundation a migrated project
+  needs (`@source` directive, `@custom-variant dark`, `@theme` fallbacks,
+  `@tailwindcss/postcss`).
+- **`mieweb-ui-icons` skill** — the lucide-react aliases that replace
+  hand-rolled `<svg>` and icon fonts.
+- The installed `mieweb-ui.instructions.md` — the policy you enforce
+  (NITRO-first for tables, tokens not hardcoded colors, lucide-react icons).
+
+## The prime directive: patterns, not just imports
+
+Compliance is not "does the file import @mieweb/ui". Raw HTML that serves
+the same purpose as a component is a violation even when the file already
+imports the library:
+
+- `<span className="rounded-full bg-blue-100 px-2 …">` is a `Badge`.
+- `<div className="rounded-lg border p-4 shadow">` is a `Card`.
+- `<div className="fixed inset-0 bg-black/50">…` is a `Modal`.
+- A hand-rolled `<svg>` or icon-font glyph is a `lucide-react` icon.
+- Any `<table>` the user will sort, filter, page, or export is
+  **DataVis NITRO** (`Table` only for a few static rows; `AGGrid` is
+  deprecated — never migrate _to_ it).
+
+## Audit workflow
+
+1. **Scope the audit.** A file, a page, or a whole project — confirm which,
+   then read the files before reporting. Exclude test files from violation
+   counts.
+2. **Grep for raw elements** — `<button`, `<input`, `<select`, `<textarea`,
+   `<table`/`<thead`/`<tbody`/`<tr`/`<td`/`<th`, `<form` controls. Also grep
+   the **dynamic forms**: literal `type="date"` misses
+   `type={cond ? 'date' : 'text'}` — search `type={` and other
+   prop-expression variants too.
+3. **Grep for patterns** — badge/pill/tag spans, card-like divs
+   (`rounded…border…shadow`), modal/overlay divs (`fixed inset-0`), inline
+   `<svg>` and icon-font classes, hand-rolled spinners/progress bars,
+   custom tab/breadcrumb/pagination markup.
+4. **Check the CSS foundation** (project-level audits): identify the
+   consumer's CSS mode first, then audit against that mode's checklist in
+   the `mieweb-ui-tailwind4` skill — Tailwind 4 (`@source` for
+   `@mieweb/ui/dist`, `@custom-variant dark`, `@theme` fallbacks,
+   `@tailwindcss/postcss`), Tailwind 3 (preset + safelist + `content`
+   coverage), or precompiled CSS (`styles.css`/`init.css` import — never
+   prescribe Tailwind tooling to it). Validate the dark-mode toggle
+   against the `@custom-variant` actually in effect (a single-hook toggle
+   against `init.css` is valid); setting both `.dark` and `data-theme` is
+   the recommendation for new code, not a violation when one hook matches.
+5. **Build the resolution plan**, prioritized: layout shell (`AppHeader`,
+   `Sidebar`, `SiteFooter`) → buttons → form elements → cards & modals →
+   tables (NITRO) → feedback (`Badge`, `Toast`, `Spinner`) → navigation
+   (`Tabs`, `Breadcrumb`, `Pagination`). Replacements preserve existing
+   functionality and event handlers.
+6. **Detect gaps.** A pattern with no `@mieweb/ui` equivalent is not a
+   violation — report it with the tier recommendation: compose from existing
+   primitives; build locally in library style (CVA variants, `forwardRef`,
+   theme CSS variables, dark mode, ARIA); headless-module contract if it
+   renders a caller-owned collection; contribute upstream once stable.
+7. **Report, then hand off.** Findings in the format below; offer
+   **Apply Fixes** for the edits.
+
+## Audit output format
+
+### 🧭 @mieweb/ui compliance audit for `<scope>`
+
+| #   | Category | File | Line | Violation | Replacement |
+| --- | -------- | ---- | ---- | --------- | ----------- |
+
+Order findings: raw elements, then patterns, then CSS foundation, then gaps.
+After the table, the compliance summary:
+
+| Category                | Count | Status |
+| ----------------------- | ----- | ------ |
+| Raw `<button>`          | X     | ❌     |
+| Raw form elements       | X     | ❌     |
+| Raw `<table>`           | X     | ❌     |
+| Custom modal/card/badge | X     | ❌     |
+| Hand-rolled icons       | X     | ❌     |
+| CSS foundation          | —     | ✅/❌  |
+| Gaps (no equivalent)    | N     | 📝     |
+
+Close with what passes, any judgment calls, and the **Apply Fixes** handoff.
+
+## Migration planning (beyond single-file audits)
+
+For whole-app migrations (e.g. Meteor 2 + Blaze → Meteor 3 + React +
+@mieweb/ui), plan in this order: scaffold → install deps → the three
+critical CSS/PostCSS/Tailwind config files → verify Tailwind renders →
+shared hooks (`useTheme`, `useBrand`) → layout shell → features one at a
+time, auth first → verify dark mode, brand switching, and `tsc --noEmit`.
+Meteor 3 specifics: all methods async, collection ops use `*Async()`
+variants. Verify each migrated feature before starting the next.
+
+## Redirects
+
+- "Which component should I use?" for new (non-migration) work → **MIE UI
+  Design Agent** (your mapping covers replacements; open-ended selection is
+  theirs).
+- Broken styling after install, unstyled components, Tailwind wiring →
+  **MIE UI Install Agent** (you flag the missing foundation; they debug it).
+- Token/brand/dark-mode policy questions → **MIE UI Styling Agent**.
+- ARIA, keyboard navigation, focus, contrast → **MIE UI A11y Agent** (your
+  replacements inherit library a11y; auditing what remains is theirs).
+- String externalization, locale bundles, RTL → **MIE UI i18n Agent**.
+
+## Rules
+
+1. Evidence over checklists: cite file and line for every finding; read the
+   code before flagging it.
+2. **Patterns, not just imports** — a compliant import list proves nothing;
+   grep for the raw markup the components replace.
+3. Grep dynamic forms: prop expressions (`type={…}`, spread props,
+   conditional classes) hide violations that literal-string greps miss.
+4. Never prescribe a component or prop you cannot verify in the catalog
+   skill, the published component docs (https://ui.mieweb.org), or the
+   package's public types — the catalog is a selection inventory, not an
+   API reference; a gap honestly reported beats an invented replacement.
+5. Replacements must preserve behavior — event handlers, controlled state,
+   form semantics. Flag any replacement that would change behavior as a
+   judgment call instead of silently prescribing it.

package/agent/evals/README.md

@@ -0,0 +1,74 @@
+# Agent team evals
+
+Golden-question eval sets for the MIE UI agent team (#545, seeded by #587).
+Each file covers one specialist domain with 20+ entries sourced from the real
+adoption corpus — [lessons/](../../lessons/README.md), the generated and
+hand-written [agent/skills/](../skills/), the installed
+[mieweb-ui.instructions.md](../mieweb-ui.instructions.md), and past consumer
+issues in this repo.
+
+These files are maintainer-side quality tooling. They are **not** shipped by
+`init-agent.mjs` — consumers get agents and skills, not the exam answers.
+
+## Files
+
+| File                           | Domain                               | Primary agent          |
+| ------------------------------ | ------------------------------------ | ---------------------- |
+| [selection.md](./selection.md) | Component selection / catalog        | MIE UI Design Agent    |
+| [styling.md](./styling.md)     | Styling, tokens, brands, dark mode   | MIE UI Styling Agent   |
+| [install.md](./install.md)     | Install, CSS foundation, wiring      | MIE UI Install Agent   |
+| [a11y.md](./a11y.md)           | Accessibility                        | MIE UI A11y Agent      |
+| [i18n.md](./i18n.md)           | Internationalization / RTL           | MIE UI i18n Agent      |
+| [migration.md](./migration.md) | Migration / compliance (incl. icons) | MIE UI Migration Agent |
+
+## Entry format
+
+```markdown
+### SEL-3 — Raw table replacement
+
+- **Ask:** "What @mieweb/ui component replaces a raw `<table>`?"
+- **Expect:** `Table` + composition slots for static rows; `DataVisNitroGrid`
+  once sorting/filtering/paging/export is needed; never hand-roll grid features.
+- **Agent:** MIE UI Design Agent
+- **Source:** mieweb-ui.instructions.md — Rules 1, 3
+```
+
+- **Ask** — the question, phrased the way a consumer actually asks it.
+- **Expect** — the key points a correct answer must contain. Not a transcript:
+  an answer passes if every Expect point is present and nothing contradicts
+  the corpus. Missing key points downgrade per the scoring procedure below
+  (PARTIAL, or FAIL when the answer is wrong overall); inventing APIs or
+  prescribing forbidden tooling is always FAIL.
+- **Agent** — the specialist that should end up answering. When the question
+  is posed to the MIE UI Design Agent, correct routing to this agent (or a
+  correct direct answer where the orchestrator owns the domain, e.g.
+  selection) is part of the pass criteria.
+- **Source** — where the known-good answer lives, so graders can re-verify
+  and corpus fixes have a target.
+
+## Running a manual eval
+
+1. Install the team into a sandbox app:
+   `node <ui-repo>/agent/init-agent.mjs init-agent --experimental-agents`
+   (run from the sandbox root; verify `pwd` first).
+2. Open the installed agent for the domain under test (or start from the
+   MIE UI Design Agent to also score routing).
+3. Ask a sample of questions from the file — a stratified sample of 3–5 per
+   domain is a meaningful smoke; the full set is for release-gating runs.
+4. Score each answer PASS / PARTIAL / FAIL against **Expect**:
+   - PASS — all key points present, no corpus contradictions.
+   - PARTIAL — correct direction but a key point missing.
+   - FAIL — wrong, invented, or missing answer; misrouted.
+5. File every PARTIAL/FAIL as a corpus fix: if the knowledge exists but the
+   agent missed it, fix the agent/skill prompt; if the knowledge is absent,
+   add it to `lessons/` (and regenerate skills with `pnpm agent:skills` when
+   the fix lands in generated inputs).
+
+## Maintaining the sets
+
+- Add entries when a real consumer question or issue exposes a gap — cite the
+  issue number in **Source**.
+- Update entries when the corpus changes (component retirements, new rules);
+  stale Expect text is worse than no entry.
+- Keep answers grounded: every Expect point must be verifiable in the cited
+  source. Do not write aspirational answers.

package/agent/evals/a11y.md

@@ -0,0 +1,183 @@
+# Evals — Accessibility
+
+Primary agent: **MIE UI A11y Agent**. See [README.md](./README.md) for format
+and scoring.
+
+### A11Y-1 — Icon-only button name
+
+- **Ask:** "Is `aria-label` enough for an icon-only button, or do I need
+  visible text?"
+- **Expect:** `aria-label` is sufficient but must be descriptive
+  (`aria-label="Save"`, never "icon"/"button"); icon-only controls always
+  need one; decorative icons get `aria-hidden="true"`.
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — Audit (1); mieweb-ui.instructions.md — Rule 2
+
+### A11Y-2 — Drag-and-drop keyboard support
+
+- **Ask:** "My list reorders by drag-and-drop. Do I need keyboard support?"
+- **Expect:** Yes — `useDragReorder` with at least one keyboard path:
+  `keyboard: true` + `rowProps(id)` spread on rows (Alt+↑/↓) and/or visible
+  `moveButtonProps` buttons (either alone is supported). Also render the
+  hook's `announcement` in a polite `sr-only` live region so reorders are
+  announced.
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — Audit (2), toolkit; src/hooks/useDragReorder.ts
+
+### A11Y-3 — Modal focus restore
+
+- **Ask:** "Modal traps focus and closes on Escape. Anything else?"
+- **Expect:** Return focus to the trigger on close — the focus trap doesn't
+  restore focus itself; track the trigger ref and focus it in `onOpenChange`
+  when the next-open value is `false` (Modal has no `onClose` prop).
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — Audit (3), toolkit; src/components/Modal — `ModalProps`
+
+### A11Y-4 — Announcement chattiness
+
+- **Ask:** "Should a live region announce the item count on every keystroke?"
+- **Expect:** No — announce meaningful changes only; debounce or scope to
+  commits (e.g. reorders). `role="status"`/`aria-live="polite"` for passive
+  updates, `role="alert"` for errors.
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — Audit (4)
+
+### A11Y-5 — White on primary-500
+
+- **Ask:** "Does white text on `bg-primary-500` (BlueHive) pass AA?"
+- **Expect:** No — 2.65:1, and it still fails at primary-700. Use
+  `<Button variant="primary">` (AA-safe shade internally); never hardcode
+  colors for button-like elements.
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — Known AA contrast traps
+
+### A11Y-6 — Interactive element checklist
+
+- **Ask:** "What makes an interactive element accessible here?"
+- **Expect:** Accessible name (visible text, `aria-label`, or
+  `aria-labelledby`), semantic HTML (no clickable divs), announced dynamic
+  updates (Toast/Alert), logical tab order, focus indicators never removed.
+- **Agent:** MIE UI A11y Agent
+- **Source:** mieweb-ui.instructions.md — Rule 9
+
+### A11Y-7 — Muted text trap
+
+- **Ask:** "Is `text-neutral-500` on `bg-neutral-100` OK for small text?"
+- **Expect:** No — 4.34:1 fails AA for small text; use `text-neutral-600`. In
+  dark mode pair `dark:text-neutral-400` with a dark surface like
+  `dark:bg-neutral-800`; verify per brand.
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — Known AA contrast traps
+
+### A11Y-8 — Live announcements
+
+- **Ask:** "How do I announce a state change to screen readers?"
+- **Expect:** `const [announcement, announce] = useLiveAnnouncement()` and
+  render `<div aria-live="polite" className="sr-only">{announcement}</div>`;
+  call `announce()` on meaningful changes.
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — toolkit
+
+### A11Y-9 — Loading states
+
+- **Ask:** "Custom CSS spinner for loading, or a component?"
+- **Expect:** Library components only: `Spinner` (inline), `Skeleton`
+  (placeholder), `LoadingPage` (full page). Never hand-roll.
+- **Agent:** MIE UI A11y Agent
+- **Source:** mieweb-ui.instructions.md — Rule 8
+
+### A11Y-10 — Clickable div
+
+- **Ask:** "My clickable div lacks `role=\"button\"` and `tabIndex`. Add
+  them?"
+- **Expect:** No — replace it with `Button` (or the right semantic
+  component); don't bolt ARIA onto divs when a real component exists.
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — Audit (2)
+
+### A11Y-11 — Hidden file input
+
+- **Ask:** "A hidden `<input type=\"file\">` sits behind a styled drop zone.
+  Keyboard story?"
+- **Expect:** It must stay keyboard-openable — wire keyboard handlers that
+  trigger the input's `click()`, or use `DropzoneOverlay`/`FileManager`.
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — Audit (2)
+
+### A11Y-12 — Scrollable region
+
+- **Ask:** "How do I make an overflow container keyboard-accessible?"
+- **Expect:** `tabIndex={0}` + `role="region"` + `aria-label`, and it must be
+  the single scroll container (no nested scrolling children).
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — toolkit
+
+### A11Y-13 — Dark-mode hover contrast
+
+- **Ask:** "Tab hover states look fine in light mode — do I need to check
+  dark mode separately?"
+- **Expect:** Yes — hover/active states must pass AA in **both** themes;
+  dark-mode hover shades have regressed before (Tabs, outline Button). Use
+  token pairs from the a11y checklist and verify per theme.
+- **Agent:** MIE UI A11y Agent
+- **Source:** issues #512, #511; agent/skills/mieweb-ui-a11y-checklist/SKILL.md — contrast traps
+
+### A11Y-14 — Toasts and dynamic updates
+
+- **Ask:** "Do async save results need announcing?"
+- **Expect:** Yes — dynamic updates are announced via `Toast`/`Alert` (which
+  carry live-region semantics), not silent inline text swaps.
+- **Agent:** MIE UI A11y Agent
+- **Source:** mieweb-ui.instructions.md — Rule 9
+
+### A11Y-15 — Focus indicators
+
+- **Ask:** "Can I remove the focus ring? The designer finds it ugly."
+- **Expect:** No — focus indicators are never removed; restyle via tokens if
+  needed, keep them visible (including in dark mode).
+- **Agent:** MIE UI A11y Agent
+- **Source:** mieweb-ui.instructions.md — Rule 9
+
+### A11Y-16 — Semantic landmarks
+
+- **Ask:** "Is a div-based layout fine if the CSS is right?"
+- **Expect:** No — use semantic HTML (`nav`, `main`, `button`, …); screen
+  readers navigate by landmarks and roles, not by class names.
+- **Agent:** MIE UI A11y Agent
+- **Source:** mieweb-ui.instructions.md — Rule 9
+
+### A11Y-17 — Exit animations
+
+- **Ask:** "During an exit animation, the screen reader still reads the
+  leaving element. Is that expected?"
+- **Expect:** It happens today but isn't acceptable — exiting children must be
+  `aria-hidden` and `inert` for the duration. `AnimatedPresence` does **not**
+  yet do this automatically (open #474); hand-rolled exits must handle it
+  themselves.
+- **Agent:** MIE UI A11y Agent
+- **Source:** issue #474 (open); agent/skills/mieweb-ui-a11y-checklist/SKILL.md — exit animations
+
+### A11Y-18 — Icon-only Button pattern
+
+- **Ask:** "What's the canonical icon-only button?"
+- **Expect:** `<Button size="icon" aria-label="...">` — the `aria-label` is
+  required, not optional.
+- **Agent:** MIE UI A11y Agent
+- **Source:** mieweb-ui.instructions.md — Rule 2
+
+### A11Y-19 — Tab order
+
+- **Ask:** "Does visual order vs DOM order matter for keyboard users?"
+- **Expect:** Yes — tab order must be logical; don't reorder purely with CSS
+  so that focus jumps around, and don't use positive `tabIndex` to patch it.
+- **Agent:** MIE UI A11y Agent
+- **Source:** mieweb-ui.instructions.md — Rule 9
+
+### A11Y-20 — Verifying contrast per brand
+
+- **Ask:** "Contrast passes on the default palette. Done?"
+- **Expect:** No — brands redefine the primary scale, so brand-dependent
+  pairs must be re-verified per brand (the checklist's traps are stated for
+  the default palette/BlueHive).
+- **Agent:** MIE UI A11y Agent
+- **Source:** agent/skills/mieweb-ui-a11y-checklist/SKILL.md — Known AA contrast traps

package/agent/evals/i18n.md

@@ -0,0 +1,185 @@
+# Evals — Internationalization / RTL
+
+Primary agent: **MIE UI i18n Agent**. See [README.md](./README.md) for format
+and scoring.
+
+### I18N-1 — Hardcoded strings
+
+- **Ask:** "I wrote `<Button>Save</Button>`. Is that OK?"
+- **Expect:** No — every user-facing string goes through `t()`:
+  `<Button>{t('common.save')}</Button>`. Includes aria-labels, placeholders,
+  and error messages.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Audit (1)
+
+### I18N-2 — Missing keys ship silently
+
+- **Ask:** "I added a locale bundle but missed some keys. Will anything
+  break visibly?"
+- **Expect:** No — missing keys silently fall back to `fallbackLng`, so they
+  ship invisibly. Every bundle must cover every logical key of the canonical
+  bundle in the same commit.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Audit (2)
+
+### I18N-3 — Auditing locale completeness
+
+- **Ask:** "How do I check a locale bundle is complete?"
+- **Expect:** Diff logical keys against the canonical bundle, stripping
+  plural suffixes (`_one`, `_other`, …) but preserving context suffixes
+  (`invite_admin` vs `invite_guest` stay distinct) — then separately verify
+  each pluralized key carries all plural forms that locale's CLDR rules
+  require (e.g. Arabic needs more than `_one`/`_other`).
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Audit (2)
+
+### I18N-4 — Hardcoded locale in formatting
+
+- **Ask:** "Is `date.toLocaleDateString('en-US', …)` fine?"
+- **Expect:** No — that pins every user to en-US. Call it without a hardcoded
+  tag, using the active language via `useLocale()` (where `LocaleProvider` is
+  in scope) or `i18n.language`.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Audit (3)
+
+### I18N-5 — String concatenation
+
+- **Ask:** "Can I build messages like `t('greeting') + name` or
+  `` `${t('count')} items` ``?"
+- **Expect:** No — concatenation breaks word order across languages. Use
+  interpolation: `t('greeting', { name })`; `t('items', { count })` for
+  plurals.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Audit (3)
+
+### I18N-6 — Plurals
+
+- **Ask:** "How do I translate '3 items' vs '1 item'?"
+- **Expect:** One logical key with `count` interpolation; bundles carry CLDR
+  plural forms (`_one`, `_other`, …) — never an in-code
+  `count === 1 ? … : …` branch.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Audit (2), (3)
+
+### I18N-7 — Physical margin classes
+
+- **Ask:** "Does `className=\"ml-4\"` work in RTL?"
+- **Expect:** No — use logical classes: `ms-4`, `ps-*`, `start-*`,
+  `text-start`; never `ml-*`, `pl-*`, `left-*`, `right-*`, `text-left`.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — RTL checklist; mieweb-ui.instructions.md — Rule 10
+
+### I18N-8 — Flipping icons
+
+- **Ask:** "Do chevrons flip automatically in RTL?"
+- **Expect:** No — add `rtl:-scale-x-100` to directional chevrons/arrows; do
+  NOT flip decorative icons (checkmarks, media controls, up/down arrows).
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — RTL checklist
+
+### I18N-9 — Arrow-key direction
+
+- **Ask:** "My keyboard handler uses ArrowLeft/ArrowRight. RTL concern?"
+- **Expect:** Yes — arrow keys follow **visual** direction: check
+  `isRtl(event.currentTarget)` in the handler and swap the semantics.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — RTL checklist
+
+### I18N-10 — isRtl vs useDirection
+
+- **Ask:** "When `isRtl()` vs `useDirection(ref)`?"
+- **Expect:** `isRtl()` is a one-shot snapshot for event handlers;
+  `useDirection(ref)` is reactive, for when direction drives rendering. Never
+  store an `isRtl` result across renders — it stales.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — direction toolkit
+
+### I18N-11 — Portals and direction
+
+- **Ask:** "How does a portaled Tooltip know the direction?"
+- **Expect:** Portals escape local `dir` overrides — read direction from a
+  non-portaled ref via `useDirection(ref)`, not from the portaled node.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — RTL checklist
+
+### I18N-12 — Hardcoded BCP-47 tags
+
+- **Ask:** "Can I pass `'en-US'` to `Intl.NumberFormat`?"
+- **Expect:** No — drive Intl APIs from the active language, never hardcoded
+  tags.
+- **Agent:** MIE UI i18n Agent
+- **Source:** mieweb-ui.instructions.md — Rule 10
+
+### I18N-13 — Manual currency formatting
+
+- **Ask:** "Is `'$' + amount.toFixed(2)` acceptable?"
+- **Expect:** No — use `Intl.NumberFormat` with
+  `{ style: 'currency', currency }` under the active locale; manual string
+  formatting breaks symbols, separators, and placement.
+- **Agent:** MIE UI i18n Agent
+- **Source:** mieweb-ui.instructions.md — Rule 10; agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Audit (3)
+
+### I18N-14 — Adding a locale
+
+- **Ask:** "What's the full procedure to add a new locale?"
+- **Expect:** Add `<locale>.json` beside existing bundles covering every
+  logical key with that locale's CLDR plural forms; register in i18next
+  `resources`; expose in the language selector; on change call
+  `i18n.changeLanguage(code)` and set `dir` via `isRtlLocale()`; verify Intl
+  output.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Adding a locale
+
+### I18N-15 — Physical inline styles
+
+- **Ask:** "My inline styles use `marginLeft` and `textAlign: 'left'`. Caught
+  by the class greps?"
+- **Expect:** No — inline physical styles evade class greps and silently
+  break RTL. Use `marginInlineStart`, `insetInlineStart`,
+  `textAlign: 'start'`.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — RTL checklist
+
+### I18N-16 — Key naming
+
+- **Ask:** "Can I use the English text as the translation key?"
+- **Expect:** Use logical keys (`common.save`), not English sentences —
+  bundles are keyed by meaning, and plural/context suffixes attach to logical
+  keys.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Audit (1), (2)
+
+### I18N-17 — Non-visible strings
+
+- **Ask:** "Do aria-labels, placeholders, and toast messages need `t()` too?"
+- **Expect:** Yes — every user-facing string, including assistive-tech-only
+  text, placeholders, and error/notification messages.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Audit (1)
+
+### I18N-18 — Setting dir on language change
+
+- **Ask:** "The user switches to Arabic. What besides `changeLanguage`?"
+- **Expect:** Set the document `dir` on every language change via
+  `isRtlLocale()` — translations without `dir` leave the layout LTR.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — Adding a locale
+
+### I18N-19 — RTL audit mechanics
+
+- **Ask:** "How do I audit a codebase for RTL violations?"
+- **Expect:** Grep for physical classes (`ml-`, `mr-`, `pl-`, `pr-`,
+  `left-`, `right-`, `text-left`, `text-right`) **and** check what greps
+  miss: inline physical styles, dynamic/conditional class strings, and
+  directional keyboard handlers.
+- **Agent:** MIE UI i18n Agent
+- **Source:** agent/skills/mieweb-ui-i18n-checklist/SKILL.md — RTL checklist
+
+### I18N-20 — Scope of Rule 10
+
+- **Ask:** "What does the i18n rule actually require?"
+- **Expect:** All user-facing text externalized through `t()`; dates,
+  numbers, and currency via Intl under the active language; logical CSS
+  properties/classes for RTL; no hardcoded locale tags.
+- **Agent:** MIE UI i18n Agent
+- **Source:** mieweb-ui.instructions.md — Rule 10