@hegemonart/get-design-done 1.0.7

package/reference/DEPRECATIONS.md

@@ -0,0 +1,41 @@
+# Deprecations
+
+This registry tracks renamed, split, or removed plugin concepts. Each entry names the deprecated name, the phase that deprecated it, the replacement, and a migration note.
+
+**CI enforcement:** `scripts/detect-stale-refs.cjs` scans shipped `.md` files
+for legacy tokens and fails the build on any occurrence. The scanner's pattern
+list mirrors the tokens named below. When a new deprecation lands here, update
+the scanner pattern list in lockstep.
+
+## Namespaces
+
+- **`/design:<cmd>`** → `/gdd:<cmd>` — deprecated in Phase 7 (namespace rename). All commands now use the `/gdd:` prefix. Migrated: every shipped skill invocation and agent reference now uses `/gdd:`.
+
+## Agents
+
+- **`design-context-builder`** — replaced by the Phase 3 agent split (design-context-reader + design-context-summarizer). Mentioned only in historical documentation; new work must spawn the split agents directly.
+- **`design-pattern-mapper`** (monolithic) → split into 5 domain mappers in Phase 3 (migrated):
+  - `token-mapper`
+  - `component-taxonomy-mapper`
+  - `a11y-mapper`
+  - `motion-mapper`
+  - `visual-hierarchy-mapper`
+
+  The legacy `design-pattern-mapper.md` agent is retained as a compatibility shim pending full removal in a later phase. New work should spawn the domain mappers directly.
+
+## Stages
+
+- **`scan`** (stage name) → merged/renamed into `explore` in Phase 3. Migration: references to the `scan` stage in shipped skills and agents were replaced with `explore`.
+- **`discover`** (stage name) → merged/renamed into `explore` in Phase 3. Migration: references to the `discover` stage in shipped skills and agents were replaced with `explore`.
+
+## Scanner scope
+
+`scripts/detect-stale-refs.cjs` flags these tokens (line-granular match):
+
+- `/design:<cmd>` — any occurrence of the legacy namespace
+- `design-context-builder` (standalone word)
+- `design-pattern-mapper` (when not followed by `-<suffix>`)
+- `scan/SKILL.md` and `discover/SKILL.md` path references
+
+The scanner excludes `.planning/`, `.claude/`, `.design/`, `node_modules/`,
+`test-fixture/`, and this file itself.

package/reference/STATE-TEMPLATE.md

@@ -0,0 +1,200 @@
+# `.design/STATE.md` Template
+
+This is the canonical template for the design pipeline's runtime state file.
+
+**How stages use this template:**
+- At scan stage entry, if `.design/STATE.md` does not exist, scan copies this template to `.design/STATE.md` and fills the frontmatter `started_at` and `last_checkpoint` with the current ISO 8601 timestamp.
+- Every subsequent stage (discover, plan, design, verify) reads `.design/STATE.md` at entry and updates it at completion, per the Write Contract below.
+- `.design/` is gitignored (not distributed with the plugin); only this template ships.
+
+**Distinction from `.planning/STATE.md`:**
+- `.planning/STATE.md` is GSD development state — used by the developers building this plugin.
+- `.design/STATE.md` is pipeline runtime state — used by the pipeline when it runs in a user's project.
+- Keep them strictly separate. Cross-references between them are deferred to Phase 6 per CONTEXT.md.
+
+---
+
+## Template body
+
+Copy the block below (between the `==== BEGIN TEMPLATE ====` and `==== END TEMPLATE ====` markers) to `.design/STATE.md` at scan entry.
+
+```
+==== BEGIN TEMPLATE ====
+---
+pipeline_state_version: 1.0
+stage: brief
+cycle: ""
+wave: 1
+started_at: <ISO 8601 timestamp — set once at scan entry>
+last_checkpoint: <ISO 8601 timestamp — updated at each stage exit>
+---
+
+# Pipeline State — <project name>
+
+<position>
+stage: brief
+wave: 1
+task_progress: 0/0
+status: initialized
+handoff_source: ""
+handoff_path: ""
+skipped_stages: ""
+</position>
+<!-- handoff_source: "claude-design-html" | "claude-design-bundle" | "manual" | "" (empty = normal pipeline) -->
+<!-- handoff_path: path to the handoff bundle file or directory; empty for normal pipeline runs -->
+<!-- skipped_stages: comma-separated list of stages bypassed by handoff routing (e.g., "scan, discover, plan") -->
+
+<decisions>
+<!-- Filled by discover stage. Format: -->
+<!-- D-01: [decision text] (locked | tentative) -->
+</decisions>
+
+<must_haves>
+<!-- Filled by discover stage. Format: -->
+<!-- M-01: [observable behavior description] | status: pending -->
+<!-- Valid status values: pending | pass | fail -->
+</must_haves>
+
+<connections>
+<!-- Detected at scan entry; updated if connections become available mid-pipeline. -->
+<!-- Format: <connection_name>: <available | unavailable | not_configured> -->
+figma: not_configured
+refero: not_configured
+pinterest: not_configured
+claude_design: not_configured
+</connections>
+
+<blockers>
+<!-- Active blockers preventing stage completion. -->
+<!-- Format: [stage] [ISO date]: [description] -->
+</blockers>
+
+<parallelism_decision>
+<!-- Written by each stage orchestrator after computing parallelism verdict -->
+<!-- Format:
+stage: explore
+verdict: parallel | serial
+reason: "2 mappers, disjoint Touches, savings est. 45s"
+agents: ["token-mapper", "component-taxonomy-mapper"]
+-->
+</parallelism_decision>
+
+<todos>
+<!-- Mirror of .design/TODO.md counts for quick lookup by /gdd:progress and /gdd:stats. -->
+<!-- Format:
+pending: 0
+in_progress: 0
+done: 0
+-->
+</todos>
+
+<timestamps>
+started_at: <ISO 8601>
+last_checkpoint: <ISO 8601>
+brief_completed_at: ~
+explore_completed_at: ~
+plan_completed_at: ~
+design_completed_at: ~
+verify_completed_at: ~
+</timestamps>
+==== END TEMPLATE ====
+```
+
+---
+
+## Field reference
+
+### Frontmatter
+
+| Field | Type | Set by | Purpose |
+|-------|------|--------|---------|
+| `pipeline_state_version` | float | fixed at `1.0` | Forward-compat marker for future format changes |
+| `stage` | enum | every stage at entry | Current stage — one of: `brief|explore|plan|design|verify` |
+| `cycle` | string | lifecycle commands | Cycle identifier for Wave B multi-cycle projects (default: empty string) |
+| `wave` | int | every stage | Wave number within current stage |
+| `started_at` | ISO 8601 | scan at creation | Immutable — never updated after creation |
+| `last_checkpoint` | ISO 8601 | every stage at exit | Updated on every stage transition and on mid-stage checkpoint |
+
+### `<position>`
+
+Mirrors frontmatter stage/wave plus progress and status. Duplication is intentional — frontmatter is scannable by tooling; `<position>` is scannable by prose reading.
+
+- `task_progress`: `<completed>/<total>` — e.g. `3/7` means 3 of 7 tasks in the current stage complete
+- `status`: one of
+  - `initialized` — scan just created the file, no work done
+  - `in_progress` — stage is actively running
+  - `completed` — stage finished successfully; next stage may begin
+  - `blocked` — stage cannot proceed; see `<blockers>`
+
+### `<decisions>`
+
+Discover stage populates. Each decision:
+- `D-<NN>`: sequential identifier
+- `[decision text]`: human-readable statement
+- `(locked | tentative)`: `locked` means downstream stages must honor; `tentative` means open for revision by subsequent stages
+
+### `<must_haves>`
+
+Discover stage populates with observable behaviors. Verify stage updates status.
+- `M-<NN>`: sequential identifier
+- `[description]`: testable behavior or artifact
+- `status`: `pending` (default), `pass` (verify confirmed), `fail` (verify rejected)
+
+### `<connections>`
+
+One line per external connection. Detected at scan entry via MCP availability probes.
+- `available`: MCP tool present and responding
+- `unavailable`: MCP configured but not responding (auth failure, offline, etc.)
+- `not_configured`: MCP not present in session
+
+### `<blockers>`
+
+Append-only log of active blockers. Format: `[stage] [ISO date]: [description]`. Cleared manually when blocker resolves (do not auto-clear — preserve the record).
+
+### `<timestamps>`
+
+Per-stage completion record. `~` means not yet completed. Updated at each stage's successful exit.
+
+---
+
+## Write Contract
+
+Every stage that runs in the pipeline MUST follow this contract when reading and writing `.design/STATE.md`:
+
+**At entry:**
+1. Read `.design/STATE.md`. If the file does not exist and the current stage is `scan`, create it from this template with `started_at` = now and `last_checkpoint` = now; otherwise abort with a clear error ("run scan first").
+2. Parse frontmatter `stage` and `<position>` `status`.
+3. If `stage == current_stage` and `status == in_progress`: RESUME — pick up from `task_progress` offset; do not reset progress.
+4. If `stage != current_stage`: this is a normal stage transition. Set frontmatter `stage = current_stage`, `<position>` `stage = current_stage`, `<position>` `status = in_progress`, `<position>` `task_progress = 0/<total>`.
+5. Update `<connections>` by probing each MCP tool; write the detected status.
+6. Update `last_checkpoint` to now.
+7. Write `.design/STATE.md`.
+
+**During execution (mid-stage checkpoints):**
+- After each task completes, update `<position>` `task_progress` and `last_checkpoint`. Write `.design/STATE.md`.
+- This enables resume if the stage is interrupted.
+
+**At exit (successful completion):**
+1. Set `<position>` `status = completed`.
+2. Set the corresponding `<stage>_completed_at` timestamp in `<timestamps>`.
+3. Update `last_checkpoint`.
+4. Write `.design/STATE.md`.
+
+**At exit (blocked):**
+1. Set `<position>` `status = blocked`.
+2. Append to `<blockers>`: `[<stage>] [<ISO date>]: <blocker description>`.
+3. Update `last_checkpoint`.
+4. Write `.design/STATE.md`.
+
+**Resume semantics (STATE-03):**
+- A stage re-invoked with `status == in_progress` and `stage == self` must resume from `task_progress` without re-running completed tasks.
+- The `task_progress` numerator is the ONLY source of truth for resume. Consumers must NOT infer resume point from timestamps alone.
+
+---
+
+## Notes for Phase 2 implementors
+
+- Do not add new top-level XML sections without updating this template.
+- The write contract is non-negotiable — stages that skip the read-at-entry step break resume.
+- `<decisions>` and `<must_haves>` identifiers are sequential per-project, not globally unique. A new pipeline run on the same project starts at `D-01` / `M-01`.
+- When in doubt, prefer appending new fields to existing sections over introducing new sections — preserves compatibility with `pipeline_state_version: 1.0`.

package/reference/accessibility.md

@@ -0,0 +1,190 @@
+# Accessibility — Thresholds and Requirements
+
+These are concrete, measurable standards. WCAG 2.1 AA is the minimum baseline for all design work unless the client explicitly requires AAA or specifies otherwise.
+
+---
+
+## WCAG 2.1 AA — Required Thresholds
+
+### Color Contrast
+
+| Text type | Minimum ratio (AA) | Enhanced (AAA) |
+|---|---|---|
+| Normal text (< 18pt / < 14pt bold) | **4.5 : 1** | 7 : 1 |
+| Large text (≥ 18pt or ≥ 14pt bold) | **3 : 1** | 4.5 : 1 |
+| UI components and graphical objects | **3 : 1** | — |
+| Decorative elements | No requirement | — |
+
+**Calculate contrast**: `(L1 + 0.05) / (L2 + 0.05)` where L1 is the lighter luminance.
+
+Common pitfalls:
+- Placeholder text in inputs: must meet 4.5:1 (often doesn't — gray placeholders fail)
+- Disabled state text: WCAG exempts disabled elements, but aim for ≥ 3:1 anyway
+- Link color vs body text: must be distinguishable by more than color alone (underline or 3:1 ratio vs background)
+- Focus ring color vs its background: must meet 3:1
+
+Tools: Use browser DevTools > Accessibility tab, or pass hex values through contrast calculation.
+
+### Touch Target Size
+
+| Platform | Minimum tap target |
+|---|---|
+| iOS (Apple HIG) | **44 × 44 pt** |
+| Android (Material Design) | **48 × 48 dp** |
+| Web (WCAG 2.5.5 AAA) | **44 × 44 px** |
+| Web (WCAG 2.5.8 AA — WCAG 2.2) | **24 × 24 px** (minimum, with spacing) |
+
+Recommended target: 44 × 44 px on all platforms. Never smaller for primary actions.
+
+Minimum spacing between targets: **8px** to prevent accidental taps.
+
+Use `hitSlop` in React Native to expand tap area beyond visual bounds:
+```js
+hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}
+```
+
+### Focus States
+
+All interactive elements must have a visible focus indicator.
+
+**Required for WCAG 2.4.11 (AA — WCAG 2.2):**
+- Focus indicator at minimum: **2px solid** outline, encloses the component
+- Contrast between focused and unfocused: **3:1**
+- Focus indicator doesn't overlap component content
+
+**Best practice:**
+```css
+:focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+}
+
+/* Never remove focus without replacement */
+:focus:not(:focus-visible) {
+  outline: none; /* OK — only removes keyboard focus ring for mouse users */
+}
+```
+
+Recommended focus ring: **3px solid**, `2px offset`, brand primary or `#2563eb`.
+
+### Semantic Structure
+
+- One `<h1>` per page. Headings are sequential: `h1` → `h2` → `h3` — never skip levels.
+- Interactive elements are focusable: use `<button>` for buttons, `<a href>` for links — never `<div onClick>`.
+- Form inputs have associated `<label for="id">` — not just placeholder text.
+- Images have descriptive `alt=""` for meaningful images; `alt=""` for decorative.
+- Icon-only buttons have `aria-label`: `<button aria-label="Close dialog">×</button>`.
+
+### Color Must Not Be The Only Differentiator
+
+Error states: red color + error icon + text message (not just red border).
+Required fields: asterisk (*) + visible label (not just red label).
+Charts: color + pattern/texture + direct labels.
+
+### Keyboard Navigation
+
+All functionality reachable via keyboard:
+- Tab order matches visual reading order (top-left → bottom-right)
+- Focus never trapped except in modals (where it SHOULD be trapped)
+- `Escape` closes any overlay (modal, dropdown, drawer)
+- Enter/Space activates focused button/link
+- Arrow keys navigate within component groups (radio buttons, tabs, menus)
+
+---
+
+## ARIA Patterns (Common)
+
+### Modal Dialog
+```html
+<div role="dialog" aria-modal="true" aria-labelledby="modal-title">
+  <h2 id="modal-title">Confirm Deletion</h2>
+  <!-- content -->
+  <button>Cancel</button>
+  <button>Delete</button>
+</div>
+```
+On open: move focus to first focusable element or dialog title.
+On close: return focus to the trigger element.
+
+### Live Regions
+```html
+<!-- For dynamic content updates (toasts, status messages) -->
+<div aria-live="polite" aria-atomic="true">
+  <!-- Status messages injected here -->
+</div>
+
+<!-- For urgent updates (errors) -->
+<div aria-live="assertive">
+  <!-- Error messages injected here -->
+</div>
+```
+
+### Loading States
+```html
+<button aria-disabled="true" aria-busy="true">
+  <span aria-hidden="true">⟳</span>
+  Saving...
+</button>
+```
+
+---
+
+## Responsive and Dynamic Type
+
+- Base font size: minimum **16px** on mobile (smaller = pinch-zoom for many users)
+- Honor system text scaling: don't lock font sizes in px when users have increased system font size
+- In React Native: use `Text` component which respects Dynamic Type automatically
+- In web: use `rem` units for font sizes, not `px`
+
+```css
+/* GOOD — scales with user preference */
+font-size: 1rem; /* = 16px at default, scales if user sets larger system font */
+
+/* RISKY — overrides user preference */
+font-size: 16px;
+```
+
+---
+
+## Motion Accessibility
+
+All animations must respect `prefers-reduced-motion: reduce`. See `reference/motion.md`.
+
+The `prefers-reduced-motion` check is an accessibility requirement (WCAG 2.3.3 AAA; WCAG 2.2 reduces to recommendation — but implement it regardless).
+
+---
+
+## Quick Accessibility Audit Checklist
+
+Run through this before marking any design complete:
+
+**Contrast:**
+- [ ] All body text ≥ 4.5:1 against background
+- [ ] Large text ≥ 3:1
+- [ ] UI components (inputs, buttons) ≥ 3:1
+- [ ] Placeholder text ≥ 4.5:1
+- [ ] Focus rings ≥ 3:1 against adjacent colors
+
+**Interaction:**
+- [ ] All tap targets ≥ 44×44px
+- [ ] 8px minimum gap between targets
+- [ ] Focus ring visible on all interactive elements
+- [ ] Tab order is logical
+- [ ] Escape closes overlays
+- [ ] No keyboard traps outside modals
+
+**Semantics:**
+- [ ] One h1 per page, heading hierarchy is sequential
+- [ ] All images have meaningful alt text or alt=""
+- [ ] Form labels associated with inputs
+- [ ] Icon buttons have aria-label
+- [ ] Error messages associated with fields (aria-describedby)
+- [ ] Live regions for dynamic content
+
+**Color:**
+- [ ] No color-only meaning (+ icon, pattern, or text)
+- [ ] Error states have visual indicator beyond color
+
+**Motion:**
+- [ ] prefers-reduced-motion handled
+- [ ] Auto-playing video can be paused