@hegemonart/get-design-done 1.19.0 → 1.19.6

package/agents/design-planner.md

@@ -349,4 +349,14 @@ You MUST NOT:
 @.design/intel/dependencies.json (if present)
 @.design/intel/graph.json (if present)
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## PLANNING COMPLETE

package/agents/design-reflector.md

@@ -51,6 +51,16 @@ Write these sections in order. If source data is missing, write the section head
 
 Compare `.design/DESIGN-VERIFICATION.md` gaps to `.design/DESIGN-PLAN.md` acceptance criteria. List decisions that deviated from plan, unexpected cost spikes (agent cost > 2× typical), agents that ran > 3× their `typical-duration-seconds`. One bullet per surprise; cite cycle slug and evidence.
 
+After listing standard surprises, apply the **Four Principles Checks** from `reference/emotional-design.md` and `reference/first-principles.md`:
+
+**Reducibility check** — Did any executed task add elements that fail the reducibility test (body / attention / memory justification absent)? If DESIGN-PLAN.md tasks added >3 visual elements none of which appear in DESIGN-VERIFICATION.md acceptance criteria, flag as "possible decorative accumulation."
+
+**Memory-load check** — Does DESIGN-VERIFICATION.md show any H-06 (Recognition > Recall) gap? If yes, flag: "Memory invariant violation — users may need to remember context between screens." Cite the specific gap.
+
+**Peak-End check** — Scan DESIGN-PLAN.md and DESIGN-VERIFICATION.md for evidence of a designed peak moment (a completion screen, a celebration, a distinct success state). If none found, flag: "No peak moment designed — reflective-level experience may score low. Consider adding a designed end state."
+
+**Error-redemption check** — Scan DESIGN-VERIFICATION.md for H-09 (Error Recovery) score. If score < 3, flag: "Error-redemption gap — error states do not guide users to resolution. This is a behavioral-level failure that also damages the reflective level (users remember bad endings)."
+
 ### 2. Recurring Decisions
 
 Scan STATE.md `<decisions>` block for D-XX codes. Cross-reference `.design/learnings/` files from prior cycles if present. Flag decisions that: (a) appeared in multiple sessions of the same cycle, or (b) appear under the same keyword in learnings from ≥2 prior cycles. These are candidates for `reference/` additions.
@@ -172,4 +182,14 @@ Aggregate per agent across cycles:
 - Proposals are additive — propose additions, not deletions of existing content, unless the evidence is clear (e.g., wrong frontmatter value).
 - Maximum 20 proposals per reflection file. If more are warranted, batch the lowest-priority ones into a single summary note at the end.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## REFLECTION COMPLETE

package/agents/design-research-synthesizer.md

@@ -163,4 +163,14 @@ Read .design/STATE.md
 
 Single file: `.design/DESIGN-CONTEXT.md`.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## SYNTHESIZE COMPLETE

package/agents/design-start-writer.md

@@ -219,3 +219,13 @@ The JSON block at the bottom is the contract future `/gdd:fast` / `/gdd:do` invo
 - Do not omit any of the seven H2 sections — even empty, they must exist for downstream regression fixtures.
 
 ## START-WRITER COMPLETE
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/design-update-checker.md

@@ -115,3 +115,13 @@ Last line of your response MUST be:
 ```
 
 The spawning skill greps for this marker to confirm you finished successfully. Emit it even on the "no cache" fallback path.
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/design-verifier-gate.md

@@ -94,4 +94,14 @@ You MAY:
 
 Per 10.1-CONTEXT decision **D-21** (Lazy Checker Spawning): "Cheap Haiku gate agents at `agents/*-gate.md` decide whether to spawn full checker. Gate agent: reads DIFF of changed files, applies heuristic (design-system paths touched? copy strings touched? token files touched?), returns `{spawn: true|false, rationale: '...'}`. If false, skip full checker, log as `lazy_skipped: true` in telemetry." This gate is the verifier-specific instance of that pattern — full `design-verifier` is an XL-size spawn and the most expensive single agent in the pipeline, so gating it behind a cheap Haiku diff-scan yields the largest single cost win in Phase 10.1.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## GATE COMPLETE

package/agents/design-verifier.md

@@ -553,6 +553,17 @@ Emit a 2–4 sentence summary paragraph describing results, then:
 Emit `## GAPS FOUND` heading, then the full structured gap list (BLOCKER first, MAJOR, MINOR, COSMETIC), then on a new line:
 
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## VERIFICATION COMPLETE
 ```
 

package/agents/gdd-graphify-sync.md

@@ -98,3 +98,13 @@ Graphify status: <status line>
 @.design/intel/files.json (if present)
 
 ## GRAPHIFY-SYNC COMPLETE
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/gdd-intel-updater.md

@@ -85,4 +85,14 @@ Generated:      <timestamp>
 A slice is stale if its `generated` timestamp is older than the newest `mtime` in `files.json`.
 The updater does not need to check this manually — `build-intel.cjs` handles mtime comparison.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## INTEL UPDATE COMPLETE

package/agents/gdd-learnings-extractor.md

@@ -82,4 +82,14 @@ For each learning with `Proposed reference update: yes`:
 @.design/intel/patterns.json (if present)
 @.design/learnings/LEARNINGS.md (if present)
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## LEARNINGS EXTRACTION COMPLETE

package/agents/motion-mapper.md

@@ -210,4 +210,14 @@ If no violations found, emit: `## Micro-motion findings — CLEAN (0 violations)
 
 No modifications outside `.design/map/`. No git. No agent spawning.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## MOTION MAP COMPLETE

package/agents/token-mapper.md

@@ -144,4 +144,14 @@ Total: N findings. (0 = clean)
 
 You MUST NOT modify anything outside `.design/map/`. Do not run git commands or spawn agents.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## TOKEN MAP COMPLETE

package/agents/visual-hierarchy-mapper.md

@@ -121,4 +121,14 @@ Total: N findings.
 
 No modifications outside `.design/map/`. No git. No agent spawning.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## VISUAL HIERARCHY MAP COMPLETE

package/hooks/gdd-decision-injector.js

@@ -25,6 +25,14 @@ const MIN_BYTES = 1500;
 const TOP_N = 15;
 const MATCHER_RE = /[\\/](?:\.design|reference|\.planning)[\\/][^\n]*\.md$/;
 
+// Phase 19.5: try FTS5 backend first; fall back to grep silently.
+let _designSearch = null;
+try {
+  _designSearch = require(path.join(__dirname, '..', 'scripts', 'lib', 'design-search.cjs'));
+} catch { /* not available in this install */ }
+
+const BACKEND = _designSearch ? _designSearch.backendName() : null;
+
 function ripgrepAvailable() {
   try {
     const r = spawnSync('rg', ['--version'], { encoding: 'utf8', windowsHide: true });
@@ -103,7 +111,7 @@ function sortKeyFor(tag) {
   return 0;
 }
 
-function buildRecallBlock(matches, basename) {
+function buildRecallBlock(matches, basename, backendLabel) {
   if (!matches.length) return null;
   const uniq = [];
   const seen = new Set();
@@ -125,10 +133,11 @@ function buildRecallBlock(matches, basename) {
     const excerpt = m.text.length > 140 ? m.text.slice(0, 137) + '…' : m.text;
     lines.push(`> - [${tag}] ${excerpt} (${path.relative(process.cwd(), m.file)}:${m.line})`);
   }
+  // backendLabel passed in from main()
   if (uniq.length > TOP_N) {
-    lines.push(`> … (${uniq.length - TOP_N} more matches; use \`/gdd:recall <term>\` to expand. Grep backend; FTS5 upgrade in Phase 19.5.)`);
+    lines.push(`> … (${uniq.length - TOP_N} more matches; use \`/gdd:recall <term>\` to expand. Backend: ${backendLabel}.)`);
   } else {
-    lines.push(`> (${uniq.length} match${uniq.length === 1 ? '' : 'es'} surfaced. Grep backend; FTS5 upgrade in Phase 19.5.)`);
+    lines.push(`> (${uniq.length} match${uniq.length === 1 ? '' : 'es'} surfaced. Backend: ${backendLabel}.)`);
   }
   lines.push('');
   return lines.join('\n');
@@ -173,13 +182,26 @@ async function main() {
     return;
   }
 
-  const useRg = ripgrepAvailable();
-  const hits = [];
-  for (const src of sources) {
-    hits.push(...(useRg ? grepLinesRg(src, terms) : grepLinesNode(src, terms)));
+  const useRgGlobal = ripgrepAvailable();
+  let hits = [];
+  if (BACKEND === 'fts5' && _designSearch) {
+    // FTS5 path: single query across all indexed docs
+    try {
+      const query = terms.join(' OR ');
+      hits = _designSearch.search(query, cwd, { limit: TOP_N * 3 });
+    } catch { hits = []; }
+    if (!hits.length) {
+      // FTS5 db may be stale — rebuild silently then retry
+      try { _designSearch.reindex(cwd); hits = _designSearch.search(terms.join(' OR '), cwd, { limit: TOP_N * 3 }); } catch { hits = []; }
+    }
+  } else {
+    for (const src of sources) {
+      hits.push(...(useRgGlobal ? grepLinesRg(src, terms) : grepLinesNode(src, terms)));
+    }
   }
 
-  const block = buildRecallBlock(hits, basename);
+  const backendLabel = BACKEND || (useRgGlobal ? 'ripgrep' : 'node-grep');
+  const block = buildRecallBlock(hits, basename, backendLabel);
   if (!block) {
     process.stdout.write(JSON.stringify({ continue: true }));
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.19.0",
+  "version": "1.19.6",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -82,7 +82,23 @@
     "information-architecture",
     "form-patterns",
     "data-viz",
-    "platforms"
+    "platforms",
+    "cross-cycle-memory",
+    "fts5",
+    "checkpoints",
+    "experience-archive",
+    "recall",
+    "relevance-counter",
+    "record-contract",
+    "first-principles",
+    "emotional-design",
+    "component-authoring",
+    "disney-12-principles",
+    "peak-end-rule",
+    "loss-aversion",
+    "cognitive-load",
+    "doherty-threshold",
+    "rams-lens"
   ],
   "skills": [
     "SKILL.md"

package/reference/authority-feeds.md

@@ -4,8 +4,8 @@
 >
 > **Anti-slop thesis:** No Dribbble. No Behance. No LinkedIn. No generic trending aggregators. See `.planning/PROJECT.md` and `.planning/phases/13.2-external-authority-watcher/13.2-CONTEXT.md` §D-08.
 
-**Last reviewed:** 2026-04-19
-**Feed count:** 26 (updated each time a feed is added or removed)
+**Last reviewed:** 2026-04-24
+**Feed count:** 28 (updated each time a feed is added or removed)
 
 ---
 
@@ -46,6 +46,8 @@
 - **[Scott Jehl](https://scottjehl.com/)** — `kind: named-practitioner` · `url: https://scottjehl.com/feed/` · `cadence-hint: monthly` · *Progressive enhancement and web performance; long-form durable analysis.*
 - **[Heydon Pickering](https://heydonworks.com/)** — `kind: named-practitioner` · `url: https://heydonworks.com/feed.xml` · `cadence-hint: irregular` · *Accessibility-first component design; Inclusive Components author.*
 - **[Una Kravets](https://una.im/)** — `kind: named-practitioner` · `url: https://una.im/feed.xml` · `cadence-hint: monthly` · *Chrome DevRel on CSS; surfaces and explains new platform capabilities.*
+- **[Don Norman — jnd.org](https://jnd.org/)** — `kind: named-practitioner` · `url: https://jnd.org/feed/` · `cadence-hint: monthly` · *Don Norman's essays on emotional design, affordances, cognitive design, and human-centered AI. Primary source for `reference/emotional-design.md`.*
+- **[Vitsœ — Dieter Rams](https://www.vitsoe.com/gb/about/good-design)** — `kind: named-practitioner` · `url: https://www.vitsoe.com/feed` · `cadence-hint: irregular` · *Canonical source for Rams's 10 Principles of Good Design. Published by Vitsœ, who worked directly with Rams at Braun. Primary source for the Rams Lens in `reference/checklists.md`.*
 
 ## User-added Are.na channels (user-extensible)
 

package/reference/checklists.md

@@ -162,3 +162,33 @@ Use this checklist after the main design review for pixel-level craft verificati
 - [ ] No `transition: all` anywhere (see BAN-12 transition-all)
 - [ ] No `will-change: all` anywhere (see BAN-13 will-change-all)
 - [ ] `prefers-reduced-motion` respected via `MotionConfig` or `useReducedMotion()`
+
+---
+
+## Rams Lens — 10 Design Questions
+
+Dieter Rams's 10 principles of good design (Vitsœ/Braun, 1970s–80s) applied as a self-audit lens. Each question maps to one principle.
+
+- [ ] **Innovative** — Does this design solve the problem in a way that was not possible or obvious before?
+- [ ] **Useful** — Does every element serve the primary function? Nothing decorative that doesn't earn its place?
+- [ ] **Aesthetic** — Is the visual appearance the minimum necessary for legibility and emotional resonance?
+- [ ] **Understandable** — Can the user figure out how to use this without reading documentation or a tooltip?
+- [ ] **Unobtrusive** — Does the design stay in the background and let the content or task take focus?
+- [ ] **Honest** — Does the design not imply capabilities, quality, or status that the product doesn't have?
+- [ ] **Long-lasting** — Is this design free of trend-dependent choices (gradients, micro-styles) that will age in 12 months?
+- [ ] **Thorough** — Have edge cases been considered and handled (empty states, error states, loading states, overflow text)?
+- [ ] **Environmentally friendly** — Is the performance footprint minimal? (image sizes, JS bundle, font weight)
+- [ ] **As little design as possible** — If you removed 20% of the design decisions, would the product be worse? If not, remove them.
+
+---
+
+## Sonner / Component-Authoring Lens — 6 Questions
+
+Emil Kowalski's component-authoring principles applied as a per-component self-audit. Full reference: `reference/component-authoring.md`.
+
+- [ ] **P-01 API surface** — Does this component work correctly in 1 line with zero configuration?
+- [ ] **P-02 Composability** — Does this component compose via slots/children, not via style-configuration props?
+- [ ] **P-03 Defaults** — Are the defaults so sensible that most consumers never need to pass any props?
+- [ ] **P-04 Animation** — Does every animation in this component communicate a state change? No decorative loops?
+- [ ] **P-05 Accessibility** — Does this component have a complete ARIA contract before any visual styling?
+- [ ] **P-06 Edge honesty** — Are known failure modes documented with `// KNOWN:` or `// EDGE:` comments?

package/reference/component-authoring.md

@@ -0,0 +1,184 @@
+# Component Authoring Principles
+
+Source: Emil Kowalski's work on Sonner, Vaul, and cmdk — synthesised from his published writing and talks. See also: `reference/framer-motion-patterns.md`, `reference/motion-advanced.md`.
+
+Use this file when authoring, reviewing, or auditing UI components. The 6 principles apply as a lens during code review and design verification. Each principle has a grep-able audit signal.
+
+---
+
+## The 6 Principles
+
+### P-01: Minimal API Surface
+
+> Expose only what the consumer needs. Every prop is a contract you must maintain forever.
+
+A component with the right API surface works in 1 line for 80% of cases and 3 lines for 95% of cases. A component that requires 7 props for basic usage has too much surface.
+
+**Audit signal:**
+```bash
+# Count required (non-optional) props in a component interface
+grep -E "^\s+\w+: " src/components/Button.tsx | grep -v "?" | wc -l
+```
+
+**Thresholds:**
+- ≤5 props total: excellent
+- 6–9 props total: acceptable if logically grouped
+- ≥10 props: flag for decomposition
+
+**Pattern — variant over prop explosion:**
+```tsx
+// BAD — prop explosion
+<Button color="blue" size="md" rounded={true} shadow={true} uppercase={false} />
+
+// GOOD — variant collapses 5 props to 1
+<Button variant="primary" size="md" />
+```
+
+---
+
+### P-02: Composability Over Configuration
+
+> Components should compose, not configure. Accepting `backgroundColor` or `textColor` is a sign the abstraction boundary is wrong.
+
+The right abstraction lets consumers build what they need by combining small pieces, not by passing increasingly specific configuration. Slot-based APIs > configuration-object APIs.
+
+**Audit signal:**
+```bash
+# Configuration props that should be design tokens instead
+grep -rE "(backgroundColor|textColor|borderRadius|fontSize)=" src/components/ --include="*.tsx"
+```
+
+**Pattern — slot composition:**
+```tsx
+// BAD — too much configuration
+<Card title="Hello" subtitle="World" icon="user" rightContent={<Badge />} />
+
+// GOOD — slot composition; parent controls layout
+<Card>
+  <Card.Header>
+    <Card.Icon><UserIcon /></Card.Icon>
+    <Card.Title>Hello</Card.Title>
+    <Card.Subtitle>World</Card.Subtitle>
+    <Badge />
+  </Card.Header>
+</Card>
+```
+
+---
+
+### P-03: Sensible Defaults
+
+> The zero-config case should work and look correct. Options are for exceptions.
+
+A component with sensible defaults doesn't require the consumer to know its internals. The defaults encode the design system's opinion about what "normal" looks like.
+
+**Audit signal:**
+```bash
+# Props with no default values (every prop is required = red flag)
+grep -E "^\s+\w+: " src/components/Toast.tsx | grep -v "?" | wc -l
+```
+
+**The Sonner model:** `<Toaster />` with zero props renders a toast system that follows the OS color scheme, positions correctly on all viewports, stacks properly, and auto-dismisses at a sensible duration. All options exist — but the zero-prop case works.
+
+**Anti-pattern:** Required props for things with a logical default (e.g., `position` on a modal that should always default to `center`).
+
+---
+
+### P-04: Animation as State Communication
+
+> Transitions communicate state change. They are not decoration. An animation that fires without a state change is noise.
+
+Every motion in a component should answer: "What did the system just do?" If the animation doesn't have a clear answer, remove it.
+
+**Audit signal:**
+```bash
+# Animations not tied to state change (decorative loops = red flag)
+grep -rE "animate.*loop|animation.*infinite|keyframes.*repeat" src/components/ --include="*.tsx"
+```
+
+**The Sonner model:**
+- Toast enters → communicates: "event occurred"
+- Toast stacks → communicates: "multiple events queued"
+- Toast exits → communicates: "event acknowledged or expired"
+- No animation fires without a state change triggering it
+
+**Thresholds:**
+- All animations tied to state: excellent
+- ≤1 decorative animation (e.g., a loading shimmer): acceptable
+- ≥2 decorative animations: flag for review
+
+See `reference/motion-advanced.md` for implementation patterns.
+
+---
+
+### P-05: Accessibility Before Visuals
+
+> If a component isn't accessible by keyboard and screen reader, it isn't done. Accessibility is not a post-processing step.
+
+Build the ARIA contract before the visual. The visual is a rendering of the semantic layer, not the other way around.
+
+**Audit signal:**
+```bash
+# Interactive divs/spans without ARIA role (missing semantic contract)
+grep -rE "<(div|span)[^>]*onClick" src/components/ --include="*.tsx" | grep -v "role="
+```
+
+**Required ARIA contracts by component type:**
+
+| Component | Required attributes |
+|---|---|
+| Dialog / Modal | `role="dialog"`, `aria-modal="true"`, `aria-labelledby` |
+| Combobox / Select | `role="combobox"`, `aria-expanded`, `aria-controls` |
+| Menu | `role="menu"`, `role="menuitem"`, keyboard trap |
+| Toast / Alert | `role="status"` (polite) or `role="alert"` (assertive) |
+| Toggle / Switch | `role="switch"`, `aria-checked` |
+| Tabs | `role="tablist"`, `role="tab"`, `role="tabpanel"`, `aria-selected` |
+| Tooltip | `role="tooltip"`, `aria-describedby` on trigger |
+
+---
+
+### P-06: Edge Case Honesty
+
+> Document the cases where the component fails. If you know it breaks with strings longer than 30 characters, say so.
+
+Undocumented edge cases become production bugs. A component spec that acknowledges failure modes is more trustworthy than one that claims universal correctness.
+
+**Audit signal:**
+```bash
+# Look for documented edge cases
+grep -rE "// KNOWN:|// EDGE:|// LIMIT:" src/components/ --include="*.tsx"
+```
+
+**Template for component edge case documentation:**
+```tsx
+// KNOWN: Toast title truncates at ~80 chars on 320px viewport; use short titles
+// KNOWN: Stacking > 5 toasts simultaneously is unsupported; excess toasts are queued
+// EDGE: If `duration` is set to Infinity, a visible dismiss button is required
+```
+
+The presence of these comments is a quality signal, not a code smell. It means the author thought about the boundary conditions.
+
+---
+
+## Lens Application in Audits
+
+When auditing a component, apply these six principles as a checklist:
+
+| Principle | Pass condition | Fail condition |
+|---|---|---|
+| P-01 Minimal API | ≤9 props; zero-config case works | ≥10 props; required props for things with defaults |
+| P-02 Composability | Slot-based composition; no style props | `backgroundColor`/`textColor` props present |
+| P-03 Defaults | Zero-prop case renders correctly | Most props required for basic usage |
+| P-04 Animation | All motion tied to state change | Decorative loops or orphaned animations present |
+| P-05 Accessibility | ARIA contract complete; keyboard navigable | `onClick` on `div`; missing `role`; no keyboard trap |
+| P-06 Edge honesty | Known limits documented with `// KNOWN:` | No documentation of failure modes |
+
+---
+
+## Wiring
+
+**design-auditor:** Apply as an optional sub-check within Pillar 7 (Micro-Polish) for component-heavy UIs. Cite principle ID (P-01 through P-06) in findings.
+
+**design-discussant:** In `--spec` mode, ask one component-authoring question per component under review: "For [ComponentName]: does the API surface expose only what consumers need, or are there configuration props that reveal implementation details?"
+
+**design-verifier:** When verifying component-library phases, include P-01 through P-06 in the must-have checklist as a component quality gate.