@hegemonart/get-design-done 1.19.5 → 1.19.6

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.19.5"
+    "version": "1.19.6"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Ships 35-component benchmark corpus with pipeline integration (auditor conformance, executor pre-flight, doc-writer scaffold, pattern-mapper convergence). Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary, platform design patterns (iOS/Android/web/visionOS), RTL/CJK/cultural adaptations, IA catalog, form UX patterns, data-visualization matrix, and user-research methodology, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression.",
-      "version": "1.19.5",
+      "version": "1.19.6",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.19.5",
+  "version": "1.19.6",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Ships 35-component benchmark corpus (Waves 1–5) with pipeline integration: auditor conformance scoring, executor spec pre-flight, doc-writer scaffold, pattern-mapper convergence detector. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary (RN MIT easings/spring/interpolate + hyperframes transition taxonomy), platform design patterns (iOS/Android/web/visionOS), RTL/CJK/cultural adaptations, information architecture catalog, form UX patterns (Wroblewski label research), data-visualization matrix (25 chart types, Okabe-Ito palette), and user-research methodology, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.19.6] — 2026-04-24
+
+### Added — Design Philosophy Layer
+
+Adds a generative reasoning spine on top of the defensive (anti-patterns) and descriptive (heuristics) layers. Purely additive knowledge + lens integration — no new agents, skills, or commands.
+
+**New `reference/first-principles.md`:** 3-invariant framework (body / attention / memory) with grep-able principle→code pairs and a reducibility test for every design element. Wired into `design-discussant` as Step 0.5 — three invariant questions prepended to the brief-stage interview; answers recorded as `[Invariant]` D-XX decisions in STATE.md.
+
+**New `reference/emotional-design.md`:** Don Norman's visceral / behavioral / reflective three-level framework as a cross-cutting scoring lens. Per-level scoring rubrics (1–4) and a cross-level conflict table. Wired into `design-auditor` (Step 4.5 Emotional Design Overlay appended to DESIGN-AUDIT.md) and `design-reflector` (visceral/behavioral divergence check in Section 1).
+
+**New `reference/component-authoring.md`:** Emil Kowalski / Sonner 6-principle component quality standard — P-01 Minimal API, P-02 Composability, P-03 Defaults, P-04 Animation as State, P-05 Accessibility First, P-06 Edge Honesty — with grep-able audit signals and an ARIA contract table by component type. Wired into design-auditor (Pillar 7 sub-check), design-discussant (`--spec` mode question), and design-verifier must-have checklist.
+
+**`reference/heuristics.md` extended:** Added Peak-End Rule, Loss Aversion, Cognitive Load Theory (intrinsic / extraneous / germane), Aesthetic-Usability Effect, Doherty Threshold (400ms), and Flow (Csikszentmihalyi) — completing the psychology foundations layer.
+
+**`reference/motion-advanced.md`:** Disney's 12 Principles UX mapping stub replaced with full authoring — all 12 principles translated to interface motion with code examples (Squash and Stretch, Anticipation, Staging, Straight Ahead vs Pose to Pose, Follow Through, Slow In/Slow Out, Arcs, Secondary Action, Timing, Exaggeration, Solid Drawing, Appeal).
+
+**`reference/checklists.md`:** Added Rams Lens (10 questions mapping Dieter Rams's principles) and Sonner / Component-Authoring Lens (6 P-0N questions) as post-audit self-checks.
+
+**`reference/shared-preamble.md`:** Added Design Philosophy Layer block pointing to the three new reference files — ensures all agents are aware of the philosophy spine.
+
+**`reference/authority-feeds.md`:** Added `jnd.org` (Don Norman) and `vitsoe.com` (Dieter Rams / Vitsœ) as named-practitioner feeds. Feed count: 26 → 28.
+
+**`design-auditor`:** Required reading expanded with `reference/emotional-design.md` and `reference/component-authoring.md`. Step 4.5 (Emotional Design Overlay) added to execution steps.
+
+**`design-discussant`:** Step 0.5 (First-Principles Invariants) prepends three invariant questions during brief/discover stage.
+
+**`design-reflector`:** Section 1 extended with four principles-check prompts: reducibility, memory-load, peak-end, and error-redemption.
+
+---
+
 ## [1.19.5] — 2026-04-24
 
 ### Added — Cross-Cycle Memory: Recall, Checkpoints, Experience Archive

package/agents/design-auditor.md

@@ -62,6 +62,8 @@ Minimum expected files:
 - `reference/data-visualization.md` — chart-choice matrix, color-blind palettes, axis conventions (use for chart-heavy projects)
 - `reference/rtl-cjk-cultural.md` — RTL mirroring, CJK typography, cultural color meanings (use when i18n or multi-locale is in scope)
 - `reference/information-architecture.md` — nav pattern catalog, menu-depth rules, wayfinding (use when nav structure is in scope)
+- `reference/emotional-design.md` — Norman's visceral/behavioral/reflective cross-cutting lens; apply after pillar scoring as an informational overlay (see Emotional Design Overlay section below)
+- `reference/component-authoring.md` (if present) — Kowalski/Sonner P-01–P-06 principles; apply as sub-check within Pillar 7 (Micro-Polish) for component-heavy UIs
 
 ---
 
@@ -334,6 +336,16 @@ For each of the 7 pillars:
 
 Write `.design/DESIGN-AUDIT.md` using the output format below.
 
+### Step 4.5: Emotional Design Overlay
+
+After pillar scoring, apply the three-level lens from `reference/emotional-design.md`:
+
+1. **Visceral** — map Pillar 3 (Color) + Pillar 2 (Visual Hierarchy) → does the aesthetic surface convey the intended emotional register within 3 seconds?
+2. **Behavioral** — map Pillar 6 (Experience Design) + H-01/H-09 signals → does feedback arrive within 400ms? Are errors human-readable?
+3. **Reflective** — is there a designed peak moment in the primary flow? Does brand voice carry through to empty states?
+
+Emit a `## Emotional Design Overlay` section in DESIGN-AUDIT.md (informational; does not affect /28 score). Flag any cross-level conflict (e.g., high behavioral + low visceral) as a priority finding.
+
 ### Step 5: Emit Completion Marker
 
 After writing the file, emit `## AUDIT COMPLETE` as the final line of the response.

package/agents/design-discussant.md

@@ -32,6 +32,20 @@ The spawning prompt supplies `<required_reading>`. Read every listed file before
 
 If `<connections>` in STATE.md shows `figma: available`, read the `prefix=` field on that line (call it `{P}`). Then `ToolSearch({ query: "figma get_variable_defs", max_results: 5 })` and call `{P}get_variable_defs`. For each returned variable, draft a *tentative* D-XX decision (mark "tentative — confirm with user"). Silently skip on any error. Do NOT grep the codebase.
 
+## Step 0.5 — First-Principles Invariants (brief stage only)
+
+If `<stage>` in the spawning prompt is `brief` or `discover`, prepend these three invariant questions **before** the main design interview. Record answers as D-XX decisions prefixed `[Invariant]` in STATE.md.
+
+Read `reference/first-principles.md` before asking. Questions to ask (one at a time, using `AskUserQuestion`):
+
+1. **Body invariant** — "Are there accessibility requirements for motor-impaired users, or will this be used primarily on mobile devices? (This affects minimum touch target sizes and input method assumptions.)"
+2. **Attention invariant** — "What is the single most important action a user should take on the primary screen? (This will be the only element styled as a primary action.)"
+3. **Memory invariant** — "Are there any multi-step flows where users must carry information from one screen to the next? (This determines whether we need progress indicators or inline context cues.)"
+
+After recording all three answers, apply the **Reducibility Test** framing: note in STATE.md which design elements are invariant-justified (body/attention/memory) and which are decorative.
+
+Skip this step if: `<stage>` is not `brief`/`discover`, if `<mode>` is `--from-handoff` (handoff decisions already encode invariants), or if D-XX decisions prefixed `[Invariant]` already exist in STATE.md.
+
 ## Step 1 — Mode dispatch
 
 Inspect the orchestrator prompt for `<mode>`:

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.19.5",
+  "version": "1.19.6",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -89,7 +89,16 @@
     "experience-archive",
     "recall",
     "relevance-counter",
-    "record-contract"
+    "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.

package/reference/emotional-design.md

@@ -0,0 +1,124 @@
+# Emotional Design — Norman's Three Levels
+
+Source: Don Norman, *Emotional Design: Why We Love (or Hate) Everyday Things* (2004). See also: `jnd.org`.
+
+Use this file as a **cross-cutting scoring lens** in design audits and reflections. The three levels apply simultaneously to every design decision — they are not sequential stages.
+
+---
+
+## The Three Levels
+
+### Visceral Level
+
+> The immediate, pre-cognitive, automatic reaction to sensory input.
+
+The visceral level operates before the user thinks. It is driven by appearance, proportion, colour, texture — the aesthetic surface. A user who says "I don't know why, but this feels cheap" is responding at the visceral level.
+
+**What it governs:**
+- First impression within 50ms of page load (aesthetic-usability effect)
+- Color palettes and their emotional valence
+- Typography weight, roundness, and whitespace generosity
+- Illustration style, photography tone, iconography personality
+- Whether motion feels fluid or mechanical
+
+**Audit signals:**
+- Does the visual system convey the intended emotional register within 3 seconds?
+- Are there conflicting visceral signals? (e.g., playful illustration + harsh red error banners)
+- Does the `style-vocabulary.md` aesthetic type match the product's emotional promise?
+
+**Scoring rubric (visceral):**
+
+| Score | Evidence |
+|---|---|
+| 4 | Emotional register clear within 3s; no conflicting signals; references a named design authority |
+| 3 | Clear emotional intent; 1–2 minor conflicts (e.g., one off-brand icon) |
+| 2 | Ambiguous emotional register; mixed signals across surfaces |
+| 1 | No discernible emotional intent; generic or template appearance |
+
+---
+
+### Behavioral Level
+
+> The experience of use — whether actions feel controllable, predictable, and rewarding.
+
+The behavioral level is what UX heuristics primarily address. It covers usability, feedback, error recovery, and responsiveness. A user who says "This is frustrating to use" is responding at the behavioral level.
+
+**What it governs:**
+- Interaction feedback (loading states, error messages, success confirmations)
+- Control and reversibility (undo, cancel, back navigation)
+- Response latency — the Doherty Threshold: feedback within 400ms
+- Error prevention and recovery
+- Learnability and consistency across screens
+
+**Audit signals:**
+- Can the user always tell what the system is doing? (H-01 Visibility)
+- Are errors expressed as human problems with solutions? (H-09 Error Recovery)
+- Is every action reversible within 5 seconds?
+- Does the system respond within 400ms (Doherty Threshold)?
+
+**Scoring rubric (behavioral):**
+
+| Score | Evidence |
+|---|---|
+| 4 | All states visible; errors human + actionable; Doherty Threshold met; all destructive actions reversible |
+| 3 | Most states covered; 1–2 feedback gaps that don't block task completion |
+| 2 | Notable feedback gaps; some irreversible actions without warning |
+| 1 | System status invisible; errors developer-facing; no undo for destructive actions |
+
+---
+
+### Reflective Level
+
+> The conscious, post-use evaluation — meaning, narrative, and self-image.
+
+The reflective level is where brand identity, storytelling, and pride of ownership live. A user who says "I love showing this tool to colleagues" is responding at the reflective level. This level takes the longest to build and the longest to repair when damaged.
+
+**What it governs:**
+- Whether the product aligns with the user's self-image
+- Brand narrative consistency across all touchpoints
+- Delight and surprise moments — not gimmicks; earned moments
+- The **Peak** moment in the Peak-End Rule: the highest positive moment in the flow
+- Long-term loyalty and word-of-mouth referral
+
+**Audit signals:**
+- Is there an identifiable "peak" moment in the primary user flow?
+- Does the brand voice (from `brand-voice.md`) carry through to microcopy and empty states?
+- Is there a designed completion state that communicates personality?
+- Does the product give users a story to tell? (e.g., a completion screen, an achievement, a shareable output)
+
+**Scoring rubric (reflective):**
+
+| Score | Evidence |
+|---|---|
+| 4 | Identifiable designed peak moment; brand voice consistent from entry to completion; users have a story to tell |
+| 3 | Brand voice present in most surfaces; peak moment implicit but not deliberately designed |
+| 2 | Brand voice inconsistent; no designed peak; product is functional but forgettable |
+| 1 | Generic experience; no emotional arc; could be any product in the category |
+
+---
+
+## Cross-Cutting Lens Application
+
+Apply this lens as a **secondary overlay** after scoring the primary audit pillars. For each of the three levels:
+
+1. Identify 1–2 evidence items from the primary audit (e.g., Pillar 3 Color → Visceral Level)
+2. Note conflicts between levels (e.g., Behavioral score 4 but Visceral score 1 = technically functional but aesthetically repellent)
+3. Flag the weakest level as the highest-leverage improvement opportunity
+
+**Common cross-level conflict patterns:**
+
+| Conflict pattern | Diagnosis | Remedy |
+|---|---|---|
+| High behavioral, low visceral | Technically usable but aesthetically generic | Audit against `style-vocabulary.md`; commit to a stronger aesthetic type |
+| High visceral, low behavioral | Beautiful but broken | Fix H-01, H-09 violations first — UX before aesthetics |
+| High visceral + behavioral, low reflective | Polished but forgettable | Design a peak moment; review `brand-voice.md` emotional arc |
+
+---
+
+## Wiring
+
+**design-auditor:** After pillar scoring, apply emotional-design lens as a cross-cutting overlay. Add `## Emotional Design Overlay` section to `DESIGN-AUDIT.md` with scores for all three levels and any cross-level conflict notes.
+
+**design-reflector:** In Section 1 (What Surprised Us), flag if visceral vs behavioral scores diverge by ≥2 points — this is a leading indicator of the "beautiful but broken" pattern.
+
+**design-discussant:** In `--spec` mode, include one reflective-level confidence-scored question: "What story does this product help the user tell about themselves?"

package/reference/first-principles.md

@@ -0,0 +1,89 @@
+# First Principles — Invariant Design Constraints
+
+> These are the three invariants that no design decision can override. They are facts about human biology and cognition, not preferences or conventions. Every design choice is downstream of these three constraints.
+
+Use during the brief/discover stage (`design-discussant`) as a sanity check: does the proposed direction respect all three invariants? Use during verify as a reducibility check: can each element be removed without breaking the user's ability to complete their goal?
+
+---
+
+## Invariant 1: Body
+
+The user has a physical body with physiological limits. No amount of design skill overrides human motor physiology.
+
+**Principle → Code pairs:**
+
+| Principle | Code Pattern |
+|---|---|
+| Touch targets must accommodate tremor and fat-finger error | `min-h-[44px] min-w-[44px]` on all interactive elements |
+| Precision degrades with distance (Fitts's Law) | Destructive actions separated from primary actions by ≥24px or significantly smaller |
+| Scroll fatigue is real | Sticky headers + back-to-top anchor for content > 3 viewport heights |
+| Physical feedback confirms action | `scale(0.96)` press feedback on all clickable surfaces |
+| Eye strain limits reading distance | Body text ≥16px; line-length 60–75ch |
+
+**Reducibility check:** Can the user complete this task without a mouse? Without a precise pointer? On a 4-inch screen in a moving vehicle?
+
+---
+
+## Invariant 2: Attention
+
+Attention is finite and non-renewable per unit of time. Every element on screen competes for the same fixed budget.
+
+**Principle → Code pairs:**
+
+| Principle | Code Pattern |
+|---|---|
+| Attention capacity: 5–9 items (Miller's Law) | Navigation: ≤7 top-level items; dropdown > 7 items gets search |
+| Decision cost grows with choice count (Hick's Law) | Pricing: ≤3 tiers; feature lists: ≤4 items per group |
+| One primary action per screen | Single `.btn-primary` per viewport; all others `.btn-secondary` or `.btn-ghost` |
+| Animation hijacks attention | Motion only on state change; no decorative looping animations |
+| Progressive disclosure reduces overload | Advanced options behind disclosure trigger, not visible by default |
+
+**Reducibility check:** If you removed 30% of the elements on this screen, would task completion rate drop? If not, remove them.
+
+---
+
+## Invariant 3: Memory
+
+Working memory holds approximately 7 items and degrades rapidly within seconds. Design that requires users to remember things between screens fails.
+
+**Principle → Code pairs:**
+
+| Principle | Code Pattern |
+|---|---|
+| Recognition over recall (H-06) | Visible navigation labels, not icon-only; breadcrumbs on deep paths |
+| Context must be preserved | Multi-step forms: prior-step summary visible; form state not cleared on back-navigate |
+| Error memory fades fast | Inline validation: errors adjacent to the field that caused them |
+| Completion status reduces anxiety | Progress indicators: `Step 2 of 4`; Zeigarnik Effect — show percentage done |
+| Last action should be reversible | Undo available for destructive/irreversible actions within 5 seconds |
+
+**Reducibility check:** Does this screen require the user to remember something from a previous screen? If yes, surface that context inline.
+
+---
+
+## The Reducibility Test
+
+For any proposed design element, apply in order:
+
+1. **Body test** — Is this element reachable by a person with limited motor precision on a small screen?
+2. **Attention test** — Does this element earn its place by directly supporting the primary task?
+3. **Memory test** — Does this element surface context the user would otherwise need to remember?
+
+If an element fails all three tests, it is purely decorative. Decorative elements are not forbidden — but they are not invariant-justified, and they are the first candidates for removal when performance or clarity is at risk.
+
+---
+
+## Wiring to Design Discussant
+
+When `design-discussant` runs the brief stage, it prepends this invariants question before the main interview:
+
+> "Before we discuss the design direction, let me confirm three constraints: (1) Are there any accessibility requirements for motor-impaired users? (2) Is the primary use case on mobile or desktop — or both? (3) Are there any multi-step flows where the user must carry context between screens?"
+
+Answers are recorded as D-XX decisions prefixed `[Invariant]` in STATE.md.
+
+---
+
+## Relationship to Other References
+
+- `reference/heuristics.md` — H-01 through H-10 are the behavioral-level expression of Invariants 2 and 3
+- `reference/emotional-design.md` — Invariant 1 (Body) maps to the Visceral level; Invariants 2–3 map to the Behavioral level
+- `reference/component-authoring.md` — P-01 through P-06 are the component-level expression of all three invariants

package/reference/heuristics.md

@@ -181,6 +181,76 @@ People **remember incomplete tasks** better than completed ones. Implications:
 
 ---
 
+## Peak-End Rule
+
+Users judge an experience primarily by how it felt at its most intense moment (the **peak**) and how it ended — not by the average across the whole session. Implications:
+- Design a deliberate positive peak in every primary flow (e.g., a celebratory completion screen, an instant result, a delightful empty state).
+- The **end state** of a flow matters disproportionately: the last screen the user sees shapes their memory of the whole interaction.
+- Reduce negative peaks first (error states, loading hangs) — they weigh heavier than neutral moments.
+- A long frustrating form followed by a satisfying completion screen is remembered more positively than a mildly annoying end to an otherwise smooth flow.
+
+---
+
+## Loss Aversion
+
+Users feel the pain of loss approximately **twice as strongly** as the pleasure of an equivalent gain (Kahneman & Tversky). Implications:
+- Frame CTAs around what users keep/save, not what they gain: "Don't lose your progress" over "Save your work."
+- Subscription cancellation flows that show what the user will lose (features, data, streak) leverage loss aversion ethically to reduce churn — but only if the stated losses are real.
+- Free trial countdowns ("3 days left") trigger loss aversion more effectively than benefit reminders.
+- Destructive action confirmations should name what is lost: "Delete this project and all 47 files?" not just "Are you sure?"
+
+---
+
+## Cognitive Load Theory
+
+Working memory is limited to approximately **7 ± 2 chunks** simultaneously (Miller, 1956) and degrades under conditions of stress, distraction, or novelty. Cognitive Load Theory (Sweller, 1988) distinguishes three types:
+
+| Type | Definition | Design implication |
+|---|---|---|
+| **Intrinsic** | Load inherent to the task itself (complexity of the domain) | Cannot be reduced; must be scaffolded |
+| **Extraneous** | Load imposed by poor design (navigation, unclear labels, visual noise) | Eliminate this completely |
+| **Germane** | Load that builds understanding (learning, pattern recognition) | Preserve and support |
+
+Practical rules:
+- Every element of visual noise is extraneous load — remove it.
+- New UI patterns create extraneous load (Jakob's Law); use platform conventions.
+- Chunk complex tasks into steps of ≤3 decisions each.
+- Error messages that require decoding ("Error 422") create extraneous load; plain language removes it.
+
+---
+
+## Aesthetic-Usability Effect
+
+Users perceive **aesthetically pleasing designs as more usable**, even when functionality is identical — and this perception persists through initial usability problems. Implications:
+- A polished visual appearance buys tolerance for minor UX rough edges in early releases.
+- This effect is strongest on first impression; it degrades over time as behavioral friction compounds.
+- The effect can mask genuine usability problems in user testing if participants rate overall satisfaction rather than task completion.
+- Do NOT use the aesthetic-usability effect as a reason to defer fixing usability problems — it explains tolerance, not satisfaction.
+
+---
+
+## Doherty Threshold
+
+A system that responds within **400ms** keeps users in a state of flow. Response times above 400ms cause users to shift attention, leading to a productivity drop that compounds with task complexity. Named after W.J. Doherty and R.H. Thadhani (IBM, 1982). Implications:
+- Interactive responses (button click → visible feedback) must be ≤400ms.
+- For operations > 400ms, show optimistic UI immediately and settle in the background.
+- For operations > 1000ms, use a progress indicator.
+- For operations > 10s, provide a way to continue other tasks (async notification on complete).
+- Loading spinners that appear within 400ms reduce perceived wait; those that appear late increase it.
+
+---
+
+## Flow (Csikszentmihalyi)
+
+Users enter a **flow state** when task difficulty matches their skill level exactly — high enough to engage, low enough to feel achievable. Flow is characterized by complete absorption, loss of time awareness, and intrinsic motivation. Implications:
+- Progressive difficulty: onboarding tasks should be trivially easy; expert tasks should provide just enough challenge.
+- Interruptions break flow permanently for that session; avoid modal interruptions in high-focus workflows.
+- Clear goals + immediate feedback are the two design levers for inducing flow (H-01, H-05).
+- Forms designed for flow: one question per screen, immediate validation, visible progress.
+- Notification design: distinguish ambient notifications (don't break flow) from critical interruptions (must break flow).
+
+---
+
 ## How to Score During Verification
 
 For each NNG heuristic (H-01 through H-10), rate 0–4:

package/reference/motion-advanced.md

@@ -746,9 +746,198 @@ Fresh eyes catch what in-the-moment iteration misses. Animations feel correct wh
 
 ## Disney's 12 Principles — UX Mapping
 
-<!-- STUB: Disney's 12 Principles UX mapping — Phase 19.6 will author this section -->
-<!-- Cross-reference: reference/motion-easings.md, reference/motion-spring.md -->
+Original source: Frank Thomas & Ollie Johnston, *The Illusion of Life: Disney Animation* (1981). The 12 principles were developed for hand-drawn character animation; the UX mappings below translate each to interface motion.
 
-*This section is reserved for Phase 19.6 (Design Philosophy Layer). A full UX mapping of all 12 principles will be authored there and this stub will be replaced.*
+---
+
+### 1. Squash and Stretch
+
+**Animation:** Objects deform under force — squash on impact, stretch during fast movement.
+
+**UX mapping:** Scale feedback communicates physical weight and responsiveness.
+```tsx
+// Press: squash slightly (wider, shorter)
+// Release: snap back through scale(1.05) → scale(1)
+<motion.button
+  whileTap={{ scaleX: 1.05, scaleY: 0.95 }}
+  transition={{ type: "spring", stiffness: 500, damping: 30 }}
+/>
+```
+**Rule:** Constrain squash/stretch to ≤5% deviation — more reads as glitchy, not physical.
+
+---
+
+### 2. Anticipation
+
+**Animation:** A small preparatory motion before the main action (e.g., a character bending knees before jumping).
+
+**UX mapping:** Preview animations prime the user for what's about to happen.
+```tsx
+// Drawer that "breathes" slightly before opening
+<motion.div
+  animate={isOpen ? { x: 0 } : { x: -8 }}
+  initial={{ x: -8 }}
+  transition={{ type: "spring", stiffness: 300, damping: 24 }}
+/>
+```
+**Rule:** Anticipation delays should be ≤80ms; longer delays read as lag, not anticipation.
+
+---
+
+### 3. Staging
+
+**Animation:** Present one idea at a time; the primary action draws the eye; secondary elements are subordinate.
+
+**UX mapping:** One primary motion per state change. All other motion is either absent or staggered to follow.
+- Never animate two elements of equal visual weight simultaneously
+- Use stagger to create a reading order for entering content
+- The element the user acted on should move first
+
+---
+
+### 4. Straight Ahead vs Pose to Pose
+
+**Animation:** Straight-ahead: draw each frame in sequence. Pose-to-pose: define key positions and interpolate.
+
+**UX mapping:** All CSS transitions and spring animations are pose-to-pose by definition — you define start and end states. This means:
+- Transitions retarget smoothly when interrupted (see CSS Transitions vs Keyframes section above)
+- The in-between frames are computed by the engine, not designed
+- Design the **poses** (states) carefully; the interpolation handles itself
+
+---
+
+### 5. Follow Through and Overlapping Action
+
+**Animation:** Parts of an object continue moving after the main action stops; related elements finish at slightly different times.
+
+**UX mapping:** Stagger exit animations and let secondary elements settle slightly after primary.
+```tsx
+// List exit: items stagger out with slight delay between each
+const container = {
+  exit: { transition: { staggerChildren: 0.04, staggerDirection: -1 } },
+};
+const item = {
+  exit: { opacity: 0, y: -8, transition: { duration: 0.2 } },
+};
+```
+**Rule:** Follow-through delay ≤60ms per level. Beyond this, the UI feels sluggish.
+
+---
+
+### 6. Slow In and Slow Out
+
+**Animation:** Objects accelerate from rest and decelerate to a stop; they are never at constant velocity.
+
+**UX mapping:** Never use `linear` easing for UI transitions. Always use a curve that starts slow, speeds up, and decelerates.
+```css
+/* The standard Material/web ease — correct for most UI */
+transition: transform 0.24s cubic-bezier(0.4, 0, 0.2, 1);
+
+/* Enter (slow in) */
+transition: transform 0.24s cubic-bezier(0, 0, 0.2, 1);
+
+/* Exit (slow out) */
+transition: transform 0.2s cubic-bezier(0.4, 0, 1, 1);
+```
+**Rule:** `linear` easing is only valid for: scroll-driven animations tied to position, and progress bar fills.
+
+---
+
+### 7. Arcs
+
+**Animation:** Objects in the real world move in slight arcs, not straight lines.
+
+**UX mapping:** For spatial transitions (element moving from one position to another), a slight arc feels more natural than a straight-line translate. Achieved by animating both axes with slightly different timing:
+```tsx
+<motion.div
+  initial={{ x: -40, y: 10, opacity: 0 }}
+  animate={{ x: 0, y: 0, opacity: 1 }}
+  transition={{
+    x: { type: "spring", stiffness: 300, damping: 28 },
+    y: { type: "spring", stiffness: 300, damping: 28, delay: 0.04 },
+    opacity: { duration: 0.2 },
+  }}
+/>
+```
+**Rule:** Arcs apply only to spatial motion. Opacity, scale, and color changes do not arc.
+
+---
+
+### 8. Secondary Action
+
+**Animation:** A supporting action that reinforces the primary one (e.g., a character's hair bouncing while they walk).
+
+**UX mapping:** A small supplementary animation that confirms and amplifies the main interaction.
+- Toast notification: icon pulses briefly after the toast appears (secondary action confirming the event)
+- Success state: checkmark draws itself after the confirmation color appears
+- Delete: item fades + the list count badge decrements with a small number-flip animation
+
+**Rule:** Secondary actions must complete before or simultaneously with the primary — never after. They reinforce, not extend.
+
+---
+
+### 9. Timing
+
+**Animation:** Duration communicates physical weight. Fast = light and snappy. Slow = heavy and significant.
+
+**UX mapping:**
+
+| Duration | Use for |
+|---|---|
+| 80–120ms | Micro-interactions: hover states, active states, icon swaps |
+| 150–200ms | Standard component transitions: dropdowns, tooltips, toasts |
+| 220–300ms | Page-level state changes, drawer open/close, modal appear |
+| 300–500ms | Full-page route transitions |
+| > 500ms | Reserved for intentionally cinematic moments only |
+
+**Rule:** Match duration to the visual weight of the element. A small icon swap at 300ms feels lethargic; a full-page transition at 80ms feels jarring.
+
+---
+
+### 10. Exaggeration
+
+**Animation:** Push key poses slightly beyond reality for emphasis and clarity.
+
+**UX mapping:** Slight overshoot in spring animations communicates energy and intention.
+```tsx
+// Slight overshoot via underdamped spring — not bouncy, but alive
+<motion.div
+  animate={{ scale: 1 }}
+  transition={{ type: "spring", stiffness: 400, damping: 22, mass: 0.8 }}
+/>
+// Peak scale ≈ 1.03–1.05 before settling — imperceptible consciously, felt physically
+```
+**Rule:** Exaggeration in UI should be invisible when you're looking for it. If users notice the bounce, it's too much. Target spring `bounce` values of 0.1–0.2.
+
+---
+
+### 11. Solid Drawing
+
+**Animation:** Characters have weight, depth, and obey perspective; they feel three-dimensional.
+
+**UX mapping:** UI elements should feel visually grounded — not floating. Shadows, depth layering, and transform-origin choices communicate which layer an element lives on.
+- Drawers and sheets slide from an edge — they feel physically attached
+- Modals emerge from center or from the triggering element — they float above the page
+- Tooltips appear near the cursor — they are attached to the pointer
+- `transform-origin` must match where the element conceptually emerges from
+
+---
+
+### 12. Appeal
+
+**Animation:** Characters have a quality that makes the audience want to watch them — not necessarily cute, but interesting.
+
+**UX mapping:** Animation has personality that is consistent with the product's brand.
+
+| Product type | Animation personality |
+|---|---|
+| Financial / serious tools | Crisp, minimal, sub-150ms, no bounce |
+| Consumer apps | Warm, slightly slower, gentle ease-out |
+| Playful / creative tools | Spring physics, slight overshoot, expressive icon animations |
+| Data dashboards | Smooth, purposeful, transitions that reveal data sequentially |
+
+**Rule:** Animation personality must be decided once per product and applied consistently. Mixed personalities (snappy in one area, bouncy in another) destroy cohesion.
+
+---
 
 See also: `reference/motion-easings.md`, `reference/motion-spring.md`, `reference/framer-motion-patterns.md`

package/reference/registry.json

@@ -3,6 +3,27 @@
   "version": 1,
   "generated_at": "2026-04-24T00:00:00.000Z",
   "entries": [
+    {
+      "name": "component-authoring",
+      "path": "reference/component-authoring.md",
+      "type": "heuristic",
+      "phase": 19.6,
+      "description": "Kowalski/Sonner 6-principle component quality standard (P-01 Minimal API, P-02 Composability, P-03 Defaults, P-04 Animation as State, P-05 Accessibility First, P-06 Edge Honesty) with grep-able audit signals"
+    },
+    {
+      "name": "emotional-design",
+      "path": "reference/emotional-design.md",
+      "type": "heuristic",
+      "phase": 19.6,
+      "description": "Don Norman's visceral/behavioral/reflective three-level cross-cutting scoring lens with per-level rubrics and cross-level conflict patterns"
+    },
+    {
+      "name": "first-principles",
+      "path": "reference/first-principles.md",
+      "type": "heuristic",
+      "phase": 19.6,
+      "description": "3-invariant framework (body/attention/memory) with grep-able principle→code pairs and reducibility test; wired into design-discussant brief stage"
+    },
     {
       "name": "DEPRECATIONS",
       "path": "reference/DEPRECATIONS.md",

package/reference/shared-preamble.md

@@ -26,6 +26,16 @@ Do not reorder. Do not inline this preamble. Do not splice dynamic content ahead
 
 The `/gdd:warm-cache` command (ships in Plan 10.1-02) pre-warms this identical prefix in the Anthropic cache before a design sprint, so the first real agent spawn of the sprint is already a cache hit on the shared-preamble bytes. You do not need to do anything special to participate — just keep the import directive at the top of your body.
 
+## Design Philosophy Layer (Phase 19.6)
+
+The framework is anchored to three design philosophy references that agents may read during brief, audit, and verify stages:
+
+- `reference/first-principles.md` — 3-invariant framework (body, attention, memory); reducibility test for every design element
+- `reference/emotional-design.md` — Norman's visceral / behavioral / reflective cross-cutting scoring lens
+- `reference/component-authoring.md` — Kowalski/Sonner 6-principle component quality standard (P-01 through P-06)
+
+These references encode *why* the heuristics and anti-patterns exist — not rules to follow, but constraints derived from human biology and cognition. Agents that read these files apply them as lenses, not checklists.
+
 ---
 
 *Imported by: every file under `agents/*.md` (except `agents/README.md`). Maintained as part of Phase 10.1 (OPT-07) and Phase 14.5 (L0/L2 split). Edits to this file affect every agent simultaneously — verify across the full agent suite before committing.*