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

package/agent/evals/install.md

@@ -0,0 +1,200 @@
+# Evals — Install, CSS foundation, wiring
+
+Primary agent: **MIE UI Install Agent**. See [README.md](./README.md) for
+format and scoring.
+
+### INS-1 — Required dependencies
+
+- **Ask:** "What do I install to use @mieweb/ui in a React app?"
+- **Expect:** `@mieweb/ui react react-dom` plus the required `@kerebron/*`
+  runtime peers (`editor`, `editor-kits`, `extension-basic-editor`,
+  `extension-menu`, `wasm` — the main-barrel `Textarea` rides the Kerebron
+  engine), and dev deps `tailwindcss@4 @tailwindcss/postcss autoprefixer`
+  for the Tailwind 4 path.
+- **Agent:** MIE UI Install Agent
+- **Source:** package.json — peerDependencies/peerDependenciesMeta; CONTRIBUTING.md — Optional peer dependencies
+
+### INS-2 — Minimum CSS entry
+
+- **Ask:** "What's the minimum CSS entry point, and does order matter?"
+- **Expect:** In order: base stylesheet (`@mieweb/ui/styles.css`) then brand
+  CSS (both unlayered), `@import 'tailwindcss'`, `@source` for
+  `node_modules/@mieweb/ui/dist`, `@custom-variant dark`, and `@theme` with
+  color scales + fallbacks.
+- **Agent:** MIE UI Install Agent
+- **Source:** agent/skills/mieweb-ui-tailwind4/SKILL.md — CSS entry, Option B
+
+### INS-3 — Quick start
+
+- **Ask:** "Is there a one-import setup?"
+- **Expect:** Almost — the TW4 quick start is **three** lines in your own CSS
+  entry: `@import 'tailwindcss'`, `@source "../node_modules/@mieweb/ui/dist"`,
+  then `@import '@mieweb/ui/init.css'` (dark variant + `@theme` fallbacks +
+  default brand + base styles). `init.css` is Tailwind input, not standalone;
+  for no-Tailwind apps the one-import answer is `styles.css`.
+- **Agent:** MIE UI Install Agent
+- **Source:** agent/skills/mieweb-ui-tailwind4/SKILL.md — CSS entry, Option A; src/styles/init.css usage header
+
+### INS-4 — PostCSS config
+
+- **Ask:** "My CSS doesn't process — I have the `tailwindcss` plugin in
+  `postcss.config.cjs`."
+- **Expect:** That's the Tailwind 3 plugin; on TW4 use
+  `{'@tailwindcss/postcss': {}, autoprefixer: {}}`. The old plugin silently
+  fails or produces wrong output.
+- **Agent:** MIE UI Install Agent
+- **Source:** lessons/tailwind4-integration.md — Lesson 2
+
+### INS-5 — Unstyled after install
+
+- **Ask:** "Fresh install on Tailwind 4 — components render but have black
+  borders and no backgrounds."
+- **Expect:** Tailwind 4 tree-shakes `node_modules` by default; add
+  `@source "../node_modules/@mieweb/ui/dist"` to the CSS entry.
+- **Agent:** MIE UI Install Agent
+- **Source:** lessons/tailwind4-integration.md — Lesson 1
+
+### INS-6 — @source vs safelist
+
+- **Ask:** "`@source` or safelist — which do I use?"
+- **Expect:** Depends on mode: TW4 → `@source`; TW3 → `miewebUIPreset` +
+  `miewebUISafelist`. Never a safelist on TW4.
+- **Agent:** MIE UI Install Agent
+- **Source:** agent/skills/mieweb-ui-tailwind4/SKILL.md; lessons/migration-meteor-blaze-to-react.md — Lesson 4
+
+### INS-7 — Verifying the setup
+
+- **Ask:** "How do I verify the install actually works?"
+- **Expect:** Render a probe (`className="bg-primary-500 text-white p-4"`),
+  check the dark-mode toggle, check brand switching, and run
+  `npx tsc --noEmit`.
+- **Agent:** MIE UI Install Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Phases 2.1, 3.1
+
+### INS-8 — Peer dependency model
+
+- **Ask:** "`pnpm install` warns about unmet peers like `leaflet` and
+  `three`. Do I need them all?"
+- **Expect:** No — required peers are `react`/`react-dom` (≥18) **and** the
+  five `@kerebron/*` runtime packages (main-barrel `Textarea`; bundling them
+  would duplicate `prosemirror-state`). Everything else heavy is optional,
+  needed only for the entry points you use (maps → `leaflet`, globe →
+  `three`/`react-globe.gl`, collab → `@kerebron/extension-yjs`/`yjs`); a
+  warning for an entry you never import is noise.
+- **Agent:** MIE UI Install Agent
+- **Source:** package.json — peerDependenciesMeta; CONTRIBUTING.md — Optional peer dependencies; agent/skills/mieweb-ui-catalog/SKILL.md — entry points
+
+### INS-9 — React 19
+
+- **Ask:** "Does @mieweb/ui work with React 19?"
+- **Expect:** Yes — the peer range is `react >= 18`.
+- **Agent:** MIE UI Install Agent
+- **Source:** package.json — peerDependencies
+
+### INS-10 — Meteor migration order
+
+- **Ask:** "What order do I migrate a Meteor 2 Blaze app to Meteor 3 + React +
+  @mieweb/ui?"
+- **Expect:** Scaffold (`meteor create --typescript --react`) → npm deps →
+  CSS entry + PostCSS + Tailwind config → verify Tailwind → `useTheme`/
+  `useBrand` → layout shell → migrate features → verify dark mode, brand,
+  TypeScript.
+- **Agent:** MIE UI Install Agent
+- **Source:** lessons/migration-meteor-blaze-to-react.md — Migration Order
+
+### INS-11 — Preset-only usage
+
+- **Ask:** "Can I use @mieweb/ui as just a Tailwind preset without the React
+  components?"
+- **Expect:** It's a React component library — `miewebUIPreset` is one export
+  (the TW3 token path), not a standalone product; install the library for
+  components.
+- **Agent:** MIE UI Install Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Phase 1.1
+
+### INS-12 — Raw-HTML audit
+
+- **Ask:** "How do I find everything that needs replacing in my app?"
+- **Expect:** Grep `src/` for `<button`, `<input`, `<select`, `<table`,
+  `<textarea` (`--include='*.tsx' --include='*.jsx'`) and count violations per
+  category against @mieweb/ui usage.
+- **Agent:** MIE UI Install Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Phases 1.2, 1.4
+
+### INS-13 — Phased replacement order
+
+- **Ask:** "Replace everything at once, or in phases?"
+- **Expect:** Phases, highest impact first: layout shell → buttons → form
+  elements → cards & modals → tables → feedback → navigation → specialized.
+  This verifies theming early.
+- **Agent:** MIE UI Install Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Phase 2.4
+
+### INS-14 — Installing from git source
+
+- **Ask:** "`npm install github:mieweb/ui` fails on `link:` dependencies.
+  How do I install?"
+- **Expect:** Install the published `@mieweb/ui` package from the npm
+  registry — source installs require the pnpm workspace + submodules and are
+  not an npm-consumer path.
+- **Agent:** MIE UI Install Agent
+- **Source:** issue #489
+
+### INS-15 — Package manager
+
+- **Ask:** "npm or pnpm for working in the mieweb/ui repo itself?"
+- **Expect:** pnpm — the repo is a pnpm workspace and the docs standardize on
+  pnpm commands. (Consumers of the published package can use any manager.)
+- **Agent:** MIE UI Install Agent
+- **Source:** issue #500; README.md
+
+### INS-16 — Grid entry point
+
+- **Ask:** "Which entry point do I import a data grid from?"
+- **Expect:** `DataVisNitroGrid` from `@mieweb/ui/datavis`; never
+  `@mieweb/ui/ag-grid` (deprecated).
+- **Agent:** MIE UI Install Agent
+- **Source:** mieweb-ui.instructions.md — Rules 1, 12
+
+### INS-17 — Wiring headless modules
+
+- **Ask:** "How do I connect `ViewSet` (or SuperChat-style modules) to my app
+  data?"
+- **Expect:** Write an adapter in the app — the module never fetches,
+  subscribes, or navigates. Two distinct contracts: **ViewSet** (collection
+  views) takes `items`/`loading`/`error`, accessor props, promise-returning
+  `on*` callbacks (built-in optimistic UI + revert), and `onOpen` + `getHref`;
+  **SuperChatInbox** has its own props (`conversations`, `onMessageSent`,
+  `onConversationOpened`) — never hand it collection-view props.
+- **Agent:** MIE UI Install Agent
+- **Source:** agent/skills/mieweb-ui-tailwind4/SKILL.md — Wiring headless modules; lessons/wiring-headless-modules.md
+
+### INS-18 — Dark-mode plumbing
+
+- **Ask:** "What plumbing does dark mode need after install?"
+- **Expect:** A toggle that matches the **active** `@custom-variant dark`
+  selector — `init.css` accepts either `.dark` or `data-theme="dark"`, so a
+  single-hook toggle can be valid; setting both via `useTheme` is the
+  compatibility-safe recommendation, not a hard requirement. Diagnose by
+  comparing the toggle to the variant in effect.
+- **Agent:** MIE UI Install Agent
+- **Source:** agent/skills/mieweb-ui-tailwind4/SKILL.md — Dark mode toggle
+
+### INS-19 — Brand loads but looks broken
+
+- **Ask:** "I load only the brand CSS and most components look unstyled."
+- **Expect:** Brand CSS is a delta (primary + semantic tokens), not a full
+  foundation — the base stylesheet (`styles.css`/`init.css`) must load first.
+- **Agent:** MIE UI Install Agent
+- **Source:** agent/skills/mieweb-ui-brands/SKILL.md; lessons/recommended-changes.md — P0 Issue 2
+
+### INS-20 — Common install traps
+
+- **Ask:** "What are the usual reasons a fresh @mieweb/ui setup looks
+  broken?"
+- **Expect:** Missing `@source` (tree-shaken classes), missing
+  `@custom-variant dark`, missing `var()` fallbacks (transparent renders),
+  wrong PostCSS plugin (TW3 plugin on TW4), wrong brand import path, missing
+  base stylesheet.
+- **Agent:** MIE UI Install Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Common Traps; lessons/tailwind4-integration.md

package/agent/evals/migration.md

@@ -0,0 +1,202 @@
+# Evals — Migration / compliance (incl. icon compliance)
+
+Primary agent: **MIE UI Migration Agent**. See [README.md](./README.md) for
+format and scoring. MIG-1 through MIG-5 are the icon-compliance cases
+(#587 requires them here).
+
+### MIG-1 — Foreign icon libraries
+
+- **Ask:** "Can I add Font Awesome / Material Icons / Heroicons for a few
+  missing icons?"
+- **Expect:** No — every icon comes from `lucide-react`: the `*Icon` aliases
+  re-exported from `@mieweb/ui` (188 icons) or direct `lucide-react` imports.
+  `@fortawesome/*` is ESLint-blocked; mixed sets break consistency.
+- **Agent:** MIE UI Migration Agent
+- **Source:** mieweb-ui.instructions.md — Rule 17; agent/skills/mieweb-ui-icons/SKILL.md
+
+### MIG-2 — Icon-only control labeling
+
+- **Ask:** "Audit finding: icon-only buttons using lucide icons. What's
+  required?"
+- **Expect:** `aria-label` on every icon-only control; decorative icons get
+  `aria-hidden="true"`.
+- **Agent:** MIE UI Migration Agent
+- **Source:** agent/skills/mieweb-ui-icons/SKILL.md — Conventions; Rules 2, 9
+
+### MIG-3 — Root-barrel icon shadows
+
+- **Ask:** "I imported `CloseIcon`/`RefreshIcon`/`SendIcon`/`SparklesIcon`
+  from `@mieweb/ui` and `size={16}` doesn't work."
+- **Expect:** Those root-barrel names are shadowed by custom AI components,
+  not Lucide re-exports — Lucide props don't apply. Import the Lucide
+  originals (`X`, `RefreshCw`, `Send`, `Sparkles`) from `lucide-react`.
+- **Agent:** MIE UI Migration Agent
+- **Source:** agent/skills/mieweb-ui-icons/SKILL.md — Root-barrel overrides (⚠)
+
+### MIG-4 — Hand-rolled SVG
+
+- **Ask:** "The icon I need isn't in the alias list. Hand-roll the SVG?"
+- **Expect:** No — the full lucide-react set (1000+ icons) is available by
+  direct import; never hand-roll `<svg>` icons.
+- **Agent:** MIE UI Migration Agent
+- **Source:** mieweb-ui.instructions.md — Rule 17
+
+### MIG-5 — Icon sizing
+
+- **Ask:** "What size do inline icons get?"
+- **Expect:** `h-4 w-4` (16px) default; `h-5 w-5` for emphasis; `h-3.5 w-3.5`
+  in dense UI; Lucide's `size={16}` is equivalent. Dynamic icon props are
+  typed `LucideIcon` (re-exported from `@mieweb/ui`).
+- **Agent:** MIE UI Migration Agent
+- **Source:** agent/skills/mieweb-ui-icons/SKILL.md — Conventions; Rule 17
+
+### MIG-6 — AGGrid in the app
+
+- **Ask:** "We still use AGGrid. Keep it?"
+- **Expect:** No — AGGrid is deprecated and deprecations are law; migrate to
+  `DataVisNitroGrid` from `@mieweb/ui/datavis`; never `@mieweb/ui/ag-grid` in
+  new code.
+- **Agent:** MIE UI Migration Agent
+- **Source:** mieweb-ui.instructions.md — Rules 1, 13
+
+### MIG-7 — Hand-rolled grid features
+
+- **Ask:** "Can I add sorting/paging on a plain `Table` myself?"
+- **Expect:** No — grid features start with DataVis NITRO; never hand-roll
+  them on a plain table or bring a third-party grid.
+- **Agent:** MIE UI Migration Agent
+- **Source:** mieweb-ui.instructions.md — Rule 1
+
+### MIG-8 — Patterns, not just imports
+
+- **Ask:** "We import @mieweb/ui everywhere. Are we compliant?"
+- **Expect:** Not necessarily — compliance is patterns, not imports: badge
+  spans, card divs, modal divs, raw buttons, and inline SVGs are violations
+  even in files that import @mieweb/ui.
+- **Agent:** MIE UI Migration Agent
+- **Source:** agent/agents/mieweb-ui-migration.agent.md — prime directive; lessons/adopting-mieweb-ui.md — Phase 1.3
+
+### MIG-9 — Raw HTML hard rule
+
+- **Ask:** "Can a migrated app keep a few raw `<button>`s in low-traffic
+  pages?"
+- **Expect:** No — never raw HTML for UI; `Button`, `Input`, `Card`, `Modal`,
+  `Badge`, `Select`, `Table` etc. everywhere, for consistent theming, dark
+  mode, and accessibility.
+- **Agent:** MIE UI Migration Agent
+- **Source:** lessons/migration-meteor-blaze-to-react.md — Lesson 7; Rule 3
+
+### MIG-10 — Dynamic attribute greps
+
+- **Ask:** "I grepped `type=\"date\"` and found nothing. Am I clean?"
+- **Expect:** No — also grep dynamic forms: `type={cond ? 'date' : 'text'}`
+  and other `type={…}` expressions evade literal greps.
+- **Agent:** MIE UI Migration Agent
+- **Source:** agent/agents/mieweb-ui-migration.agent.md — audit workflow
+
+### MIG-11 — Meteor 3 async APIs
+
+- **Ask:** "After the Meteor 3 upgrade, `Meteor.userId()` throws in a
+  method."
+- **Expect:** Meteor 3 server APIs are async — make methods async, `await
+Meteor.userId()`/`Meteor.user()`, and use `*Async()` collection variants
+  (`fetchAsync`, `insertAsync`, `updateAsync`, `removeAsync`).
+- **Agent:** MIE UI Migration Agent
+- **Source:** lessons/migration-meteor-blaze-to-react.md — Lesson 6
+
+### MIG-12 — Completion checklist
+
+- **Ask:** "How do I verify the migration is done?"
+- **Expect:** Final compliance checklist: CSS foundation correct **for the
+  app's mode** (TW4: `@source` + `@custom-variant` + fallbacks; TW3: preset +
+  safelist + content glob; precompiled: `styles.css` imported), zero raw HTML,
+  theming works (dark mode + brands), accessibility (ARIA, keyboard), clean
+  build (`npx tsc --noEmit`, no console errors).
+- **Agent:** MIE UI Migration Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Phase 4; agent/skills/mieweb-ui-tailwind4/SKILL.md — supported modes
+
+### MIG-13 — @source vs safelist in audits
+
+- **Ask:** "The audited app uses a Tailwind 3 safelist on Tailwind 4. Flag
+  it?"
+- **Expect:** Yes — on TW4 the supported mechanism is `@source`; a safelist
+  there is a migration leftover that bloats CSS.
+- **Agent:** MIE UI Migration Agent
+- **Source:** lessons/recommended-changes.md — P2 Issue 6; lessons/tailwind4-integration.md — Lesson 1
+
+### MIG-14 — Mode-aware CSS prescriptions
+
+- **Ask:** "The audited app ships precompiled CSS and no Tailwind. Do we
+  prescribe `@source`?"
+- **Expect:** No — the CSS-foundation check is mode-aware (TW4 / TW3 preset /
+  precompiled); never prescribe Tailwind tooling to a precompiled app.
+- **Agent:** MIE UI Migration Agent
+- **Source:** agent/agents/mieweb-ui-migration.agent.md; agent/skills/mieweb-ui-tailwind4/SKILL.md — supported modes
+
+### MIG-15 — Optimistic mutations in adapters
+
+- **Ask:** "Migrating to `ViewSet` — add my own optimistic state for
+  mutations?"
+- **Expect:** No — return the promise from `on*` callbacks; the view shows
+  the pending position and reverts on rejection. Optimistic UI + recovery
+  come free.
+- **Agent:** MIE UI Migration Agent
+- **Source:** lessons/wiring-headless-modules.md — The shape
+
+### MIG-16 — Common migration traps
+
+- **Ask:** "What traps should a migration audit check first?"
+- **Expect:** Tailwind tree-shaking (`@source`), missing `@custom-variant
+dark`, missing var fallbacks (transparent renders), wrong PostCSS plugin,
+  wrong brand import path, Meteor sync→async, raw HTML patterns, subpath
+  instead of barrel brand imports.
+- **Agent:** MIE UI Migration Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Common Traps; lessons/migration-meteor-blaze-to-react.md — Common Traps
+
+### MIG-17 — Verifying component APIs
+
+- **Ask:** "The catalog lists `Modal`. Can I infer its props from the catalog
+  entry?"
+- **Expect:** No — the catalog is inventory, not an API reference. Verify
+  props in the Storybook docs or the public types before prescribing usage.
+- **Agent:** MIE UI Migration Agent
+- **Source:** agent/agents/mieweb-ui-migration.agent.md — Rule 4
+
+### MIG-18 — Behavior-preserving replacements
+
+- **Ask:** "Replacing `window.confirm` with `AlertDialog` changes blocking
+  behavior. Just do it?"
+- **Expect:** Replacements must be behavior-preserving by default; a
+  blocking→async change is flagged as a judgment call for the app team, not
+  silently applied.
+- **Agent:** MIE UI Migration Agent
+- **Source:** agent/agents/mieweb-ui-migration.agent.md — Rule 5
+
+### MIG-19 — Nothing in the catalog fits
+
+- **Ask:** "No component covers this need. Write a custom one?"
+- **Expect:** Follow Rule 15: check composition of existing components first,
+  then propose a gap with a tier recommendation (contribution vs app-local);
+  don't silently fork or restyle an existing component.
+- **Agent:** MIE UI Migration Agent
+- **Source:** mieweb-ui.instructions.md — Rule 15; agent/agents/mieweb-ui-migration.agent.md — gap detection
+
+### MIG-20 — Destructive confirms
+
+- **Ask:** "The app confirms deletes with `window.confirm`. What's the
+  target?"
+- **Expect:** `AlertDialog` (destructive yes/no), noting the sync→async
+  behavior change as a judgment call (see MIG-18).
+- **Agent:** MIE UI Migration Agent
+- **Source:** agent/skills/mieweb-ui-catalog/selection-guidance.md; agent/agents/mieweb-ui-migration.agent.md
+
+### MIG-21 — Audit mechanics
+
+- **Ask:** "What does a full compliance audit actually grep for?"
+- **Expect:** Raw elements (`<button`, `<input`, `<select`, `<table`,
+  `<textarea`, incl. dynamic `type={…}`), pattern duplicates (badge spans,
+  card divs, modal divs, inline `<svg>`), foreign icon imports, then the
+  mode-aware CSS foundation check — reported as a prioritized plan, not a
+  dump.
+- **Agent:** MIE UI Migration Agent
+- **Source:** agent/agents/mieweb-ui-migration.agent.md — audit workflow; lessons/adopting-mieweb-ui.md — Phases 1.2–1.4

package/agent/evals/runs/2026-11-02.md

@@ -0,0 +1,53 @@
+# Manual eval run — 2026-11-02 (first run, #587)
+
+First manual run of the golden-question sets against the installed team
+(sandbox: `init-agent.mjs --experimental-agents`, team state = PR #688).
+Method per [../README.md](../README.md): stratified sample of 4 questions per
+domain (24 total), each specialist emulated from its installed agent file +
+skills, answers scored against **Expect**.
+
+## Scores
+
+| Domain    | Sample                            | PASS | PARTIAL | FAIL |
+| --------- | --------------------------------- | ---- | ------- | ---- |
+| selection | SEL-12, SEL-16, SEL-18, SEL-22    | 2    | 1       | 1    |
+| styling   | STY-7, STY-13, STY-14, STY-16     | 2    | 1       | 1    |
+| install   | INS-5, INS-8, INS-14, INS-17      | 3    | 1       | 0    |
+| a11y      | A11Y-3, A11Y-5, A11Y-13, A11Y-17  | 3    | 1       | 0    |
+| i18n      | I18N-3, I18N-10, I18N-11, I18N-13 | 4    | 0       | 0    |
+| migration | MIG-3, MIG-10, MIG-14, MIG-18     | 4    | 0       | 0    |
+
+## Findings and fixes filed
+
+1. **SEL-12 FAIL — design agent can't answer headless-wiring questions and
+   didn't route them.** The knowledge lives in the tailwind4 skill ("Wiring
+   headless modules", Install agent's source), but the orchestrator's routing
+   table had no wiring row. _Fix:_ added a routing row (wiring headless
+   modules → MIE UI Install Agent) to `mieweb-ui-design.agent.md`.
+2. **STY-13 FAIL — corpus gap caused a wrong diagnosis.** Nothing in the
+   corpus covered the brand CSS's unlayered `*` transition shorthand beating
+   layered `transition-*` utilities (open #460/#682); the agent
+   mis-attributed the symptom to the brand-without-base pitfall. _Fix:_
+   troubleshooting rows added to the tailwind4 skill and
+   `lessons/tailwind4-integration.md` (fix = layer the transition rule, not
+   scope it — it already lists only color properties).
+3. **INS-14 PARTIAL — honest corpus gap on installing from git source**
+   (#489). _Fix:_ install note added to the tailwind4 skill (published npm
+   package only; source tree is a pnpm workspace with `link:` deps).
+4. **A11Y-17 PARTIAL — corpus silent on exit-animation semantics**, and the
+   eval's own Expect overstated the motion layer (`AnimatedPresence` does
+   NOT yet hide exiting children — open #474). _Fix:_ exit-animation note
+   added to the a11y-checklist skill; eval entry corrected to cite #474 as
+   open.
+5. **STY-14 PARTIAL — preset drift (#628) unknowable from corpus.** The
+   generic safelist/content diagnosis is correct behavior; the drift itself
+   is an open library bug, not a corpus gap. _Fix:_ eval Expect rewritten to
+   match the corpus-known-good diagnosis path, citing #628 as open.
+6. **SEL-16 eval defect — ambiguous Ask.** "Sometimes… sometimes" read as one
+   component needing both behaviors; the agent correctly mapped all three
+   badges but declared a gap. _Fix:_ Ask rephrased to three distinct
+   placements.
+
+No findings for i18n or migration — both specialists answered their samples
+fully from the corpus, including the root-barrel icon shadows (MIG-3) and the
+behavior-change judgment call (MIG-18).

package/agent/evals/selection.md

@@ -0,0 +1,212 @@
+# Evals — Component selection / catalog
+
+Primary agent: **MIE UI Design Agent** (owns selection via the
+`mieweb-ui-catalog` skill and its selection guidance). See
+[README.md](./README.md) for format and scoring.
+
+### SEL-1 — Table or NITRO
+
+- **Ask:** "Should I use `Table` or DataVis NITRO for a data grid?"
+- **Expect:** Start with `DataVisNitroGrid` from `@mieweb/ui/datavis` for
+  anything with sorting, filtering, paging, or export; `Table` only for static
+  rows; AGGrid is deprecated — never in new code.
+- **Agent:** MIE UI Design Agent
+- **Source:** mieweb-ui.instructions.md — Rule 1
+
+### SEL-2 — Two adjacent buttons
+
+- **Ask:** "I have two buttons side by side. Do I need `ButtonGroup`?"
+- **Expect:** Yes — always wrap two or more adjacent buttons in `ButtonGroup`;
+  also wrap a single button with a long/unpredictable label (translated text,
+  user data), using `orientation="auto"`.
+- **Agent:** MIE UI Design Agent
+- **Source:** mieweb-ui.instructions.md — Rule 2
+
+### SEL-3 — Raw table replacement
+
+- **Ask:** "What @mieweb/ui component replaces a raw `<table>`?"
+- **Expect:** `Table` + `TableHeader`/`TableBody`/`TableRow`/`TableCell` for
+  static data; `DataVisNitroGrid` once interactivity is needed; never
+  hand-roll grid features.
+- **Agent:** MIE UI Design Agent
+- **Source:** mieweb-ui.instructions.md — Rules 1, 3
+
+### SEL-4 — Raw button
+
+- **Ask:** "Can I keep a raw `<button>` element, or do I need `Button`?"
+- **Expect:** Every interactive element uses @mieweb/ui components — replace
+  `<button>` with `Button` (and `<input>` with `Input`/`Checkbox`/`Radio`,
+  etc.) for consistent theming, dark mode, and accessibility.
+- **Agent:** MIE UI Design Agent
+- **Source:** mieweb-ui.instructions.md — Rule 3
+
+### SEL-5 — Modal internals
+
+- **Ask:** "I'm building a Modal with a title, content, and footer. Divs, or
+  something else?"
+- **Expect:** Use composition slots — `ModalHeader`/`ModalBody`/`ModalFooter`,
+  not bespoke divs; same pattern for `Card` and `Table` slots.
+- **Agent:** MIE UI Design Agent
+- **Source:** mieweb-ui.instructions.md — Rule 4
+
+### SEL-6 — Badge span
+
+- **Ask:** "Is `<span className=\"badge\">Active</span>` fine if it's styled
+  correctly?"
+- **Expect:** No — raw HTML that duplicates a component is a violation; use
+  `Badge`. This applies to all badge/pill/tag spans.
+- **Agent:** MIE UI Design Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Phase 1.3
+
+### SEL-7 — Date inputs
+
+- **Ask:** "What do I use for a date picker, and for a date range?"
+- **Expect:** `DateInput` for a single date, `DateRangePicker` for a range;
+  never raw `<input type="date">`.
+- **Agent:** MIE UI Design Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Phase 1.3
+
+### SEL-8 — Phone number input
+
+- **Ask:** "I need a phone number field. Raw input with a mask, or a
+  component?"
+- **Expect:** `PhoneInput` — it handles formatting and validation.
+- **Agent:** MIE UI Design Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Phase 1.3
+
+### SEL-9 — ViewSet responsibilities
+
+- **Ask:** "Does `ViewSet` fetch data, subscribe to changes, and navigate
+  itself?"
+- **Expect:** No — it's headless: receives `items`/`loading`/`error` as props,
+  returns mutations through `on*` callbacks; never fetches, subscribes, or
+  navigates. Pass `onOpen` + `getHref` for real anchors.
+- **Agent:** MIE UI Design Agent
+- **Source:** mieweb-ui.instructions.md — Rule 14; lessons/wiring-headless-modules.md
+
+### SEL-10 — MediaFeed vs NewsWidget
+
+- **Ask:** "Is `MediaFeed` a drop-in replacement for our standalone news
+  widget?"
+- **Expect:** No — `MediaFeed` takes items through props and accessor
+  functions; the app owns RSS/Discourse adapters, loading, navigation, and
+  engagement callbacks. Convert posts to `MediaFeedMedia` with accessors and
+  use optional slots for custom rendering.
+- **Agent:** MIE UI Design Agent
+- **Source:** lessons/news-widget-migration.md
+
+### SEL-11 — Collection component contract
+
+- **Ask:** "I'm adding a component that renders a collection (list, board,
+  calendar). What contract must it follow?"
+- **Expect:** Headless module: `items`/`loading`/`error` in via props,
+  mutations out via `on*` callbacks typed `void | Promise<void>`; no
+  fetch/subscribe/navigate inside; generic via accessor props (`getId`,
+  `getStatus`, …); strings overridable through `labels`.
+- **Agent:** MIE UI Design Agent
+- **Source:** mieweb-ui.instructions.md — Rule 14
+
+### SEL-12 — ViewSet navigation
+
+- **Ask:** "How do I wire navigation into `ViewSet` — just `onOpen`?"
+- **Expect:** Pass both `onOpen` (client-side routing on left-click) and
+  `getHref` (real anchors so middle-click/copy-link work); `onOpen` alone
+  degrades links to buttons.
+- **Agent:** MIE UI Install Agent (posed to the orchestrator — correct
+  behavior is delegation via its headless-wiring routing row)
+- **Source:** lessons/wiring-headless-modules.md; agent/agents/mieweb-ui-design.agent.md — routing table
+
+### SEL-13 — Danger styling
+
+- **Ask:** "I want a destructive-looking button — `className=\"bg-red-600\"`?"
+- **Expect:** No — `variant="danger"`. Variants (`primary`, `secondary`,
+  `ghost`, `outline`, `danger`, `link`) and sizes (`sm`, `md`, `lg`, `icon`)
+  are props, never className hacks.
+- **Agent:** MIE UI Design Agent
+- **Source:** mieweb-ui.instructions.md — Rule 5
+
+### SEL-14 — Imitating a variant
+
+- **Ask:** "Can I restyle a component with className tweaks to look like
+  another variant instead of using the prop?"
+- **Expect:** No — if a component has a prop for it, use the prop; never
+  imitate an existing variant via className.
+- **Agent:** MIE UI Design Agent
+- **Source:** mieweb-ui.instructions.md — Rule 5
+
+### SEL-15 — Where to compare components
+
+- **Ask:** "Where do I check which component to use when several look
+  similar?"
+- **Expect:** The Storybook family overview pages — every family has a
+  comparison ("which one?") table; read it before choosing. (From an agent:
+  the catalog skill's selection guidance mirrors these tables.)
+- **Agent:** MIE UI Design Agent
+- **Source:** lessons/adopting-mieweb-ui.md — Phase 1.3; agent/skills/mieweb-ui-catalog/selection-guidance.md
+
+### SEL-16 — Badge vs CountBadge vs FreshnessBadge
+
+- **Ask:** "I need a status pill in one place, a clickable count pill in
+  another, and a pill whose colour depends on age in a third — which badge
+  for each?"
+- **Expect:** `Badge` for a state/category mapped to a `variant`;
+  `CountBadge` when it's a clickable "Label N" pill that opens rows;
+  `FreshnessBadge` when the colour depends on a date.
+- **Agent:** MIE UI Design Agent
+- **Source:** agent/skills/mieweb-ui-catalog/selection-guidance.md — Data display
+
+### SEL-17 — Destructive confirmation
+
+- **Ask:** "What do I use for a 'Delete this record?' confirmation — `Modal`?"
+- **Expect:** `AlertDialog` for a single yes/no destructive confirm; `Modal`
+  is for richer content.
+- **Agent:** MIE UI Design Agent
+- **Source:** agent/skills/mieweb-ui-catalog/selection-guidance.md
+
+### SEL-18 — MessageComposer is retired
+
+- **Ask:** "Should new chat UIs use `MessageComposer`?"
+- **Expect:** No — `MessageComposer` was retired in 0.10.0, superseded by
+  `ChatComposer` (see `MIGRATION.md#chat-composer`); `ChatComposer` is the
+  standardized chat input for new work.
+- **Agent:** MIE UI Design Agent
+- **Source:** agent/skills/mieweb-ui-catalog/selection-guidance.md — Chat; MIGRATION.md
+
+### SEL-19 — Text editing surfaces
+
+- **Ask:** "Plain comment box vs rich notes field vs full document editor —
+  which components?"
+- **Expect:** `Textarea` when the value must be plain text; `TextAreaRich`
+  for a textarea-like HTML surface (toolbar hidden until asked, auto-grow);
+  `RichTextEditor` for an HTML document with an always-on toolbar, variables,
+  or dictation; `RichEditor` when you need Markdown, links/tables/code, or
+  collaboration.
+- **Agent:** MIE UI Design Agent
+- **Source:** agent/skills/mieweb-ui-catalog/selection-guidance.md — Editors
+
+### SEL-20 — Filter count strip
+
+- **Ask:** "I want '1,204 of 8,911 records — 3 filters active · Clear all'
+  above my grid. Build it from spans?"
+- **Expect:** `FilterSummaryBar` above a host-filtered `DataVisNITRO`/`Table`;
+  removable filter chips are `Badge` with `onRemove`, not a custom strip.
+- **Agent:** MIE UI Design Agent
+- **Source:** agent/skills/mieweb-ui-catalog/selection-guidance.md — Data display
+
+### SEL-21 — Confirming AI-extracted values
+
+- **Ask:** "A user must confirm AI-extracted values before they overwrite the
+  record — form, dialog, or something else?"
+- **Expect:** `ReconciliationPanel` (confidence-aware defaults,
+  `onApply(accepted)`); a plain form when there's no existing record to
+  compare; `AlertDialog` when it's a single yes/no.
+- **Agent:** MIE UI Design Agent
+- **Source:** agent/skills/mieweb-ui-catalog/selection-guidance.md — Chat
+
+### SEL-22 — Unexported components
+
+- **Ask:** "Can I import Speaker Scribe from `@mieweb/ui` today?"
+- **Expect:** No — the catalog marks it "not exported yet"; it exists in
+  Storybook but is not in the public API, so don't recommend or import it.
+- **Agent:** MIE UI Design Agent
+- **Source:** agent/skills/mieweb-ui-catalog/SKILL.md — inventory ("not exported yet" annotations)