@hegemonart/get-design-done 1.59.3 → 1.59.5

package/scripts/skill-templates/context/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: gdd-context
+description: "Queries the typed DesignContext graph at .design/context-graph.json - the design-semantic map of tokens, components, variants, states, motion, a11y patterns, screens, layers, and design patterns plus the edges between them. Lists and filters nodes and edges, traces a path between two nodes, finds the consumers of a node, and reports unreachable nodes, dependency cycles, and coverage. Use when the user wants to inspect the design graph, find what depends on a token or component, trace how one node reaches another, or check graph health. Activates for requests involving the design context graph, design dependencies, token consumers, component composition, unreachable design nodes, design cycles, or design coverage."
+argument-hint: "[nodes --type X | edges --type Z | path <a> <b> | consumers-of <id> | unreachable | cycles | coverage]"
+tools: Read, Bash
+user-invocable: true
+---
+
+# {{command_prefix}}context
+
+**Role:** Read-only front end for the typed DesignContext graph. The graph is a design-semantic map: nodes are tokens, components, variants, states, motion fragments, a11y patterns, screens, layers, and design patterns; edges connect them (uses-token, composes, extends, transitions-to, depends-on, mirrors, conflicts-with, referenced-by, tested-by, documented-by, consumes-context, provides-context). This skill queries that graph. It never writes to it. The graph is authored by the mapper agents plus the design-research-synthesizer; this skill only reads.
+
+The query engine ships at `scripts/lib/design-context-query.cjs` (authored elsewhere; this skill only calls it). It is pure and dep-free, exposing `load`, `nodes`, `edges`, `path`, `consumersOf`, `unreachable`, `cycles`, and `coverage`. The merged graph lives at `.design/context-graph.json` with the shape `{ schema_version, generated_at, nodes[], edges[] }`.
+
+If `.design/context-graph.json` is absent, print: `No DesignContext graph yet. Run the design research pipeline (mappers plus {{command_prefix}}synthesize) to generate .design/context-graph.json.` Then STOP. Do not invent a graph.
+
+The engine exposes a module API rather than a CLI, so drive it from a short `node -e` script, the same way other skills call a `scripts/lib` helper:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.nodes(g, { type: process.env.NODE_TYPE || undefined, tag: process.env.TAG || undefined })));"
+```
+
+## Invocation Modes
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}context nodes` | List graph nodes, optionally filtered by `--type` and `--tag` (default mode). |
+| `{{command_prefix}}context edges` | List graph edges, optionally filtered by `--type`. |
+| `{{command_prefix}}context path <a> <b>` | Trace a path from node `<a>` to node `<b>`. |
+| `{{command_prefix}}context consumers-of <id>` | List the nodes that consume node `<id>`. |
+| `{{command_prefix}}context unreachable` | List nodes no edge reaches. |
+| `{{command_prefix}}context cycles` | List dependency cycles in the graph. |
+| `{{command_prefix}}context coverage` | Report graph coverage (typed and tagged ratios). |
+
+Output discipline: emit JSON when a tool or another skill is the caller; render a compact table when a person is at the terminal.
+
+## nodes
+
+List nodes. `--type <t>` filters by node type (token, component, variant, state, motion-fragment, a11y-pattern, screen, layer, pattern, anti-pattern). `--tag <tag>` filters by a controlled tag. Call `nodes(graph, { type, tag })`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.nodes(g, { type: process.env.NODE_TYPE || undefined, tag: process.env.TAG || undefined })));"
+```
+
+Render one row per node. Keep it scannable:
+
+```
+ID                  TYPE        COMPLEXITY  NAME
+token:color/brand   token       simple      Brand primary
+component:Button    component   moderate    Button
+```
+
+If no nodes match, say so plainly and suggest a broader filter.
+
+## edges
+
+List edges. `--type <t>` filters by edge type (uses-token, composes, extends, transitions-to, depends-on, mirrors, conflicts-with, referenced-by, tested-by, documented-by, consumes-context, provides-context). Call `edges(graph, { type })`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.edges(g, { type: process.env.EDGE_TYPE || undefined })));"
+```
+
+Render `source -> target (type, weight)` per row. If none match, report it and suggest dropping the filter.
+
+## path
+
+Trace a path between two node ids. Call `path(graph, from, to)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.path(g, process.env.FROM, process.env.TO)));"
+```
+
+Print the ordered node ids joined by arrows. If no path exists, print `No path from <a> to <b>.` Do not fabricate intermediate nodes.
+
+## consumers-of
+
+List the nodes that consume a given node (the inbound side). Call `consumersOf(graph, id)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.consumersOf(g, process.env.ID)));"
+```
+
+Render the consumer ids one per row. If the id is unknown, print `No node <id> in the graph.` and suggest `{{command_prefix}}context nodes`.
+
+## unreachable
+
+List nodes that no edge reaches (orphans). Call `unreachable(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.unreachable(g)));"
+```
+
+If the list is empty, print `Every node is reachable.`
+
+## cycles
+
+List dependency cycles. Call `cycles(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.cycles(g)));"
+```
+
+Print each cycle as its ordered node ids. If there are none, print `No cycles detected.`
+
+## coverage
+
+Report graph coverage. Call `coverage(graph)`:
+
+```bash
+node -e "const q=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/design-context-query.cjs'); \
+  const g=q.load('.design/context-graph.json'); \
+  console.log(JSON.stringify(q.coverage(g)));"
+```
+
+Surface the returned ratios (for example typed and tagged coverage and node and edge counts) as a short summary.
+
+## Do Not
+
+- Do not edit `.design/context-graph.json` or the fragments under `.design/fragments/`. All writes go through the mapper agents and the synthesizer.
+- Do not invent nodes, edges, or paths. If a query returns nothing, report it plainly.
+- Do not modify `scripts/lib/design-context-query.cjs` or the DesignContext schema.
+
+## CONTEXT COMPLETE

package/scripts/skill-templates/continue/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: gdd-continue
+description: "Alias for {{command_prefix}}resume - restore session context from the most recent checkpoint."
+argument-hint: "[<checkpoint-N>]"
+tools: Read, Write, Bash, Glob
+disable-model-invocation: true
+---
+
+@reference/retrieval-contract.md
+
+# {{command_prefix}}continue
+
+Alias for `{{command_prefix}}resume`. Delegates immediately to the resume skill with the same argument.
+
+This alias exists for discoverability - users familiar with `git continue` or similar conventions find `{{command_prefix}}continue` more intuitive than `{{command_prefix}}resume` after a pause.
+
+## Steps
+
+1. Forward the argument (if any) to the `{{command_prefix}}resume` skill logic.
+2. Execute all `{{command_prefix}}resume` steps exactly as documented in `skills/resume/SKILL.md`.
+
+The two commands are functionally identical. `{{command_prefix}}resume` is the canonical form; `{{command_prefix}}continue` is the convenience alias.
+
+## CONTINUE COMPLETE

package/scripts/skill-templates/darkmode/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: gdd-darkmode
+description: "Audit a project's dark mode implementation - detects architecture (CSS custom props, Tailwind `dark:` prefix, or JS class toggle), runs architecture-specific contrast / token-override / anti-pattern / meta-property checks, and writes a prioritized fix list to `.design/DARKMODE-AUDIT.md`. Use when the user wants to verify dark mode quality without re-running the full design pipeline. Read-only - no score writeback to `DESIGN.md`. Activates for requests involving auditing dark mode, checking dark-theme contrast, or dark-mode anti-patterns."
+argument-hint: ""
+user-invocable: true
+---
+
+# gdd-darkmode - Dark Mode Audit
+
+Standalone dark mode audit. Detects the project's dark mode architecture, runs architecture-specific checks across contrast, token completeness, anti-patterns, and meta properties, then writes a prioritized fix list to `.design/DARKMODE-AUDIT.md`.
+
+For the full step-by-step methodology (architecture-detection greps, WCAG contrast formula, anti-pattern grep snippets, meta-property checks, screenshot capture, and `DARKMODE-AUDIT.md` template), see `./darkmode-audit-procedure.md`. For the perceptual-contrast layer (APCA / WCAG 3 draft) sitting on top of WCAG 2.1 ratios, see `../../reference/contrast-advanced.md`. For OKLCH-based dark token-pair generation, see `../../reference/color-theory.md` §OKLCH. For the cross-skill output discipline + connection-probe pattern, see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`.
+
+---
+
+## Scope
+
+This command is a **standalone audit** - not a pipeline stage:
+
+- Does NOT update `DESIGN.md` scores (V2-05 deferred - two-sources-of-truth risk).
+- Does NOT invoke `design-auditor` (Pitfall 4 - darkmode runs its own inline audit, separate from the `DESIGN-AUDIT.md` pipeline).
+- Does NOT write to `.design/STATE.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, `DESIGN-SUMMARY.md`, or `DESIGN-VERIFICATION.md`.
+- Writes exactly ONE artifact: `.design/DARKMODE-AUDIT.md`.
+- Does NOT execute fixes - audit-only per V2-07 deferral (fixes belong in the design pipeline's color task).
+
+Output artifact prefix `DARKMODE-AUDIT` is distinct from the pipeline namespace (`DESIGN-*.md`). No naming conflict.
+
+---
+
+## Pre-Flight
+
+Confirm source root exists. Try in order: `src/` (preferred), `app/` (Next.js App Router), `lib/` (libraries), `pages/` (Next.js Pages Router). Set `SRC_ROOT` to the first that exists. If none exist, abort: `"No source directory detected. Run /get-design-done scan first."`
+
+Confirm `.design/` exists (create if absent: `mkdir -p .design/`).
+
+Probe `preview` connection per `../../reference/shared-preamble.md#connection-handshake-summary` (ToolSearch → `mcp__Claude_Preview__preview_list` → STATE.md write). Result drives Step 5B (visual dark mode rendering).
+
+---
+
+## Workflow
+
+1. **Architecture Detection (DARK-02)** - run three greps (CSS custom props / Tailwind `dark:` / JS class toggle), classify primary architecture or `Hybrid` or `None`. If `None`, abort. Detail: `./darkmode-audit-procedure.md#step-1-architecture-detection-dark-02`.
+2. **Contrast Audit (DARK-03)** - extract dark-context token pairs for the detected architecture, compute WCAG 2.1 ratios, flag failures at 4.5:1 (body) / 3:1 (large text + UI boundaries). Cross-check with APCA from `../../reference/contrast-advanced.md` for thin / large / colored text. Detail: `./darkmode-audit-procedure.md#step-2-contrast-audit-dark-03`.
+3. **Token Override Completeness (DARK-04)** - every light-mode color token must have a dark-mode override. Flag missing overrides → P1. Detail: `./darkmode-audit-procedure.md#step-3-token-override-completeness-dark-04`.
+4. **Dark-Specific Anti-Patterns (DARK-05)** - Images/SVGs without dark variant (P2), pure-black backgrounds in dark context = BAN-05 (P1), missing `@media (forced-colors)` (P2). Detail: `./darkmode-audit-procedure.md#step-4-dark-specific-anti-patterns-dark-05`.
+5. **Meta Property Check (DARK-06)** - `color-scheme` property + `prefers-color-scheme` query. Each absent → P2. Detail: `./darkmode-audit-procedure.md#step-5-meta-property-check-dark-06`.
+6. **Visual Rendering (preview: available only)** - capture light/dark screenshot pair to `.design/screenshots/darkmode/{light,dark}.png`. Detail: `./darkmode-audit-procedure.md#step-5b-dark-mode-rendering-screenshots-when-preview-available`.
+7. **Write `.design/DARKMODE-AUDIT.md`** - group flagged issues by priority (P0 → P1 → P2 → P3). Full template at `./darkmode-audit-procedure.md#step-6-darkmode-auditmd-template`.
+
+---
+
+## Constraints
+
+This command MUST NOT (per `../../reference/shared-preamble.md#output-contract-reminders`):
+
+- Write to `DESIGN.md`, `DESIGN-SUMMARY.md`, `DESIGN-VERIFICATION.md`, `DESIGN-CONTEXT.md`, or `.design/STATE.md`.
+- Invoke `design-auditor` (Pitfall 4 - this is a separate audit with its own inline checks).
+- Execute any fixes - audit-only (V2-07 deferred).
+- Write scores back to `DESIGN.md` (V2-05 deferred - two-sources-of-truth risk).
+- Add rows to `DESIGN.md` or append to pipeline-owned artifacts.
+
+MUST write exactly one output file: `.design/DARKMODE-AUDIT.md`.
+
+---
+
+## Completion
+
+After writing the audit, print:
+
+```
+Dark mode audit complete. Architecture: <X>. Fixes: P0=<N>, P1=<M>, P2=<K>, P3=<J>. See .design/DARKMODE-AUDIT.md.
+```
+
+Do not summarize individual issues in the completion message - the file contains the full detail.
+
+## DARKMODE AUDIT COMPLETE

package/scripts/skill-templates/darkmode/darkmode-audit-procedure.md

@@ -0,0 +1,258 @@
+---
+name: darkmode-audit-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [darkmode, dark-mode, contrast, audit, procedure, extracted]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/darkmode/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+The skill's essential routing + decision tree stays in `../skills/darkmode/SKILL.md`; this
+file holds the architecture-detection greps, contrast computation, anti-pattern grep
+snippets, and the `DARKMODE-AUDIT.md` report template.
+
+# Dark Mode Audit Procedure
+
+Detailed procedure for the `gdd-darkmode` standalone audit - companion to
+`../skills/darkmode/SKILL.md`. Read this file when executing a specific audit step
+(architecture detection, contrast computation, anti-pattern grep, report layout). The
+SKILL.md keeps the essential pre-flight + step routing; this file holds the deep
+methodology.
+
+For the perceptual layer (APCA / WCAG 3 draft) sitting on top of the WCAG 2.1 ratios used
+in Step 2, see `./contrast-advanced.md`. For modern OKLCH-based dark token-pair generation,
+see `./color-theory.md` §OKLCH. For the cross-skill output discipline + connection-probe
+pattern, see `./shared-preamble.md#output-contract-reminders` and
+`./shared-preamble.md#connection-handshake-summary`.
+
+---
+
+## Step 1: Architecture Detection (DARK-02)
+
+Run all three architecture greps against `$SRC_ROOT`. Use `2>/dev/null` on each to suppress missing-directory errors.
+
+```bash
+# Architecture 1: CSS custom properties with dark media query
+arch1_count=$(grep -rEn "prefers-color-scheme.*dark|\.dark[[:space:]]*\{" "$SRC_ROOT" \
+  --include="*.css" --include="*.scss" 2>/dev/null | wc -l)
+
+# Architecture 2: Tailwind dark: prefix
+arch2_count=$(grep -rEn "dark:[a-z]" "$SRC_ROOT" \
+  --include="*.tsx" --include="*.jsx" --include="*.html" 2>/dev/null | wc -l)
+
+# Architecture 3: JS class toggle on <html> / <body>
+arch3_count=$(grep -rEn "classList.*dark|setAttribute.*dark|document\.documentElement" "$SRC_ROOT" \
+  --include="*.ts" --include="*.tsx" --include="*.js" 2>/dev/null | wc -l)
+```
+
+**Classification rules:**
+
+| Condition | Classification |
+|-----------|---------------|
+| All three counts < 3 | No dark mode - abort: "No dark mode implementation detected - nothing to audit." |
+| Exactly one count ≥ 3 | Primary architecture = that one |
+| Two or more counts ≥ 5 | Hybrid (list all detected architectures) |
+| One count ≥ 3, others < 5 | Primary = highest count |
+
+Record `ARCH_DETECTED` as one of: `Architecture 1 (CSS custom props)`, `Architecture 2 (Tailwind dark:)`, `Architecture 3 (JS class toggle)`, or `Hybrid`.
+
+---
+
+## Step 2: Contrast Audit (DARK-03)
+
+For the detected architecture, enumerate color token + background token pairs used in dark context, then compute WCAG contrast ratios.
+
+**Token extraction by architecture:**
+
+**Architecture 1 (CSS custom props):**
+```bash
+grep -rEn "\.dark[[:space:]]*\{|prefers-color-scheme.*dark" "$SRC_ROOT" \
+  --include="*.css" --include="*.scss" -A 30 2>/dev/null \
+  | grep -E "^\s*--[a-z].*:\s*#[0-9a-fA-F]{3,8}|^\s*--[a-z].*:\s*rgb"
+```
+
+**Architecture 2 (Tailwind dark:):**
+```bash
+grep -rEhon "dark:(bg|text)-[a-z0-9-]+" "$SRC_ROOT" \
+  --include="*.tsx" --include="*.jsx" --include="*.html" 2>/dev/null | sort -u
+```
+
+**Architecture 3 (JS class toggle):**
+```bash
+grep -rEn "\.dark[[:space:]]*\{" "$SRC_ROOT" \
+  --include="*.css" --include="*.scss" -A 30 2>/dev/null \
+  | grep -E "color|background"
+```
+
+**WCAG contrast computation:**
+
+Use the linearized-sRGB formula from `agents/design-executor.md` Type: accessibility (pre-calibrated - do not re-derive):
+
+1. Convert each hex channel to linear light: `c_lin = (c/255 ≤ 0.04045) ? c/255/12.92 : ((c/255 + 0.055)/1.055)^2.4`
+2. Relative luminance: `L = 0.2126 * R_lin + 0.7152 * G_lin + 0.0722 * B_lin`
+3. Contrast ratio: `(L_lighter + 0.05) / (L_darker + 0.05)`
+
+**Thresholds:**
+
+| Text type | Min ratio | Fail severity |
+|-----------|-----------|---------------|
+| Body text (< 18pt or < 14pt bold) | 4.5:1 | P0 (critical) |
+| Large text (≥ 18pt or ≥ 14pt bold) | 3:1 | P1 (major) |
+| UI component boundaries | 3:1 | P1 (major) |
+
+Flag every pair that fails its threshold. Include token names, hex values, computed ratio, and required ratio in the fix description.
+
+For pairs that pass WCAG 2.1 but feel wrong perceptually (thin mid-gray text, large saturated text, saturated-on-saturated), cross-check with the APCA Lc thresholds in `./contrast-advanced.md` and annotate `[APCA-mismatch]` in the fix description.
+
+---
+
+## Step 3: Token Override Completeness (DARK-04)
+
+Check that every light-mode color token has a corresponding dark-mode override.
+
+**Enumerate light-mode tokens:**
+```bash
+grep -rEhon "var\(--color-[a-z0-9-]+\)" "$SRC_ROOT" \
+  --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx" 2>/dev/null \
+  | grep -oE "\-\-color-[a-z0-9-]+" | sort -u
+
+grep -rEhon "(bg|text|border|ring)-[a-z]+-[0-9]+" "$SRC_ROOT" \
+  --include="*.tsx" --include="*.jsx" 2>/dev/null | sort -u
+```
+
+**Check dark overrides (architecture-specific):**
+- Arch 1: Token appears in `.dark { --color-* }` block or `@media (prefers-color-scheme: dark) { --color-* }`
+- Arch 2: A `dark:` prefixed variant of the Tailwind class exists in the same file or a shared layout
+- Arch 3: Token appears in the dark CSS block activated by JS class toggle
+
+**Flag:** Any light-mode color token with no dark override → P1 (major). For OKLCH-based pair generation guidance, see `./color-theory.md` §OKLCH.
+
+---
+
+## Step 4: Dark-Specific Anti-Patterns (DARK-05)
+
+**Anti-pattern A: Images and SVGs without dark variant**
+
+```bash
+grep -rEn "<img[^>]+src=|<svg" "$SRC_ROOT" \
+  --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" 2>/dev/null \
+  | grep -v "dark\."
+```
+
+For each image/SVG found, check whether any of the following exist:
+- A sibling file with pattern `[name]-dark.{png,svg,webp}`
+- A `dark:hidden` / `dark:block` swap class pairing in the same component
+- A `<picture>` element with a `prefers-color-scheme: dark` source
+
+Flag images/SVGs with none of the above → P2 (minor).
+
+**Anti-pattern B: Pure-black backgrounds (BAN-05)**
+
+```bash
+grep -rEn "#000000|#000\b|rgb\([[:space:]]*0[[:space:]]*,[[:space:]]*0[[:space:]]*,[[:space:]]*0[[:space:]]*\)|background[^:]*:[[:space:]]*black" \
+  "$SRC_ROOT" --include="*.css" --include="*.scss" 2>/dev/null
+```
+
+Any match within a `.dark {}` block or `@media (prefers-color-scheme: dark)` context → P1 (major). Pure black (`#000000`) in dark mode causes visual harshness and fails accessibility in high-contrast conditions. Use near-black (`#0a0a0a` – `#1a1a1a`) instead.
+
+**Anti-pattern C: Missing forced-colors media query**
+
+```bash
+forced_count=$(grep -rEn "@media.*forced-colors" "$SRC_ROOT" \
+  --include="*.css" --include="*.scss" 2>/dev/null | wc -l)
+```
+
+If `forced_count` equals 0 → P2 (minor). The `forced-colors` media query ensures the design respects Windows High Contrast mode and similar OS accessibility overrides.
+
+---
+
+## Step 5: Meta Property Check (DARK-06)
+
+**color-scheme property:**
+```bash
+cs_count=$(grep -rEn "color-scheme" "$SRC_ROOT" public/ \
+  --include="*.html" --include="*.tsx" --include="*.css" 2>/dev/null | wc -l)
+```
+If `cs_count` equals 0 → P2 (minor).
+
+**prefers-color-scheme media query:**
+```bash
+pcs_count=$(grep -rEn "prefers-color-scheme" "$SRC_ROOT" public/ \
+  --include="*.html" --include="*.tsx" --include="*.css" 2>/dev/null | wc -l)
+```
+If `pcs_count` equals 0 → P2 (minor). Absence means the site ignores the OS-level dark mode preference.
+
+---
+
+## Step 5B: Dark Mode Rendering Screenshots (when preview: available)
+
+Check `preview` status from `.design/STATE.md <connections>` (per `./shared-preamble.md#connection-handshake-summary`).
+
+**If `preview: available`:**
+
+1. `preview_navigate` to the primary route (e.g., `http://localhost:3000/`).
+2. Capture light-mode: `preview_screenshot` → `.design/screenshots/darkmode/light.png`.
+3. Inject dark mode using the project's toggle mechanism (check `DESIGN-CONTEXT.md` D-XX decisions):
+   - Tailwind dark: `preview_eval("document.documentElement.classList.add('dark')")`
+   - data-theme: `preview_eval("document.documentElement.setAttribute('data-theme','dark')")`
+   - Custom class: `preview_eval("document.documentElement.classList.add('theme-dark')")`
+   - If mechanism is unknown: attempt Tailwind default first; note in `DARKMODE-AUDIT.md` which method was used.
+4. `preview_screenshot` → `.design/screenshots/darkmode/dark.png`.
+5. Record both paths (NOT base64) for embedding in `## Dark Mode Rendering` section.
+
+**If `preview: unavailable` or `preview: not_configured`:** omit `## Dark Mode Rendering` section entirely. Emit `Visual dark mode check skipped — preview not configured.` in Notes.
+
+---
+
+## Step 6: DARKMODE-AUDIT.md Template
+
+Output path: `.design/DARKMODE-AUDIT.md`.
+
+```markdown
+# Dark Mode Audit
+
+**Generated:** <ISO date>
+**Architecture detected:** <Architecture 1 (CSS custom props) | Architecture 2 (Tailwind dark:) | Architecture 3 (JS class toggle) | Hybrid | None>
+**Source scanned:** <SRC_ROOT>
+
+## Summary
+
+| Category | Status | Issues |
+|----------|--------|--------|
+| Contrast (DARK-03) | <pass / fail> | <count> |
+| Token Overrides (DARK-04) | <pass / fail> | <count> |
+| Anti-Patterns (DARK-05) | <pass / fail> | <count> |
+| Meta Properties (DARK-06) | <pass / fail> | <count> |
+
+## P0 Fixes (Critical — contrast failure on body text)
+- [CONTRAST] <token-pair>: ratio <X:1> — required 4.5:1. File: <path>
+
+## P1 Fixes (Major — large-text contrast / missing dark overrides / pure-black)
+- [CONTRAST-LARGE] <token-pair>: ratio <X:1> — required 3:1. File: <path>
+- [TOKEN-OVERRIDE] Missing dark override for <--token-name>. Light value: <hex>. File: <path>
+- [BAN-05] Pure-black background detected in dark context. File: <path>:line
+
+## P2 Fixes (Minor — missing SVG variants / forced-colors / meta props)
+- [SVG-DARK] <image.svg> has no dark variant. File: <path>
+- [FORCED-COLORS] No @media (forced-colors) block detected in any CSS file.
+- [COLOR-SCHEME] No color-scheme property or meta tag detected.
+- [PREFERS-COLOR-SCHEME] No prefers-color-scheme query detected.
+
+## P3 Fixes (Cosmetic)
+- <cosmetic issues, if any>
+
+## Dark Mode Rendering
+<Either side-by-side screenshot references, or "Visual dark mode check skipped — preview not configured.">
+
+## Notes
+This audit is read-only. It does NOT write scores back to DESIGN.md.
+To apply fixes, run the design pipeline and include dark mode decisions in DESIGN-CONTEXT.md.
+Score writeback (V2-05) is deferred.
+```
+
+If a priority bucket has no issues, omit that section or write "None."
+
+---
+
+*Imported by: `../skills/darkmode/SKILL.md`. Maintained as part of Phase 28.5 (Bucket 2 rework - D-10).*

package/scripts/skill-templates/debug/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: gdd-debug
+description: "Symptom-driven design debugger with persistent state. Phase 1 builds a feedback loop; Phase 2 hypothesizes. Writes findings to .design/DEBUG.md. Use when a symptom needs systematic, one-variable-at-a-time tracking."
+argument-hint: "[<symptom description>]"
+tools: Read, Write, Grep, Glob, AskUserQuestion, Task
+---
+
+# {{command_prefix}}debug
+
+Systematic, checkpoint-driven design debugger. Loads framing from `./../reference/debugger-philosophy.md` (five principles) and the feedback-loop construction catalog from `./debug-feedback-loops.md` (10 priority-ordered loop paths). Phase 1 builds the loop; Phase 2 generates hypotheses. Writes every step to `.design/DEBUG.md` so killed sessions can resume.
+
+## Steps
+
+1. **Load philosophy + feedback-loop catalog**: Read `reference/debugger-philosophy.md` (five principles) and `./debug-feedback-loops.md` (10 construction paths; iterate-on-loop discipline). Keep both in mind for the entire session.
+2. **Symptom**: If no symptom argument was passed, ask (AskUserQuestion): "What design symptom are you investigating? (observable only - 'cards look crowded', not 'padding is wrong')"
+3. **Resume check**: Read `.design/DEBUG.md` if it exists. If there is an open session with no `### Fix Proposal` block, ask: "Resume existing session '<symptom>' or start a new one?"
+4. **Ground truth load**: Read `.design/DESIGN-PLAN.md` (goals), `.design/STATE.md` `<decisions>` block (D-XX items), and any source files pointed at by the symptom.
+5. **Phase 1 - Build a feedback loop**: Before ANY hypothesizing, build a deterministic, fast, agent-runnable pass/fail signal that reproduces the symptom. See `./debug-feedback-loops.md` for the 10 construction paths in priority order (failing test > curl > CLI fixture > headless browser > trace replay > throwaway harness > fuzz > bisect > differential > HITL bash). Iterate on the loop itself (cache setup, narrow scope, pin time, seed RNG, isolate filesystem, freeze network) before iterating on the bug. For non-deterministic bugs: raise reproduction rate to at least 30%, not clean repro. **Do not proceed to Phase 2 (hypothesis generation) until you have a loop you believe in.**
+6. **Optional rendered-output check**: Use ToolSearch to see if Playwright/Preview MCP tools are available. If yes, capture rendered state. If no, fall back to code-only analysis.
+7. **Phase 2 - Investigation loop** (one hypothesis at a time) - for each step:
+   - Form one hypothesis (one variable).
+   - Investigate (read files, grep, measure). Re-run the Phase 1 feedback loop to confirm the hypothesis pinpoints the symptom.
+   - Append to `.design/DEBUG.md`:
+
+     ```markdown
+     ## <symptom> — <date>
+     ### Hypothesis <N>
+     ### Investigation
+     ### Finding
+     ```
+
+   - Ask (AskUserQuestion): "Continue investigating? (yes / found it / dead end)"
+8. **When found**: Write `### Fix Proposal` block with a concrete patch description. Re-run the Phase 1 loop to confirm the fix flips it from fail to pass. Ask: "Create a todo with `{{command_prefix}}todo add`, or execute the fix now?"
+
+## Do Not
+
+- Do not change multiple variables at once.
+- Do not modify global tokens to fix a single component without explicit user approval.
+- Do not close the DEBUG.md session without a finding (mark as "dead end" if abandoned).
+
+## DEBUG COMPLETE

package/scripts/skill-templates/debug/debug-feedback-loops.md

@@ -0,0 +1,119 @@
+---
+name: debug-feedback-loops
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [debug, feedback-loop, deterministic-signal, iterate-on-loop, mit-port, mattpocock]
+last_updated: 2026-05-18
+---
+
+Source: mattpocock/skills (MIT) - engineering/diagnose Phase 1 - adapted with permission. See `../NOTICE` for the full attribution block.
+
+# Debug Feedback Loops
+
+Build a feedback loop before any hypothesizing. A feedback loop is a deterministic, fast, agent-runnable pass/fail signal that tells you whether the bug is reproduced right now, every time, in well under a minute. Without it, debugging degenerates to speculation.
+
+**Do not proceed to Phase 2 (hypothesis generation) until you have a loop you believe in.**
+
+## The 10 construction paths
+
+Listed in priority order - try the cheaper, faster paths first. Each entry: when to reach for it, the shape of the loop, and the verification snippet.
+
+### 1. Failing test
+
+The strongest signal. Write the failing test in the project's native test framework (pytest, jest, vitest, go test, cargo test, junit, rspec). Assert the buggy behavior; run with watch mode if available. When the test goes green, the bug is fixed. Best case: reproduces in under 2 seconds, runnable by a fresh agent with one command.
+
+When to reach: the project already has a test runner the agent can invoke; the bug is in a unit/integration-testable code path; the symptom is expressible as a deterministic assertion.
+
+### 2. `curl` against a running endpoint
+
+For HTTP endpoints, a `curl` against the staging or local server with assertion on body/status. Pipe to `jq` for structured assertions. Cheap, reliable, framework-free. Wrap in a 3-line bash script so the loop is one command.
+
+When to reach: the bug is in an HTTP endpoint; the server is already runnable locally; the symptom shows up in response body/status/headers.
+
+### 3. CLI fixture
+
+For CLI tools, a small shell script that invokes the binary with fixture inputs and `grep`s for the symptom in stdout/stderr. Bash one-liner is enough; no test framework. Capture exit code, stdout, and stderr separately.
+
+When to reach: the bug is in a CLI tool; the symptom shows up in stdout/stderr/exit-code; the failure mode is reproducible from a fixed input.
+
+### 4. Headless browser
+
+For UI bugs, a Playwright or Puppeteer script that opens the page, performs the trigger action, and screenshots the symptom region. Compare against a known-good fixture or assert on a DOM selector's text/attribute. Use a deterministic seed for any randomness (animations, IDs, dates).
+
+When to reach: the bug is visible only in a rendered browser context; DOM-level inspection isn't enough; the symptom involves layout, paint, or interaction timing.
+
+### 5. Trace replay
+
+For bugs reproducible from a captured execution trace, replay the trace deterministically. `rr` on Linux for native binaries, record-and-replay plugins for some browsers, Chrome DevTools recording for web, or a captured production trace for distributed systems. Replays are bit-for-bit reproducible - the gold standard for non-deterministic bugs that have been captured once.
+
+When to reach: the bug is hard to reproduce live but you have a captured trace; the trace runtime is available; bit-identical replay is achievable.
+
+### 6. Throwaway harness
+
+Write a minimal `main()` that calls the buggy function with known inputs and prints the output. ~10 lines. Side-step framework startup costs entirely. Throw away when fixed. Useful when the test framework's setup is too heavy to iterate quickly.
+
+When to reach: the bug is in a single function with a clear input/output contract; framework setup dominates iteration time; you'd rather iterate on a 10-line script than wait for the framework to boot.
+
+### 7. Fuzz
+
+When the bug surfaces unpredictably, use property-based testing (Hypothesis, fast-check, jqwik) or AFL/libfuzzer for native code. The fuzzer narrows on the failing input across runs. Combine with a "minimize" pass to shrink the failing input to its smallest form.
+
+When to reach: the input space is exotic (parsers, serializers, network protocols); the bug isn't tied to a specific input you can name; you suspect a class of inputs but can't enumerate it.
+
+### 8. Bisect
+
+When you know "it worked on commit X, fails on commit Y," `git bisect` is the loop. Each iteration runs the test/curl/CLI from a higher path. Reproduces in O(log N) commits. Combine with `git bisect run <script>` to fully automate.
+
+When to reach: the bug regressed between two known commits; you have a binary pass/fail script from one of the earlier paths; you don't yet know which commit introduced the regression.
+
+### 9. Differential
+
+When you have two systems and one's correct, write a differential harness: feed the same input to both, assert outputs match. Cheap for migration bugs (old → new implementation) and protocol bugs (your client vs reference client). The harness becomes the regression test once the bug is fixed.
+
+When to reach: a known-good reference implementation exists; the buggy code is supposed to match the reference; input space is enumerable enough to drive both implementations side by side.
+
+### 10. HITL bash (Human In The Loop)
+
+Last resort. A documented sequence of bash commands a human runs that produces a pass/fail signal. Slower (human in the path), but better than no loop. The agent reads stdout/stderr; the human reads the screen and reports. Use only when no automatable signal is available - physical hardware, vendor portals, manual eyeball checks.
+
+When to reach: every other path is blocked by an unautomatable surface; the human cost is acceptable for the duration of the investigation; the loop will be retired or upgraded the moment any earlier path becomes possible.
+
+## Iterate on the loop itself
+
+The loop is a first-class artifact. Iterate on it before iterating on hypotheses. A 5-minute loop run 20 times costs 100 minutes; a 5-second loop run 20 times costs 100 seconds. Spending 30 minutes tightening the loop pays back inside the same session.
+
+- **Cache setup**: hoist expensive setup (DB seed, fixture load, container start) out of the loop body. Run the loop only on the fast inner part. Use `--no-rebuild`, persistent containers, or test-runner watch modes.
+- **Narrow scope**: if the loop runs the full test suite to verify one bug, narrow to just the failing test/group. Fewer side-effects, faster iterations. `pytest -k`, `jest -t`, `vitest --testNamePattern`, `go test -run` are your friends.
+- **Pin time**: when the bug is time-dependent, freeze the clock (`sinon.useFakeTimers`, `jest.useFakeTimers`, `freezegun`, `time-machine`). Removes wallclock as a variable.
+- **Seed RNG**: every random source gets a fixed seed in the loop. `Math.random`, `crypto.randomBytes`, `random.seed(...)`, `rand::SeedableRng`. Determinism over coverage - the loop must be bit-identical given the same code state.
+- **Isolate filesystem**: run in a `tmpdir`; reset between iterations. Avoids "fixed on my machine" via stale state. Bind-mount or copy fixtures into the tmpdir per iteration.
+- **Freeze network**: mock or record/replay all outbound calls (`nock`, `vcr`, `polly.js`, `mitmproxy --replay`). Real-network loops are non-deterministic by definition.
+
+The discipline: every iteration of the loop should be bit-identical given the same code state. If two iterations differ without a code change, the loop has a hidden input - find it and pin it before continuing.
+
+## Non-deterministic bugs
+
+Some bugs surface only sometimes. The goal is NOT a clean repro - the goal is to raise the reproduction rate to debuggable.
+
+- **Measure baseline rate**: run the loop N=20 times. Note pass/fail count. Record the rate so you can tell whether later changes helped.
+- **Raise stressors**: add concurrency, contention, memory pressure, network jitter (use `tc qdisc add dev lo root netem delay 100ms 50ms` on Linux, `Network Link Conditioner` on macOS). Re-measure.
+- **Target the suspect axis**: if you suspect a race, add a deterministic sleep at the suspect point and measure. If reproduction jumps to 100% with sleep, the race is in that region. If it stays at baseline, the race is elsewhere.
+- **A 30% reproduction rate is debuggable.** A 5% rate isn't - keep raising stressors until you cross 30%. At 30% you can iterate; at 5% you're guessing whether your fix helped or you got lucky.
+
+## When the loop is good enough
+
+The loop is good enough when:
+
+- It runs in under a minute (preferably under 10 seconds).
+- It's deterministic (or, for non-determinism, reproduces at least 30% of the time).
+- It's automatable - no human in the inner loop except by explicit choice (Path 10).
+- A fresh agent could pick up the loop and run it without context.
+
+Only after the loop is good enough should you proceed to hypothesizing the fix. The hypothesis cycle is governed by `./debugger-philosophy.md` (one variable at a time, do not stop at first plausible cause, the bug is where you didn't look).
+
+## Cross-references
+
+- `./debugger-philosophy.md` - companion framing; the hypothesis-cycle discipline that runs in Phase 2 once the loop is in place.
+- `../skills/debug/SKILL.md` - Phase 1 of the debug skill mandates this catalog before any hypothesis generation.
+- `../NOTICE` - full mattpocock/skills MIT attribution.