@hegemonart/get-design-done 1.35.5 → 1.36.2

package/reference/domains/civic-patterns.md

@@ -0,0 +1,101 @@
+# Civic & Government Design Patterns
+
+This pack collects the design patterns, legal floors, and review heuristics that apply when building public-sector interfaces — benefits portals, permit and licensing flows, tax filing, election information, and municipal services. GDD loads it automatically when it detects a government / public-sector / civic project (see Detection signals). The legal citations below assume a US context, but the underlying patterns — accessibility floors, plain language, multilingual access, and high-trust defaults — generalize to public services anywhere.
+
+## Why civic is different
+
+In the private sector, accessibility, plain language, and translation are often framed as "nice to have" optimizations weighed against conversion. In government, they are obligations. The audience is non-self-selecting: a citizen cannot choose a competitor when a benefits form is unusable. People arrive under stress, on old hardware, on metered or slow connections, across many languages and literacy levels, often with a disability. The patterns here treat the hardest case as the design center, not the edge.
+
+## Accessibility legal floor
+
+Section 508 of the Rehabilitation Act incorporates **WCAG 2.1 Level AA** as the binding technical standard for US federal ICT. The Americans with Disabilities Act (ADA) extends comparable obligations to state and local government (Title II) and many public accommodations. Treat **WCAG 2.1 AA as a hard floor** — not optional, not an AAA-aspirational stretch goal. You do not "prioritize" it against other work; you cannot ship below it.
+
+Concretely, every civic UI must satisfy at least:
+
+| Requirement | WCAG SC | What it means in practice |
+|---|---|---|
+| Keyboard operable | 2.1.1 | Every interactive element works without a mouse; no keyboard traps (2.1.2). |
+| Visible focus | 2.4.7 | A clear, non-removed focus indicator on every focusable control. |
+| Landmarks & headings | 1.3.1, 2.4.6 | Real `main`/`nav`/`header`/`footer` regions; a logical, non-skipping heading outline. |
+| Error identification | 3.3.1 | Errors are described in text, programmatically associated with their field. |
+| Labels & instructions | 3.3.2 | Every input has a persistent, programmatic label — placeholder is not a label. |
+| Not color alone | 1.4.1 | Status, required fields, and errors never rely on color as the only cue. |
+| Text contrast | 1.4.3 | 4.5:1 for body text, 3:1 for large text and meaningful UI/graphics (1.4.11). |
+| Reflow | 1.4.10 | Usable at 400% zoom / 320 CSS px with no loss of content or horizontal scroll. |
+| Captions & transcripts | 1.2.2, 1.2.4 | Captions for video; transcripts/audio descriptions for time-based media. |
+| Name, role, value | 4.1.2 | Custom widgets expose correct accessible name, role, and state to assistive tech. |
+
+WCAG 2.2 AA adds obligations worth meeting now: **Focus Not Obscured (2.4.11)**, **Target Size (Minimum) 2.5.8** (24×24 CSS px floor; aim for ~44×44 for primary touch targets), and **Accessible Authentication (3.3.8)** (no cognitive-function test like solving a puzzle or transcribing characters as the only way in). Authoritative references: https://www.section508.gov and https://www.w3.org/WAI/WCAG21/quickref/.
+
+## Multi-language government forms
+
+A practical US minimum is **English + Spanish + Simplified Chinese (`zh-Hans`)**; agencies under Executive Order 13166 / Title VI must provide meaningful access to limited-English-proficient (LEP) users, and the right language set is driven by the served population (Vietnamese, Tagalog, Korean, Haitian Creole, Arabic, and others are common).
+
+Patterns:
+
+- **Persistent language toggle** in a predictable location (top of every page), not buried in a footer or settings panel. Selection persists across the whole session and survives navigation.
+- **Translate the content, not just the chrome.** Field labels, help text, **validation/error messages**, confirmation screens, emails, and PDFs must all be localized — a form that switches its buttons to Spanish but throws English errors has failed.
+- Set `lang` on the document and on any in-page language switches so assistive tech pronounces content correctly.
+- **Right-to-left readiness**: build layouts with logical properties / `dir="rtl"` support so Arabic, Farsi, Urdu, and Hebrew mirror correctly. Don't hard-code left/right.
+- **Avoid machine-only translation for legal text.** Eligibility rules, consent, rights notices, and binding terms need human translation and review; raw MT can be a compliance and liability problem.
+- Offer an **"I Speak" language-identification card** (a list of "I speak ___" statements in each language) so a user can self-identify their language and request an interpreter.
+
+## Plain language
+
+The **Plain Writing Act of 2010** requires US federal agencies to write public-facing material clearly. Target a **reading level of grade 6–8** (many benefits and health programs aim for grade 6 or lower).
+
+- **Active voice and short sentences.** Prefer "We denied your application" over "Your application has been denied." Keep most sentences under ~20 words; one idea per sentence.
+- **Define or avoid jargon and acronyms.** Spell out acronyms on first use; better, replace agency jargon with the everyday word ("proof of income," not "income documentation substantiation").
+- **Question-style labels.** "What is your date of birth?" reads more clearly than "DOB" or "Birthdate field."
+- **Clear next-step CTAs.** Buttons name the action and outcome ("Submit my application," "Check my status") rather than generic "OK"/"Continue" where ambiguous.
+- **Front-load the point.** Lead with what the user must do or what happened, then the detail. Use headings, short paragraphs, and lists.
+- Guidance: https://www.plainlanguage.gov. The **US Web Design System (USWDS)** encodes much of this in components and content guidance: https://designsystem.digital.gov.
+
+## Trust & accessibility-first defaults
+
+- **Generous session timeouts with warning + extend.** Per **WCAG 2.2.1 (Timing Adjustable)**, warn before a session expires and let the user extend or turn off the limit; never silently discard a half-finished benefits application. Pair with save-and-resume.
+- **No dark patterns.** No pre-checked consent, no confirm-shaming, no buried opt-outs, no fake urgency. Government must not manipulate; defaults should favor the user.
+- **Save-and-resume for long forms.** Let users leave and return without losing data — assume interruptions, shared/library computers, and multi-session completion.
+- **Print-friendliness.** Provide clean print styles and downloadable/printable confirmations and records; many users keep paper copies or mail documents.
+- **Low-bandwidth / older-device tolerance.** Server-render core content, keep payloads small, avoid blocking on heavy JS, and ensure the form is usable without the latest browser. Test on slow connections and old devices.
+- **Clear `.gov` identity & PII handling.** Show the official agency identity (the USWDS gov banner pattern), a plain-language privacy notice, and explain what personal information is collected, why, and how it is protected. Minimize PII collected; never expose SSNs or case numbers in URLs.
+
+## Forms at scale
+
+- **One-thing-per-page** (GOV.UK Design System style): ask a single question (or one tight group) per screen. It lowers cognitive load, simplifies validation and error messaging, and is far easier to make accessible and translatable. See https://design-system.service.gov.uk.
+- **Progressive disclosure.** Reveal follow-up questions only when relevant (conditional reveals), and keep the default path short for the common case.
+- **Inline validation that doesn't punish.** Validate on blur / on submit, not on every keystroke; never block typing. Allow flexible input formats (phone, dates) and normalize server-side rather than rejecting.
+- **Accessible error summary.** On a failed submit, render an error summary at the top of the form that lists each problem as a link jumping focus to the offending field, and move focus to the summary. Each field error is also shown inline and programmatically tied to its input (3.3.1).
+- **Helpful, specific errors.** Say what's wrong and how to fix it ("Enter your ZIP code as 5 digits"), in plain language and in the user's chosen language.
+- **Preserve user input on error.** Re-display everything the user entered; never make them re-key a long form because one field failed.
+
+## Detection signals
+
+GDD should auto-detect the civic/government domain from any combination of:
+
+- **Content / naming keywords:** `gov`, `government`, `public`, `citizen`, `benefits`, `permit`, `license`, `tax`, `election`, `voter`, `municipal`, `county`, `agency`, `eligibility`, `enrollment`, `public service`.
+- **`package.json` dependencies (strong signal):**
+  - `@uswds/uswds`, `uswds` — US Web Design System
+  - `@trussworks/react-uswds` — React USWDS components
+  - `govuk-frontend` — GOV.UK Design System
+  - `@18f/...` — 18F / TTS tooling and components
+- **Domain / config signals:** a `.gov`, `.mil`, or `.gov.<cc>` domain in config or deploy targets; accessibility-first project config (axe-core, `pa11y`, `jest-axe`, `eslint-plugin-jsx-a11y`, Lighthouse a11y budgets) wired into CI.
+
+Any one strong dependency match, or several keyword + domain matches together, should trigger loading this pack.
+
+## Audit checklist
+
+The auditor agent runs these against a civic UI. Each item is concrete and verifiable.
+
+1. Every interactive control is fully keyboard-operable with a visible focus ring, and there are no keyboard traps (WCAG 2.1.1, 2.1.2, 2.4.7).
+2. The page exposes correct landmarks and a logical, non-skipping heading outline; custom widgets expose correct name/role/value (WCAG 1.3.1, 2.4.6, 4.1.2).
+3. Text contrast meets 4.5:1 (body) / 3:1 (large text and meaningful UI), and no information is conveyed by color alone (WCAG 1.4.1, 1.4.3, 1.4.11).
+4. Content reflows and remains fully usable at 400% zoom / 320 CSS px with no horizontal scrolling or lost content (WCAG 1.4.10).
+5. Interactive targets meet the 24×24 CSS px minimum (primary touch targets ~44×44), and focus is never obscured (WCAG 2.5.8, 2.4.11).
+6. Every input has a persistent programmatic label (not placeholder-only); errors are described in text and tied to their field (WCAG 3.3.1, 3.3.2).
+7. On submit failure, an error summary lists each problem, links to and moves focus to the field, and user input is preserved.
+8. Reading level is grade 6–8: active voice, short sentences, no undefined jargon/acronyms, question-style labels (Plain Writing Act of 2010).
+9. A persistent language toggle covers content, help text, and **errors** — not just UI chrome — for at least EN + ES + zh-Hans, with correct `lang` and RTL readiness; legal/eligibility text is human-translated, not machine-only.
+10. Session timeout warns before expiry and offers an extend/disable option, and the form supports save-and-resume (WCAG 2.2.1).
+11. No dark patterns: no pre-checked consent, confirm-shaming, or buried opt-outs; defaults favor the user.
+12. Official `.gov` identity, a plain-language privacy/PII notice, print-friendly confirmations, and graceful behavior on low bandwidth / older devices are all present; no PII (SSN, case IDs) exposed in URLs.

package/reference/domains/finance-patterns.md

@@ -0,0 +1,123 @@
+# Finance & Fintech Design Patterns
+
+This pack documents the data-display, trading-UI, compliance, and payment-security conventions that distinguish finance products from generic SaaS. GDD loads it automatically when it detects a trading, brokerage, banking, ledger, or payments project (see Detection signals below). The auditor agent runs the Audit checklist at the end of this file against any finance UI.
+
+## Data-table density
+
+Financial UIs are table-first: positions, orders, ledgers, transaction histories. The table is the product, so its legibility budget is non-negotiable.
+
+| Property | Convention |
+|---|---|
+| Comfortable row height | 44-52px (touch-reachable, default for retail) |
+| Compact row height | 28-36px (pro/desktop blotters, high row counts) |
+| Density toggle | Offer comfortable/compact (and sometimes a 24px "ultra") as a persistent user setting |
+| Numeric font | `font-variant-numeric: tabular-nums` (or a font with lining + tabular figures) so digits occupy equal width |
+| Numeric alignment | Right-align all numbers; align on the decimal point so magnitudes stack visually |
+| Text columns | Left-align labels/symbols; never right-align prose |
+| Row separation | Prefer 1px hairline rules (or subtle zebra) for dense data; avoid heavy zebra that fights the numbers |
+| Header | Sticky/frozen header row; freeze the first identifier column (symbol/account) on horizontal scroll |
+| Column min-width | Size to the widest plausible value (e.g. a 12-digit notional), not the average |
+
+- Tabular numerals matter most where values change in place (live P&L): non-tabular figures cause horizontal jitter on every tick.
+- Right-aligning currency columns lets the eye compare orders of magnitude at a glance; decimal alignment is what makes `1,234.50` and `9.05` line up.
+- Keep currency symbols and unit suffixes out of the number cell when possible (put `USD`/`%` in the header) so the digits align cleanly.
+
+## Trading-interface conventions
+
+### Direction & semantics (never color alone)
+- Red = down/loss/sell, green = up/gain/buy is the Western default; some markets (e.g. parts of East Asia) invert this — make the mapping a setting, not a hard-coded assumption.
+- Roughly 1 in 12 men have red-green color vision deficiency. Never encode gain/loss with color only. Always pair color with a non-color cue: a `+`/`-` sign, an up/down arrow (▲/▼), or parentheses for negatives.
+- Use a colorblind-safe palette (e.g. teal/orange or blue/orange instead of pure red/green) or let users opt into one.
+
+### Real-time updates
+- Flash the cell background briefly (~150-300ms) on value change — green tint up, red tint down — then fade back. This draws the eye without permanent clutter.
+- Throttle/coalesce updates: batch ticks to ~4-10 fps (every 100-250ms) rather than rendering every websocket message; high-frequency feeds will otherwise pin the CPU and make text unreadable.
+- Show a stale/latency indicator: timestamp of last update, a "delayed 15 min" badge for non-real-time quotes (a regulatory requirement for many retail feeds), and grey the data when the feed is stale.
+
+### Order entry & destructive actions
+- Add deliberate friction to order submission: an explicit review/confirm step that restates side, symbol, quantity, order type, limit price, and estimated cost before the order is live.
+- Distinguish market vs limit orders clearly; warn on market orders in illiquid or fast-moving instruments.
+- Guard destructive/irreversible actions (cancel-all, close-all, liquidate, withdraw): require a confirmation that names the consequence, and consider type-to-confirm for account-level actions.
+- Disable the submit button while a submission is in flight; never allow accidental double-submission of an order.
+
+## Regulatory disclaimer placement
+
+The governing principle from advertising rules (SEC, FINRA) is proximity: a disclosure must sit next to the claim it qualifies, not buried in a global footer or behind a tooltip.
+
+| Context | Disclosure |
+|---|---|
+| Margin trading / leverage | Reg-T margin risk disclosure and current margin requirements, shown in the margin/borrow flow |
+| Performance / returns figures | "Past performance does not guarantee future results"; show net-of-fees and the period, adjacent to the number |
+| EU cost transparency | MiFID II ex-ante (pre-trade) cost & charges estimate at order entry; ex-post (annual) statement of aggregated costs |
+| Quotes & data | Delayed-data badge; real-time entitlement notice |
+| Projections / hypotheticals | Label clearly as hypothetical and state assumptions inline |
+
+- Ex-ante cost disclosure (MiFID II) belongs in the order ticket before confirmation, expressed in both percentage and cash terms, including the effect of costs on return.
+- FINRA Rule 2210 and SEC marketing rules require communications to be fair, balanced, and not misleading — risk disclosures must be presented with at least equal prominence to the benefit/claim, not in 8px grey fine print.
+- Authorities: https://www.sec.gov/ , https://www.finra.org/ , and the EU MiFID II framework.
+
+## Card & payment data (PCI-DSS)
+
+PCI-DSS governs how cardholder data is handled in the UI and beyond. Design must assume the front end is in scope.
+
+- Mask the PAN: display only the last 4 digits (e.g. `•••• •••• •••• 4242`). The first 6 (BIN) may be shown only where genuinely needed.
+- Never display, log, or store the CVV/CVC2/CID after authorization — not in state, not in logs, not in analytics. It is the one value that must never persist.
+- Never put PAN, CVV, or full account numbers in URLs, query strings, `localStorage`, analytics events, error reports, or screenshots.
+- Use tokenization: send card details directly to the processor (Stripe Elements, Plaid Link, etc.) so raw PAN never touches your servers; store the returned token, not the card.
+- Mask card entry inputs and disable autocomplete logging of the CVV field; clear sensitive fields from memory after submit.
+- Authority: https://www.pcisecuritystandards.org/
+
+## Number formatting precision
+
+Honest, locale-correct number formatting is a trust signal in finance. Use the platform's locale APIs (e.g. `Intl.NumberFormat`) rather than hand-rolled formatting.
+
+- Currency minor units: respect each currency's decimal places — USD/EUR use 2, JPY/KRW use 0, and several (BHD, KWD, TND) use 3. Do not hard-code 2.
+- Percentages: pick a precision and keep it consistent per context (2 decimals for yields/rates is common); show a trailing zero rather than dropping it (`5.00%`, not `5%`).
+- Basis points (bps): 1 bp = 0.01% = 0.0001. Use bps for small rate moves and spreads; label the unit explicitly.
+- Locale grouping/decimals: respect locale separators (`1,234.56` en-US vs `1.234,56` de-DE vs `1 234,56` fr-FR). Never assume `.` is the decimal mark.
+- Negatives: in accounting contexts, show negatives in parentheses `(1,234.50)` (often with red); elsewhere a leading minus is fine. Pick one convention per surface and apply it everywhere.
+- Rounding honesty: state whether a figure is rounded or truncated; never round a fee/cost down in a way that understates what the user pays. Carry full precision internally and round only at display.
+
+## Real-time data UI
+
+- Websocket cadence: subscribe to streams, but render on a throttled tick (100-250ms) and coalesce intermediate updates; full-snapshot on (re)connect, deltas thereafter.
+- Optimistic vs confirmed: clearly distinguish an order/transfer that is *pending* (optimistic, locally echoed) from one *confirmed* by the venue/backend. Use a distinct state — never let a pending action look settled.
+- Connection loss: show a persistent "Reconnecting…" banner the moment the socket drops; auto-reconnect with backoff.
+- Stale-data greying: when the feed is stale or disconnected, grey out live values and freeze the last-known number with its timestamp, so users never act on data that looks live but is not.
+
+## Detection signals
+
+GDD treats a project as finance/fintech when it sees these signals. Keywords (in product copy, route names, schema, or component names) plus payment/market data dependencies in `package.json` are the strongest indicators.
+
+**Keywords:** trading, trade, order, blotter, portfolio, position, P&L, brokerage, ledger, journal entry, invoice, banking, account balance, fintech, payments, payout, wallet, KYC, AML, custody, settlement.
+
+**`package.json` dependencies:**
+
+| Dependency | Signals |
+|---|---|
+| `stripe`, `@stripe/stripe-js`, `@stripe/react-stripe-js` | Card payments / billing |
+| `plaid`, `@plaid/...`, `react-plaid-link` | Bank account linking / ACH |
+| `dwolla-v2` | ACH transfers / payouts |
+| `finnhub`, `@alpacahq/alpaca-trade-api` | Market data / brokerage trading |
+| `ccxt` | Crypto exchange connectivity |
+| `lightweight-charts`, `react-financial-charts` | Financial / candlestick charting |
+| `highcharts` / `highstock` | Stock charting |
+
+Any one payment/market dependency, or a cluster of the keywords, should trigger this domain pack.
+
+## Audit checklist
+
+A finance UI should pass every item below.
+
+1. Numeric columns use `tabular-nums` (or tabular lining figures), are right-aligned, and align on the decimal point.
+2. The data table offers a density mode (comfortable/compact) and uses appropriate row heights; headers (and key identifier columns) stay frozen on scroll.
+3. Gain/loss and up/down are never conveyed by color alone — each carries a sign, arrow, or parentheses, and a colorblind-safe palette is available.
+4. Live values flash on change and updates are throttled/coalesced (no per-message re-render); a stale/delayed indicator and last-update timestamp are present.
+5. Order entry has an explicit confirmation step restating side, symbol, quantity, type, and estimated cost; submit is disabled while a request is in flight.
+6. Destructive/irreversible actions (cancel-all, liquidate, withdraw) are guarded by a consequence-naming confirmation.
+7. Cost and risk disclosures sit adjacent to the figure they qualify (e.g. ex-ante costs in the order ticket), not in a global footer, and are at least as prominent as the claim.
+8. Margin/leverage flows show the Reg-T margin risk disclosure; performance figures carry a past-performance disclaimer with period and net-of-fees basis.
+9. PAN is masked to last-4; CVV is never displayed, logged, persisted, or stored after authorization.
+10. No PAN, CVV, or account number appears in URLs, query strings, `localStorage`, analytics events, or error reports; card data is tokenized via the processor.
+11. Currency, percentage, and basis-point values respect the correct minor units, locale separators, and a consistent negative convention; rounding/truncation is honest and applied only at display.
+12. Real-time UI distinguishes pending (optimistic) from confirmed states and greys/freezes stale data on connection loss with a visible reconnect indicator.

package/reference/domains/gaming-patterns.md

@@ -0,0 +1,111 @@
+# Game UI & HUD Design Patterns
+
+This pack covers UI, HUD, and interaction patterns specific to games and interactive entertainment: the diegetic-UI taxonomy, high-motion accessibility, age-rating gates, multi-input (controller / touch / keyboard-mouse) interaction models, and game-feel feedback. GDD loads this domain automatically when it detects a game, HUD, or interactive-entertainment project (see Detection signals). The auditor agent runs the Audit checklist against the project's UI.
+
+## HUD / diegetic UI taxonomy
+
+The canonical model is the four-quadrant scheme from Fagerholt & Lorentzon ("Beyond the HUD", 2009), classified on two axes: whether the element exists in the game's **story (fiction)** and whether it exists in the **3D geometry of the game space**.
+
+| Type | In the fiction? | In 3D space? | Example | Use when |
+|------|-----------------|--------------|---------|----------|
+| **Non-diegetic** | No | No | Classic flat overlay: health bar, minimap, ammo counter | Information must be instantly legible regardless of camera; competitive or fast-twitch genres |
+| **Diegetic** | Yes | Yes | Dead Space health spine, Metro 2033 wrist watch, in-world ammo on the gun | Immersion-first single-player; the readout can plausibly belong to a character/object |
+| **Spatial** | No | Yes | Floating waypoint markers, enemy outlines, footstep VFX rendered in-world | Guidance anchored to a location/entity but not justified by the story |
+| **Meta** | Yes | No | Blood/cracked-glass screen splatter, rain on the "lens", damage-direction vignette | Conveying character state via the presentation layer / 4th-wall surface |
+
+Guidance:
+
+- Default competitive and twitch genres (shooters, MOBAs, fighting) to **non-diegetic** for raw readability; reserve diegetic/meta for ambience.
+- Diegetic elements must degrade gracefully — if the player can't see the gun, they can't see the ammo, so pair with an accessibility fallback (toggleable non-diegetic readout).
+- **Minimalist / no-HUD trends**: contextual fade (show on change, fade when idle), HUD-on-demand (hold a button to reveal), and full no-HUD modes (Journey, photo modes). Always make HUD density a player setting rather than a hard removal.
+- Never encode critical state in a single channel that a player may have disabled (color, a diegetic-only readout, an audio-only cue).
+
+## High-motion accessibility
+
+### Vestibular / motion triggers
+
+Provide **in-game toggles** for each of the following AND honor the OS / platform "reduce motion" signal (`prefers-reduced-motion` on web, the equivalent OS accessibility flag on console/mobile). The in-game control overrides, but reduced-motion should set the safe default.
+
+- Camera shake (combat, explosions, footsteps) — slider 0–100%, not just on/off.
+- Parallax and large background motion in menus and HUD.
+- Head-bob / weapon-sway / view-bob during locomotion.
+- Screen-wide motion: speed lines, motion blur, chromatic aberration, full-screen zoom/punch.
+- Field-of-view (FOV) slider; narrow FOV is a common nausea trigger in first-person.
+
+### Photosensitive epilepsy (PSE)
+
+- No more than **three general flashes per second** over any one-second window (WCAG 2.3.1 *Three Flashes or Below Threshold*; aligns with the Harding/ITU broadcast limit).
+- Apply extra caution to **saturated red** flashes — red flashing is disproportionately provocative and has a stricter threshold than general luminance flashes.
+- Avoid large high-contrast rapidly-alternating patterns (stripes, checkerboards) covering a large area of the screen.
+- Surface a PSE warning at first launch and document risky effects; offer a "reduce flashing" toggle that caps strobe effects.
+
+### Motion-sickness comfort (esp. VR)
+
+- Comfort vignette / tunneling that narrows peripheral vision during fast movement or turns.
+- **Snap-turn** (discrete angular increments) as an alternative to smooth turning; teleport locomotion as an alternative to smooth movement.
+- Fixed visual reference (cockpit, nose, horizon line) and a static-world option.
+
+## ESRB / PEGI age-gates & content disclosure
+
+- **Neutral date-of-birth gate**: collect day/month/year with **no pre-filled default** and no shortcut. Do **not** use a "Are you 18?" yes/no toggle or any single-tap affirmation — these are non-compliant gates. The gate should not telegraph the passing answer.
+- Display the **correct regional rating**: ESRB (North America, esrb.org), PEGI (Europe, pegi.info), plus regional bodies where shipped (USK in Germany, CERO in Japan, ACB in Australia, GRAC in Korea, ClassInd in Brazil).
+- Show **content descriptors** alongside the rating mark (e.g., Violence, Blood, Strong Language, Sexual Content, Use of Drugs) and **interactive elements** notices.
+- Disclose **in-game purchases** and the **"Includes Random Items"** / loot-box descriptor when paid randomized rewards exist; honor regional loot-box and odds-disclosure rules (e.g., published drop-rate odds where required).
+- See ESRB ratings guide: https://www.esrb.org/ratings-guide/ and PEGI: https://pegi.info/.
+
+## Input model — controller-first vs touch-first vs KB/M
+
+Detect the **active** input device and adapt; never assume mouse hover exists.
+
+- **Spatial focus navigation**: every interactive element must be reachable and selectable via D-pad / left-stick with a clearly visible focus highlight. Maintain a sane focus order and wrap/clamp logic; nothing should be reachable by pointer only.
+- **Adaptive button-prompt glyphs**: on-screen prompts must swap to match the detected device (Xbox A/B/X/Y, PlayStation cross/circle/square/triangle, Nintendo A/B/X/Y, or KB/M key caps). Re-detect on device switch mid-session.
+- **No hover-only affordances**: tooltips, reveals, and actions that only appear on mouse hover are invisible to controller and touch. Provide a focus/press equivalent.
+- **Dead-zone & cursor-vs-stick**: expose stick dead-zone and sensitivity; if a virtual cursor is driven by a stick, tune acceleration; distinguish analog cursor from discrete focus navigation.
+- **TV-safe area / overscan**: keep critical HUD and text inside a safe margin (target ~5% inset, the action-safe region) so nothing is clipped on overscanning TVs; offer a HUD-bounds/safe-area adjustment screen.
+- **Touch-first**: minimum touch target ~44–48 px; thumb-reach zones; avoid placing controls under resting thumbs; provide on-screen stick/buttons that can be repositioned and resized.
+- **Remappable controls as accessibility**: full rebinding for every action (including toggle-vs-hold options and the ability to remap sprint/crouch/aim) is an accessibility requirement, not a luxury.
+
+## Feedback & game-feel
+
+- **Juice, used deliberately**: hit-stop (brief freeze on impact), screen-shake, particle bursts, and squash/stretch sell impact — but screen-shake and heavy effects must be **sparing and toggleable** (ties into the vestibular sliders above).
+- **Readable damage / state feedback without color alone**: pair damage-direction indicators with shape/position, low-health with a non-color cue (audio heartbeat, vignette + icon), and status effects with distinct icons + text, not just a tint. This satisfies the color-independence requirement (WCAG 1.4.1 *Use of Color* as a design north star).
+- **Latency budgets**: target end-to-end input-to-photon responsiveness — roughly under ~100 ms feels responsive, under ~50 ms feels tight; competitive/rhythm titles need the tightest budgets. Never debounce or animation-gate a core action input so heavily that it adds perceptible lag.
+- **Multi-channel confirmation**: important events (pickup, hit-confirm, objective complete) should land on at least two of {visual, audio, haptic} so a player with one channel disabled still gets feedback.
+
+## Detection signals
+
+GDD activates this domain when it sees these signals in the repo or brief.
+
+**Keywords** (prose, file names, route/scene names): `game`, `HUD`, `player`, `level`, `multiplayer`, `leaderboard`, `inventory`, `quest`, `sprite`, `gamepad`, `controller`, `respawn`, `loot`.
+
+**`package.json` dependencies** (any one is a strong signal):
+
+| Dependency | Engine / role |
+|------------|---------------|
+| `phaser` | 2D HTML5 game framework |
+| `three` | WebGL 3D renderer |
+| `@react-three/fiber` | React renderer for three.js |
+| `@react-three/drei` | Helpers for react-three-fiber |
+| `pixi.js` | 2D WebGL rendering |
+| `babylonjs` / `@babylonjs/core` | 3D game engine |
+| `colyseus` | Authoritative multiplayer server |
+| `playcanvas` | 3D/WebGL game engine |
+| `excalibur` | TypeScript 2D game engine |
+| `matter-js` | 2D physics engine |
+
+The presence of a game engine dep plus any HUD/player keyword should auto-route the project into this domain.
+
+## Audit checklist
+
+1. Every motion effect (camera shake, parallax, head-bob, motion blur, screen-wide zoom) respects the OS reduced-motion setting AND exposes an in-game slider (not just on/off).
+2. No visual effect flashes more than **three times per second**, and saturated-red flashing is specifically avoided (WCAG 2.3.1); a PSE warning is shown at first launch.
+3. An FOV slider and a motion-sickness comfort option (vignette/tunneling; snap-turn or teleport in VR) are present where the camera is first/close-third person.
+4. The age gate is a **neutral date-of-birth entry** with no pre-filled default — not an "Are you 18?" yes/no toggle.
+5. The correct regional rating mark, content descriptors, and an in-game-purchase / loot-box ("Includes Random Items") disclosure are displayed.
+6. Every interactive element is reachable via D-pad / stick focus navigation with a visible focus highlight; nothing is pointer-only.
+7. On-screen button prompts adapt to the active input device (Xbox / PlayStation / Nintendo / KB-M) and re-detect on device switch; nothing relies on mouse hover.
+8. Critical HUD and text sit inside a TV-safe / action-safe margin (~5% inset) and survive overscan; a HUD-bounds adjustment exists where relevant.
+9. All gameplay controls are fully remappable (with toggle-vs-hold options) as an accessibility provision.
+10. No critical state is encoded by color alone — damage, low-health, and status effects use shape, position, icon+text, or audio in addition to color.
+11. Screen-shake and other "juice" are sparing and toggleable; core action inputs are not animation-gated into perceptible lag (input-to-response budget honored).
+12. Important events (hit-confirm, pickup, objective) are confirmed on at least two of visual / audio / haptic channels.

package/reference/domains/healthcare-patterns.md

@@ -0,0 +1,103 @@
+# Healthcare & Clinical Design Patterns
+
+This pack covers domain-specific UI/UX patterns for healthcare, clinical, and EHR/EMR software: HIPAA-aware forms, audit-trail surfaces, patient-portal flows, accessibility for vulnerable populations, and safe medical-data visualization. GDD loads it automatically when it detects a healthcare/clinical/EHR project from the signals below. GDD surfaces these patterns and flags likely risks; it does **not** certify HIPAA compliance — that is a legal and organizational process (Business Associate Agreements, Security Risk Analysis, counsel sign-off) that no design tool can perform.
+
+## HIPAA-aware form patterns
+
+Protected Health Information (PHI) is any individually identifiable health data — the 18 HIPAA identifiers include name, dates (DOB, admission), MRN, account numbers, biometric IDs, full-face photos, and any of the geographic/contact fields. Design forms so PHI is contained, intentional, and minimal.
+
+- **PHI isolation.** Keep PHI fields in clearly bounded form sections, visually and structurally separate from non-PHI (preferences, UI settings, marketing opt-ins). This makes the data classification obvious to engineers and supports field-level encryption/access scoping downstream.
+- **Minimum-necessary principle.** The HIPAA Privacy Rule requires using/disclosing only the PHI needed for the task. Do not collect a field "just in case." Every PHI input should map to a stated purpose; prefer progressive disclosure over one giant intake form.
+- **Never leak PHI into ambient surfaces.** No PHI in URLs, path segments, or query strings (`/patient/12345?ssn=...` is a breach vector — it lands in browser history, server logs, and `Referer` headers). No PHI in page `<title>`, no PHI in client analytics events (Google Analytics, Segment, Mixpanel, session-replay tools like FullStory/Hotjar — these are notorious for inadvertent capture), and no PHI written to console or client logs.
+- **Session auto-logout + idle timeout.** Auto-terminate or lock the session after **10-15 minutes** of inactivity (shorter on shared/kiosk workstations). Show a countdown warning ~60s before logout with an "I'm still here" extend action. Clear in-memory PHI on logout; never persist PHI to `localStorage`.
+- **Break-the-glass emergency access.** When a clinician needs records outside their normal authorization (e.g., a patient in the ED who isn't theirs), allow override but **capture justification at the moment of access** (free-text reason + structured reason code), warn that the access is logged and reviewed, and flag the event for compliance audit. The friction is intentional.
+- **Auto-fill / autocomplete.** Disable browser autofill on sensitive fields (`autocomplete="off"` where appropriate) and never pre-fill another patient's data into a shared form.
+
+## Audit trails as UI
+
+Access logging is mandated by the HIPAA Security Rule (audit controls, §164.312(b)). Treat the audit log as a first-class, user-visible feature — not just a backend table.
+
+- **Who-accessed-what.** Surface access events with actor identity, role, timestamp, the specific record/section viewed, and the action (view/edit/export/print).
+- **Access reason.** Where access requires justification (break-the-glass, sensitive segments), display the captured reason inline with the event.
+- **Immutability.** Audit entries are append-only. The UI must never offer edit/delete on a log row; show it as a read-only, chronological ledger. Surface tamper-evidence (e.g., sequence numbers) if the backend provides it.
+- **Patient-facing "who saw my record."** Patient portals should let patients review an access history of their own chart and report suspected inappropriate access. This supports the patient's right to an accounting of disclosures.
+
+## Patient-portal flows (MyChart-class)
+
+Patient portals (MyChart, Athenahealth, Healow-style) share a recognizable set of flows. Design each with the safety/consent rules below.
+
+| Flow | Key design considerations |
+|------|---------------------------|
+| Appointment scheduling | Real-time slot availability, visit-type/reason capture, pre-visit forms, reminders, easy reschedule/cancel with cancellation-window rules. |
+| Lab / result release | Respect **provider hold windows** — sensitive results (oncology, genetics, HIV, pathology) may be embargoed so the provider can contact the patient first. Note: the ONC Information Blocking rule (21st Century Cures Act) generally requires *prompt* release, so holds must be narrow and policy-driven. Always show units + reference ranges (see visualization). |
+| Proxy / caregiver access | Distinct, scoped access for parents of minors, caregivers, and guardians. Handle the **adolescent-confidentiality transition** (access often narrows at age 12-18 per state law). Show proxies clearly whose record they are viewing. |
+| Secure messaging | Encrypted in-app messaging with care team, not email/SMS. Set expectations (not for emergencies — direct to 911/ED), show response-time SLAs, and capture message threads in the chart. |
+| After-visit summary (AVS) | Plain-language recap of the visit: diagnoses, meds, instructions, follow-ups. Printable/downloadable, reading-level controlled. |
+| Prescription / refills | Refill requests, pharmacy selection, and medication lists with names, doses, and clear active/discontinued status. |
+
+## Accessibility-first
+
+Healthcare reaches the broadest, most impaired population of any domain: elderly users, low vision, motor and cognitive impairment, low health literacy, limited English proficiency, and people in pain or distress. Target **WCAG 2.1 Level AAA** where feasible (not just AA) and design for stress cases.
+
+- **Touch targets.** Minimum **44x44 px** (Apple HIG / WCAG 2.5.5 AAA recommends 44pt; Material recommends 48dp). Generous spacing between targets to prevent mis-taps.
+- **Contrast.** AAA text contrast is **7:1** for normal text and **4.5:1** for large text (vs. AA's 4.5:1 / 3:1). Do not rely on hairline gray-on-gray.
+- **Plain medical language + reading level.** Default to plain language (CDC guidance targets roughly a 6th-8th grade reading level for patient materials). Offer a reading-level / "explain this" control, expand acronyms (BP, A1C), and pair clinical terms with lay equivalents ("hypertension (high blood pressure)").
+- **Error messages that explain.** Say what is wrong, why, and how to fix it ("Date of birth must be in the past — use MM/DD/YYYY"). Never error-by-color-only; include text + icon and associate the message programmatically with the field (`aria-describedby`).
+- **Scalable type & zoom.** Support 200% zoom and OS text-scaling without loss of content (WCAG 1.4.4 / 1.4.10 reflow). Respect `prefers-reduced-motion`.
+- **Language access.** Support translation/interpreter pathways; civil-rights rules (ACA Section 1557) expect meaningful access for limited-English-proficiency patients.
+
+## Medical-data visualization
+
+Lab and vitals visualization is safety-critical. The goal is accurate interpretation without implying a diagnosis the data does not support.
+
+- **Values with reference ranges + units.** Every result shows the value, the **unit** (mg/dL, mmol/L, mEq/L — unit ambiguity causes real harm), and the lab's reference range. Ranges can be age/sex-specific; show the applicable range.
+- **Normal / abnormal / critical flags.** Mark results as within-range, abnormal (H/L), or critical (HH/LL / panic value). Critical values warrant the strongest treatment.
+- **Never color-only for critical values.** Encode status with **icon + text + position**, not hue alone (8% of men have color-vision deficiency). A red dot is invisible to many users and to grayscale printouts; pair it with an explicit "Critical — High" label and an icon.
+- **Trends over time.** Plot longitudinal values with the reference band shaded behind the line so abnormality is visible at a glance. Label axes with units; keep consistent scales when comparing.
+- **Avoid implying diagnosis.** Present data and flags, not conclusions. Don't auto-label a value as a disease; surface it as a flagged result for clinician interpretation. Show result status (preliminary vs. final), collection time, and the ordering provider.
+
+## Detection signals
+
+GDD auto-detects this domain from project keywords and dependencies.
+
+**Keywords (code, copy, file/route names):** `patient`, `clinical`, `EHR`, `EMR`, `telehealth`, `HIPAA`, `PHI`, `provider`, `diagnosis`, `prescription`, plus supporting terms like `MRN`, `chart`, `encounter`, `appointment`, `lab result`.
+
+**`package.json` dependencies (strong signal):**
+
+| Package | Indicates |
+|---------|-----------|
+| `fhir` | FHIR resource models/parsing |
+| `fhirclient` | SMART on FHIR client (EHR launch) |
+| `fhir-kit-client` | FHIR REST client |
+| `@medplum/core` / `medplum` | Medplum healthcare platform SDK |
+| `hl7` | HL7 v2 messaging |
+| `@types/fhir` | FHIR TypeScript types |
+| `redox` | Redox EHR integration engine |
+
+Any FHIR/HL7/Medplum/Redox dependency, or a cluster of the keywords above, should trigger loading this pack.
+
+## Audit checklist
+
+Concrete, verifiable items for reviewing a healthcare UI:
+
+1. **No PHI in URLs, path params, query strings, page titles, or client analytics/session-replay events.** Inspect routes and analytics payloads for identifiers.
+2. **Forms collect only minimum-necessary PHI** — each PHI field maps to a stated purpose; no speculative "just in case" fields.
+3. **PHI fields are isolated** from non-PHI (preferences, marketing) in clearly bounded sections.
+4. **Session auto-logs-out after a 10-15 min idle timeout**, with a countdown warning and an extend action; in-memory PHI is cleared and never stored in `localStorage`.
+5. **Break-the-glass / emergency access captures a justification** (reason code + free text), warns the user it is logged, and flags the event for review.
+6. **An immutable, append-only access log is surfaced in the UI** (actor, role, timestamp, record, action) with no edit/delete affordance.
+7. **Patients can view who accessed their own record** and report suspected inappropriate access.
+8. **Sensitive lab/result release honors provider hold windows** and proxy/adolescent-confidentiality rules.
+9. **Lab results show value + unit + reference range**, with normal/abnormal/critical flags.
+10. **Lab criticals are flagged by icon + text (and position), not color alone**, and remain legible in grayscale.
+11. **Visualizations present flagged data, not diagnoses** — no auto-labeling of results as a disease.
+12. **Accessibility meets the AAA bar where feasible:** touch targets >= 44x44 px, 7:1 text contrast, plain-language/reading-level control, and error messages that explain what's wrong and how to fix it.
+
+## Canonical references
+
+- HIPAA Privacy & Security Rules (HHS): https://www.hhs.gov/hipaa/for-professionals/index.html
+- HHS guidance on tracking technologies and PHI: https://www.hhs.gov/hipaa/for-professionals/privacy/guidance/index.html
+- WCAG 2.1 (W3C/WAI): https://www.w3.org/TR/WCAG21/
+- WAI accessibility guidance: https://www.w3.org/WAI/
+- HL7 FHIR specification: https://hl7.org/fhir/
+- ONC Cures Act / information blocking (HealthIT.gov): https://www.healthit.gov/topic/information-blocking

package/reference/registry.json

@@ -937,6 +937,34 @@
       "type": "heuristic",
       "phase": 35.5,
       "description": "Phase 35.5 /gdd:export contract — the source set (EXPERIENCE.md + DESIGN.md + DESIGN-VERIFICATION.md + decisions + screenshots), the three formats (self-contained HTML via scripts/lib/export/build-html.cjs, Paged.js-compatible print PDF rendered by the user, Notion page via the Notion MCP), mandatory scripts/lib/redact.cjs + the --pseudonymize opt-in (scripts/lib/pseudonymize.cjs), and the --pr hand-off to pr-commenter. No bundled PDF/markdown runtime (D-02)."
+    },
+    {
+      "name": "finance",
+      "path": "reference/domains/finance-patterns.md",
+      "type": "heuristic",
+      "phase": 36.1,
+      "description": "Phase 36.1 Tier-3 domain pack — finance/fintech UI patterns: data-table density (tabular-nums), trading-interface conventions (colorblind-safe gain/loss), regulatory disclosure placement (Reg-T, MiFID II), PCI-DSS PAN masking, number-formatting precision, real-time data states. Carries Detection signals (keywords + deps) + an Audit checklist consumed by design-context-builder Step 0F + design-auditor."
+    },
+    {
+      "name": "healthcare",
+      "path": "reference/domains/healthcare-patterns.md",
+      "type": "heuristic",
+      "phase": 36.1,
+      "description": "Phase 36.1 Tier-3 domain pack — healthcare/clinical UI patterns: HIPAA-aware PHI isolation (no PHI in URLs/logs/analytics), idle auto-logout, audit-trail-as-UI, MyChart-class flows, WCAG 2.1 AAA, medical-data visualization. Surfaces risk, does not certify compliance. Detection signals + Audit checklist for Step 0F + design-auditor."
+    },
+    {
+      "name": "gaming",
+      "path": "reference/domains/gaming-patterns.md",
+      "type": "heuristic",
+      "phase": 36.1,
+      "description": "Phase 36.1 Tier-3 domain pack — game UI/HUD patterns: diegetic/non-diegetic/spatial/meta HUD taxonomy, vestibular + photosensitive safety (3 flashes/sec, reduced-motion + in-game toggles), ESRB/PEGI age-gates, input-model adaptation (controller/touch/KBM), TV-safe area. Detection signals + Audit checklist for Step 0F + design-auditor."
+    },
+    {
+      "name": "civic",
+      "path": "reference/domains/civic-patterns.md",
+      "type": "heuristic",
+      "phase": 36.1,
+      "description": "Phase 36.1 Tier-3 domain pack — civic/government UI patterns: Section 508 + WCAG 2.1 AA hard floor, multi-language gov forms (EN/ES/zh-Hans), Plain Writing Act (grade 6-8), USWDS, session-timeout warnings, one-thing-per-page forms. Detection signals + Audit checklist for Step 0F + design-auditor."
     }
   ]
 }

package/scripts/lib/motion/validate-motion.cjs

@@ -0,0 +1,92 @@
+'use strict';
+/**
+ * scripts/lib/motion/validate-motion.cjs — Phase 36.2 motion-export validator.
+ *
+ * Pure + dep-free (D-01): zero `require`, no Lottie/Rive runtime. Deterministic — same
+ * input → same output (hermetic tests, D-06). Every finding is a WARNING, never a hard
+ * error (D-02: motion is creative, not contractually broken) — the caller decides whether
+ * a `must_have` escalates it.
+ *
+ * - validateLottie(json, {bytes?, budgetBytes?}) → {ok, warnings:[{rule,detail}], info}
+ *     structural + perf sanity on a Lottie JSON (parsed object OR string).
+ * - motionBudget(bytes, budgetBytes?) → {rule:'MO-BUDGET', detail} | null  (shared by Lottie + Rive)
+ * - riveHeader(headerBytes) → boolean   (cheap .riv magic-byte sanity; the deep state-machine
+ *     graph needs the Rive runtime — out of pure-JS reach, D-04)
+ *
+ * Rules: MO-PARSE, MO-FR, MO-DUR, MO-LAYERS, MO-IMG, MO-BUDGET.
+ */
+
+const DEFAULT_BUDGET_BYTES = 200 * 1024; // 200 KB — D-05 fallback when config has no motion_budget_kb
+
+function motionBudget(bytes, budgetBytes = DEFAULT_BUDGET_BYTES) {
+  if (typeof bytes !== 'number' || !isFinite(bytes) || bytes < 0) return null;
+  if (bytes > budgetBytes) {
+    return { rule: 'MO-BUDGET', detail: `motion bundle ${(bytes / 1024).toFixed(1)}KB exceeds budget ${(budgetBytes / 1024).toFixed(0)}KB` };
+  }
+  return null;
+}
+
+function validateLottie(input, opts = {}) {
+  let j;
+  if (typeof input === 'string') {
+    try { j = JSON.parse(input); } catch (e) {
+      return { ok: false, warnings: [{ rule: 'MO-PARSE', detail: 'not valid JSON' }], info: {} };
+    }
+  } else if (input && typeof input === 'object') {
+    j = input;
+  } else {
+    return { ok: false, warnings: [{ rule: 'MO-PARSE', detail: 'no input' }], info: {} };
+  }
+
+  // Lottie signature: version `v`, framerate `fr`, in/out points `ip`/`op`, `layers` array.
+  const isLottie = j && typeof j === 'object' && 'v' in j && 'fr' in j && Array.isArray(j.layers);
+  if (!isLottie) {
+    return { ok: false, warnings: [{ rule: 'MO-PARSE', detail: 'not a Lottie document (missing v / fr / layers)' }], info: {} };
+  }
+
+  const warnings = [];
+  const fr = Number(j.fr);
+  const ip = Number(j.ip);
+  const op = Number(j.op);
+  const layers = j.layers.length;
+
+  if (!(fr > 0) || fr > 120) warnings.push({ rule: 'MO-FR', detail: `frame rate ${j.fr} is outside the sane 1-120 range` });
+  if (!(op > ip)) warnings.push({ rule: 'MO-DUR', detail: `non-positive duration (ip=${j.ip}, op=${j.op})` });
+  if (layers > 200) warnings.push({ rule: 'MO-LAYERS', detail: `${layers} layers — high; review runtime cost` });
+
+  // Embedded raster assets bloat the bundle — a Lottie asset with an inline data URI in `p`.
+  const assets = Array.isArray(j.assets) ? j.assets : [];
+  const embedded = assets.filter((a) => a && typeof a.p === 'string' && /^data:/.test(a.p)).length;
+  if (embedded > 0) warnings.push({ rule: 'MO-IMG', detail: `${embedded} embedded raster asset(s) — prefer external / optimized images` });
+
+  // Perf budget (only when the caller supplies the on-disk byte size).
+  if (typeof opts.bytes === 'number') {
+    const b = motionBudget(opts.bytes, opts.budgetBytes);
+    if (b) warnings.push(b);
+  }
+
+  const durationFrames = op - ip;
+  return {
+    ok: warnings.length === 0,
+    warnings,
+    info: {
+      fr,
+      layers,
+      durationFrames,
+      durationSeconds: fr > 0 ? Number((durationFrames / fr).toFixed(2)) : null,
+      embeddedAssets: embedded,
+    },
+  };
+}
+
+function riveHeader(headerBytes) {
+  // .riv files begin with the ASCII magic "RIVE". Accept a string or an array of byte values.
+  const s = typeof headerBytes === 'string'
+    ? headerBytes.slice(0, 4)
+    : Array.isArray(headerBytes)
+      ? String.fromCharCode.apply(null, headerBytes.slice(0, 4))
+      : '';
+  return s === 'RIVE';
+}
+
+module.exports = { validateLottie, motionBudget, riveHeader, DEFAULT_BUDGET_BYTES };

package/skills/connections/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-connections
-description: "Interactive onboarding wizard for the 19 external integrations the pipeline supports — probes all (`figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`, `lazyweb`, `mobbin`, `slack`, `discord`, `linear`, `jira`, `notion`), recommends based on project type, walks the user through setup (auto-run MCP install or copy-command fallback), writes results to `STATE.md <connections>`. Use after `/gdd:new-project` or whenever the user wants to add, inspect, or skip a connection. Re-runnable anytime."
+description: "Interactive onboarding wizard for the 21 external integrations the pipeline supports — probes all (`figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`, `lazyweb`, `mobbin`, `slack`, `discord`, `linear`, `jira`, `notion`, `lottie`, `rive`), recommends based on project type, walks the user through setup (auto-run MCP install or copy-command fallback), writes results to `STATE.md <connections>`. Use after `/gdd:new-project` or whenever the user wants to add, inspect, or skip a connection. Re-runnable anytime."
 argument-hint: "[list | <connection-name> | --auto]"
 user-invocable: true
 tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, ToolSearch
@@ -8,11 +8,11 @@ tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, ToolSearch
 
 # /gdd:connections
 
-Interactive onboarding for the 19 external integrations the pipeline supports. Replaces "probe silently at scan entry and hope the user noticed" with an explicit "here is what can plug in, here is how."
+Interactive onboarding for the 21 external integrations the pipeline supports. Replaces "probe silently at scan entry and hope the user noticed" with an explicit "here is what can plug in, here is how."
 
 Canonical per-connection specs live in `../../connections/<name>.md` (one file per integration). The capability matrix + probe-pattern spec live in `../../connections/connections.md`. This skill is the **user-facing front end** for those specs.
 
-For the 19 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization, per-connection setup screen, auto-run eligibility matrix, value-prop one-liners, and STATE.md / config.json write contracts, see `./connections-onboarding.md`. For the cross-skill probe pattern + connection-handshake summary, see `../../reference/shared-preamble.md#connection-handshake-summary`. For the cross-skill output discipline, see `../../reference/shared-preamble.md#output-contract-reminders`.
+For the 21 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization, per-connection setup screen, auto-run eligibility matrix, value-prop one-liners, and STATE.md / config.json write contracts, see `./connections-onboarding.md`. For the cross-skill probe pattern + connection-handshake summary, see `../../reference/shared-preamble.md#connection-handshake-summary`. For the cross-skill output discipline, see `../../reference/shared-preamble.md#output-contract-reminders`.
 
 ---
 
@@ -38,7 +38,7 @@ For the 19 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization
 
 ## Workflow
 
-1. **Probe all 19 connections** — run every probe script per `./connections-onboarding.md#step-1--probe-all-19-connections`. MCP probes use `ToolSearch` first; HTTP / CLI / file probes follow non-MCP patterns. Merge results into `STATE.md <connections>` with the three-value schema (`available | unavailable | not_configured`) — never add new values.
+1. **Probe all 21 connections** — run every probe script per `./connections-onboarding.md#step-1--probe-all-21-connections`. MCP probes use `ToolSearch` first; HTTP / CLI / file probes follow non-MCP patterns. Merge results into `STATE.md <connections>` with the three-value schema (`available | unavailable | not_configured`) — never add new values.
 2. **Categorize + build summary** — bucket each probe result (available / recommended / optional / skipped / unavailable) using project-hint detection. Detail + recommendation mapping: `./connections-onboarding.md#step-2--bucket-categorization`.
 3. **Print summary table** — show buckets + value-prop one-liners (verbatim from `./connections-onboarding.md#step-3--summary-table`).
 4. **Route by mode** — `list` / `--auto` exits after summary; `<name>` jumps straight to Step 5; default mode opens an AskUserQuestion (configure recommended / pick one by one / configure all optional / re-check specific / exit). Routing detail: `./connections-onboarding.md#step-4--route-by-mode`.