@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/gdd-threat-model.md

@@ -5,7 +5,7 @@
 
 ## Scope
 
-This document models the security posture of **GDD's own runtime** — the
+This document models the security posture of **GDD's own runtime** - the
 multi-MCP-server, peer-CLI-spawning, WebSocket-emitting SDK that grew across
 Phases 20–27 without a formalized security model. It does **NOT** model the
 user code that GDD audits; the safety floor for *audited user code* is Phase
@@ -25,10 +25,10 @@ audit trail), **I**nformation disclosure (leaking data to the wrong party),
 Each of the five in-scope components below gets a fixed five-part treatment:
 **Assets** (what an attacker wants), **Entry points** (the untrusted-input
 boundary), **STRIDE threats** (which categories apply), **Current mitigations**
-(citing **real shipped code** — file + line + behavior), and **Residual risks**
+(citing **real shipped code** - file + line + behavior), and **Residual risks**
 (threats current code does **not** fully cover, each routed to the Phase 33.5
 plan that closes it). Out of scope per CONTEXT: rewriting the issue-reporter
-network model — it is **documented** here as already-mitigated, not
+network model - it is **documented** here as already-mitigated, not
 re-engineered.
 
 ## Trust boundaries
@@ -46,13 +46,13 @@ controls; the table names what crosses the line.
 | OpenRouter catalog fetch `→` openrouter.ai | The OpenRouter `/models` API host (and any MITM on the path) | The `Authorization: Bearer <OPENROUTER_API_KEY>` request header + the untrusted `/models` JSON the host returns |
 
 The event payloads that traverse the bus (and therefore the WS transport and
-any persisted JSONL) are scrubbed at serialize time — see Component 4's
+any persisted JSONL) are scrubbed at serialize time - see Component 4's
 `redact.cjs` mitigation, which is the cross-cutting information-disclosure
 control for the whole bus.
 
 ---
 
-## Component 1 — Hooks (SessionStart update-check + budget/context-monitor)
+## Component 1 - Hooks (SessionStart update-check + budget/context-monitor)
 
 The hooks run automatically: `SessionStart` fires the update-check on every
 session, and the budget / context-monitor hook runs on tool-use to enforce
@@ -71,16 +71,16 @@ inside the user's repo, with no sandbox.
     "latest version" response to the update-check.
   - **Tampering:** A malformed `.design/config.json` could try to corrupt the
     budget/context accounting or flip the monitor's thresholds.
-  - **Repudiation:** Hook actions are largely silent — limited audit trail of
+  - **Repudiation:** Hook actions are largely silent - limited audit trail of
     what a SessionStart hook did or why a budget veto fired.
   - **Information disclosure:** The update-check's User-Agent / outbound
     request reveals that GDD is in use; a verbose hook could echo env into logs.
   - **Denial of service:** A hung or slow update endpoint could stall session
     start if the fetch were unbounded.
-  - **Elevation of privilege:** The hook already runs at full user privilege —
+  - **Elevation of privilege:** The hook already runs at full user privilege -
     the residual concern is a config-driven path or command injection lifting
     *attacker* input to that privilege level.
-- **Current mitigations:** The update-check is **advisory** — it informs of a
+- **Current mitigations:** The update-check is **advisory** - it informs of a
   newer version and never auto-installs or executes downloaded code, so a
   spoofed version string cannot achieve code execution. The budget /
   context-monitor reads config defensively (missing file / malformed JSON /
@@ -98,13 +98,13 @@ inside the user's repo, with no sandbox.
 
 ---
 
-## Component 2 — MCP servers (gdd-state: 11 mutating tools / gdd-mcp: read)
+## Component 2 - MCP servers (gdd-state: 11 mutating tools / gdd-mcp: read)
 
 Two MCP servers expose GDD state to an MCP client: **gdd-state**
-(`sdk/mcp/gdd-state/`) with **11 mutating tools** — `add_blocker`,
+(`sdk/mcp/gdd-state/`) with **11 mutating tools** - `add_blocker`,
 `add_decision`, `add_must_have`, `checkpoint`, `frontmatter_update`, `get`,
 `probe_connections`, `resolve_blocker`, `set_status`, `transition_stage`,
-`update_progress` — and **gdd-mcp** (`sdk/mcp/gdd-mcp/`) with read tools. The
+`update_progress` - and **gdd-mcp** (`sdk/mcp/gdd-mcp/`) with read tools. The
 mutating server is the higher-value target because it writes `STATE.md`.
 
 - **Assets:** The integrity of `STATE.md` (the project's source of truth for
@@ -120,7 +120,7 @@ mutating server is the higher-value target because it writes `STATE.md`.
     `STATE.md`, or `GDD_STATE_PATH` could redirect writes onto an unintended
     file (path traversal).
   - **Repudiation:** Without a complete mutation audit trail, a hostile or
-    buggy mutation is hard to attribute — partly addressed by the event
+    buggy mutation is hard to attribute - partly addressed by the event
     emissions below.
   - **Information disclosure:** A `get` against a traversed path could read a
     file outside the intended `.design/` boundary.
@@ -132,14 +132,14 @@ mutating server is the higher-value target because it writes `STATE.md`.
 - **Current mitigations:** Every mutation emits a `state.mutation` /
   `state.transition` event through `emitStateMutation()` / `emitStateTransition()`
   (`sdk/mcp/gdd-state/tools/shared.ts` lines 91–140), giving a partial audit
-  trail (anti-repudiation). Handlers **never throw to the harness** — every
+  trail (anti-repudiation). Handlers **never throw to the harness** - every
   error funnels through `errorResponse()` → `toToolError()` into a structured
   `{success:false,error}` (shared.ts lines 28–31, 148–151), so a malformed
   input degrades to a clean error instead of a crash. Each of the 11 tools
   already ships a JSON input schema under `sdk/mcp/gdd-state/schemas/`. State
   events are redacted by `redact.cjs` at serialize time (Component 4).
 - **Residual risks:** `resolveStatePath()` (`sdk/mcp/gdd-state/tools/shared.ts`
-  lines 60–64) honors `GDD_STATE_PATH` with **no path-traversal guard** — it
+  lines 60–64) honors `GDD_STATE_PATH` with **no path-traversal guard** - it
   returns the override verbatim, so `..` escape / absolute-outside / symlink
   escape are unchecked. The tool schemas exist but carry **no payload-size cap**
   (no JSON-bomb guard) and are not uniformly tightened
@@ -149,15 +149,15 @@ mutating server is the higher-value target because it writes `STATE.md`.
 
 ---
 
-## Component 3 — Peer-CLI broker (acp-client + asp-client child spawn)
+## Component 3 - Peer-CLI broker (acp-client + asp-client child spawn)
 
 The broker spawns peer CLIs over stdio: `scripts/lib/peer-cli/acp-client.cjs`
 (ACP-protocol peers) and `scripts/lib/peer-cli/asp-client.cjs` (Codex
 app-server protocol). Both fork a local child process and exchange
-line-delimited JSON over its stdio. The child is **untrusted** — it is a
+line-delimited JSON over its stdio. The child is **untrusted** - it is a
 third-party CLI whose stdout the broker parses.
 
-- **Assets:** GDD's process environment — specifically `ANTHROPIC_API_KEY`,
+- **Assets:** GDD's process environment - specifically `ANTHROPIC_API_KEY`,
   `GH_TOKEN`, and any `GDD_*` / provider secret in `process.env`; the broker's
   memory/availability; the integrity of the JSON protocol exchange.
 - **Entry points:** The child's **stdout** (untrusted JSON frames the broker
@@ -170,23 +170,23 @@ third-party CLI whose stdout the broker parses.
     the broker's line-buffer / pending-request state.
   - **Repudiation:** Limited record of exactly what env a given child was
     handed at spawn.
-  - **Information disclosure:** **The headline risk** — the child inherits
+  - **Information disclosure:** **The headline risk** - the child inherits
     GDD's full environment, so a hostile or compromised peer reads
     `ANTHROPIC_API_KEY` / `GH_TOKEN` straight out of `process.env`.
   - **Denial of service:** A peer that never emits a newline could force the
     broker to buffer unbounded stdout until memory exhaustion.
   - **Elevation of privilege:** Inherited secrets let a peer act *as GDD*
-    against GDD's providers — using GDD's keys for the peer's own ends.
+    against GDD's providers - using GDD's keys for the peer's own ends.
 - **Current mitigations:** `acp-client.cjs` caps an un-terminated stdout line
   at **`MAX_LINE_BYTES = 16 * 1024 * 1024`** (16 MiB; defined line 62, enforced
-  lines 166–176 — a peer that emits 16 MiB without a newline gets its active
+  lines 166–176 - a peer that emits 16 MiB without a newline gets its active
   prompt rejected as a protocol violation). This is a real **DoS guard** on the
   untrusted stdout channel. The broker uses plain `spawn` with **no shell**
   (acp-client.cjs lines 106–113, `windowsHide: true`), avoiding shell-injection
   on the command path. Per-request correlation via a pending-id map bounds the
   protocol state machine.
 - **Residual risks:** Both clients default the child's environment to the
-  **full `process.env`** when `opts.env` is absent — `acp-client.cjs` line 102
+  **full `process.env`** when `opts.env` is absent - `acp-client.cjs` line 102
   (`const env = opts.env && typeof opts.env === 'object' ? opts.env :
   process.env;`) and `asp-client.cjs` line 122 (when `opts.env` is absent no
   `spawnOptions.env` is set, so the child inherits the parent's `process.env` by
@@ -197,11 +197,11 @@ third-party CLI whose stdout the broker parses.
 
 ---
 
-## Component 4 — WebSocket event-stream transport (scripts/lib/transports/ws.cjs)
+## Component 4 - WebSocket event-stream transport (scripts/lib/transports/ws.cjs)
 
 `scripts/lib/transports/ws.cjs` exposes the event-stream bus over WebSocket:
 one JSON event per text frame, with optional replay of a tail file to each new
-connection. It is an **optional dependency** (`ws`) — absent installs render an
+connection. It is an **optional dependency** (`ws`) - absent installs render an
 install hint instead of starting. When running, it is a network listener.
 
 - **Assets:** The **event stream itself** (every `state.mutation` /
@@ -213,11 +213,11 @@ install hint instead of starting. When running, it is a network listener.
 - **STRIDE threats:**
   - **Spoofing:** A client without the token attempting to subscribe to the
     live event stream.
-  - **Tampering:** N/A for inbound (the transport is push-only to clients) —
+  - **Tampering:** N/A for inbound (the transport is push-only to clients) -
     the concern is read access, not write.
   - **Repudiation:** No per-connection identity beyond the shared token, so
     individual subscribers are not distinguishable in an audit.
-  - **Information disclosure:** **The headline risk** — an unauthorized
+  - **Information disclosure:** **The headline risk** - an unauthorized
     subscriber would receive the entire live event stream, including any
     sensitive payload detail, if it could reach the socket and pass auth.
   - **Denial of service:** Many connections / a slow consumer could pressure
@@ -227,12 +227,12 @@ install hint instead of starting. When running, it is a network listener.
 - **Current mitigations:** **Bearer-token auth is enforced on every upgrade**:
   `ws.cjs` lines 110–116 reject any upgrade whose header is missing or where
   the supplied token does not match the expected `Bearer` value, returning an `HTTP/1.1 401 Unauthorized` and a
-  socket destroy. The token **must be ≥8 chars** — `startServer` throws a
+  socket destroy. The token **must be ≥8 chars** - `startServer` throws a
   `TypeError` if `opts.token.length < 8` (line 74), preventing trivially weak
   tokens. Backpressure is **fire-and-forget with no queue** (lines 91–108):
   events for a non-OPEN socket are dropped, bounding memory under a slow
   consumer. Cross-cutting for the whole bus: **`redact.cjs`** deep-walks every
-  event payload at serialize time (`scripts/lib/redact.cjs` — `redact()` lines
+  event payload at serialize time (`scripts/lib/redact.cjs` - `redact()` lines
   95–116, `redactString()` lines 75–83) and scrubs **8 secret patterns** (pem,
   jwt, anthropic `sk-ant-`, stripe `sk_live_`, slack `xox[baprs]`, github_pat
   `ghp_`, aws `AKIA`, generic `sk-`), so secrets in event payloads are masked
@@ -240,7 +240,7 @@ install hint instead of starting. When running, it is a network listener.
   the runtime's primary information-disclosure control across **all** components
   that emit events.
 - **Residual risks:**
-  - The server binds to **all interfaces (`0.0.0.0`)** by default —
+  - The server binds to **all interfaces (`0.0.0.0`)** by default -
     `httpServer.listen(opts.port, ...)` (line 145) passes **no host argument**,
     so on a multi-homed / LAN host the token-protected stream is reachable
     off-box. The token compare uses `!==` (line 112), which is
@@ -256,7 +256,7 @@ install hint instead of starting. When running, it is a network listener.
 
 ---
 
-## Component 5 — Issue-reporter outbound (gh CLI only)
+## Component 5 - Issue-reporter outbound (gh CLI only)
 
 `scripts/lib/issue-reporter/` is the only first-party feature that intentionally
 reaches the network. It assembles a bug report and submits it through the user's
@@ -271,25 +271,25 @@ model).
   from local state); the `.design/config.json` and the env that gate whether the
   reporter runs at all.
 - **STRIDE threats:**
-  - **Spoofing:** A forged destination could try to receive reports — mitigated
+  - **Spoofing:** A forged destination could try to receive reports - mitigated
     by the frozen destination below.
   - **Tampering:** Attempting to redirect submissions to an attacker repo by
     injecting a destination override.
   - **Repudiation:** Submissions flow through `gh` under the user's identity,
     which is itself the attribution record.
-  - **Information disclosure:** **The headline risk** — a report could exfiltrate
+  - **Information disclosure:** **The headline risk** - a report could exfiltrate
     secrets / PII embedded in local state if the payload were not scrubbed.
-  - **Denial of service:** Not a meaningful vector — submission is a
+  - **Denial of service:** Not a meaningful vector - submission is a
     user-initiated, one-shot CLI call.
   - **Elevation of privilege:** Using the user's `gh` credentials beyond the
     single sanctioned submit.
-- **Current mitigations (ALREADY shipped — documented, no change here):**
+- **Current mitigations (ALREADY shipped - documented, no change here):**
   - **Outbound is via the `gh` CLI ONLY.** `gh-submit.cjs` wraps
     `gh issue create --repo <DESTINATION_REPO> --title … --body-file …` and is
     explicit that "the user's gh CLI is the sole outbound primitive. No HTTP-S
     URL literals, no global fetch primitive, no plugin-side credentials" (D-05).
     There is no raw HTTP egress in this subtree.
-  - **Frozen destination.** `destination.cjs` is an `Object.freeze`-d module —
+  - **Frozen destination.** `destination.cjs` is an `Object.freeze`-d module -
     the single source of truth for the destination repo, with **no env-var
     lookup, no config override, no flag override**. A static CI gate asserts it
     is the only file under the report-issue tree that contains the destination
@@ -302,7 +302,7 @@ model).
   - Payloads pass through privacy-diff / consent-prompt machinery before
     submission, and event telemetry is redacted by `redact.cjs` (Component 4).
 - **Residual risks:** The issue-reporter's **own** network model has no residual
-  this phase changes — it is intentionally documented as complete. The only
+  this phase changes - it is intentionally documented as complete. The only
   cross-cutting residual touching it is the **lack of a machine-readable
   outbound allowlist + CI gate** that proves `gh-submit` is the sole egress in
   this subtree at a tree-wide level: closed by **33.5-02** (the canonical
@@ -312,10 +312,10 @@ model).
 
 ---
 
-## Component 6 — OpenRouter catalog fetcher (scripts/lib/openrouter/catalog-fetcher.cjs)
+## Component 6 - OpenRouter catalog fetcher (scripts/lib/openrouter/catalog-fetcher.cjs)
 
 > Added in Phase 33.6 (OR-01, CONTEXT D-06). This is the runtime's **first
-> plugin-side outbound REST client** — the issue-reporter (Component 5) reaches
+> plugin-side outbound REST client** - the issue-reporter (Component 5) reaches
 > the network only through the user's `gh` CLI, and the WS transport (Component
 > 4) is a *server*, not an outbound client. The catalog fetcher is the first
 > first-party code to open an outbound HTTP request to a third-party host
@@ -326,7 +326,7 @@ model).
 OpenRouter model catalog (`https://openrouter.ai/api/v1/models`) through an
 **injectable `fetchImpl`** (default global `fetch`), maps the response into the
 `.design/cache/openrouter-models.json` cache shape, and writes it atomically.
-The live fetch is opt-in — gated on `OPENROUTER_API_KEY` being present at
+The live fetch is opt-in - gated on `OPENROUTER_API_KEY` being present at
 runtime; absent it, the fetcher returns cached-if-any-else-null and tier
 resolution falls back to the native provider.
 
@@ -340,7 +340,7 @@ resolution falls back to the native provider.
     `OPENROUTER_BASE_URL`) could feed a forged catalog.
   - **Tampering:** A malformed/oversized `/models` body could try to corrupt the
     cache the resolver reads, or smuggle unexpected fields downstream.
-  - **Information disclosure:** **The headline risk** — leaking the
+  - **Information disclosure:** **The headline risk** - leaking the
     `OPENROUTER_API_KEY` by persisting it to the cache, logging it, or sending it
     to an unintended host.
   - **Denial of service:** A hung or slow host could stall the fetch; a giant
@@ -349,7 +349,7 @@ resolution falls back to the native provider.
     an attacker-chosen model id.
 - **Current mitigations:** The key is read from **`OPENROUTER_API_KEY` env only**,
   sent **solely** as an `Authorization: Bearer` request header, and is **never
-  persisted to the cache nor written to any log seam** — the cache shape carries
+  persisted to the cache nor written to any log seam** - the cache shape carries
   only `id`/`name`/`context_length`/`pricing`, and the mapper keeps **only** those
   fields, dropping everything else (the `/models` body is **mapped, never
   eval'd**). The cache write is **atomic** (per-pid temp + rename) into the
@@ -359,11 +359,11 @@ resolution falls back to the native provider.
   cached-if-any-else-null, bounding the DoS surface, and retries are **bounded**
   (max 3 attempts) on a jittered-backoff curve with `rate-guard` awareness.
   Egress is **allowlisted** via `scripts/lib/openrouter/**` in
-  `scripts/security/outbound-allowlist.json` — the only sanctioned outbound site
-  in that subtree — so the 33.5 `scan:outbound` gate proves no un-approved egress
+  `scripts/security/outbound-allowlist.json` - the only sanctioned outbound site
+  in that subtree - so the 33.5 `scan:outbound` gate proves no un-approved egress
   crept in. The **injectable `fetchImpl`** keeps the default `npm test` suite
-  hermetic (D-07) — no live network — and there is **no new HTTP dependency**
-  (global `fetch` + `sdk/primitives` only — D-10), avoiding both a new supply-chain
+  hermetic (D-07) - no live network - and there is **no new HTTP dependency**
+  (global `fetch` + `sdk/primitives` only - D-10), avoiding both a new supply-chain
   surface and the gate's `axios`/`node-fetch`/`undici` package patterns.
 - **Residual risks:** None this phase leaves open. The catalog is advisory data
   consumed by the tier-resolver heuristic (33.6-02), which already clamps to

package/reference/gemini-tools.md

@@ -3,7 +3,7 @@
 Last verified: 2026-04-24
 
 When a GDD skill references a Claude Code tool name, the Gemini runtime
-translates to the equivalent below. Skills do NOT need to branch — the tool
+translates to the equivalent below. Skills do NOT need to branch - the tool
 name in prose is authoritative; Gemini resolves via this map.
 
 ## Tool-name mapping
@@ -40,7 +40,7 @@ All 11 tools exposed by the server appear as `mcp__gdd_state__*` in Gemini.
 
 ## Known gaps
 
-- `Task` spawning: same as Codex — prefer `run_shell_command("npx gdd-sdk stage ...")`.
+- `Task` spawning: same as Codex - prefer `run_shell_command("npx gdd-sdk stage ...")`.
   See GEMINI.md for invocation details.
 - Gemini's `replace` has stricter uniqueness requirements than CC's Edit;
   when `old_string` appears more than once, Gemini requires context lines.
@@ -49,5 +49,5 @@ All 11 tools exposed by the server appear as `mcp__gdd_state__*` in Gemini.
 
 ---
 
-Last verified: 2026-04-24 — tool surface re-checked against Gemini CLI docs
+Last verified: 2026-04-24 - tool surface re-checked against Gemini CLI docs
 current to this date. Revisit whenever Gemini ships a tool-vocabulary change.

package/reference/gestalt.md

@@ -3,9 +3,9 @@
 <!-- UUPM ux-guidelines.csv rows deduped into this file and heuristics.md/anti-patterns.md/priority-matrix.md — see .planning/research/uupm-import/ux-guidelines-reconciliation.md -->
 <!-- Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/ux-guidelines.csv (deduped) -->
 
-Gestalt psychology explains how the human visual system automatically organizes individual elements into coherent wholes. Designers who understand Gestalt principles can use them intentionally — grouping what belongs together, separating what is distinct, directing attention flow, and reducing cognitive effort. Designers who ignore these principles will inadvertently create layouts that confuse perception, because the visual system will apply Gestalt organization regardless of the designer's intent.
+Gestalt psychology explains how the human visual system automatically organizes individual elements into coherent wholes. Designers who understand Gestalt principles can use them intentionally - grouping what belongs together, separating what is distinct, directing attention flow, and reducing cognitive effort. Designers who ignore these principles will inadvertently create layouts that confuse perception, because the visual system will apply Gestalt organization regardless of the designer's intent.
 
-The eight principles below are not rules to follow in isolation — they interact. A single design decision often activates multiple principles simultaneously. The audit checklist at the end of this file helps identify where principles are being violated or underutilized.
+The eight principles below are not rules to follow in isolation - they interact. A single design decision often activates multiple principles simultaneously. The audit checklist at the end of this file helps identify where principles are being violated or underutilized.
 
 ---
 
@@ -13,11 +13,11 @@ The eight principles below are not rules to follow in isolation — they interac
 
 **Definition:** Elements that are physically close to each other are perceived as belonging to the same group, regardless of their visual appearance. Distance communicates separation; closeness communicates relationship.
 
-**Design application:** Related controls — a label and its input, an action button and its target, a heading and its body text — should be separated by no more than 8px. Unrelated elements should be separated by at least 32px. When this discipline is applied consistently, users read the layout's meaning before reading its content: the structure itself communicates relationships. Proximity is the most fundamental grouping tool available, and it costs nothing but intentionality.
+**Design application:** Related controls - a label and its input, an action button and its target, a heading and its body text - should be separated by no more than 8px. Unrelated elements should be separated by at least 32px. When this discipline is applied consistently, users read the layout's meaning before reading its content: the structure itself communicates relationships. Proximity is the most fundamental grouping tool available, and it costs nothing but intentionality.
 
 Proximity violations are among the most common layout defects. The symptom is a layout where users do not immediately know which label belongs to which input, or which button acts on which content area. The fix is almost always to increase the distance between unrelated groups and decrease the distance within groups.
 
-**Scoring rubric — audit by looking for:**
+**Scoring rubric - audit by looking for:**
 - Label-to-input gap: should be ≤8px; flag anything ≥16px
 - Button-to-target gap: a button that acts on a specific element should be adjacent to it, not floating at a distance
 - Section separation: distinct content sections should be separated by ≥32px; flag sections that bleed into each other
@@ -35,13 +35,13 @@ p-0     # elements with no internal padding may create proximity confusion at bo
 
 ## 2. Similarity
 
-**Definition:** Elements that share visual properties — color, shape, size, texture, or orientation — are perceived as belonging to the same category. The visual system uses similarity as a shortcut for classification: if it looks the same, it is the same kind of thing.
+**Definition:** Elements that share visual properties - color, shape, size, texture, or orientation - are perceived as belonging to the same category. The visual system uses similarity as a shortcut for classification: if it looks the same, it is the same kind of thing.
 
-**Design application:** Consistency in visual treatment is not merely an aesthetic preference — it communicates semantic meaning. All primary buttons should look identical: same size, same color, same weight. All destructive actions should look identical: same red, same border treatment, same position relative to the confirm/cancel pair. All secondary navigation items should be visually indistinguishable from each other. When similar-role elements look different, users assume they are different kinds of things, which creates confusion and erodes trust in the interface's logic.
+**Design application:** Consistency in visual treatment is not merely an aesthetic preference - it communicates semantic meaning. All primary buttons should look identical: same size, same color, same weight. All destructive actions should look identical: same red, same border treatment, same position relative to the confirm/cancel pair. All secondary navigation items should be visually indistinguishable from each other. When similar-role elements look different, users assume they are different kinds of things, which creates confusion and erodes trust in the interface's logic.
 
-Icon weight is one of the most commonly violated similarity contexts. Mixing outline icons with filled icons signals two different visual registers that users will try to interpret as meaningful — even when the mixing is accidental.
+Icon weight is one of the most commonly violated similarity contexts. Mixing outline icons with filled icons signals two different visual registers that users will try to interpret as meaningful - even when the mixing is accidental.
 
-**Scoring rubric — audit by looking for:**
+**Scoring rubric - audit by looking for:**
 - Button variants: are all primary buttons identical? Are all secondary buttons identical? Flag mixed variants on the same screen.
 - Icon weight: are all icons from the same weight family (all outline or all filled)? Flag mixing.
 - List items: do all items in a list have identical visual treatment? Flag items that are visually distinct without a semantic reason.
@@ -60,11 +60,11 @@ variant="primary"            # audit all variant prop usages for consistency
 
 **Definition:** The eye naturally follows lines, curves, and paths in the direction they are already moving. When elements are aligned along an invisible axis, the eye connects them into a continuous flow and expects the line to continue.
 
-**Design application:** Use alignment to create invisible flow lines that direct the eye through the layout in the intended sequence. Left-aligned content columns create a strong left-edge flow line that the eye tracks downward. A row of icons creates a horizontal flow line. A step indicator with connected segments creates a continuous path that the eye follows from start to finish. Carousels and horizontal scrollers leverage continuity by partially revealing the next item — the visible edge implies that more content continues in the same direction.
+**Design application:** Use alignment to create invisible flow lines that direct the eye through the layout in the intended sequence. Left-aligned content columns create a strong left-edge flow line that the eye tracks downward. A row of icons creates a horizontal flow line. A step indicator with connected segments creates a continuous path that the eye follows from start to finish. Carousels and horizontal scrollers use continuity by partially revealing the next item - the visible edge implies that more content continues in the same direction.
 
-Continuity is disrupted when elements break expected alignment without a purposeful reason. An element that juts out of an otherwise aligned column creates a visual interrupt — which can be used intentionally to draw attention, or accidentally to create confusion.
+Continuity is disrupted when elements break expected alignment without a purposeful reason. An element that juts out of an otherwise aligned column creates a visual interrupt - which can be used intentionally to draw attention, or accidentally to create confusion.
 
-**Scoring rubric — audit by looking for:**
+**Scoring rubric - audit by looking for:**
 - Alignment consistency: are all left-aligned elements aligned to the same grid column? Flag arbitrary left-offset elements.
 - Step indicators: does the visual path between steps flow clearly? Flag broken or visually interrupted step flows.
 - Carousel edge reveals: does the last visible item partially reveal the next? Flag carousels that do not imply continuation.
@@ -83,11 +83,11 @@ translate-x # horizontal animation — verify it implies continuity, not arbitra
 
 **Definition:** The human visual system actively completes incomplete shapes, filling in missing information to perceive a whole. Users will "see" a rectangle even if its corners are open, or a circle even if its arc is broken, because the mind prefers complete, recognizable forms over fragments.
 
-**Design application:** Closure is widely used in logos and icons to create forms that feel complete while being visually light. In UI, closure explains why partial borders can suggest containment without a full rectangle: a top border on a card, or a left border on a quoted text block, implies a region even without three additional sides. Progress indicators with open ends imply continuation; closed rings imply completion. Skeleton loading states use closure — partial shapes that the user's mind completes as content — to make loading feel purposeful rather than empty.
+**Design application:** Closure is widely used in logos and icons to create forms that feel complete while being visually light. In UI, closure explains why partial borders can suggest containment without a full rectangle: a top border on a card, or a left border on a quoted text block, implies a region even without three additional sides. Progress indicators with open ends imply continuation; closed rings imply completion. Skeleton loading states use closure - partial shapes that the user's mind completes as content - to make loading feel purposeful rather than empty.
 
 Closure can also be violated: a progress bar that ends before reaching the container's right edge correctly communicates incompletion, but if it ends at an arbitrary position with no visual context, users may perceive a broken UI rather than a progress state.
 
-**Scoring rubric — audit by looking for:**
+**Scoring rubric - audit by looking for:**
 - Progress indicators: does the fill/track relationship clearly communicate completion percentage? Flag indicators where progress direction is ambiguous.
 - Partial borders: do partial borders clearly imply the group they define? Flag partial borders that could be mistaken for decorative rules.
 - Skeleton states: do skeleton shapes meaningfully correspond to the content they represent? Flag skeletons that are too abstract to prime recognition.
@@ -109,9 +109,9 @@ w-1/2        # partial fill — verify progress context is established by contai
 
 **Design application:** Every interactive element, content region, and overlay depends on successful figure-ground separation. Modal dialogs work because the scrim pushes the page content to ground and the dialog to figure. Buttons work because their filled background distinguishes them from the text-on-ground surrounding them. Navigation bars work because their elevated background separates them from the page content they sit above.
 
-The practical rule: foreground elements must have at least 3:1 contrast ratio against their background, and for text, 4.5:1 for body text (WCAG AA). But figure-ground extends beyond contrast — blur, shadow, and opacity all contribute. A high-contrast element on a cluttered background may still fail to read as figure if the background is too visually active.
+The practical rule: foreground elements must have at least 3:1 contrast ratio against their background, and for text, 4.5:1 for body text (WCAG AA). But figure-ground extends beyond contrast - blur, shadow, and opacity all contribute. A high-contrast element on a cluttered background may still fail to read as figure if the background is too visually active.
 
-**Scoring rubric — audit by looking for:**
+**Scoring rubric - audit by looking for:**
 - Modal scrim: is the background content pushed to ground with sufficient opacity or blur? Flag modals where the page behind is at full visibility and full saturation.
 - Button states: do buttons clearly read as figure against all surface colors they appear on? Flag buttons with insufficient background contrast.
 - Active navigation items: are selected/active states clearly distinguished from non-selected? Flag flat navigation with only a color difference.
@@ -129,13 +129,13 @@ opacity-0.*opacity-100  # transition — verify figure emerges cleanly from grou
 
 ## 6. Common Fate
 
-**Definition:** Elements that move together — in the same direction, at the same speed, and with the same timing — are perceived as belonging to the same group, even if they are spatially separated. Movement is a powerful grouping signal precisely because it overrides static proximity and similarity cues.
+**Definition:** Elements that move together - in the same direction, at the same speed, and with the same timing - are perceived as belonging to the same group, even if they are spatially separated. Movement is a powerful grouping signal precisely because it overrides static proximity and similarity cues.
 
-**Design application:** When a group of elements should be perceived as a unit, animate them with shared timing. A card that expands while its child elements simultaneously rearrange communicates that the card and its contents are one object. A list that reorders with synchronized item movement communicates that the list is a coherent set. Conversely, animating elements at different speeds signals that they are independent objects — which can be used to establish hierarchy (parent first, then children) by staggering their entrance timing.
+**Design application:** When a group of elements should be perceived as a unit, animate them with shared timing. A card that expands while its child elements simultaneously rearrange communicates that the card and its contents are one object. A list that reorders with synchronized item movement communicates that the list is a coherent set. Conversely, animating elements at different speeds signals that they are independent objects - which can be used to establish hierarchy (parent first, then children) by staggering their entrance timing.
 
 Staggered animation (where sub-elements enter sequentially with a small delay) is a specific application of common fate that establishes a visual hierarchy within a group: the first element that moves is perceived as most important, and the trailing elements are perceived as its dependents.
 
-**Scoring rubric — audit by looking for:**
+**Scoring rubric - audit by looking for:**
 - Group animations: when a container appears or changes, do its children animate with it or independently? Flag children that animate on unrelated timings.
 - List reorder: when items reorder, do they move with shared timing that communicates the reorder as one operation? Flag lists where individual items move asynchronously.
 - Exit animations: when a group exits, do all elements leave together? Flag cases where parts of a group exit before the container.
@@ -152,13 +152,13 @@ delay-[0-9]             # stagger implementation — verify delay communicates h
 
 ## 7. Common Region
 
-**Definition:** Elements enclosed within a clearly defined boundary — a border, a background color, a shadow, or any other perceptual container — are perceived as belonging to the same group, even if they are not close to each other. Common region overrides proximity: two elements far apart within the same bounded region are perceived as more related than two elements close together on either side of a region boundary.
+**Definition:** Elements enclosed within a clearly defined boundary - a border, a background color, a shadow, or any other perceptual container - are perceived as belonging to the same group, even if they are not close to each other. Common region overrides proximity: two elements far apart within the same bounded region are perceived as more related than two elements close together on either side of a region boundary.
 
-**Design application:** Cards, panels, table rows, form field groups, and toolbars all leverage common region by using visual boundaries to say "these things go together." The boundary does not need to be a literal border — a distinct background color works equally well. This is why alternating row colors in a data table immediately communicate that each row is a distinct unit, and why a card with a white background on a grey page surface reads as a contained group without needing a border.
+**Design application:** Cards, panels, table rows, form field groups, and toolbars all use common region by using visual boundaries to say "these things go together." The boundary does not need to be a literal border - a distinct background color works equally well. This is why alternating row colors in a data table immediately communicate that each row is a distinct unit, and why a card with a white background on a grey page surface reads as a contained group without needing a border.
 
 Common region is also useful for communicating hierarchy: nested regions (a card within a page, a sub-section within a card) communicate nested relationships. The visual boundary at each level tells the eye exactly how far a group extends.
 
-**Scoring rubric — audit by looking for:**
+**Scoring rubric - audit by looking for:**
 - Card boundaries: do cards have a visible boundary (shadow, border, or background) that clearly separates them from their surroundings? Flag cards that blend into the page surface.
 - Form groups: are related form fields visually grouped within a shared container? Flag forms where field groups are separated only by vertical spacing without a region signal.
 - Table rows: are table rows distinguishable as individual regions? Flag tables with no row separation signal.
@@ -178,11 +178,11 @@ divide-y                # table row divider — check if combined with sufficien
 
 **Definition:** The visual system always interprets ambiguous inputs in the simplest possible way. When multiple interpretations of a visual input are possible, the mind chooses the interpretation that requires the least cognitive work. Complexity is resolved toward simplicity automatically.
 
-**Design application:** Prefer simple, recognizable shapes over complex, irregular ones. Remove any visual element that does not communicate something. Every decoration that does not carry meaning adds to the cognitive load the user must process before reaching the content that actually matters. This is the principle behind minimalism in UI design — not because minimalism is aesthetically superior, but because unnecessary visual complexity consumes perceptual resources that should be directed at the interface's actual purpose.
+**Design application:** Prefer simple, recognizable shapes over complex, irregular ones. Remove any visual element that does not communicate something. Every decoration that does not carry meaning adds to the cognitive load the user must process before reaching the content that actually matters. This is the principle behind minimalism in UI design - not because minimalism is aesthetically superior, but because unnecessary visual complexity consumes perceptual resources that should be directed at the interface's actual purpose.
 
 Prägnanz also implies that when two layouts can communicate the same information, the simpler one is better. A three-color palette is simpler to parse than a seven-color palette, even if the seven-color palette is "more interesting." A consistent component structure is simpler to navigate than a varied one, even if the variation is intentional.
 
-**Scoring rubric — audit by looking for:**
+**Scoring rubric - audit by looking for:**
 - Decorative elements: identify any visual element that serves no communicative purpose. Flag gradients, textures, and ornamental icons that do not carry semantic meaning.
 - Color count: how many distinct colors appear on a single screen? Flag screens with more than 4–5 distinct colors where the additional colors are not semantically required.
 - Shadow and border redundancy: are both shadow and border used simultaneously on the same element without a reason? Flag redundant depth cues.
@@ -206,7 +206,7 @@ Use this checklist when auditing a screen for Gestalt compliance. Each item maps
 
 2. **Similarity check:** Do all elements of the same semantic role share identical visual treatment? Primary buttons match primary buttons. Destructive actions match destructive actions. Icons use consistent weight. Flag any visual inconsistency that users might interpret as a semantic difference.
 
-3. **Continuity check:** Does the layout create a clear reading path through its most important content? Can you trace an invisible line — horizontal, vertical, or diagonal — that connects the primary focal points in intended viewing order? Flag layouts where the reading path requires backtracking.
+3. **Continuity check:** Does the layout create a clear reading path through its most important content? Can you trace an invisible line - horizontal, vertical, or diagonal - that connects the primary focal points in intended viewing order? Flag layouts where the reading path requires backtracking.
 
 4. **Closure check:** Are any incomplete shapes used? If so, do they close convincingly at the display size and resolution? Do progress indicators clearly communicate fill direction and completion scale? Flag ambiguous incomplete shapes.