docs: COMPONENT_AUDIT_GUIDE.md — inviolable pre-flight + audit script
Creates the binding pre-flight checklist every agent / contributor must
read before touching any UIX component. AGENTS.md gets a top-banner
linking the three required reads (this guide, DEMO_AUTHORING_GUIDE,
eidos components README).
Sections:
0. Inviolable rule — always read this + the demo guide + components
README before coding
1. Reference library matrix (radix-themes, radix-primitives, chakra,
mantine, mui, react-aria, ark, bits, shadcn, WAI-ARIA APG)
2. 4-layer ownership recap + 2-of-3 rule for morfo extensions
3. Pre-flight audit template (feature parity matrix, architectural
choices, reference comparison, decision log, user sign-off line)
4. Project-wide architectural rules — Radix item/container split,
composition over visibility props, chip parity, size category
cheatsheet, per-event intent, no re-export facades, persistent
label registries, floating layer defaults, combobox keyboard,
Chakra band-above-control chips
4.11 `npm run component:audit` is the canonical verification tool —
walks every component, parses morfo, cross-checks eidos + demo,
emits report. A component is "done" only when its scoreboard row
reads PASS with 0 errors.
5. Demo template is locked — points at DEMO_AUTHORING_GUIDE
6. Anti-pattern catalogue — every failed approach from recent
sessions with WHY it failed (shallow demos, matchAnchorWidth,
visibility booleans, inline chips, onpointerdown picks, flex
100% wrap, unregistering labels on unmount, auto-rendering
wrappers, refocus without guard, agent git reset, skipped audit)
7. Canonical canaries per domain
8. Audit log — running table with commit hashes + known gaps from
Layout Batch 1
9. Pre-port checklist (now includes README writing + the audit
script run + npm run check)
10. "When in doubt, ask the user" closer
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
dev
60a50f1c27