@hegemonart/get-design-done 1.42.0 → 1.44.0

package/reference/notification-routing.md

@@ -1,4 +1,4 @@
-# Notification Routing — the event→channel contract for `scripts/lib/notify/dispatch.cjs`
+# Notification Routing - the event→channel contract for `scripts/lib/notify/dispatch.cjs`
 
 How GDD routes pipeline events to the Team-Surfaces notification channels (Slack + Discord), redacts every outbound body, and degrades to a noop when a channel is unconfigured or disabled. Consumed by `scripts/lib/notify/dispatch.cjs`; the channel specs are `connections/slack.md` + `connections/discord.md`.
 
@@ -12,7 +12,7 @@ Event type → channels (overridable via `.design/config.json#notifications.rout
 |---|---|---|
 | `verify_fail` | a verify must-have failed | slack + discord (the "critical" surface) |
 | `audit_pass` | an audit cleared the quality floor | slack + discord (the "digest" surface) |
-| `ship` | a PR was created (`/gdd:ship`) | slack + discord (digest — PR URL + top-line audit) |
+| `ship` | a PR was created (`/gdd:ship`) | slack + discord (digest - PR URL + top-line audit) |
 
 A user narrows or splits this in `.design/config.json`:
 
@@ -28,7 +28,7 @@ A user narrows or splits this in `.design/config.json`:
 
 Unlisted event types route to nothing (no notification). Unknown channels are skipped.
 
-## Redaction (mandatory — the single chokepoint)
+## Redaction (mandatory - the single chokepoint)
 
 `dispatch(event)` builds the outbound body as `redact(summary + "\n" + details)` using `scripts/lib/redact.cjs` (11 secret/token patterns, Phase 22 + 33.5) **before** any POST. There is exactly one egress chokepoint; no notify path constructs an un-redacted outbound body. The static test `test/suite/notify-privacy-guard.test.cjs` asserts every `scripts/lib/notify/*.cjs` references `redact`.
 
@@ -43,12 +43,12 @@ A channel is a noop when **either**:
 
 ## Outbound transport (no SDK, injectable, allowlisted)
 
-`dispatch(event, { fetchImpl, config, env })` POSTs `{ <field>: body }` to the channel's webhook URL (Slack `text`, Discord `content`) via an **injectable `fetchImpl`** (defaults to global `fetch`) — **no `@slack/*` / `discord.js` dependency** (D-02). Tests inject a stub fetchImpl (no live network — D-08). The module is allowlisted under the Phase-33.5 outbound gate (`scripts/security/outbound-allowlist.json` → `scripts/lib/notify/**`) with a threat-model egress entry.
+`dispatch(event, { fetchImpl, config, env })` POSTs `{ <field>: body }` to the channel's webhook URL (Slack `text`, Discord `content`) via an **injectable `fetchImpl`** (defaults to global `fetch`) - **no `@slack/*` / `discord.js` dependency** (D-02). Tests inject a stub fetchImpl (no live network - D-08). The module is allowlisted under the Phase-33.5 outbound gate (`scripts/security/outbound-allowlist.json` → `scripts/lib/notify/**`) with a threat-model egress entry.
 
 ## Degrade-to-noop (never blocks the pipeline)
 
-For each routed channel, a missing webhook URL → `skipped (not_configured)`; kill-switch on → `skipped (disabled)`; a POST failure → `error` (logged, not thrown). `dispatch` returns `Array<{ channel, status, reason? }>` and **never throws** — notification delivery is a best-effort side surface, never a pipeline gate (D-03).
+For each routed channel, a missing webhook URL → `skipped (not_configured)`; kill-switch on → `skipped (disabled)`; a POST failure → `error` (logged, not thrown). `dispatch` returns `Array<{ channel, status, reason? }>` and **never throws** - notification delivery is a best-effort side surface, never a pipeline gate (D-03).
 
 ## Out of scope (per Phase 35 split)
 
-Linear/Jira ticket-sync (Phase 35.3); PR-inline (35.1); `pseudonymize.cjs` identity-masking (Phase 30 — wired when available; redact for secrets is the must here); Microsoft Teams; rich blocks/embeds (plain text in v1); scheduled digests (event-driven only).
+Linear/Jira ticket-sync (Phase 35.3); PR-inline (35.1); `pseudonymize.cjs` identity-masking (Phase 30 - wired when available; redact for secrets is the must here); Microsoft Teams; rich blocks/embeds (plain text in v1); scheduled digests (event-driven only).

package/reference/onboarding-progressive-disclosure.md

@@ -1,6 +1,6 @@
 # Onboarding & Progressive Disclosure
 
-New-user experience is the highest-leverage surface in any product. A user who does not reach the aha moment in the first session almost never returns. These guidelines encode the research and failure patterns accumulated across thousands of product launches into concrete, actionable rules.
+New-user experience is the highest-impact surface in any product. A user who does not reach the aha moment in the first session almost never returns. These guidelines encode the research and failure patterns accumulated across thousands of product launches into concrete, actionable rules.
 
 ---
 
@@ -10,16 +10,16 @@ Four dominant patterns exist for first-run experiences. Choosing the wrong one f
 
 | Pattern | When to use | Cognitive load | Completion rate signal | Best for product type |
 |---|---|---|---|---|
-| **Empty-state onboarding** | Product value is only visible once data exists; blank canvas is the default state | Low — user acts on their own terms | First meaningful action taken (e.g. first item created) | Creation tools, CRMs, project trackers |
-| **Product tour** | Interface is dense or non-obvious; terminology requires context | Medium — user is passive during tour | Tour completion rate (misleading — see note) | Feature-rich SaaS dashboards, admin tools |
-| **Checklist-style** | Value comes from setup completion; multiple required steps exist | Medium-high — visible task debt | Checklist completion %, items checked per session | Configuration-heavy tools, integrations |
+| **Empty-state onboarding** | Product value is only visible once data exists; blank canvas is the default state | Low - user acts on their own terms | First meaningful action taken (e.g. first item created) | Creation tools, CRMs, project trackers |
+| **Product tour** | Interface is dense or non-obvious; terminology requires context | Medium - user is passive during tour | Tour completion rate (misleading - see note) | Feature-rich SaaS dashboards, admin tools |
+| **Checklist-style** | Value comes from setup completion; multiple required steps exist | Medium-high - visible task debt | Checklist completion %, items checked per session | Configuration-heavy tools, integrations |
 | **Progressive disclosure** | Product has many features but a clear primary use case; depth should follow intent | Low at entry, scales with engagement | Feature adoption breadth over time | Consumer apps, platforms with power users |
 
-**Empty-state onboarding** works because the blank state communicates what belongs there. A well-designed empty state — with a clear headline, one CTA, and an illustrative hint — removes the need for any separate tutorial. The first action the user takes is the onboarding. The empty state must not look like an error; it should look like an invitation. Use an illustration or icon that visually previews the populated state, so users understand what they are working toward.
+**Empty-state onboarding** works because the blank state communicates what belongs there. A well-designed empty state - with a clear headline, one CTA, and an illustrative hint - removes the need for any separate tutorial. The first action the user takes is the onboarding. The empty state must not look like an error; it should look like an invitation. Use an illustration or icon that visually previews the populated state, so users understand what they are working toward.
 
-**Product tours** have notoriously misleading completion metrics. A user who clicks through all seven steps of a tour has not learned the product; they have dismissed it. Tours are most defensible when they label unfamiliar terminology (e.g. "This is your Workspace — all your projects live here") rather than demonstrating features the user should simply use. If you do run a tour, keep it to five steps maximum, make every step skippable, and allow re-entry from a persistent help menu.
+**Product tours** have notoriously misleading completion metrics. A user who clicks through all seven steps of a tour has not learned the product; they have dismissed it. Tours are most defensible when they label unfamiliar terminology (e.g. "This is your Workspace - all your projects live here") rather than demonstrating features the user should simply use. If you do run a tour, keep it to five steps maximum, make every step skippable, and allow re-entry from a persistent help menu.
 
-**Checklist-style onboarding** creates explicit visible progress. The risk is that users who skip to step 4 feel the overhead of incomplete items above them. Keep checklists short (five items maximum) and mark steps as skippable where appropriate. Celebrate completion with a visual reward. Progress bars within checklists should start at roughly 20% complete before the user takes any action — starting at zero signals a daunting amount of work ahead.
+**Checklist-style onboarding** creates explicit visible progress. The risk is that users who skip to step 4 feel the overhead of incomplete items above them. Keep checklists short (five items maximum) and mark steps as skippable where appropriate. Celebrate completion with a visual reward. Progress bars within checklists should start at roughly 20% complete before the user takes any action - starting at zero signals a daunting amount of work ahead.
 
 **Progressive disclosure** is the correct default for most modern products. Surface only what is needed at each stage of the user's journey and reveal depth as intent emerges. The cost of this approach is instrumentation: you must know what your users are actually doing in order to know what to surface next. Without event tracking and funnel analysis, progressive disclosure devolves into guesswork about which features to promote and when.
 
@@ -32,14 +32,14 @@ Four dominant patterns exist for first-run experiences. Choosing the wrong one f
 Tooltips surface contextual information at the moment of relevance without blocking interaction. Follow these placement rules strictly:
 
 - Position tooltips above the target element by default; fall back to right, left, then below only when viewport space requires it.
-- Never place a tooltip over the element it describes — it should annotate without obscuring.
+- Never place a tooltip over the element it describes - it should annotate without obscuring.
 - A dismiss button (×) is required on any tooltip that is not triggered by hover alone. Users must always have a clear, explicit path to close.
 - Cap tooltip hints at **three per session**. A fourth tooltip in the same session means the user has seen enough hints that the interface should simply be better, not that more hints are needed.
 - Do not re-show a dismissed tooltip within the same session. Respecting the dismissal is the contract.
 
 ### Spotlight / Coach Marks
 
-Spotlight overlays draw attention to a specific UI element by dimming the surrounding interface. Use them only for genuinely non-obvious interaction points — elements whose purpose or location a reasonable user would not discover through normal exploration.
+Spotlight overlays draw attention to a specific UI element by dimming the surrounding interface. Use them only for genuinely non-obvious interaction points - elements whose purpose or location a reasonable user would not discover through normal exploration.
 
 Never use coach marks for:
 
@@ -65,7 +65,7 @@ Help icons, drawers, and inline `?` affordances provide depth on demand without
 - Place `?` icons immediately to the right of the label they annotate, at the same vertical center.
 - Use a help drawer (slide-in panel) when the content exceeds three sentences. Modals are inappropriate for help content because they block the interface the user is trying to understand.
 - Distinguish between hover-triggered tooltips (quick factual answers, ≤ 20 words) and click-triggered drawers (procedural explanations, examples, links to documentation).
-- Help icons should use a consistent icon throughout the product — do not mix `?`, `ℹ`, and `…` as help affordances in the same interface.
+- Help icons should use a consistent icon throughout the product - do not mix `?`, `ℹ`, and `…` as help affordances in the same interface.
 
 ---
 
@@ -83,9 +83,9 @@ Concretely: let the user reach their first meaningful outcome, then surface the
 
 These two metrics measure different things and should never be conflated:
 
-**Activation metric** — the event that indicates a user has experienced the product's core value for the first time. It is a binary event measured once. Examples: first project created, first file synced, first message sent.
+**Activation metric** - the event that indicates a user has experienced the product's core value for the first time. It is a binary event measured once. Examples: first project created, first file synced, first message sent.
 
-**Habituation metric** — the behavioral pattern that indicates a user has formed a habit around the product. It is a frequency measure over a time window. Examples: 3 sessions per week for 4 consecutive weeks, 5 actions per session on 7 of the last 10 days.
+**Habituation metric** - the behavioral pattern that indicates a user has formed a habit around the product. It is a frequency measure over a time window. Examples: 3 sessions per week for 4 consecutive weeks, 5 actions per session on 7 of the last 10 days.
 
 Activation predicts retention at day 7. Habituation predicts retention at day 30 and beyond. Optimizing only for activation produces users who try the product once and never return. Optimizing for habituation without a clear activation path means most users never get far enough to form the habit.
 
@@ -101,9 +101,9 @@ If your product genuinely requires more than three setup steps before value is d
 
 Users who land in a product for the first time are in a state of orienting, not learning. They are trying to understand whether the product is relevant to them, not how to become experts.
 
-Surface a "Start guided tour" CTA on the **second session**, not the first. By the second session, the user has self-selected — they came back, which means something in the first session was interesting enough to return to. They are now in a learning state, not an evaluation state, and will benefit from structured guidance.
+Surface a "Start guided tour" CTA on the **second session**, not the first. By the second session, the user has self-selected - they came back, which means something in the first session was interesting enough to return to. They are now in a learning state, not an evaluation state, and will benefit from structured guidance.
 
-First-session tutorials should be limited to a single contextual hint or a dismissible welcome banner — not a step-by-step walkthrough.
+First-session tutorials should be limited to a single contextual hint or a dismissible welcome banner - not a step-by-step walkthrough.
 
 ---
 
@@ -111,9 +111,9 @@ First-session tutorials should be limited to a single contextual hint or a dismi
 
 Within five seconds of landing on a product for the first time, users form judgments on three dimensions that are extremely difficult to revise:
 
-1. **Value proposition clarity** — Do I understand what this product does and who it is for?
-2. **Trust signals** — Does this look credible, maintained, and professional?
-3. **Visual confidence** — Does the design itself inspire confidence in the product's quality?
+1. **Value proposition clarity** - Do I understand what this product does and who it is for?
+2. **Trust signals** - Does this look credible, maintained, and professional?
+3. **Visual confidence** - Does the design itself inspire confidence in the product's quality?
 
 These are not conscious evaluations. They are fast, affective responses to visual and linguistic signals. A product that fails the 5-second test loses users before any feature or flow is ever reached.
 
@@ -122,9 +122,9 @@ These are not conscious evaluations. They are fast, affective responses to visua
 **What passing looks like:**
 - The headline names the outcome, not the mechanism ("Ship faster without context switching" rather than "A collaborative project management platform")
 - At least one social proof or trust signal is visible above the fold (customer count, recognizable logo, security badge)
-- The visual design is internally consistent — font pairing, spacing, and color are coherent enough that the product feels intentional
+- The visual design is internally consistent - font pairing, spacing, and color are coherent enough that the product feels intentional
 
-A screen that takes longer than five seconds to parse is not being evaluated — it is being abandoned.
+A screen that takes longer than five seconds to parse is not being evaluated - it is being abandoned.
 
 **Common failures:**
 
@@ -144,7 +144,7 @@ Run the 5-second test on every major entry point: homepage, onboarding email lan
 
 ### Defining the Aha Moment
 
-The aha moment is the first time a user experiences the core value the product was built to deliver. It is not a feature adoption event and not an engagement metric — it is the specific moment when the product's promise becomes real and personal to the user.
+The aha moment is the first time a user experiences the core value the product was built to deliver. It is not a feature adoption event and not an engagement metric - it is the specific moment when the product's promise becomes real and personal to the user.
 
 Without a defined aha moment, onboarding cannot be optimized because there is no agreed destination to optimize toward.
 
@@ -152,9 +152,9 @@ Without a defined aha moment, onboarding cannot be optimized because there is no
 
 The most cited aha moments in product history illustrate what the concept means in practice:
 
-- **Twitter**: Users who followed at least 10 accounts within their first 48 hours retained at a dramatically higher rate than those who did not. The aha moment was not "post a tweet" — it was "see a feed of people you actually care about."
+- **Twitter**: Users who followed at least 10 accounts within their first 48 hours retained at a dramatically higher rate than those who did not. The aha moment was not "post a tweet" - it was "see a feed of people you actually care about."
 - **Slack**: Teams that exchanged at least 2,000 messages retained at over 90%. The aha moment emerged from the accumulated experience of communication flow, not from any single interaction.
-- **Dropbox**: Users who synced at least one file experienced the aha moment. The product's promise — "your files everywhere" — only became real once the first file was genuinely accessible on a second device.
+- **Dropbox**: Users who synced at least one file experienced the aha moment. The product's promise - "your files everywhere" - only became real once the first file was genuinely accessible on a second device.
 
 In all three cases, the aha moment is an outcome state, not a feature interaction. This distinction matters for instrumentation.
 
@@ -162,11 +162,11 @@ In all three cases, the aha moment is an outcome state, not a feature interactio
 
 To find your product's aha moment, run the following analysis:
 
-1. **Define candidate activation events** — identify 5–10 behavioral events that plausibly represent first value (first export, first share, first search with results, first item added, etc.).
-2. **Build retention cohorts by activation event** — for each candidate event, create two cohorts: users who performed the event in their first session vs. users who did not. Measure day-7 and day-30 retention for each cohort.
-3. **Identify the event with the largest retention delta** — the event whose presence most strongly predicts that users will still be active 30 days later is your aha moment proxy.
-4. **Validate with qualitative research** — confirm with user interviews that users who performed the event actually experienced a moment of genuine value, not just navigated through a flow.
-5. **Reduce the time-to-aha** — once the event is identified, redesign onboarding to move the user toward that event as quickly as possible, removing every unnecessary step in between.
+1. **Define candidate activation events** - identify 5–10 behavioral events that plausibly represent first value (first export, first share, first search with results, first item added, etc.).
+2. **Build retention cohorts by activation event** - for each candidate event, create two cohorts: users who performed the event in their first session vs. users who did not. Measure day-7 and day-30 retention for each cohort.
+3. **Identify the event with the largest retention delta** - the event whose presence most strongly predicts that users will still be active 30 days later is your aha moment proxy.
+4. **Validate with qualitative research** - confirm with user interviews that users who performed the event actually experienced a moment of genuine value, not just navigated through a flow.
+5. **Reduce the time-to-aha** - once the event is identified, redesign onboarding to move the user toward that event as quickly as possible, removing every unnecessary step in between.
 
 The aha moment is a hypothesis that must be re-evaluated as the product evolves. A feature change or new user segment can shift the activation event.
 
@@ -180,17 +180,17 @@ A forced tour blocks access to the product until the user completes a tutorial s
 
 Users who complete forced tours do so under duress, not interest. Their completion rate looks healthy in analytics, but their recall of tour content is near zero. More critically, the forced-tour experience establishes a negative first emotional association with the product that carries forward into subsequent sessions.
 
-**Never gate the product behind tutorial completion.** The skip button is not a concession — it is a requirement.
+**Never gate the product behind tutorial completion.** The skip button is not a concession - it is a requirement.
 
 ### Blocking Modal Overlays
 
-Modal overlays that cover the interface to display instructional content are problematic on two grounds. First, they prevent the user from interacting with the very interface they are being instructed about — learning by doing is impossible when the interface is obscured. Second, full-screen modal overlays frequently fail WCAG 2.1 Success Criterion 1.3.4 (Orientation) and 2.1.2 (No Keyboard Trap) when implemented without proper focus management, making them inaccessible to keyboard and screen reader users.
+Modal overlays that cover the interface to display instructional content are problematic on two grounds. First, they prevent the user from interacting with the very interface they are being instructed about - learning by doing is impossible when the interface is obscured. Second, full-screen modal overlays frequently fail WCAG 2.1 Success Criterion 1.3.4 (Orientation) and 2.1.2 (No Keyboard Trap) when implemented without proper focus management, making them inaccessible to keyboard and screen reader users.
 
 Use inline empty states, contextual tooltips, or side drawers for instructional content. Reserve modals for actions that require a decision before proceeding, not for passive information delivery.
 
 ### Tooltip Spam
 
-Displaying more than three tooltips simultaneously creates cognitive overload. The user cannot process multiple concurrent annotations — they will either dismiss all of them without reading or abandon the session. Three concurrent tooltips is already at the upper threshold of what users will tolerate; two is better; one is the correct default.
+Displaying more than three tooltips simultaneously creates cognitive overload. The user cannot process multiple concurrent annotations - they will either dismiss all of them without reading or abandon the session. Three concurrent tooltips is already at the upper threshold of what users will tolerate; two is better; one is the correct default.
 
 If your interface requires more than three tooltips to be usable, the interface needs redesign, not more tooltips.
 
@@ -216,9 +216,9 @@ Onboarding is only improvable if it is measured. The following metrics form the
 
 **Activation rate** is the percentage of new users who reach the activation event within a defined window (typically 7 days). Baseline activation rates vary widely by product category, but any activation rate below 40% warrants investigation. An activation rate above 70% is a strong signal.
 
-**Onboarding funnel drop-off** tracks step-by-step completion rates through any sequential onboarding flow. Every step should be instrumented individually. Drop-off above 30% at any single step is a red flag requiring immediate qualitative investigation — user interviews, session recordings, or both.
+**Onboarding funnel drop-off** tracks step-by-step completion rates through any sequential onboarding flow. Every step should be instrumented individually. Drop-off above 30% at any single step is a red flag requiring immediate qualitative investigation - user interviews, session recordings, or both.
 
-**Feature discovery breadth** measures how many distinct features or feature areas a user touches in their first 14 days. Low breadth in early sessions is not necessarily a problem — focused users often have the highest retention — but anomalously low breadth combined with low retention indicates that users are not finding the product's range of value.
+**Feature discovery breadth** measures how many distinct features or feature areas a user touches in their first 14 days. Low breadth in early sessions is not necessarily a problem - focused users often have the highest retention - but anomalously low breadth combined with low retention indicates that users are not finding the product's range of value.
 
 | Metric | Healthy range | Warning threshold |
 |---|---|---|

package/reference/openrouter-tier-mapping.md

@@ -9,7 +9,7 @@ source of the mapping. Phase 33.6, decision D-03 (heuristic + override), D-04
 ## What it maps
 
 The plugin speaks one tier vocabulary everywhere a model tier is named in
-frontmatter or config: `opus`, `sonnet`, `haiku` — the same `VALID_TIERS` the
+frontmatter or config: `opus`, `sonnet`, `haiku` - the same `VALID_TIERS` the
 Phase-26 `tier-resolver.cjs` enforces. OpenRouter, by contrast, exposes a flat
 catalog of provider-prefixed model ids (`anthropic/claude-opus-4-7`,
 `meta-llama/llama-3.1-8b-instruct`, `qwen/qwen-2.5-72b-instruct`, …). The adapter
@@ -29,18 +29,18 @@ The adapter's public `resolve(tier)` always speaks `opus` / `sonnet` / `haiku`;
 ## The buckets
 
 - **opus (HIGH) = top-tier closed.** The most capable closed-vendor model in the
-  catalog — the priciest premium id from a closed namespace. This is the
+  catalog - the priciest premium id from a closed namespace. This is the
   "spare-no-expense, hardest reasoning" slot.
 - **sonnet (MEDIUM) = mid / top-open.** A capable model that sits below the opus
-  pick — typically the mid-priced closed model, or the strongest open model when
+  pick - typically the mid-priced closed model, or the strongest open model when
   no second closed tier is present. The everyday workhorse slot.
-- **haiku (LOW) = cheap open.** The cheapest capable OPEN model — the
+- **haiku (LOW) = cheap open.** The cheapest capable OPEN model - the
   fast/inexpensive slot for high-volume, low-stakes calls.
 
 ## The signals
 
 The heuristic is computed from fields already present on each catalog model, so it
-stays deterministic for a fixed catalog (no clock, no randomness — important so the
+stays deterministic for a fixed catalog (no clock, no randomness - important so the
 33.6-04 golden baseline is stable):
 
 - **Namespace (closed vs open).** The id prefix before the `/` names the vendor.
@@ -77,7 +77,7 @@ an exact catalog id via `.design/config.json`:
 ```
 
 An override **wins** over the heuristic: when `openrouter_tier_overrides[tier]` is a
-non-empty string, the adapter returns it verbatim — even if that id is not present
+non-empty string, the adapter returns it verbatim - even if that id is not present
 in the live catalog (the user's explicit choice is honored over catalog membership).
 Tests inject the same map via `opts.overrides` instead of reading the live config
 file, so the override path is exercised hermetically. The config read is best-effort:
@@ -86,12 +86,12 @@ rather than throwing.
 
 ## The graceful-null contract
 
-OpenRouter is opt-in ALONGSIDE native provider auth — never OpenRouter-only (D-08).
+OpenRouter is opt-in ALONGSIDE native provider auth - never OpenRouter-only (D-08).
 When no catalog is available (no cache, an empty `models[]`, or a `readCatalog` that
 returns null) AND no override applies to the requested tier, `resolve` returns
 `null`. A `null` is not an error: it is the signal that the caller (the router /
 budget-enforcer, wired in 33.6-03) should fall back to the native provider via the
-existing `scripts/lib/tier-resolver.cjs` fallback chain. The adapter NEVER throws —
+existing `scripts/lib/tier-resolver.cjs` fallback chain. The adapter NEVER throws -
 an unknown tier, a missing config, a corrupt cache, or garbage options all degrade to
 `null` (or to an override when one applies). This keeps OpenRouter a strictly
 additive capability: turning it off, or having it fail to fetch, can never break a

package/reference/palette-catalog.md

@@ -6,23 +6,23 @@ source: "nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/colors.csv"
 tags: [color, palette, wcag, industry]
 ---
 
-# Palette Catalog — Industry-Vertical Color Systems
+# Palette Catalog - Industry-Vertical Color Systems
 
 This catalog gives design agents and the brief-stage palette picker a pre-verified starting point for every major industry vertical. Rather than selecting colors ad-hoc, an agent reads the vertical row that matches the product type, adopts the baseline tokens, then adjusts tints and shades to establish brand uniqueness without sacrificing legibility.
 
 ## How to Use This Catalog
 
-**Step 1 — Identify the vertical.** Match the product type to the closest row. When a product spans verticals (e.g., a wellness fintech), prefer the primary revenue model as the anchor vertical and borrow the accent color from the secondary vertical.
+**Step 1 - Identify the vertical.** Match the product type to the closest row. When a product spans verticals (e.g., a wellness fintech), prefer the primary revenue model as the anchor vertical and borrow the accent color from the secondary vertical.
 
-**Step 2 — Adopt the baseline palette.** The hex values below represent the semantic center of each role: Primary, Secondary, Accent, Background, Foreground, Card, Muted, Border, Destructive. Downstream agents (design-executor, token-mapper) map these directly to CSS custom property names (`--color-primary`, `--color-secondary`, etc.).
+**Step 2 - Adopt the baseline palette.** The hex values below represent the semantic center of each role: Primary, Secondary, Accent, Background, Foreground, Card, Muted, Border, Destructive. Downstream agents (design-executor, token-mapper) map these directly to CSS custom property names (`--color-primary`, `--color-secondary`, etc.).
 
-**Step 3 — Cross-check brand voice.** Palette choice must align with the voice axis established in the brief. A palette that reads "authoritative navy" conflicts with a voice direction of "playful and irreverent." Resolve conflicts in favor of the voice axis — palettes are easier to shift than voice. For industry voice conventions, see `reference/brand-voice.md`.
+**Step 3 - Cross-check brand voice.** Palette choice must align with the voice axis established in the brief. A palette that reads "authoritative navy" conflicts with a voice direction of "playful and irreverent." Resolve conflicts in favor of the voice axis - palettes are easier to shift than voice. For industry voice conventions, see `reference/brand-voice.md`.
 
-**Step 4 — Adjust for brand uniqueness.** All values here are mid-point baselines. Shift the primary hue ±15°, adjust lightness ±10%, or introduce a proprietary tint to differentiate the brand. Do not use these hex values verbatim in production without at least one brand-distinguishing adjustment.
+**Step 4 - Adjust for brand uniqueness.** All values here are mid-point baselines. Shift the primary hue ±15°, adjust lightness ±10%, or introduce a proprietary tint to differentiate the brand. Do not use these hex values verbatim in production without at least one brand-distinguishing adjustment.
 
 **See:** [`./color-theory.md`](./color-theory.md) §Color Harmonies for the OKLCH model that grounds these hue-shift instructions (perceptual lightness preserved across hues; sRGB ±15° distorts perceived brightness asymmetrically across yellow/blue).
 
-**Step 5 — Verify pairing.** After choosing the palette, consult `reference/typography.md` for matching typeface pairings that reinforce the vertical's tone.
+**Step 5 - Verify pairing.** After choosing the palette, consult `reference/typography.md` for matching typeface pairings that reinforce the vertical's tone.
 
 ## WCAG Compliance Notes
 
@@ -30,8 +30,8 @@ All palettes in this catalog are designed to meet WCAG 2.1 AA as a baseline:
 
 - **Body text:** Foreground-on-Background must achieve a contrast ratio of at least **4.5:1**. All rows in this table satisfy this requirement at the listed values.
 - **UI elements (icons, borders, input outlines):** Must achieve at least **3:1** against their adjacent background. Verify muted and border values when used as sole affordance indicators.
-- **Destructive actions:** The Destructive color is always shown against white (On-Primary) — verify contrast when placed on colored backgrounds.
-- **Dark mode:** This catalog covers light-mode baselines. For dark mode, invert the lightness scale — Background moves to #0A0A0A–#1C1C1E range, Foreground to #F5F5F5, and Primary desaturates by 20% to reduce eye strain. See `reference/accessibility.md` for dark-mode token guidance.
+- **Destructive actions:** The Destructive color is always shown against white (On-Primary) - verify contrast when placed on colored backgrounds.
+- **Dark mode:** This catalog covers light-mode baselines. For dark mode, invert the lightness scale - Background moves to #0A0A0A–#1C1C1E range, Foreground to #F5F5F5, and Primary desaturates by 20% to reduce eye strain. See `reference/accessibility.md` for dark-mode token guidance.
 
 > Note: Neumorphism palettes are not represented here because they structurally fail WCAG contrast requirements in most implementations. If a brief requests a neumorphic style, escalate to design-advisor before proceeding with palette selection.
 
@@ -42,43 +42,43 @@ All palettes in this catalog are designed to meet WCAG 2.1 AA as a baseline:
 | FinTech/Banking | #1A56DB | #FFFFFF | #0E9F6E | #FFFFFF | #F05252 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #E02424 | Authoritative navy-blue signals trust and regulatory solidity; green secondary for positive account states and confirmations; red destructive for irreversible transfers and deletions. WCAG verified. |
 | Healthcare/Medical | #0E9F6E | #FFFFFF | #1A56DB | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #E02424 | Clinical green primary communicates health and safety; blue secondary for informational states; amber accent for caution alerts. Avoids emergency red as primary to prevent alarm. WCAG verified. |
 | SaaS/B2B Tools | #6875F5 | #FFFFFF | #0E9F6E | #FFFFFF | #F05252 | #FFFFFF | #111928 | #F9FAFB | #F3F4F6 | #E5E7EB | #E02424 | Periwinkle-purple primary is the contemporary B2B SaaS signal (productively calm, not boring blue); green secondary for success states; red destructive. Cards slightly off-white to create depth without shadows. WCAG verified. |
-| E-commerce/Retail | #D97706 | #FFFFFF | #1A56DB | #FFFFFF | #E02424 | #FFFFFF | #111928 | #F9FAFB | #FEF3C7 | #E5E7EB | #DC2626 | Amber primary drives purchase urgency and warmth; blue secondary for trust (payments, account); muted in warm-yellow family for promotional surfaces. Avoid pure red as primary — reserve for destructive/sale badges. WCAG verified. |
-| Gaming/Entertainment | #7E3AF2 | #FFFFFF | #FF8A4C | #111928 | #F05252 | #111928 | #F9FAFB | #1F2937 | #374151 | #4B5563 | #EF4444 | Deep violet primary on dark background — high visual energy without neon; amber accent for XP/reward moments; dark card on near-black background creates depth. Light foreground on dark background meets 4.5:1. WCAG verified. |
-| Social/Community | #3F83F8 | #FFFFFF | #0E9F6E | #FFFFFF | #F05252 | #FFFFFF | #111928 | #F9FAFB | #EFF6FF | #E5E7EB | #DC2626 | Friendly blue primary — approachable, not corporate; green for connection/online states; light muted sky for feed background separation. WCAG verified. |
+| E-commerce/Retail | #D97706 | #FFFFFF | #1A56DB | #FFFFFF | #E02424 | #FFFFFF | #111928 | #F9FAFB | #FEF3C7 | #E5E7EB | #DC2626 | Amber primary drives purchase urgency and warmth; blue secondary for trust (payments, account); muted in warm-yellow family for promotional surfaces. Avoid pure red as primary - reserve for destructive/sale badges. WCAG verified. |
+| Gaming/Entertainment | #7E3AF2 | #FFFFFF | #FF8A4C | #111928 | #F05252 | #111928 | #F9FAFB | #1F2937 | #374151 | #4B5563 | #EF4444 | Deep violet primary on dark background - high visual energy without neon; amber accent for XP/reward moments; dark card on near-black background creates depth. Light foreground on dark background meets 4.5:1. WCAG verified. |
+| Social/Community | #3F83F8 | #FFFFFF | #0E9F6E | #FFFFFF | #F05252 | #FFFFFF | #111928 | #F9FAFB | #EFF6FF | #E5E7EB | #DC2626 | Friendly blue primary - approachable, not corporate; green for connection/online states; light muted sky for feed background separation. WCAG verified. |
 | Developer Tools | #0F172A | #F8FAFC | #6875F5 | #FFFFFF | #22D3EE | #F8FAFC | #0F172A | #FFFFFF | #F1F5F9 | #CBD5E1 | #EF4444 | Near-black primary on white for precision and professionalism; purple secondary for interactive elements; cyan accent for syntax-highlight-inspired pops. Matches developer expectations set by GitHub, Linear, Vercel. WCAG verified. |
-| EdTech/Learning | #FF8A4C | #FFFFFF | #6875F5 | #FFFFFF | #0E9F6E | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #DC2626 | Warm amber primary is energizing and optimistic — signals motivation and focus; violet secondary for interactive quiz/exercise elements; warm background avoids clinical white. WCAG verified. |
-| Legal/Compliance | #1E3A5F | #FFFFFF | #374151 | #FFFFFF | #B45309 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Deep navy primary signals authority, gravity, and precision; slate secondary for neutral UI chrome; amber accent for deadlines and flagged items. No bright colors — the palette communicates seriousness. WCAG verified. |
-| HR/People Ops | #7E3AF2 | #FFFFFF | #FF8A4C | #FFFFFF | #0E9F6E | #FAF5FF | #111928 | #FFFFFF | #F3F4F6 | #E9D5FF | #DC2626 | Violet primary balances authority and empathy — appropriate for people-management contexts; amber secondary for recognition/reward surfaces; lavender muted for soft separation. WCAG verified. |
+| EdTech/Learning | #FF8A4C | #FFFFFF | #6875F5 | #FFFFFF | #0E9F6E | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #DC2626 | Warm amber primary is energizing and optimistic - signals motivation and focus; violet secondary for interactive quiz/exercise elements; warm background avoids clinical white. WCAG verified. |
+| Legal/Compliance | #1E3A5F | #FFFFFF | #374151 | #FFFFFF | #B45309 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Deep navy primary signals authority, gravity, and precision; slate secondary for neutral UI chrome; amber accent for deadlines and flagged items. No bright colors - the palette communicates seriousness. WCAG verified. |
+| HR/People Ops | #7E3AF2 | #FFFFFF | #FF8A4C | #FFFFFF | #0E9F6E | #FAF5FF | #111928 | #FFFFFF | #F3F4F6 | #E9D5FF | #DC2626 | Violet primary balances authority and empathy - appropriate for people-management contexts; amber secondary for recognition/reward surfaces; lavender muted for soft separation. WCAG verified. |
 | Real Estate/Property | #065F46 | #FFFFFF | #1A56DB | #FFFFFF | #B45309 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Deep forest green primary signals land, stability, and value; blue secondary for financing/trust contexts; amber accent for featured/premium listings. Avoids the overused real-estate red. WCAG verified. |
 | Travel/Hospitality | #1A56DB | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #EFF6FF | #111928 | #FFFFFF | #DBEAFE | #BFDBFE | #DC2626 | Sky blue primary evokes open skies and freedom; green secondary for bookings confirmed and eco-travel; warm amber accent for warmth of destination discovery. Sky-tinted muted background is distinctive. WCAG verified. |
-| Food/Delivery | #D97706 | #FFFFFF | #E02424 | #FFFFFF | #0E9F6E | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #B91C1C | Amber primary stimulates appetite and speed; red secondary for urgency (limited offers, spicy badge) — distinct from destructive red which is darker; warm background mirrors food photography warmth. WCAG verified. |
+| Food/Delivery | #D97706 | #FFFFFF | #E02424 | #FFFFFF | #0E9F6E | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #B91C1C | Amber primary stimulates appetite and speed; red secondary for urgency (limited offers, spicy badge) - distinct from destructive red which is darker; warm background mirrors food photography warmth. WCAG verified. |
 | Fitness/Wellness | #047857 | #FFFFFF | #1A56DB | #FFFFFF | #F05252 | #F0FDF4 | #111928 | #FFFFFF | #DCFCE7 | #BBF7D0 | #DC2626 | Saturated green primary signals vitality, growth, and health achievement; blue secondary for calm recovery/sleep contexts; red accent for intensity/max-effort moments. Green-tinted background reinforces wellness. WCAG verified. |
-| Non-profit/NGO | #065F46 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Deep green primary signals mission and environmental conscience; amber secondary for warmth and community; blue accent for data/impact reporting. Avoid corporate-looking palettes — earthy and grounded. WCAG verified. |
+| Non-profit/NGO | #065F46 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Deep green primary signals mission and environmental conscience; amber secondary for warmth and community; blue accent for data/impact reporting. Avoid corporate-looking palettes - earthy and grounded. WCAG verified. |
 | Government/Civic | #1E3A5F | #FFFFFF | #374151 | #FFFFFF | #D97706 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Deep navy is the global convention for government digital services (GOV.UK, USWDS, Australian DTA); slate secondary for dense information displays; amber accent for notices and alerts. Trust through convention. WCAG verified. |
-| Luxury/Fashion | #111928 | #F9FAFB | #374151 | #F9FAFB | #B45309 | #FFFFFF | #111928 | #F9FAFB | #F9FAFB | #E5E7EB | #DC2626 | Near-black primary on white background is the international language of luxury — Chanel, Saint Laurent, Bottega; slate secondary for layered surfaces; gold-amber accent for price points and premium badges. Minimum color = maximum status. WCAG verified. |
-| Media/Publishing | #111928 | #F9FAFB | #E02424 | #FFFFFF | #D97706 | #FFFFFF | #111928 | #F9FAFB | #F3F4F6 | #E5E7EB | #B91C1C | Near-black primary on white mirrors newspaper printing conventions — ink on paper; red secondary for breaking news, featured sections, and editorial accents (NYT, BBC, The Guardian pattern); amber for secondary sections. WCAG verified. |
-| Analytics/BI | #1A56DB | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Blue primary is the universal data-visualization anchor color — maps cleanly to sequential chart palettes; green secondary for positive delta/growth; amber accent for cautionary thresholds. Minimal decoration — the data is the hero. WCAG verified. |
-| AI/ML Platform | #4F46E5 | #FFFFFF | #7E3AF2 | #FFFFFF | #22D3EE | #0F172A | #F8FAFC | #1E293B | #334155 | #475569 | #EF4444 | Indigo primary on dark background — the established AI product visual language (Anthropic, Cohere, Mistral); violet secondary for model/capability exploration; cyan accent for real-time/streaming states. Dark-first layout. WCAG verified. |
+| Luxury/Fashion | #111928 | #F9FAFB | #374151 | #F9FAFB | #B45309 | #FFFFFF | #111928 | #F9FAFB | #F9FAFB | #E5E7EB | #DC2626 | Near-black primary on white background is the international language of luxury - Chanel, Saint Laurent, Bottega; slate secondary for layered surfaces; gold-amber accent for price points and premium badges. Minimum color = maximum status. WCAG verified. |
+| Media/Publishing | #111928 | #F9FAFB | #E02424 | #FFFFFF | #D97706 | #FFFFFF | #111928 | #F9FAFB | #F3F4F6 | #E5E7EB | #B91C1C | Near-black primary on white mirrors newspaper printing conventions - ink on paper; red secondary for breaking news, featured sections, and editorial accents (NYT, BBC, The Guardian pattern); amber for secondary sections. WCAG verified. |
+| Analytics/BI | #1A56DB | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Blue primary is the universal data-visualization anchor color - maps cleanly to sequential chart palettes; green secondary for positive delta/growth; amber accent for cautionary thresholds. Minimal decoration - the data is the hero. WCAG verified. |
+| AI/ML Platform | #4F46E5 | #FFFFFF | #7E3AF2 | #FFFFFF | #22D3EE | #0F172A | #F8FAFC | #1E293B | #334155 | #475569 | #EF4444 | Indigo primary on dark background - the established AI product visual language (Anthropic, Cohere, Mistral); violet secondary for model/capability exploration; cyan accent for real-time/streaming states. Dark-first layout. WCAG verified. |
 | Cybersecurity | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #22D3EE | #0A0A0A | #F8FAFC | #111827 | #1F2937 | #374151 | #EF4444 | Deep navy on near-black background signals a monitoring environment; green secondary for "all clear" / healthy system states; cyan accent for network traffic visualization and active scanning states. Terminal-inspired palette. WCAG verified. |
-| Logistics/Supply Chain | #D97706 | #111928 | #1A56DB | #FFFFFF | #0E9F6E | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #DC2626 | Amber primary mirrors physical logistics — high-vis safety colors, warehouse signage, shipping labels; blue secondary for tracking/digital interfaces; warm background differentiates from generic enterprise SaaS. WCAG verified. |
-| Insurance | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #D97706 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Navy primary signals protection, stability, and reliability — the universal insurance palette anchor (Allianz, AXA pattern); green secondary for claims approved and policy active states; amber for upcoming renewals and caution. WCAG verified. |
-| Automotive | #111928 | #F9FAFB | #374151 | #F9FAFB | #E02424 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #B91C1C   | Near-black primary matches the premium automotive convention — matte dark, precision engineering; red accent for performance/sport trims and urgency (limited availability); silver-gray secondary for neutral chrome surfaces. WCAG verified. |
-| Agriculture/AgriTech | #065F46 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F0FDF4 | #111928 | #FFFFFF | #DCFCE7 | #A7F3D0 | #DC2626 | Deep green primary is literal and honest — crops, fields, sustainability; amber secondary for harvest, yield, soil richness; blue accent for water management and satellite data. Green-tinted background grounds the product in nature. WCAG verified. |
-| CleanTech/Sustainability | #047857 | #FFFFFF | #1A56DB | #FFFFFF | #D97706 | #F0FDF4 | #111928 | #FFFFFF | #DCFCE7 | #BBF7D0 | #DC2626 | Rich emerald primary signals genuine environmental commitment — distinct from generic "eco green"; blue secondary for water/energy resource tracking; amber accent for carbon credit and offset metrics. Avoid greenwashing: use the earthy tones. WCAG verified. |
-| Pharmaceutical | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Regulated navy primary signals clinical authority and FDA compliance; green secondary for dosage confirmed and health-positive states; amber accent for contraindications and warnings. Never use red as primary — reserved for severe adverse events only. WCAG verified. |
-| Architecture/AEC | #374151 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Slate primary evokes material neutrality — concrete, steel, rendered surfaces; amber secondary for warmth of wood, brick, and material samples; blue accent for technical drawings and BIM layers. Restrained palette mirrors blueprint conventions. WCAG verified. |
-| Interior Design | #92400E | #FFFFFF | #065F46 | #FFFFFF | #1E3A5F | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #DC2626 | Warm terracotta-brown primary evokes material warmth — timber, linen, clay; deep green secondary for biophilic design moments and plant integration; warm cream background mimics actual interior photography styling. WCAG verified. |
-| Music/Audio | #111928 | #F9FAFB | #7E3AF2 | #FFFFFF | #F05252 | #0A0A0A | #F9FAFB | #1F2937 | #374151 | #4B5563 | #EF4444 | Near-black dark primary — music is a dark-mode-first medium (Spotify, SoundCloud, Apple Music pattern); violet secondary for playlist/discovery surfaces; red accent for recording states and live moments. WCAG verified on dark background. |
-| Photography/Video | #111928 | #F9FAFB | #374151 | #F9FAFB | #FF8A4C | #0A0A0A | #F9FAFB | #1F2937 | #374151 | #4B5563 | #EF4444 | Near-black dark canvas lets photography and video content take center stage — the UI must disappear; slate secondary for control surfaces; amber accent for selected states and active tools. WCAG verified on dark background. |
+| Logistics/Supply Chain | #D97706 | #111928 | #1A56DB | #FFFFFF | #0E9F6E | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #DC2626 | Amber primary mirrors physical logistics - high-vis safety colors, warehouse signage, shipping labels; blue secondary for tracking/digital interfaces; warm background differentiates from generic enterprise SaaS. WCAG verified. |
+| Insurance | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #D97706 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Navy primary signals protection, stability, and reliability - the universal insurance palette anchor (Allianz, AXA pattern); green secondary for claims approved and policy active states; amber for upcoming renewals and caution. WCAG verified. |
+| Automotive | #111928 | #F9FAFB | #374151 | #F9FAFB | #E02424 | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #B91C1C   | Near-black primary matches the premium automotive convention - matte dark, precision engineering; red accent for performance/sport trims and urgency (limited availability); silver-gray secondary for neutral chrome surfaces. WCAG verified. |
+| Agriculture/AgriTech | #065F46 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F0FDF4 | #111928 | #FFFFFF | #DCFCE7 | #A7F3D0 | #DC2626 | Deep green primary is literal and honest - crops, fields, sustainability; amber secondary for harvest, yield, soil richness; blue accent for water management and satellite data. Green-tinted background grounds the product in nature. WCAG verified. |
+| CleanTech/Sustainability | #047857 | #FFFFFF | #1A56DB | #FFFFFF | #D97706 | #F0FDF4 | #111928 | #FFFFFF | #DCFCE7 | #BBF7D0 | #DC2626 | Rich emerald primary signals genuine environmental commitment - distinct from generic "eco green"; blue secondary for water/energy resource tracking; amber accent for carbon credit and offset metrics. Avoid greenwashing: use the earthy tones. WCAG verified. |
+| Pharmaceutical | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Regulated navy primary signals clinical authority and FDA compliance; green secondary for dosage confirmed and health-positive states; amber accent for contraindications and warnings. Never use red as primary - reserved for severe adverse events only. WCAG verified. |
+| Architecture/AEC | #374151 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Slate primary evokes material neutrality - concrete, steel, rendered surfaces; amber secondary for warmth of wood, brick, and material samples; blue accent for technical drawings and BIM layers. Restrained palette mirrors blueprint conventions. WCAG verified. |
+| Interior Design | #92400E | #FFFFFF | #065F46 | #FFFFFF | #1E3A5F | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #DC2626 | Warm terracotta-brown primary evokes material warmth - timber, linen, clay; deep green secondary for biophilic design moments and plant integration; warm cream background mimics actual interior photography styling. WCAG verified. |
+| Music/Audio | #111928 | #F9FAFB | #7E3AF2 | #FFFFFF | #F05252 | #0A0A0A | #F9FAFB | #1F2937 | #374151 | #4B5563 | #EF4444 | Near-black dark primary - music is a dark-mode-first medium (Spotify, SoundCloud, Apple Music pattern); violet secondary for playlist/discovery surfaces; red accent for recording states and live moments. WCAG verified on dark background. |
+| Photography/Video | #111928 | #F9FAFB | #374151 | #F9FAFB | #FF8A4C | #0A0A0A | #F9FAFB | #1F2937 | #374151 | #4B5563 | #EF4444 | Near-black dark canvas lets photography and video content take center stage - the UI must disappear; slate secondary for control surfaces; amber accent for selected states and active tools. WCAG verified on dark background. |
 | Crypto/Web3 | #4F46E5 | #FFFFFF | #0E9F6E | #FFFFFF | #F59E0B | #0F172A | #F8FAFC | #1E293B | #334155 | #475569 | #EF4444 | Indigo on dark background signals the crypto-native aesthetic (Coinbase, Uniswap pattern); green secondary for price-up and confirmed transaction states; gold accent for high-value wallet events. Dark-first mandatory. WCAG verified. |
 | Marketing/AdTech | #D97706 | #111928 | #E02424 | #FFFFFF | #7E3AF2 | #FFFFFF | #111928 | #F9FAFB | #FEF3C7 | #FDE68A | #B91C1C | Amber primary signals campaign energy and conversion urgency; red secondary for CTAs and limited-offer badges; violet accent for creative/brand moments. Warm background differentiates from SaaS tools. WCAG verified. |
-| Recruitment/HR Tech | #7E3AF2 | #FFFFFF | #1A56DB | #FFFFFF | #0E9F6E | #FAF5FF | #111928 | #FFFFFF | #F3E8FF | #E9D5FF | #DC2626 | Violet primary signals human potential and opportunity — differentiated from corporate blue; navy secondary for employer-side trust; green accent for application submitted and offer extended. Lavender muted backgrounds are distinctive in the space. WCAG verified. |
-| Customer Support/CX | #0E9F6E | #FFFFFF | #3F83F8 | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Green primary signals resolution and "all good" — the opposite of customer frustration red; blue secondary for informational knowledge base surfaces; amber accent for escalation and SLA-risk alerts. WCAG verified. |
-| E-learning/MOOC | #6875F5 | #FFFFFF | #FF8A4C | #FFFFFF | #0E9F6E | #F9FAFB | #111928 | #FFFFFF | #EFF6FF | #E0E7FF | #DC2626 | Periwinkle primary is academically focused yet modern — bridges EdTech energy with SaaS discipline; amber secondary for assignment deadlines and achievement badges; green accent for progress and course completion. WCAG verified. |
-| Telemedicine | #1A56DB | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #EFF6FF | #111928 | #FFFFFF | #DBEAFE | #BFDBFE | #DC2626 | Blue primary signals clinical authority and digital trust — video-consult contexts require colors that photograph well on video call backgrounds; green secondary for patient-status OK and prescription-ready states; sky-blue background creates a calm, clinical context. WCAG verified. |
-| Smart Home/IoT | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #F59E0B | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Deep navy primary signals reliable infrastructure and always-on connectivity; green secondary for device-online and automation-active states; amber accent for device warnings and energy usage peaks. Functional palette — never decorative. WCAG verified. |
-| Manufacturing/Industrial | #374151 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Slate primary mirrors industrial material honesty — steel, aluminum, precision tooling; amber secondary mirrors high-visibility safety equipment conventions; blue accent for digital HMI overlays and OEE dashboards. Avoid soft consumer palettes. WCAG verified. |
-| Construction | #D97706 | #111928 | #374151 | #FFFFFF | #1A56DB | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #B91C1C | Amber primary is literal high-vis construction site signaling — hard hats, caution tape, equipment; slate secondary for technical drawing and plan review surfaces; blue accent for BIM integration and weather/site tracking. Warm background. WCAG verified. |
+| Recruitment/HR Tech | #7E3AF2 | #FFFFFF | #1A56DB | #FFFFFF | #0E9F6E | #FAF5FF | #111928 | #FFFFFF | #F3E8FF | #E9D5FF | #DC2626 | Violet primary signals human potential and opportunity - differentiated from corporate blue; navy secondary for employer-side trust; green accent for application submitted and offer extended. Lavender muted backgrounds are distinctive in the space. WCAG verified. |
+| Customer Support/CX | #0E9F6E | #FFFFFF | #3F83F8 | #FFFFFF | #FF8A4C | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Green primary signals resolution and "all good" - the opposite of customer frustration red; blue secondary for informational knowledge base surfaces; amber accent for escalation and SLA-risk alerts. WCAG verified. |
+| E-learning/MOOC | #6875F5 | #FFFFFF | #FF8A4C | #FFFFFF | #0E9F6E | #F9FAFB | #111928 | #FFFFFF | #EFF6FF | #E0E7FF | #DC2626 | Periwinkle primary is academically focused yet modern - bridges EdTech energy with SaaS discipline; amber secondary for assignment deadlines and achievement badges; green accent for progress and course completion. WCAG verified. |
+| Telemedicine | #1A56DB | #FFFFFF | #0E9F6E | #FFFFFF | #FF8A4C | #EFF6FF | #111928 | #FFFFFF | #DBEAFE | #BFDBFE | #DC2626 | Blue primary signals clinical authority and digital trust - video-consult contexts require colors that photograph well on video call backgrounds; green secondary for patient-status OK and prescription-ready states; sky-blue background creates a calm, clinical context. WCAG verified. |
+| Smart Home/IoT | #1E3A5F | #FFFFFF | #0E9F6E | #FFFFFF | #F59E0B | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #E5E7EB | #DC2626 | Deep navy primary signals reliable infrastructure and always-on connectivity; green secondary for device-online and automation-active states; amber accent for device warnings and energy usage peaks. Functional palette - never decorative. WCAG verified. |
+| Manufacturing/Industrial | #374151 | #FFFFFF | #D97706 | #111928 | #1A56DB | #F9FAFB | #111928 | #FFFFFF | #F3F4F6 | #D1D5DB | #DC2626 | Slate primary mirrors industrial material honesty - steel, aluminum, precision tooling; amber secondary mirrors high-visibility safety equipment conventions; blue accent for digital HMI overlays and OEE dashboards. Avoid soft consumer palettes. WCAG verified. |
+| Construction | #D97706 | #111928 | #374151 | #FFFFFF | #1A56DB | #FFFBEB | #111928 | #FFFFFF | #FEF3C7 | #FDE68A | #B91C1C | Amber primary is literal high-vis construction site signaling - hard hats, caution tape, equipment; slate secondary for technical drawing and plan review surfaces; blue accent for BIM integration and weather/site tracking. Warm background. WCAG verified. |
 
 For matching typography pairings by vertical, see `reference/typography.md`.
 For industry voice conventions that must align with palette choice, see `reference/brand-voice.md`.

package/reference/parallelism-rules.md

@@ -4,25 +4,25 @@ The decision engine reads these rules at every stage spawn point and writes its
 
 ---
 
-## Hard Rules — Always Serial (override everything)
-
-1. **Sequential dependency** — Agent B requires output from Agent A → serial.
-2. **Shared write conflict** — Two agents write to the same file path (intersecting `writes:` fields) → serial.
-3. **Interactive agent** — Agent requires `AskUserQuestion` during execution → serial. Interactive agents cannot be parallelized.
-4. **Single task** — Only 1 candidate in the wave → serial (nothing to parallelize).
-5. **Overlapping Touches** — Two tasks have overlapping `Touches:` fields (same file paths) → serial.
-6. **Schema migrations** — Any agent altering database schema (migrations, `ALTER TABLE`, index changes) → serial within its wave.
-7. **Rate-limited external API** — Agents calling an external API with shared rate limits (same auth token, same quota) → serial.
-
-## Soft Rules — Prefer Serial (yield to config overrides)
-
-8. **Below savings threshold** — `sum(typical-duration-seconds) - max(typical-duration-seconds) < config.min_estimated_savings_seconds` (default 30s) → prefer serial.
-9. **All candidates fast** — Every candidate has `typical-duration-seconds < 10` → parallel overhead may exceed savings → prefer serial.
-10. **Beyond max_parallel_agents cap** — N candidates > `config.max_parallel_agents` → split into sequential waves of `max_parallel_agents` each.
-11. **Worktree isolation unavailable** — `worktree_isolation: true` in config but git worktrees not available → fall back to serial.
-12. **Below min_tasks_to_parallelize** — Fewer than `config.min_tasks_to_parallelize` (default 2) eligible → serial.
-13. **Large context** — Any candidate's `<required_reading>` total is >100K tokens — risk of context bloat in concurrent dispatch → prefer serial.
-14. **Token-costly agents** — Agents tagged `model: opus` with `typical-duration-seconds > 120s` — prefer serial to avoid bursty spend unless explicitly opted in.
+## Hard Rules - Always Serial (override everything)
+
+1. **Sequential dependency** - Agent B requires output from Agent A → serial.
+2. **Shared write conflict** - Two agents write to the same file path (intersecting `writes:` fields) → serial.
+3. **Interactive agent** - Agent requires `AskUserQuestion` during execution → serial. Interactive agents cannot be parallelized.
+4. **Single task** - Only 1 candidate in the wave → serial (nothing to parallelize).
+5. **Overlapping Touches** - Two tasks have overlapping `Touches:` fields (same file paths) → serial.
+6. **Schema migrations** - Any agent altering database schema (migrations, `ALTER TABLE`, index changes) → serial within its wave.
+7. **Rate-limited external API** - Agents calling an external API with shared rate limits (same auth token, same quota) → serial.
+
+## Soft Rules - Prefer Serial (yield to config overrides)
+
+8. **Below savings threshold** - `sum(typical-duration-seconds) - max(typical-duration-seconds) < config.min_estimated_savings_seconds` (default 30s) → prefer serial.
+9. **All candidates fast** - Every candidate has `typical-duration-seconds < 10` → parallel overhead may exceed savings → prefer serial.
+10. **Beyond max_parallel_agents cap** - N candidates > `config.max_parallel_agents` → split into sequential waves of `max_parallel_agents` each.
+11. **Worktree isolation unavailable** - `worktree_isolation: true` in config but git worktrees not available → fall back to serial.
+12. **Below min_tasks_to_parallelize** - Fewer than `config.min_tasks_to_parallelize` (default 2) eligible → serial.
+13. **Large context** - Any candidate's `<required_reading>` total is >100K tokens - risk of context bloat in concurrent dispatch → prefer serial.
+14. **Token-costly agents** - Agents tagged `model: opus` with `typical-duration-seconds > 120s` - prefer serial to avoid bursty spend unless explicitly opted in.
 
 ---
 
@@ -105,4 +105,4 @@ WRITE verdict to STATE.md <parallelism_decision>
 
 ## Why this is a first-class primitive
 
-"Why didn't it parallelize?" becomes a one-file STATE.md read — not a guess. Every stage orchestrator computes and writes a verdict before any multi-agent spawn. Operators can audit the decision without rerunning.
+"Why didn't it parallelize?" becomes a one-file STATE.md read - not a guess. Every stage orchestrator computes and writes a verdict before any multi-agent spawn. Operators can audit the decision without rerunning.

package/reference/peer-cli-capabilities.md

@@ -4,7 +4,7 @@ Last verified: 2026-04-29
 
 Authoritative capability matrix for the peer-CLI delegation layer (Phase 27).
 The registry at `scripts/lib/peer-cli/registry.cjs` reads this map (encoded as
-data in the `.cjs` source — this doc is the human-readable mirror) to decide
+data in the `.cjs` source - this doc is the human-readable mirror) to decide
 which peer-CLI claims which agent role and which protocol to speak.
 
 If you change this matrix, you MUST also change `CAPABILITY_MATRIX` in
@@ -14,7 +14,7 @@ The two are version-locked by Phase 27 D-05.
 ## Capability matrix
 
 Each peer claims a fixed set of agent roles. The registry refuses to dispatch
-a role to a peer that does not claim it — this prevents accidental
+a role to a peer that does not claim it - this prevents accidental
 mis-delegations like "let's try `design-auditor` against Qwen" that produce
 garbage output (Phase 27 CONTEXT D-05).
 
@@ -28,19 +28,19 @@ garbage output (Phase 27 CONTEXT D-05).
 
 Slash-command translation lives in each per-peer adapter
 (`scripts/lib/peer-cli/adapters/<peer>.cjs`, landed by Plan 27-04). The
-registry never invokes slash commands directly — it routes the role and
+registry never invokes slash commands directly - it routes the role and
 delegates prompt-prefixing + slash translation to the adapter.
 
 ## Tie-breaking when two peers claim the same role
 
 `research` is claimed by both `gemini` and `copilot`. When the registry's
 `findPeerFor('research', tier)` runs, it walks peers in alphabetical order
-of peer ID — `codex` < `copilot` < `cursor` < `gemini` < `qwen` — and
+of peer ID - `codex` < `copilot` < `cursor` < `gemini` < `qwen` - and
 returns the first one that passes the health probe. So `copilot` wins
 `research` over `gemini` when both are installed and allowlisted.
 
 Users can override this by removing one of the two from
-`.design/config.json#peer_cli.enabled_peers` — the unlisted peer is treated
+`.design/config.json#peer_cli.enabled_peers` - the unlisted peer is treated
 as absent regardless of installation status (Phase 27 D-11 opt-in gating).
 
 ## Opt-in gating (D-11)
@@ -48,7 +48,7 @@ as absent regardless of installation status (Phase 27 D-11 opt-in gating).
 A peer is dispatched to ONLY when:
 
 1. The peer ID appears in `.design/config.json#peer_cli.enabled_peers`
-   (an array of allowlisted peer IDs). Default: `[]` — empty, nothing
+   (an array of allowlisted peer IDs). Default: `[]` - empty, nothing
    dispatches.
 2. The peer's adapter module loads at `scripts/lib/peer-cli/adapters/<peer>.cjs`.
 3. The adapter's `peerBinary()` resolver returns a path that exists on disk.
@@ -63,7 +63,7 @@ or broken peer must never break the cycle.
 ### `codex` (ASP)
 
 OpenAI Codex CLI invoked as `codex app-server`. Speaks the App Server
-Protocol — thread-oriented, supports resume across calls (currently unused;
+Protocol - thread-oriented, supports resume across calls (currently unused;
 v1.27 always starts fresh threads).
 
 - **Provenance:** runtime entry in `scripts/lib/install/runtimes.cjs` (`id: 'codex'`).
@@ -98,7 +98,7 @@ workflows.
 ### `copilot` (ACP)
 
 GitHub Copilot CLI in ACP mode. Claims `review` and `research`. Tends to
-win `research` against `gemini` on alphabetical tie-break — users who
+win `research` against `gemini` on alphabetical tie-break - users who
 prefer Gemini for research should remove `copilot` from `enabled_peers`.
 
 - **Provenance:** runtime entry in `scripts/lib/install/runtimes.cjs` (`id: 'copilot'`).
@@ -124,7 +124,7 @@ To add a new peer-CLI to the matrix:
    Plan 27-10). It walks the protocol-fit check, the role-claim audit, the
    adapter scaffold, and the test coverage required.
 2. Append the peer to `CAPABILITY_MATRIX` in `scripts/lib/peer-cli/registry.cjs`
-   AND to the table at the top of this file. The two MUST stay in sync —
+   AND to the table at the top of this file. The two MUST stay in sync -
    the test suite (`tests/peer-cli-registry.test.cjs`) asserts the matrix
    shape.
 3. Add a `<peer>.cjs` adapter under `scripts/lib/peer-cli/adapters/`.
@@ -139,13 +139,13 @@ a peer, reverse the steps above plus update `tests/phase-27-baseline.test.cjs`.
 
 ## Cross-references
 
-- `scripts/lib/peer-cli/registry.cjs` — central dispatch, single source of
+- `scripts/lib/peer-cli/registry.cjs` - central dispatch, single source of
   truth for the capability matrix as code.
-- `scripts/lib/peer-cli/adapters/*.cjs` — per-peer thin adapters
+- `scripts/lib/peer-cli/adapters/*.cjs` - per-peer thin adapters
   (Plan 27-04).
-- `scripts/lib/peer-cli/{acp,asp}-client.cjs` — protocol clients
+- `scripts/lib/peer-cli/{acp,asp}-client.cjs` - protocol clients
   (Plans 27-01 / 27-02).
-- `scripts/lib/peer-cli/broker-lifecycle.cjs` — long-lived session per
+- `scripts/lib/peer-cli/broker-lifecycle.cjs` - long-lived session per
   `(peer, workspace)` (Plan 27-03).
-- Phase 27 CONTEXT.md — decision log including D-05 (this matrix),
+- Phase 27 CONTEXT.md - decision log including D-05 (this matrix),
   D-07 (transparent fallback), D-11 (opt-in gating).