@hegemonart/get-design-done 1.43.0 → 1.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,14 +5,14 @@
5
5
  },
6
6
  "metadata": {
7
7
  "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). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
8
- "version": "1.43.0"
8
+ "version": "1.45.0"
9
9
  },
10
10
  "plugins": [
11
11
  {
12
12
  "name": "get-design-done",
13
13
  "source": "./",
14
14
  "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. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, 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. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
15
- "version": "1.43.0",
15
+ "version": "1.45.0",
16
16
  "author": {
17
17
  "name": "hegemonart"
18
18
  },
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "get-design-done",
3
3
  "short_name": "gdd",
4
- "version": "1.43.0",
4
+ "version": "1.45.0",
5
5
  "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. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, 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. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
6
6
  "author": {
7
7
  "name": "hegemonart",
package/CHANGELOG.md CHANGED
@@ -4,6 +4,93 @@ All notable changes to get-design-done are documented here. Versions follow [sem
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.45.0] - 2026-06-02
8
+
9
+ ### Phase 45 - Canonical Domain Reference Index
10
+
11
+ GDD has 38+ reference docs with flat indexing - agents loaded fragments by name and missed the rest, or
12
+ loaded all 5 motion files and wasted tokens. Phase 45 ships 7 navigation entry-points over the existing
13
+ content (it indexes, never re-authors). Planned and executed via the GSD pipeline (parallel research +
14
+ parallel authoring subagents). No new runtime dependency, no new egress.
15
+
16
+ ### Breaking changes
17
+
18
+ - **Two CI gates now guard the domain indexes.** `npm run check:domain-links` fails if any cross-link in
19
+ the 7 entry-points points at a missing file or anchor; `npm run check:no-duplication` fails if an index
20
+ copies large blocks from the fragment it should only link. Contributors editing the 7
21
+ `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md` entries must keep
22
+ links resolving and keep entries link-only.
23
+
24
+ ### Added
25
+
26
+ - **7 domain-index entry-points** at `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md`,
27
+ each <=300 lines: a mission, a "use this when" index of the subordinate fragments, 3-5 rules-of-thumb, and
28
+ cross-domain see-also links. `motion.md` and `typography.md` were transformed in place; the other five are new.
29
+ - **Registry `domain-index` kind**: `reference/registry.schema.json` gains the type; the 7 entries register
30
+ as `domain-index` so skills can query indexes first and drill into detail second.
31
+ - **`scripts/check-domain-cross-links.cjs`** + **`scripts/check-no-duplication.cjs`** (maintainer-only) + the
32
+ two CI steps.
33
+ - **Consumer migration**: `motion-mapper` now loads `motion.md` (the index) and drills into a fragment only
34
+ when classifying against it (an 89% token cut versus loading all four motion fragments up front);
35
+ `design-auditor` and `design-executor` lead their reference reading with the domain indexes. Token-load
36
+ baseline at `test/fixtures/baselines/phase-45/token-load.json`.
37
+
38
+ ### Notes
39
+
40
+ - 6-manifest lockstep at **v1.45.0** + `OFF_CADENCE_VERSIONS.add('1.45.0')` + 37 `manifests-version.txt`
41
+ baselines forward-propagated 1.44.0 -> 1.45.0. Tarball golden 869 -> 874 (+5 new shipped `reference/*.md`;
42
+ the two CI scripts are maintainer-only, not shipped).
43
+ - SC#9 (Phase 41 rule `references[]` migration to canonical entries) is deferred to a follow-up; the rule
44
+ links to `anti-patterns.md` still resolve, so the migration is a nice-to-have rather than a blocker.
45
+
46
+ ---
47
+
48
+ ## [1.44.0] - 2026-06-02
49
+
50
+ ### Phase 44 - Harness Capability Matrix
51
+
52
+ Verifying support for a harness used to mean reading five reference files plus the README, with no "is
53
+ this still current?" stamp anywhere. Phase 44 consolidates it into a generated `HARNESSES.md` backed by
54
+ one source of truth, with an honest status taxonomy and a freshness gate. Planned and executed via the GSD
55
+ pipeline (parallel research + pattern-mapper subagents, then parallel executor agents). No new runtime
56
+ dependency, no new egress.
57
+
58
+ ### Breaking changes
59
+
60
+ - **A harness freshness gate now runs in CI.** `npm run check:harness-freshness` warns at 60 days and
61
+ fails at 180 days for harnesses marked `tested` (others report `n/a` and never fail). A `tested` harness
62
+ whose `last_verified` stamp goes stale will fail the build until re-verified with
63
+ `npm run verify:harness <id>`. CI also gains `npm run build:harnesses:check` (HARNESSES.md drift gate)
64
+ and `npm run validate:manifest`. Contributors editing harness support must edit
65
+ `scripts/lib/manifest/harnesses.json` and regenerate `HARNESSES.md`; see `CONTRIBUTING.md`.
66
+
67
+ ### Added
68
+
69
+ - **`HARNESSES.md`** at repo root - the human-readable capability matrix (skill discovery, command syntax,
70
+ MCP, placeholder substitution, install path, status) + per-harness deep-dive links + a `Last verified`
71
+ stamp. GENERATED by `scripts/generate-harnesses-md.cjs` from the SoT; CI drift-gates it.
72
+ - **Harness matrix as a view of the Phase 41.5 SoT** - `scripts/lib/manifest/harnesses.json` records gain
73
+ a `capability_matrix` + `last_verified` + `fragment_links`; the manifest schema + `validate:manifest`
74
+ gate them. Unified with Phase 42's `harness-configs.cjs` (a `phase-44-harness-agreement` test fails on
75
+ any ID or command-syntax disagreement).
76
+ - **`scripts/lib/harness-freshness.cjs`** (shippable, pure, status-aware) + `scripts/check-harness-freshness.cjs`
77
+ (CLI) + `gdd:health` check #8 (`harness_freshness`).
78
+ - **`scripts/verify-harness.cjs <id>`** - runs the Phase 42 compile + smoke, then atomically stamps
79
+ `last_verified` and regenerates `HARNESSES.md`.
80
+ - **Honest status taxonomy** - `claude` is `tested`; the five peer-CLI runtimes (codex, gemini, cursor,
81
+ copilot, qwen) are `experimental`; the other eight are `untested`. The five reference fragments stay as
82
+ appendices, cross-linked from the matrix (a cross-link checker fails generation on a broken anchor).
83
+
84
+ ### Notes
85
+
86
+ - 6-manifest lockstep at **v1.44.0** + `OFF_CADENCE_VERSIONS.add('1.44.0')` + 37 `manifests-version.txt`
87
+ baselines forward-propagated 1.43.0 -> 1.44.0.
88
+ - `gdd_health` now returns 8 checks (harness_freshness added). The generator, freshness CLI, and verify
89
+ script are maintainer-only (not shipped); only `scripts/lib/harness-freshness.cjs` ships. Tarball golden
90
+ 868 -> 869 (+`scripts/lib/harness-freshness.cjs`). `HARNESSES.md` is repo-root, not in the npm tarball.
91
+
92
+ ---
93
+
7
94
  ## [1.43.0] - 2026-06-02
8
95
 
9
96
  ### Phase 43 - Editorial Quality Floor
package/README.md CHANGED
@@ -247,6 +247,10 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
247
247
 
248
248
  **Editorial quality floor (v1.43.0).** A tool that audits design quality should hold its own prose to the same bar. `npm run lint:prose` is a CI gate that fails on em dashes, prose double hyphens, and AI-prose tells (`load-bearing`, `leverage`, `robust`, `seamless`, ...) across the README, `SKILL.md`, `source/skills/`, `agents/`, `CHANGELOG.md`, and `reference/` (bodies and frontmatter descriptions). Fenced/inline code, HTML comments, and Cyrillic-majority files are skipped. The ruleset lives in `STYLE.md`, generated from the shared denylist at `scripts/lib/manifest/prose-denylist.json`. See `CONTRIBUTING.md`. **No new runtime dependency.**
249
249
 
250
+ **Harness capability matrix (v1.44.0).** The full per-harness support matrix (skill discovery, command syntax, MCP, install path, status) lives in **[`HARNESSES.md`](HARNESSES.md)** at the repo root, generated from `scripts/lib/manifest/harnesses.json` (the single source of truth; CI drift-gates it). Each harness carries an honest status (`tested` / `experimental` / `untested`) and a `last_verified` stamp; a freshness gate warns at 60 days and fails at 180 for `tested` harnesses, surfaced in `/gdd:health`. The 14-harness count above is the same SoT the matrix reads, so it cannot drift. The five deep-dive reference files (`reference/codex-tools.md`, `reference/gemini-tools.md`, `reference/peer-cli-capabilities.md`, `reference/peer-protocols.md`, `reference/runtime-models.md`) remain as appendices linked from the matrix. **No new runtime dependency.**
251
+
252
+ **Domain reference index (v1.45.0).** The 38+ reference docs are now navigated through 7 canonical entry-points - `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md` - each indexing its subordinate fragments with a "use this when" pointer plus a handful of rules-of-thumb. Design skills load the relevant domain index first and drill into a fragment only when needed (motion-mapper dropped roughly 89% of its up-front reference tokens this way). The indexes link, never copy: `check:domain-links` fails CI on a broken cross-link and `check:no-duplication` fails on large copy-paste. The detailed fragments stay in place as the drill-in targets. **No new runtime dependency.**
253
+
250
254
  Verify with:
251
255
 
252
256
  ```
@@ -45,6 +45,7 @@ Minimum expected files:
45
45
  - `.design/DESIGN-CONTEXT.md` - goals, brand direction, design decisions (D-XX)
46
46
  - `.design/DESIGN-PLAN.md` - planned tasks and acceptance criteria
47
47
  - `.design/tasks/` - what was actually done (glob all task files)
48
+ - **Domain-index navigation (Phase 45):** the 7 entry-points `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md` index every fragment below. For a pillar, load the relevant domain index first, then drill into the specific fragments it lists only as the pillar needs them - this is the cheap navigation layer over the detailed fragments.
48
49
  - `reference/audit-scoring.md` - existing 7-category scoring rubric (understand, do not duplicate)
49
50
  - `reference/brand-voice.md` - voice axes, archetype library, and tone-by-context table (use when auditing Pillar 1: Copy)
50
51
  - `reference/gestalt.md` - 8 Gestalt principles with scoring rubrics (use when auditing Pillar 2: Visual Hierarchy)
@@ -34,7 +34,7 @@ The orchestrating stage supplies a `<required_reading>` block in the prompt. Rea
34
34
  - `.design/STATE.md` - pipeline state (decisions, blockers, must-haves)
35
35
  - `.design/DESIGN-PLAN.md` - full task list (your task is identified by task_id)
36
36
  - `.design/DESIGN-CONTEXT.md` - brand decisions, constraints, locked choices
37
- - The reference file(s) relevant to the task type (e.g., `reference/typography.md` for a typography task)
37
+ - The reference file(s) relevant to the task type (e.g., `reference/typography.md` for a typography task). The 7 domain-index entry-points `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md` (Phase 45) are the navigation start: load the index, drill into the fragments it lists only as the task needs them.
38
38
 
39
39
  **Invariant:** read all listed files FIRST, before making any changes.
40
40
 
@@ -24,11 +24,15 @@ You inventory motion and animation patterns. Zero session memory. You do not mod
24
24
  ## Required Reading
25
25
 
26
26
  - `.design/STATE.md`
27
- - `reference/motion.md` (if present)
28
- - `reference/motion-advanced.md` (if present) - advanced patterns: spring physics, scroll-driven, FLIP, View Transitions API, gesture/drag mechanics, clip-path patterns, blur crossfades, Framer Motion hardware-accel gotcha
29
- - `reference/motion-easings.md` (if present) - 12 canonical easing presets; classify each detected easing against this catalog
30
- - `reference/motion-transition-taxonomy.md` (if present) - 8 transition families; classify page/route transitions against this taxonomy
31
- - `reference/motion-spring.md` (if present) - spring presets; classify spring configs against gentle/wobbly/stiff/slow
27
+ - `reference/motion.md` (if present) - **the motion domain-index (Phase 45): start here.** It indexes the
28
+ motion fragments below with a "use this when" pointer for each. Load a specific fragment ONLY when you
29
+ reach the classification step that needs it (drill-in), not all of them up front - this is the bulk of
30
+ the token saving (the index is ~1.7k tokens vs ~15k for all four fragments).
31
+ - Drill-in fragments (load on demand, per the index in `motion.md`):
32
+ - `reference/motion-advanced.md` - advanced patterns: spring physics, scroll-driven, FLIP, View Transitions API, gesture/drag mechanics, clip-path patterns, blur crossfades, Framer Motion hardware-accel gotcha
33
+ - `reference/motion-easings.md` - 12 canonical easing presets; classify each detected easing against this catalog
34
+ - `reference/motion-transition-taxonomy.md` - 8 transition families; classify page/route transitions against this taxonomy
35
+ - `reference/motion-spring.md` - spring presets; classify spring configs against gentle/wobbly/stiff/slow
32
36
  - Any files supplied by the orchestrator
33
37
 
34
38
  ## Scan Strategy
@@ -67,7 +67,7 @@ Token PRESENCE only is detected (D-10) - the token value is never read, logged,
67
67
 
68
68
  The `gdd_health` MCP surface also reports a `skill_discipline` check (Phase 32) confirming the using-gdd SessionStart bootstrap is live - detail is one of three exact strings:
69
69
  - `skill-discipline: ready` - `skills/using-gdd/SKILL.md` exists AND `hooks/hooks.json` SessionStart wires `inject-using-gdd.sh` (status `ok`).
70
- - `skill-discipline: missing using-gdd` (skill absent) or `skill-discipline: hook not wired` (skill present, no SessionStart inject) - both `warn`.
70
+ - `skill-discipline: missing using-gdd` (skill absent) or `skill-discipline: hook not wired` (skill present, no SessionStart inject) - both `warn`. The MCP surface also reports a `harness_freshness` check (Phase 44): per-harness `last_verified` age, status-aware (only `tested` harnesses warn at 60d / fail at 180d; others `n/a`). Full taxonomy in `HARNESSES.md`; refresh with `npm run verify:harness <id>`.
71
71
 
72
72
  ## Check MCP registration (gdd-mcp)
73
73
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hegemonart/get-design-done",
3
- "version": "1.43.0",
3
+ "version": "1.45.0",
4
4
  "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
5
5
  "author": "Hegemon",
6
6
  "homepage": "https://github.com/hegemonart/get-design-done",
@@ -65,6 +65,12 @@
65
65
  "lint:design": "node bin/gdd-detect test/fixtures/detect/negative --json",
66
66
  "build:style": "node scripts/generate-style-md.cjs",
67
67
  "build:style:check": "node scripts/generate-style-md.cjs --check",
68
+ "build:harnesses": "node scripts/generate-harnesses-md.cjs",
69
+ "build:harnesses:check": "node scripts/generate-harnesses-md.cjs --check",
70
+ "check:harness-freshness": "node scripts/check-harness-freshness.cjs",
71
+ "verify:harness": "node scripts/verify-harness.cjs",
72
+ "check:domain-links": "node scripts/check-domain-cross-links.cjs",
73
+ "check:no-duplication": "node scripts/check-no-duplication.cjs",
68
74
  "sync:rule-catalogue": "node scripts/sync-rule-catalogue.cjs --check",
69
75
  "validate:manifest": "node scripts/validate-manifest.cjs --check",
70
76
  "validate:schemas": "node --experimental-strip-types scripts/validate-schemas.ts",
@@ -0,0 +1,34 @@
1
+ # Color - Palette, Contrast, and Aesthetic Direction
2
+
3
+ Color governs how palettes are constructed, how semantic color roles are assigned, how
4
+ contrast compliance is verified, and how the aesthetic style direction is confirmed.
5
+ Read `color-theory.md` when building a new palette from scratch. Read `palette-catalog.md`
6
+ when adopting an industry-vertical baseline. Read `contrast-advanced.md` for APCA
7
+ thresholds on thin or colored text. Read `style-vocabulary.md` to confirm whether an
8
+ aesthetic style's color requirements fit the product type. Does not cover type sizing for
9
+ legibility (see `typography.md`) or dark-mode implementation steps beyond OKLCH token
10
+ generation (see `color-theory.md`).
11
+
12
+ ## Fragment Index
13
+
14
+ | Fragment | When to load |
15
+ |---|---|
16
+ | [`./color-theory.md`](./color-theory.md) | constructing a palette, choosing a color space, building OKLCH harmonies, animating color, auditing under color-blindness simulation |
17
+ | [`./palette-catalog.md`](./palette-catalog.md) | adopting a pre-built industry-vertical palette as a baseline token set (40+ verticals, WCAG-verified) |
18
+ | [`./contrast-advanced.md`](./contrast-advanced.md) | computing text/UI contrast beyond WCAG 2.1 AA - especially for thin, large, or colored text where WCAG 2.1 misranks |
19
+ | [`./style-vocabulary.md`](./style-vocabulary.md) | confirming a UI aesthetic direction: does the style require dark mode, what are its signature color effects, which product types should avoid it |
20
+
21
+ ## Rules of Thumb
22
+
23
+ 1. Author new palette tokens in OKLCH, not HSL or hex. OKLCH ΔL/ΔC/Δh steps are perceptually uniform - equal numeric jumps produce equal perceived brightness jumps. HSL's lightness channel is not perceptual.
24
+ 2. Never rely on color alone to convey state (error, warning, success). Always pair with an icon, label, or pattern - WCAG 1.4.1.
25
+ 3. For the APCA dual-target pattern: meet WCAG 2.1 AA (4.5:1 for body text) AND check Lc 60 (APCA) for thin weights and colored backgrounds. The two systems can disagree on the same pair.
26
+ 4. Check every palette under deutan (most common), protan, and tritan simulations before shipping. The color-blindness palettes in `color-theory.md` provide pre-vetted swap sets.
27
+
28
+ ## See Also
29
+
30
+ - Typography legibility at small sizes: [`./typography.md`](./typography.md)
31
+ - OKLCH interpolation in color animations: [`./motion.md`](./motion.md)
32
+ - Spatial depth via shadow and elevation: [`./spatial.md`](./spatial.md)
33
+ - Healthcare: critical-value flags not color-only: [`./domains/healthcare-patterns.md`](./domains/healthcare-patterns.md)
34
+ - Finance: gain/loss color rules: [`./domains/finance-patterns.md`](./domains/finance-patterns.md)
@@ -0,0 +1,48 @@
1
+ # Interaction - Domain Index
2
+
3
+ This domain covers how users trigger, navigate, and recover from actions: accessibility requirements, component API quality, form patterns, information architecture, onboarding, and the emotional layer.
4
+
5
+ <!-- Phase 45 domain-index: loads this file instead of individual interaction fragments -->
6
+
7
+ ---
8
+
9
+ ## Mission
10
+
11
+ Interaction is the broadest design domain. It governs every point where a user acts on the interface and the interface responds. Load only the specific fragment for the task at hand using the index below. Does not cover visual placement of interactive elements (see `spatial.md`) or copy for UI elements (see `ux-writing.md`).
12
+
13
+ ---
14
+
15
+ ## Fragment Index
16
+
17
+ | Fragment | When to load |
18
+ |---|---|
19
+ | `./accessibility.md` | WCAG 2.1 AA thresholds, keyboard navigation, focus management, ARIA roles. Required for every interactive surface without exception. |
20
+ | `./component-authoring.md` | Designing or reviewing component APIs: P-01 Minimal API through P-06 Edge Honesty, composability, defaults, animation-as-state |
21
+ | `./form-patterns.md` | Forms are in scope: label position, validation timing, autofill tokens, password UX, CAPTCHA ethics |
22
+ | `./information-architecture.md` | Navigation structure is in scope: hub-and-spoke, faceted nav, card sort benchmarks, wayfinding |
23
+ | `./onboarding-progressive-disclosure.md` | First-run experience is in scope: empty-state patterns, product tours, checklist onboarding, Aha-moment mapping |
24
+ | `./emotional-design.md` | Holistic quality overlay after pillar scoring: Norman visceral/behavioral/reflective three-level lens |
25
+ | `./components/README.md` | Auditing a specific component against benchmark: entry to 38 spec files (accordion through tree) |
26
+
27
+ ---
28
+
29
+ ## Rules of Thumb
30
+
31
+ 1. Accessibility is not a final checklist - build it in from the start. Every interactive component begins with the WAI-ARIA contract from `accessibility.md`, not a retrofit after design is complete.
32
+ 2. P-01 Minimal API from `component-authoring.md`: a component's API surface is its test surface. Every prop that can be removed should be removed.
33
+ 3. Form label position: top-aligned is the default for all but settings-page scan forms. Placeholder-as-label is a WCAG 1.3.5 failure on any form with more than 3 fields.
34
+ 4. Empty-state onboarding outperforms product tours by completion rate for creation tools. Only use a tour when unfamiliar terminology requires context, and cap it at 5 steps.
35
+ 5. The emotional design lens applies after technical and usability requirements are met. Visceral quality (appearance) and behavioral quality (task flow) both need to be solid before reflective quality (brand meaning) is addressed.
36
+
37
+ ---
38
+
39
+ ## Cross-Domain See Also
40
+
41
+ - Gesture animation and animation-as-state: `reference/motion.md`
42
+ - Spatial grouping informs IA mental models: `reference/spatial.md`
43
+ - Touch target sizing differs by platform: `reference/responsive.md`
44
+ - Error message copy and empty-state copy: `reference/ux-writing.md`
45
+ - Healthcare form patterns (PHI isolation): `reference/domains/healthcare-patterns.md`
46
+ - Civic one-thing-per-page forms: `reference/domains/civic-patterns.md`
47
+ - Typography: `reference/typography.md`
48
+ - Color: `reference/color.md`