@hegemonart/get-design-done 1.42.0 → 1.44.0

package/reference/shared-preamble.md

@@ -9,7 +9,7 @@ last_updated: 2026-05-18
 
 # GSD Agent Shared Preamble
 
-> **This file is imported via `@reference/shared-preamble.md` as the first line of every agent body in `agents/*.md`. Its placement is load-bearing for Anthropic's 5-minute prompt cache (see `./model-tiers.md` and Phase 10.1 decision D-08 Layer A): because every agent opens with the identical preamble prefix, the second and subsequent agent spawns in a session pay `cached_input_per_1m` rates rather than full `input_per_1m` rates for these bytes. Do not inline this content into agent bodies — always import.**
+> **This file is imported via `@reference/shared-preamble.md` as the first line of every agent body in `agents/*.md`. Its placement is essential for Anthropic's 5-minute prompt cache (see `./model-tiers.md` and Phase 10.1 decision D-08 Layer A): because every agent opens with the identical preamble prefix, the second and subsequent agent spawns in a session pay `cached_input_per_1m` rates rather than full `input_per_1m` rates for these bytes. Do not inline this content into agent bodies - always import.**
 >
 > **As of Phase 14.5 this file is an aggregator.** The framework-invariant subsections (Required Reading Discipline, Writes Protocol, Deviation Handling, Completion Markers, Context-Exhaustion & Budget awareness) live in `./meta-rules.md` (tier L0) so the L2 heuristics/anti-patterns/checklists churn never invalidates the L0 prefix.
 >
@@ -26,7 +26,7 @@ Two distinct consumers, one canonical home:
 
 ## Framework Identity
 
-You are a GSD agent operating under the `get-design-done` plugin contract (see `agents/README.md` for the full authoring contract). You are spawned by a pipeline stage (or by another agent) via the Claude Code `Task` tool with a fully self-contained prompt. You have **zero session memory** — everything you need is in the prompt string and the files listed inside its `<required_reading>` block.
+You are a GSD agent operating under the `get-design-done` plugin contract (see `agents/README.md` for the full authoring contract). You are spawned by a pipeline stage (or by another agent) via the Claude Code `Task` tool with a fully self-contained prompt. You have **zero session memory** - everything you need is in the prompt string and the files listed inside its `<required_reading>` block.
 
 You are one step in a pipeline. You do not own the pipeline. The orchestrator decides what runs next based on your output.
 
@@ -34,25 +34,25 @@ You are one step in a pipeline. You do not own the pipeline. The orchestrator de
 
 Your agent body is structured in this exact order so the cache prefix stays stable:
 
-1. **Shared preamble import** — this file, imported at the top via `@reference/shared-preamble.md`. Same bytes across every agent → caches.
-2. **Agent-specific role, tools contract, and output format** — unique to you, the "role" section the orchestrator relies on. Stable across invocations of the same agent → caches per-agent after the first call.
-3. **Dynamic task-specific content** — the `<required_reading>` block, per-invocation inputs, the concrete task description. Different every call → never caches.
+1. **Shared preamble import** - this file, imported at the top via `@reference/shared-preamble.md`. Same bytes across every agent → caches.
+2. **Agent-specific role, tools contract, and output format** - unique to you, the "role" section the orchestrator relies on. Stable across invocations of the same agent → caches per-agent after the first call.
+3. **Dynamic task-specific content** - the `<required_reading>` block, per-invocation inputs, the concrete task description. Different every call → never caches.
 
 Do not reorder. Do not inline this preamble. Do not splice dynamic content ahead of your stable role description. Every deviation costs the cache.
 
 ## Pre-Warming
 
-The `/gdd:warm-cache` command (ships in Plan 10.1-02) pre-warms this identical prefix in the Anthropic cache before a design sprint, so the first real agent spawn of the sprint is already a cache hit on the shared-preamble bytes. You do not need to do anything special to participate — just keep the import directive at the top of your body.
+The `/gdd:warm-cache` command (ships in Plan 10.1-02) pre-warms this identical prefix in the Anthropic cache before a design sprint, so the first real agent spawn of the sprint is already a cache hit on the shared-preamble bytes. You do not need to do anything special to participate - just keep the import directive at the top of your body.
 
 ## Design Philosophy Layer (Phase 19.6)
 
 The framework is anchored to three design philosophy references that agents may read during brief, audit, and verify stages:
 
-- `./first-principles.md` — 3-invariant framework (body, attention, memory); reducibility test for every design element
-- `./emotional-design.md` — Norman's visceral / behavioral / reflective cross-cutting scoring lens
-- `./component-authoring.md` — Kowalski/Sonner 6-principle component quality standard (P-01 through P-06)
+- `./first-principles.md` - 3-invariant framework (body, attention, memory); reducibility test for every design element
+- `./emotional-design.md` - Norman's visceral / behavioral / reflective cross-cutting scoring lens
+- `./component-authoring.md` - Kowalski/Sonner 6-principle component quality standard (P-01 through P-06)
 
-These references encode *why* the heuristics and anti-patterns exist — not rules to follow, but constraints derived from human biology and cognition. Agents that read these files apply them as lenses, not checklists.
+These references encode *why* the heuristics and anti-patterns exist - not rules to follow, but constraints derived from human biology and cognition. Agents that read these files apply them as lenses, not checklists.
 
 ---
 
@@ -60,13 +60,13 @@ These references encode *why* the heuristics and anti-patterns exist — not rul
 
 Seven pillars score every design audit (see `./audit-scoring.md` for the weighted-rubric detail; this section is the one-paragraph summary that the design-family skills cross-link). Used by `skills/audit`, `skills/style`, `skills/compare`.
 
-1. **Accessibility** — WCAG 2.1 AA threshold compliance; keyboard navigation; non-color signalling. See also `./contrast-advanced.md` (APCA / WCAG 3 perceptual layer).
-2. **Visual hierarchy** — F/Z scanning paths; primary action prominence; section pacing. See `./visual-hierarchy-layout.md`.
-3. **Typography** — type scale ratio (1.125 → 1.5), font-pair count cap (≤2), reading rhythm (`./typography.md`).
-4. **Color** — palette source-of-truth, contrast pair density, OKLCH discipline, semantic-token coverage (`./palette-catalog.md`, `./color-theory.md`).
-5. **Spacing & rhythm** — 4 px or 8 px modular scale, vertical-rhythm consistency (`./composition.md`, `./proportion-systems.md`).
-6. **Component coherence** — minimal API surface, animation as state, edge honesty (`./component-authoring.md`).
-7. **Anti-patterns** — BAN-*, SLOP-* tags from `./anti-patterns.md`; emotional design conflict patterns from `./emotional-design.md`.
+1. **Accessibility** - WCAG 2.1 AA threshold compliance; keyboard navigation; non-color signalling. See also `./contrast-advanced.md` (APCA / WCAG 3 perceptual layer).
+2. **Visual hierarchy** - F/Z scanning paths; primary action prominence; section pacing. See `./visual-hierarchy-layout.md`.
+3. **Typography** - type scale ratio (1.125 → 1.5), font-pair count cap (≤2), reading rhythm (`./typography.md`).
+4. **Color** - palette source-of-truth, contrast pair density, OKLCH discipline, semantic-token coverage (`./palette-catalog.md`, `./color-theory.md`).
+5. **Spacing & rhythm** - 4 px or 8 px modular scale, vertical-rhythm consistency (`./composition.md`, `./proportion-systems.md`).
+6. **Component coherence** - minimal API surface, animation as state, edge honesty (`./component-authoring.md`).
+7. **Anti-patterns** - BAN-*, SLOP-* tags from `./anti-patterns.md`; emotional design conflict patterns from `./emotional-design.md`.
 
 Score range per pillar: 0–10. Audit-overall = weighted average per `./audit-scoring.md` weights.
 
@@ -78,9 +78,9 @@ Design tokens are the discipline that prevents the 60+ raw-hex `#5C5C5C` audit-f
 
 Three audit signals:
 
-- **Raw-hex ratio** — `grep -rEo "#[0-9a-fA-F]{6}" src/` divided by total color uses. Healthy < 5 %.
-- **Token coverage** — every semantic role (primary, surface, on-surface, etc.) has a defined token. Cross-check with `./palette-catalog.md` for naming convention.
-- **Light/dark parity** — every light-mode color token has a dark-mode override (see `skills/darkmode` audit for the contrast-pair check, and `./color-theory.md` §OKLCH for the modern hue-rotation contract).
+- **Raw-hex ratio** - `grep -rEo "#[0-9a-fA-F]{6}" src/` divided by total color uses. Healthy < 5 %.
+- **Token coverage** - every semantic role (primary, surface, on-surface, etc.) has a defined token. Cross-check with `./palette-catalog.md` for naming convention.
+- **Light/dark parity** - every light-mode color token has a dark-mode override (see `skills/darkmode` audit for the contrast-pair check, and `./color-theory.md` §OKLCH for the modern hue-rotation contract).
 
 Used by: `skills/style`, `skills/darkmode`, `skills/figma-write`, `skills/audit`, `skills/compare`.
 
@@ -88,11 +88,11 @@ Used by: `skills/style`, `skills/darkmode`, `skills/figma-write`, `skills/audit`
 
 Every design-family skill writes ONE artifact (D-06 / utility-skill discipline). Recurring constraints (cited by `skills/audit`, `skills/compare`, `skills/darkmode`, `skills/figma-write`, `skills/style`):
 
-- **MUST NOT write** to pipeline-reserved paths: `DESIGN.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, `DESIGN-SUMMARY.md`, `DESIGN-VERIFICATION.md`, `.design/STATE.md` (unless the skill IS a pipeline stage — design-family skills are NOT).
+- **MUST NOT write** to pipeline-reserved paths: `DESIGN.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, `DESIGN-SUMMARY.md`, `DESIGN-VERIFICATION.md`, `.design/STATE.md` (unless the skill IS a pipeline stage - design-family skills are NOT).
 - **MUST write** the declared artifact name with a non-conflicting prefix (`DESIGN-STYLE-*`, `DARKMODE-AUDIT.md`, `COMPARE-REPORT.md`, etc.).
 - **MUST emit** a completion marker line (e.g., `## STYLE COMPLETE`, `## DARKMODE AUDIT COMPLETE`, `## COMPARE COMPLETE`) so the orchestrator can detect skill exit.
 - **MUST NOT invoke** the pipeline router (these are leaf skills, not pipeline stages).
-- **MUST NOT mutate** source files (audit-only — fixes belong in the design pipeline's color/typography/etc. task types).
+- **MUST NOT mutate** source files (audit-only - fixes belong in the design pipeline's color/typography/etc. task types).
 
 Reference paths used by completion-marker probes: see each skill's `## Completion` section for the literal artifact path.
 
@@ -102,12 +102,12 @@ The 12 external integrations (`figma`, `refero`, `preview`, `storybook`, `chroma
 
 Probe pattern (used by `skills/darkmode`, `skills/compare`, `skills/figma-write`, `skills/connections`, `skills/benchmark`):
 
-1. **ToolSearch first** — `ToolSearch({ query: "<server-name>", max_results: 5 })`. Empty result → `not_configured`. Non-empty → step 2.
-2. **Live tool call** — invoke a metadata endpoint (e.g., `preview_list`, `get_metadata`). Success → `available`. Error → `unavailable`.
-3. **Write to STATE.md `<connections>`** — three-value schema (`available | unavailable | not_configured`). Never add new values.
+1. **ToolSearch first** - `ToolSearch({ query: "<server-name>", max_results: 5 })`. Empty result → `not_configured`. Non-empty → step 2.
+2. **Live tool call** - invoke a metadata endpoint (e.g., `preview_list`, `get_metadata`). Success → `available`. Error → `unavailable`.
+3. **Write to STATE.md `<connections>`** - three-value schema (`available | unavailable | not_configured`). Never add new values.
 
 For full per-connection probe scripts (figma, refero, preview, etc.) see the individual `connections/<name>.md` files. For the onboarding wizard flow, see `./connections-onboarding.md` (Phase 28.5 extract).
 
 ---
 
-*Imported by: every file under `agents/*.md` (except `agents/README.md`). Cross-linked by: design-family skills under `skills/{audit,style,darkmode,compare,figma-write,connections,benchmark}/SKILL.md`. Maintained as part of Phase 10.1 (OPT-07), Phase 14.5 (L0/L2 split), and Phase 28.5 (Bucket 2 design-family rework — D-10). Edits to this file affect every agent simultaneously — verify across the full agent suite before committing.*
+*Imported by: every file under `agents/*.md` (except `agents/README.md`). Cross-linked by: design-family skills under `skills/{audit,style,darkmode,compare,figma-write,connections,benchmark}/SKILL.md`. Maintained as part of Phase 10.1 (OPT-07), Phase 14.5 (L0/L2 split), and Phase 28.5 (Bucket 2 design-family rework - D-10). Edits to this file affect every agent simultaneously - verify across the full agent suite before committing.*

package/reference/skill-authoring-contract.md

@@ -7,7 +7,7 @@ tags: [skill, authoring, contract, length-cap, description, frontmatter, progres
 last_updated: 2026-05-18
 ---
 
-Source: mattpocock/skills (MIT) — adapted with permission. See `../NOTICE` for the full attribution block.
+Source: mattpocock/skills (MIT) - adapted with permission. See `../NOTICE` for the full attribution block.
 
 # Skill Authoring Contract
 
@@ -27,14 +27,14 @@ Two-tier threshold, enforced by the validator (D-01):
 - **Warn at `≥100` lines.** Validator emits a warning. CI does NOT fail. Treat as a forcing
   function: a 110-line skill is fine; a 180-line skill needs a hard look at what can be
   extracted.
-- **Block at `≥250` lines.** Validator emits an error. CI FAILS. No exceptions —
+- **Block at `≥250` lines.** Validator emits an error. CI FAILS. No exceptions -
   multi-stage orchestrator skills push extraction harder, they do not waive the cap.
 
-When a skill exceeds the cap, use the extract-then-link discipline (D-10) — NEVER delete
+When a skill exceeds the cap, use the extract-then-link discipline (D-10) - NEVER delete
 content. Move it. Steps:
 
-1. Identify load-bearing workflow + decision-tree content. Keep this in `SKILL.md`.
-2. Identify domain content — heuristics, framework matrices, glossaries, extended examples.
+1. Identify essential workflow + decision-tree content. Keep this in `SKILL.md`.
+2. Identify domain content - heuristics, framework matrices, glossaries, extended examples.
    Extract to an existing `reference/<topic>.md` if the topic matches; create a new
    `reference/<topic>.md` if it does not.
 3. Replace the extracted content with a single-sentence summary + cross-link.
@@ -47,16 +47,16 @@ worst-offender and is scheduled for Bucket 1 rework in plan `28.5-04`. `skills/h
 
 Two rules:
 
-- **Length cap is STRICT.** `description ≤ 1024 chars` — no flag, no override. Under 20 chars
+- **Length cap is STRICT.** `description ≤ 1024 chars` - no flag, no override. Under 20 chars
   is also blocked as under-specification.
-- **Recommended form is LAX by default.** `<what>. Use when <triggers>.` — third person,
+- **Recommended form is LAX by default.** `<what>. Use when <triggers>.` - third person,
   first sentence what the skill does, second sentence the trigger conditions. Validator
   enforces the form regex only under `--strict-description` or `STRICT_DESCRIPTION=1`. Default
   is length-only.
 
 Why lax-by-default (D-02): `obra/superpowers/skills/writing-skills/SKILL.md` documents a
-shortcut-effect where an agent reads the description and skips the body — the more
-load-bearing the description summary, the more often this happens. Phase 33 ships an A/B
+shortcut-effect where an agent reads the description and skips the body - the more
+essential the description summary, the more often this happens. Phase 33 ships an A/B
 study at `.design/research/description-format-ab.md`; until then the regex stays advisory.
 
 Examples (both 20–1024 chars, both pass the length check):
@@ -73,18 +73,18 @@ Compares OKLCH gamut coverage against sRGB and prints a visual diff chart.
 
 Required fields (validator blocks if absent):
 
-- `name` — kebab-case skill identifier; matches `^[a-z0-9][a-z0-9-._]*$`.
-- `description` — 20–1024 chars; see `## Description format` above.
+- `name` - kebab-case skill identifier; matches `^[a-z0-9][a-z0-9-._]*$`.
+- `description` - 20–1024 chars; see `## Description format` above.
 
 Optional fields (recognized by the Claude Code agent loader):
 
-- `argument-hint` — usage hint shown in the slash-command picker.
-- `tools` — comma-separated allowed tool list (e.g. `Read, Grep`).
-- `disable-model-invocation: true|false` — when `true`, the skill fires ONLY on explicit
+- `argument-hint` - usage hint shown in the slash-command picker.
+- `tools` - comma-separated allowed tool list (e.g. `Read, Grep`).
+- `disable-model-invocation: true|false` - when `true`, the skill fires ONLY on explicit
   user invocation and the router will not auto-trigger it. Allowed ONLY on the D-09
   whitelist (pure shortcuts like `help`, `stats`, `note`, `health`, `zoom-out`). The
   validator blocks if a non-whitelisted skill sets this field to `true`.
-- `user-invocable: true|false` — whether the slash-command picker exposes the skill.
+- `user-invocable: true|false` - whether the slash-command picker exposes the skill.
 
 Concrete example:
 
@@ -103,7 +103,7 @@ References-one-level-deep is the rule (D-06):
 
 - **One level deep.** `SKILL.md` may cross-link into a reference. A reference may
   cross-link into another reference. `SKILL.md` does NOT instruct the agent to follow a
-  reference's references — load the first level only.
+  reference's references - load the first level only.
 - **When to add `scripts/`.** Per mattpocock's three criteria, add a script only when the
   step is deterministic, repeated across runs, and the failure mode needs explicit error
   handling. Anything ad-hoc or once-off stays inline as agent prose.

package/reference/skill-placeholders.md

@@ -1,4 +1,4 @@
-# Skill Placeholders — Multi-Harness Source Compilation
+# Skill Placeholders - Multi-Harness Source Compilation
 
 > Phase 42. Skills are authored once in `source/skills/` with placeholders and compiled per-harness into
 > `dist/<bundle>/<config-dir>/skills/...` by `scripts/build-skills.cjs` (the pure transform lives in
@@ -18,7 +18,7 @@
 Only `{{command_prefix}}` is currently woven through the migrated source (every literal `/gdd:` became
 `{{command_prefix}}`); the other three are documented + factory-supported for authors who need them.
 Because Claude's `command_prefix` is exactly `/gdd:`, `compile(source, claude)` reproduces `skills/`
-byte-for-byte — that pure-inverse property is what makes the drift gate safe.
+byte-for-byte - that pure-inverse property is what makes the drift gate safe.
 
 ## Per-harness substitution table
 
@@ -63,7 +63,7 @@ This sentence ships only in the Cursor and Codex bundles.
 
 The block body is kept iff the compiling harness's `id` appears in the comma list; otherwise it is removed
 entirely. Full per-harness content forking beyond placeholders and these blocks is intentionally out of
-scope (a maintenance trap) — see the Phase 42 CONTEXT.
+scope (a maintenance trap) - see the Phase 42 CONTEXT.
 
 ## Validation
 

package/reference/start-interview.md

@@ -1,4 +1,4 @@
-# /gdd:start — Locked 5-Question Interview
+# /gdd:start - Locked 5-Question Interview
 
 **Purpose:** collect the minimum signal needed to steer the findings engine without slowing first-run completion past 30 seconds of interview wall-clock. Autodetectable dimensions collapse to a one-key confirmation; genuinely non-derivable dimensions are asked explicitly.
 
@@ -6,7 +6,7 @@
 
 ---
 
-## Q1 — Pain point *(required, free text)*
+## Q1 - Pain point *(required, free text)*
 
 **Prompt:**
 
@@ -14,13 +14,13 @@
 
 **Default when `--skip-interview`:** empty string (pain hint disabled; scorer runs without boost).
 
-**Validation:** max 120 chars; trim leading/trailing whitespace. No charset restrictions — the hint is free text.
+**Validation:** max 120 chars; trim leading/trailing whitespace. No charset restrictions - the hint is free text.
 
 **Failure posture:** if the user aborts at Q1, abort the whole skill with a one-line pointer to `/gdd:scan`.
 
 ---
 
-## Q2 — Target area confirmation *(autodetected, single select)*
+## Q2 - Target area confirmation *(autodetected, single select)*
 
 **Prompt:**
 
@@ -34,7 +34,7 @@
 
 ---
 
-## Q3 — Budget / latency preference *(enum, default=balanced)*
+## Q3 - Budget / latency preference *(enum, default=balanced)*
 
 **Prompt:**
 
@@ -44,11 +44,11 @@
 
 **Validation:** must be one of `fast | balanced | thorough`. Any other input → re-prompt once, then default to `balanced`.
 
-**Failure posture:** n/a — this is non-blocking; defaulting is safe.
+**Failure posture:** n/a - this is non-blocking; defaulting is safe.
 
 ---
 
-## Q4 — Framework + design-system confirmation *(autodetected, combined)*
+## Q4 - Framework + design-system confirmation *(autodetected, combined)*
 
 **Prompt:**
 
@@ -58,11 +58,11 @@
 
 **Validation:** "override framework" → ask for a free-text label (`next | remix | vite | cra | svelte | vue | astro | solid | unknown`). "override design-system" → same, values (`tailwind | css-modules | vanilla-extract | styled | linaria | emotion | panda | unknown`). Invalid → default to `unknown`.
 
-**Failure posture:** n/a — detection output is always available even if the user skips.
+**Failure posture:** n/a - detection output is always available even if the user skips.
 
 ---
 
-## Q5 — Figma / canvas workflow *(enum, non-blocking)*
+## Q5 - Figma / canvas workflow *(enum, non-blocking)*
 
 **Prompt:**
 
@@ -72,7 +72,7 @@
 
 **Validation:** enum; any other → `skip`.
 
-**Effect:** result steers the `Visual Proof Readiness` section only — never gates the happy path or the findings engine. The writer uses this to decide whether to surface `/gdd:connections figma` or `.canvas` guidance.
+**Effect:** result steers the `Visual Proof Readiness` section only - never gates the happy path or the findings engine. The writer uses this to decide whether to surface `/gdd:connections figma` or `.canvas` guidance.
 
 ---
 

package/reference/style-vocabulary.md

@@ -6,13 +6,13 @@ source: "nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/styles.csv, data/de
 tags: [style, aesthetic, ui, vocabulary, brief]
 ---
 
-# Style Vocabulary — UI Aesthetic Catalog
+# Style Vocabulary - UI Aesthetic Catalog
 
 This catalog gives two categories of agent a shared, unambiguous vocabulary for UI aesthetics.
 
-**Brief-stage (design-context-builder):** When the user names a visual direction — or when the agent infers one from brand-direction words — look up the style name here to validate that the direction is coherent with the product type (Best For / Avoid For columns) and to understand what implementation cost to surface in the constraints section (Performance column). Pre-populate the `D-02` decision line in the context file with the style name verbatim so downstream agents can pattern-match it exactly.
+**Brief-stage (design-context-builder):** When the user names a visual direction - or when the agent infers one from brand-direction words - look up the style name here to validate that the direction is coherent with the product type (Best For / Avoid For columns) and to understand what implementation cost to surface in the constraints section (Performance column). Pre-populate the `D-02` decision line in the context file with the style name verbatim so downstream agents can pattern-match it exactly.
 
-**Audit-stage (design-auditor):** When scoring Pillar 3 (Color) and Pillar 2 (Visual Hierarchy), reference this catalog to determine whether the implemented aesthetic is internally consistent. A product that claims Glassmorphism but uses hard box-shadows scores lower on style coherence. The style name from `D-02` is the benchmark — audit against it, not against a generic checklist.
+**Audit-stage (design-auditor):** When scoring Pillar 3 (Color) and Pillar 2 (Visual Hierarchy), reference this catalog to determine whether the implemented aesthetic is internally consistent. A product that claims Glassmorphism but uses hard box-shadows scores lower on style coherence. The style name from `D-02` is the benchmark - audit against it, not against a generic checklist.
 
 Style names in this file are preserved verbatim from the UUPM source to maintain ecosystem legibility. Do not rename or abbreviate styles when writing context files or audit reports.
 
@@ -24,41 +24,41 @@ Style names in this file are preserved verbatim from the UUPM source to maintain
 
 | Style | Keywords | Signature Effects | Best For | Avoid For | Light/Dark | Performance | Era |
 |---|---|---|---|---|---|---|---|
-| Glassmorphism | frosted glass, translucency, blur, layered depth | backdrop-filter: blur(20px), semi-transparent cards (rgba bg at 60–80% opacity), 1px border at rgba(255,255,255,0.2), subtle inner glow | Dashboards, media apps, modern SaaS landing pages, AI/ML product surfaces | Data-dense tables, accessibility-critical flows, low-end devices, text-heavy content | Both (dark base preferred for maximum contrast) | High — backdrop-filter triggers compositor layer; avoid stacking more than 3 blur layers | 2019–present |
-| Brutalism | raw layout, stark contrast, intentional roughness, exposed grid, unconventional typography | Hard pixel borders (2–4px solid black), no border-radius or extreme (0px), flat color fills, oversized type, intentional misalignment as aesthetic choice | Creative portfolios, challenger brands, indie products, arts organizations, music artists | Healthcare, regulated finance, government, e-commerce conversion pages | Light mode primary | Lowest — no visual effects; pure CSS | 2016–present |
-| Neumorphism | extruded shadows, raised/inset UI, monochromatic, soft bilateral shadows | box-shadow: 8px 8px 16px rgba(0,0,0,0.15), -8px -8px 16px rgba(255,255,255,0.9); near-identical foreground/background hue; no hard borders | Personal finance concept dashboards, design system prototypes, high-end calculator UI | Accessibility-critical products (fails WCAG contrast in almost all implementations), mobile (touch targets unclear), production apps at scale | Light only | Low — CSS shadows only, but WCAG caution overrides implementation | 2019–2021 |
+| Glassmorphism | frosted glass, translucency, blur, layered depth | backdrop-filter: blur(20px), semi-transparent cards (rgba bg at 60–80% opacity), 1px border at rgba(255,255,255,0.2), subtle inner glow | Dashboards, media apps, modern SaaS landing pages, AI/ML product surfaces | Data-dense tables, accessibility-critical flows, low-end devices, text-heavy content | Both (dark base preferred for maximum contrast) | High - backdrop-filter triggers compositor layer; avoid stacking more than 3 blur layers | 2019–present |
+| Brutalism | raw layout, stark contrast, intentional roughness, exposed grid, unconventional typography | Hard pixel borders (2–4px solid black), no border-radius or extreme (0px), flat color fills, oversized type, intentional misalignment as aesthetic choice | Creative portfolios, challenger brands, indie products, arts organizations, music artists | Healthcare, regulated finance, government, e-commerce conversion pages | Light mode primary | Lowest - no visual effects; pure CSS | 2016–present |
+| Neumorphism | extruded shadows, raised/inset UI, monochromatic, soft bilateral shadows | box-shadow: 8px 8px 16px rgba(0,0,0,0.15), -8px -8px 16px rgba(255,255,255,0.9); near-identical foreground/background hue; no hard borders | Personal finance concept dashboards, design system prototypes, high-end calculator UI | Accessibility-critical products (fails WCAG contrast in almost all implementations), mobile (touch targets unclear), production apps at scale | Light only | Low - CSS shadows only, but WCAG caution overrides implementation | 2019–2021 |
 | Flat Design 2.0 | minimal decoration, subtle shadows permitted, vibrant palette, sharp iconography | Single drop-shadow at 0 2px 4px rgba (not 0 blur), bold sans-serif, geometric icons, 8pt spacing grid, no gradients on primary surfaces | Productivity apps, documentation sites, enterprise SaaS, developer tools | Luxury/fashion (too utilitarian), entertainment (too corporate) | Both | Lowest | 2014–present |
-| Material Design 3 | dynamic color, tonal surfaces, elevation via color not shadow, M3 components | Tonal surface colors derived from wallpaper/brand seed via Material You algorithm; container/on-container token pairs; state layers at 8%/12%/16% opacity | Android-first apps, cross-platform Google-adjacent products, Material ecosystem teams | Apple HIG contexts, luxury brands, editorial-first experiences | Both | Low — relies on CSS custom properties and system fonts | 2021–present |
+| Material Design 3 | dynamic color, tonal surfaces, elevation via color not shadow, M3 components | Tonal surface colors derived from wallpaper/brand seed via Material You algorithm; container/on-container token pairs; state layers at 8%/12%/16% opacity | Android-first apps, cross-platform Google-adjacent products, Material ecosystem teams | Apple HIG contexts, luxury brands, editorial-first experiences | Both | Low - relies on CSS custom properties and system fonts | 2021–present |
 | Bento Grid | card-grid layout, variable card sizes, grid gaps as design element, information hierarchy via cell size | CSS Grid with named areas; card size ranges from 1×1 to 3×2; visible grid gap (8–16px); rounded cards (radius 12–24px); subtle card shadow | Marketing landing pages, dashboard home screens, portfolio showcases, feature announcement pages | Linear narrative content, long-form reading, checkout flows | Both | Low | 2022–present |
-| AI-Native | gradient meshes, dark base, glowing accents, particle effects, flowing color | Gradient mesh backgrounds (3–5 blended color stops), subtle particle canvas overlay, glowing border via box-shadow with spread, monospace or geometric sans-serif | AI/ML products, futuristic SaaS, developer platform landing pages, inference product demos | Traditional enterprise, regulated industries, consumer packaged goods, healthcare | Dark primary | High — particle effects require canvas/WebGL; mesh gradients moderate cost | 2022–present |
+| AI-Native | gradient meshes, dark base, glowing accents, particle effects, flowing color | Gradient mesh backgrounds (3–5 blended color stops), subtle particle canvas overlay, glowing border via box-shadow with spread, monospace or geometric sans-serif | AI/ML products, futuristic SaaS, developer platform landing pages, inference product demos | Traditional enterprise, regulated industries, consumer packaged goods, healthcare | Dark primary | High - particle effects require canvas/WebGL; mesh gradients moderate cost | 2022–present |
 | Swiss Modernism 2.0 / International Style | strict grid, functional typography, red-black-white, structure as beauty | Baseline 12-column grid with explicit column rules; Helvetica/Neue Haas/Inter; red (#E02424) as the only accent; no imagery unless functional; type as layout element | Editorial platforms, design agencies, premium brand identities, cultural institutions | Consumer apps, gaming, children's products, anything requiring warmth | Both | Lowest | 1950–present (revival 2018–) |
-| Claymorphism | 3D inflated shapes, soft clay surfaces, pastel palette, inner shadows | border-radius: 30–50px; layered box-shadow (inner highlight + outer soft shadow); pastel fills; thick playful borders (3–4px) at lighter shade of fill | Consumer apps, children's products, lifestyle brands, wellness apps, gifting platforms | Enterprise software, data-dense apps, financial tools, anything requiring precision | Both | Medium — inner shadows and multiple box-shadow layers | 2021–present |
+| Claymorphism | 3D inflated shapes, soft clay surfaces, pastel palette, inner shadows | border-radius: 30–50px; layered box-shadow (inner highlight + outer soft shadow); pastel fills; thick playful borders (3–4px) at lighter shade of fill | Consumer apps, children's products, lifestyle brands, wellness apps, gifting platforms | Enterprise software, data-dense apps, financial tools, anything requiring precision | Both | Medium - inner shadows and multiple box-shadow layers | 2021–present |
 | Dark Mode First | deep backgrounds, careful elevation via surface color, low-saturation palette | Background: #0A0A0A–#121212; surfaces via gray ladder (#1C1C1E, #2C2C2E, #3A3A3C); text at #F5F5F5–#EBEBF5; color desaturated 20% vs light equivalent | Developer tools, code editors, media players, gaming interfaces, creative tools | Healthcare (eye strain concern in clinical settings), high-ambient-light kiosks, point-of-sale | Dark primary | Low | 2018–present |
-| Vaporwave/Retrowave | neon gradients, dark base, grid lines, retro typography, CRT aesthetic | Hot pink to cyan gradient (#FF00FF → #00FFFF); background grid lines at low opacity; scanline overlay; pixel or VCR-style display fonts; glow effects via text-shadow | Gaming, entertainment, nostalgia brands, Gen-Z consumer products, music products | Any trust-critical vertical, healthcare, finance, government, enterprise | Dark | High — multiple glow filters, gradient overlays | 1980s aesthetic; UI revival 2016–present |
+| Vaporwave/Retrowave | neon gradients, dark base, grid lines, retro typography, CRT aesthetic | Hot pink to cyan gradient (#FF00FF → #00FFFF); background grid lines at low opacity; scanline overlay; pixel or VCR-style display fonts; glow effects via text-shadow | Gaming, entertainment, nostalgia brands, Gen-Z consumer products, music products | Any trust-critical vertical, healthcare, finance, government, enterprise | Dark | High - multiple glow filters, gradient overlays | 1980s aesthetic; UI revival 2016–present |
 | Editorial Grid | overlapping text and image, asymmetric layout, strong typographic hierarchy, print-inspired | Text floated over image with mix-blend-mode; column-spanning type; headline at 80–120px; print-grid column rules as decoration; serif display fonts | Media platforms, publishing, editorial brands, portfolios, cultural organizations | Functional SaaS apps, data-dense dashboards, e-commerce PDP pages | Both | Low | Print tradition; digital revival 2018–present |
-| HUD/Sci-Fi FUI | monochrome on dark, thin lines, technical readout vocabulary, blinking cursors | Background #000000–#0A0A0A; primary green or cyan (#00FF41 or #22D3EE) on black; 1px rule lines; monospace type; data table with scan-animation; corner bracket UI elements | Technology/aerospace dashboards, game UI overlays, cybersecurity monitoring, concept demos | Consumer products, any app requiring instant clarity for non-technical users | Dark | High — continuous animations, WebGL elements common | Science fiction tradition; real-world FUI since 2010 |
+| HUD/Sci-Fi FUI | monochrome on dark, thin lines, technical readout vocabulary, blinking cursors | Background #000000–#0A0A0A; primary green or cyan (#00FF41 or #22D3EE) on black; 1px rule lines; monospace type; data table with scan-animation; corner bracket UI elements | Technology/aerospace dashboards, game UI overlays, cybersecurity monitoring, concept demos | Consumer products, any app requiring instant clarity for non-technical users | Dark | High - continuous animations, WebGL elements common | Science fiction tradition; real-world FUI since 2010 |
 | Minimal/Zen | maximum whitespace, single accent, natural textures, typography-first | 70%+ whitespace ratio; single color accent (one hue only); thin-weight serif or geometric sans; optional paper/linen texture overlay at 5% opacity; no drop shadows | Wellness apps, meditation products, luxury minimal brands, independent publications, author portfolios | Feature-dense apps, complex navigation structures, high-information-density dashboards | Both | Lowest | 2010–present |
-| Skeuomorphism 2.0 | realistic textures, modern execution, material-specific rendering | Leather, wood grain, metal surface textures rendered via CSS or SVG; specular highlight simulation; physical affordances (buttons with press state depth); material-appropriate border-radius | Premium music instruments, luxury hardware companion apps, high-end lifestyle products | Modern SaaS, productivity tools, anything with frequent UI updates (texture maintenance cost) | Both | Medium — texture assets and layered pseudo-elements | Original 2007–2013; revival/refinement 2021–present |
+| Skeuomorphism 2.0 | realistic textures, modern execution, material-specific rendering | Leather, wood grain, metal surface textures rendered via CSS or SVG; specular highlight simulation; physical affordances (buttons with press state depth); material-appropriate border-radius | Premium music instruments, luxury hardware companion apps, high-end lifestyle products | Modern SaaS, productivity tools, anything with frequent UI updates (texture maintenance cost) | Both | Medium - texture assets and layered pseudo-elements | Original 2007–2013; revival/refinement 2021–present |
 | Neubrutalism | visible borders, flat colors, stark contrast, browser-default-inspired, raw energy | 2–3px solid dark border on all interactive elements; flat fill (no gradient); background colors at full saturation; hover state as color-flip (swap bg/fg); no border-radius or large radius | Indie SaaS products, creative tools, challenger brands, hackathon projects | Enterprise software, regulated industries, anything requiring perceived polish or trust | Both | Lowest | 2021–present |
 | Memphis Design Revival | geometric shapes, primary colors, patterns, 80s-inspired, maximalist decoration | Bold geometric pattern fills (triangles, squiggles, dots); primary + secondary color blocking; pattern borders; mixed type weights; controlled chaos grid | Consumer brands targeting Gen Z, playful e-commerce, lifestyle/fashion campaigns, pop culture events | Professional services, enterprise, financial products, anything requiring authority | Both | Low | 1980s origin; digital revival 2022–present |
-| Glassmorphism Dark | frosted glass on dark base, darker frost panels, subtle neon borders | backdrop-filter: blur(24px) on near-black base (#0A0A0A); card at rgba(255,255,255,0.05); neon border rgba(value from accent, 0.3); text at #F8FAFC | Gaming UI, media players, nightclub/event apps, AI product dark surfaces | Any product requiring readable body text at scale (contrast is difficult to achieve) | Dark | High — same as Glassmorphism | 2020–present |
-| Aurora/Gradient Mesh | flowing color gradients, no hard borders, dreamlike quality, organic forms | CSS mesh gradient with 4–6 color stops at 40–70% opacity; no hard-edge borders; sections dissolve into each other; type floated on gradient without hard card containers | AI/ML landing pages, creative platform hero sections, generative art tools | Data-dense apps, form-heavy flows, any context requiring clear section boundaries | Both | Medium-High — large gradient areas can trigger repaint | 2021–present |
+| Glassmorphism Dark | frosted glass on dark base, darker frost panels, subtle neon borders | backdrop-filter: blur(24px) on near-black base (#0A0A0A); card at rgba(255,255,255,0.05); neon border rgba(value from accent, 0.3); text at #F8FAFC | Gaming UI, media players, nightclub/event apps, AI product dark surfaces | Any product requiring readable body text at scale (contrast is difficult to achieve) | Dark | High - same as Glassmorphism | 2020–present |
+| Aurora/Gradient Mesh | flowing color gradients, no hard borders, dreamlike quality, organic forms | CSS mesh gradient with 4–6 color stops at 40–70% opacity; no hard-edge borders; sections dissolve into each other; type floated on gradient without hard card containers | AI/ML landing pages, creative platform hero sections, generative art tools | Data-dense apps, form-heavy flows, any context requiring clear section boundaries | Both | Medium-High - large gradient areas can trigger repaint | 2021–present |
 | Monochromatic Minimal | single hue across full lightness range, typography-first, restraint as luxury | All UI elements share one hue; lightness varies from 5% (near-black) to 97% (near-white); saturation constant; type weight provides the only contrast variation; no accent color | Portfolios, luxury brand identity systems, photography showcases, editorial | Multi-action apps, e-commerce (accent colors drive CTA attention), gaming | Both | Lowest | 2015–present |
-| Conversion-First | CTA-dominant layout, social proof integration, urgency mechanics, trust signals | Primary CTA button above fold with 100%+ width on mobile; social proof blocks within 2 scroll steps; urgency timer or scarcity counter; benefit bullets over features; sticky CTA bar on mobile | Lead-gen landing pages, SaaS trial pages, product launch pages, app store alternatives | Brand storytelling pages, editorial content, informational docs | Both | Low — minimal JS, mostly static | 2010–present |
-| Story-Scroll | parallax narrative, scroll-triggered animations, cinematic pacing | IntersectionObserver-triggered fade-in sequences; horizontal scroll segments; full-bleed imagery at each act; progress indicator; chapter-style section breaks | Brand launches, product storytelling, annual reports, agency showreels | High-conversion pages (scroll depth reduces conversion), dashboard apps, utility tools | Both | Medium-High — JavaScript animation triggers and asset loading | 2014–present |
-| Product Demo | embedded interactive preview, annotated feature callouts, tooltip overlays | Inline iframe or video demo above fold; numbered callout dots on screenshot; feature spotlight with progressive disclosure; before/after toggle; interactive hotspot map | SaaS product landing pages, browser extension pages, design tool showcases | Services businesses (no product to demo), content sites, physical product e-commerce | Both | Medium — video autoplay and interactive elements | 2016–present |
+| Conversion-First | CTA-dominant layout, social proof integration, urgency mechanics, trust signals | Primary CTA button above fold with 100%+ width on mobile; social proof blocks within 2 scroll steps; urgency timer or scarcity counter; benefit bullets over features; sticky CTA bar on mobile | Lead-gen landing pages, SaaS trial pages, product launch pages, app store alternatives | Brand storytelling pages, editorial content, informational docs | Both | Low - minimal JS, mostly static | 2010–present |
+| Story-Scroll | parallax narrative, scroll-triggered animations, cinematic pacing | IntersectionObserver-triggered fade-in sequences; horizontal scroll segments; full-bleed imagery at each act; progress indicator; chapter-style section breaks | Brand launches, product storytelling, annual reports, agency showreels | High-conversion pages (scroll depth reduces conversion), dashboard apps, utility tools | Both | Medium-High - JavaScript animation triggers and asset loading | 2014–present |
+| Product Demo | embedded interactive preview, annotated feature callouts, tooltip overlays | Inline iframe or video demo above fold; numbered callout dots on screenshot; feature spotlight with progressive disclosure; before/after toggle; interactive hotspot map | SaaS product landing pages, browser extension pages, design tool showcases | Services businesses (no product to demo), content sites, physical product e-commerce | Both | Medium - video autoplay and interactive elements | 2016–present |
 | Trust-Builder | certification display, testimonial photography, risk-reduction copy, authority signals | Client logo strip at top of page; testimonial cards with real photos (not stock); certification badges (SOC 2, ISO, G2); security copy near forms; money-back guarantee callout | B2B SaaS sales pages, fintech onboarding, legal/compliance products, high-ticket e-commerce | Consumer social apps, entertainment (trust signals read as corporate), developer tools (badges feel marketing-y) | Both | Low | 2012–present |
-| Playful Consumer | rounded UI, emoji integration, micro-animations, confetti moments | border-radius: 24–32px everywhere; emoji in headings; lottie animation for success states; confetti particle burst on conversion; pastel color fills; bouncy spring animations (spring: 200ms) | Consumer apps, gifting platforms, children's products, food delivery, social features | Enterprise, financial products, healthcare, government | Both | Medium — Lottie/animation assets | 2018–present |
+| Playful Consumer | rounded UI, emoji integration, micro-animations, confetti moments | border-radius: 24–32px everywhere; emoji in headings; lottie animation for success states; confetti particle burst on conversion; pastel color fills; bouncy spring animations (spring: 200ms) | Consumer apps, gifting platforms, children's products, food delivery, social features | Enterprise, financial products, healthcare, government | Both | Medium - Lottie/animation assets | 2018–present |
 | Dark Premium | full dark canvas, gold or silver accents, whitespace-heavy, editorial hierarchy | Background #0A0A0A; accent: gold (#B8860B or #D4AF37) or silver (#C0C0C0); large display serif or geometric sans at 80–120px; section-level spacing (120–200px vertical rhythm) | Luxury SaaS, high-end service brands, premium membership products, whiskey/watch brands | Mass-market consumer apps, anything needing color variety for information hierarchy | Dark | Low | 2018–present |
 | Typography-Led | large type as hero element, minimal imagery, type as design | Display type at 100–200px viewport width; type positioned absolutely over background color; tight leading (line-height 0.9–1.1) at display scale; type color is the background color inverted | Editorial brands, design agencies, type foundries, artist/creative portfolios | Functional apps (type-only layouts hide UI conventions), e-commerce (products need imagery) | Both | Lowest | Print tradition; digital 2015–present |
-| Data-Driven | charts and statistics as hero visual, number-forward design | Large KPI numbers at 80–120px in hero; inline sparkline or bar chart in above-fold section; data annotation typography; monospace or tabular numerals; confidence interval UI | Analytics tools, investor relations pages, research organizations, fintech reporting features | Lifestyle brands, emotional products, services without clear metrics | Both | Low — static SVG charts | 2019–present |
+| Data-Driven | charts and statistics as hero visual, number-forward design | Large KPI numbers at 80–120px in hero; inline sparkline or bar chart in above-fold section; data annotation typography; monospace or tabular numerals; confidence interval UI | Analytics tools, investor relations pages, research organizations, fintech reporting features | Lifestyle brands, emotional products, services without clear metrics | Both | Low - static SVG charts | 2019–present |
 | Data Dense | information-maximized layout, minimal chrome, small type | 12–13px body in tables; 4–8px row padding; no card containers (table row is the container); tooltips over labels to save space; condensed font weight; color coded only for status | Bloomberg-style terminals, trading desks, operations centers, medical records systems | Consumer apps (cognitive overload), mobile-primary experiences, accessibility-critical | Both (dark preferred for terminal contexts) | Low | 1990s terminal origin; modern SaaS 2012–present |
 | Executive Dashboard | large KPIs, traffic-light status indicators, minimal labels, decision-oriented | KPI cards at 48–64px number size; 3-color status system (green/amber/red for good/warning/critical); sparkline trend line per KPI; maximum 6 KPIs above fold; no data tables in primary view | C-suite reporting dashboards, board packs, PE portfolio monitoring, business reviews | Operational monitoring (needs more granularity), self-serve analytics (needs exploration) | Both | Low | 2010–present |
-| Operational Monitor | real-time status indicators, alert color system, live data feel, dense timeline | WebSocket or SSE refresh indicator; color-coded service status dots; rolling log window (monospace, dark); alert banner docking at top; incident timeline view | DevOps dashboards, NOC (network operations center), cloud infrastructure monitoring, on-call tools | Executive reporting, consumer apps, any latency-sensitive rendering environment | Dark primary | Medium — live data updates | 2012–present |
+| Operational Monitor | real-time status indicators, alert color system, live data feel, dense timeline | WebSocket or SSE refresh indicator; color-coded service status dots; rolling log window (monospace, dark); alert banner docking at top; incident timeline view | DevOps dashboards, NOC (network operations center), cloud infrastructure monitoring, on-call tools | Executive reporting, consumer apps, any latency-sensitive rendering environment | Dark primary | Medium - live data updates | 2012–present |
 | Data Storytelling | prose plus inline charts, guided narrative, progressive disclosure of complexity | Section header states the finding; chart below supports it; annotation layer on chart pointing to key data moment; reading-width body column (640–720px); chapter progress indicator | Insight reports, analytics product "stories" feature, investor updates, public data journalism | Self-serve exploration dashboards (storytelling is prescriptive, not exploratory), real-time ops | Both | Low | 2017–present |
-| Grid/Matrix | dense tabular layout, frozen headers, column sorting, data comparison | CSS sticky column headers; alternating row background (zebra stripe); column resize handles; monospace numbers; sort indicator arrows; cell-level color coding for heatmaps | Financial data apps, CRM list views, ERP interfaces, spreadsheet-replacement tools | Dashboards with narrative focus, mobile primary (tables on mobile are difficult) | Both | Low — but DOM size can be high; virtualize rows beyond 500 | 2000–present |
-| Graph/Network | node-edge visualization, force-directed layout, interactive topology | SVG or Canvas force-directed graph; node size encodes metric; edge color encodes relationship type; zoom and pan; node inspection panel on click; cluster isolation on hover | Dependency maps, org charts, knowledge graphs, security blast-radius visualization | Reports (static charts better for non-interactive), mobile primary | Both | High — force simulation is CPU-intensive; use WebGL for >1000 nodes | 2012–present |
-| Geospatial | map-first layout, choropleth overlays, geographic filter | Full-bleed map as primary content area (Mapbox/Leaflet); choropleth color scale in legend; point cluster markers; polygon selection for region drill-down; sidebar for data detail | Logistics route analytics, retail location analytics, real estate market maps, public health dashboards | Products with no inherently geographic data, mobile with small screen | Both | High — map tile loading and vector layer rendering | 2010–present |
-| Timeline-First | chronological layout, Gantt-inspired, temporal density | Horizontal scroll timeline; date-stamped lane per entity; milestone markers; dependency lines between tasks; zoom from year → week → day; color coding per project/team | Project management tools, roadmap views, history visualization, editorial production tracking | Real-time monitoring (timeline is retrospective), KPI dashboards | Both | Medium — virtualized timeline required for long date ranges | 2015–present |
+| Grid/Matrix | dense tabular layout, frozen headers, column sorting, data comparison | CSS sticky column headers; alternating row background (zebra stripe); column resize handles; monospace numbers; sort indicator arrows; cell-level color coding for heatmaps | Financial data apps, CRM list views, ERP interfaces, spreadsheet-replacement tools | Dashboards with narrative focus, mobile primary (tables on mobile are difficult) | Both | Low - but DOM size can be high; virtualize rows beyond 500 | 2000–present |
+| Graph/Network | node-edge visualization, force-directed layout, interactive topology | SVG or Canvas force-directed graph; node size encodes metric; edge color encodes relationship type; zoom and pan; node inspection panel on click; cluster isolation on hover | Dependency maps, org charts, knowledge graphs, security blast-radius visualization | Reports (static charts better for non-interactive), mobile primary | Both | High - force simulation is CPU-intensive; use WebGL for >1000 nodes | 2012–present |
+| Geospatial | map-first layout, choropleth overlays, geographic filter | Full-bleed map as primary content area (Mapbox/Leaflet); choropleth color scale in legend; point cluster markers; polygon selection for region drill-down; sidebar for data detail | Logistics route analytics, retail location analytics, real estate market maps, public health dashboards | Products with no inherently geographic data, mobile with small screen | Both | High - map tile loading and vector layer rendering | 2010–present |
+| Timeline-First | chronological layout, Gantt-inspired, temporal density | Horizontal scroll timeline; date-stamped lane per entity; milestone markers; dependency lines between tasks; zoom from year → week → day; color coding per project/team | Project management tools, roadmap views, history visualization, editorial production tracking | Real-time monitoring (timeline is retrospective), KPI dashboards | Both | Medium - virtualized timeline required for long date ranges | 2015–present |
 | Comparison View | side-by-side panels, diff highlighting, symmetrical layout | Two-column layout at 50%/50%; synchronized scroll; highlighted diff lines (green/red) or changed values; overlay mode toggle; summary diff count in header | A/B test result dashboards, design diff tools, version comparison, benchmark analysis | Single-subject dashboards, mobile primary (two columns collapse badly) | Both | Low | 2015–present |
-| Mobile Analytics | touch-optimized charts, swipe navigation, bottom-sheet detail | Horizontal bar charts (not vertical — finger-friendly tap targets); swipe between metric cards; bottom-sheet expansion for drill-down; large tap targets (48px minimum); chart gestures (pinch-zoom) | Field sales apps, retail staff dashboards, on-the-go executive views, mobile-first ops tools | Desktop-primary tools (mobile patterns feel cramped on large screens), data-dense tables | Both | Low — but chart libraries must support touch events | 2018–present |
+| Mobile Analytics | touch-optimized charts, swipe navigation, bottom-sheet detail | Horizontal bar charts (not vertical - finger-friendly tap targets); swipe between metric cards; bottom-sheet expansion for drill-down; large tap targets (48px minimum); chart gestures (pinch-zoom) | Field sales apps, retail staff dashboards, on-the-go executive views, mobile-first ops tools | Desktop-primary tools (mobile patterns feel cramped on large screens), data-dense tables | Both | Low - but chart libraries must support touch events | 2018–present |

package/reference/surfaces.md

@@ -1,11 +1,11 @@
 # Surfaces
-Source: jakubkrehel/make-interfaces-feel-better (MIT) — surfaces.md
+Source: jakubkrehel/make-interfaces-feel-better (MIT) - surfaces.md
 
 Rules for nested surfaces, optical alignment, shadow systems, image outlines, and hit areas.
 
 ## Concentric Radius Formula
 
-When nesting interactive elements inside a container (e.g., a card with a button, or a modal with an input), the inner radius must be SMALLER than the outer radius — by exactly the padding between them:
+When nesting interactive elements inside a container (e.g., a card with a button, or a modal with an input), the inner radius must be SMALLER than the outer radius - by exactly the padding between them:
 
 ```
 outerRadius = innerRadius + padding
@@ -20,14 +20,14 @@ Example: card with `border-radius: 16px` and `padding: 16px` → inner elements
 
 **Exception:** when `padding > 24px`, treat the inner element as a visually separate surface and apply its own standard radius (4/8/12px depending on its type).
 
-Why this matters: same radius on nested surfaces creates a visual disconnect — the inner element appears to "float" without belonging to the outer surface. The concentric formula creates perceptual depth and containment.
+Why this matters: same radius on nested surfaces creates a visual disconnect - the inner element appears to "float" without belonging to the outer surface. The concentric formula creates perceptual depth and containment.
 
 ## Optical Alignment
 
 Mathematical centering ≠ optical centering for asymmetric elements:
 
 - **Icon with text:** `padding-inline-start` for the icon side should be 2px less than `padding-inline-end` for the text side. This corrects for the visual weight imbalance.
-- **Play/chevron triangles:** shift right by 2px from mathematical center — triangles have more visual mass on their left side (the flat edge).
+- **Play/chevron triangles:** shift right by 2px from mathematical center - triangles have more visual mass on their left side (the flat edge).
 - **SVG icons with irregular bounding box:** inspect the actual glyph bounds, not the viewBox. Add `padding` to compensate for asymmetric whitespace within the SVG.
 
 ## 3-Layer Shadow System

package/reference/ticket-sync.md

@@ -1,6 +1,6 @@
-# Ticket Sync — the `<ticket_links>` contract for `agents/ticket-sync-agent.md`
+# Ticket Sync - the `<ticket_links>` contract for `agents/ticket-sync-agent.md`
 
-How GDD links a design cycle to a Linear/Jira ticket, reads its comments as context, and writes a redacted status update on completion — all via MCP tools (no raw HTTP, no bundled SDK). The per-system probe + tool detail live in `connections/linear.md` + `connections/jira.md`.
+How GDD links a design cycle to a Linear/Jira ticket, reads its comments as context, and writes a redacted status update on completion - all via MCP tools (no raw HTTP, no bundled SDK). The per-system probe + tool detail live in `connections/linear.md` + `connections/jira.md`.
 
 ---
 
@@ -20,15 +20,15 @@ jira: PROJ-45
 - The link is set by the user (or a future `/gdd:link-ticket`); the agent **reads** it, never invents a link.
 - No link for the current cycle → the agent is a noop on both paths.
 
-## Read path (decision-injector — `.design/**.md` open)
+## Read path (decision-injector - `.design/**.md` open)
 
-When a design artifact opens and the cycle has a link to an `available` system, the agent fetches the linked ticket's recent comments (via the resolved `mcp__linear__*` / `mcp__atlassian__*` tool) and surfaces a short **redacted** digest as cycle context — so a decision made in the ticket reaches the pipeline. Read-only; nothing is written on this path.
+When a design artifact opens and the cycle has a link to an `available` system, the agent fetches the linked ticket's recent comments (via the resolved `mcp__linear__*` / `mcp__atlassian__*` tool) and surfaces a short **redacted** digest as cycle context - so a decision made in the ticket reaches the pipeline. Read-only; nothing is written on this path.
 
 ## Write path (`/gdd:complete-cycle`)
 
 On cycle completion, for each linked + available system:
 
-1. **Transition** the ticket status — the default map (overridable in `.design/config.json#ticket_sync.transitions`):
+1. **Transition** the ticket status - the default map (overridable in `.design/config.json#ticket_sync.transitions`):
 
    | Cycle outcome | Ticket transition |
    |---|---|
@@ -40,11 +40,11 @@ On cycle completion, for each linked + available system:
 
 ## Conflict resolution (tracker wins)
 
-If the ticket's current status diverges from what `<ticket_links>` last recorded (a human moved it), **the tracker is the source of truth** — the agent reconciles `<ticket_links>` to the tracker's state and posts an explicit "GDD observed an external status change; reconciling" note, rather than force-overwriting the human transition. (ROADMAP Phase-35 open-Q default.)
+If the ticket's current status diverges from what `<ticket_links>` last recorded (a human moved it), **the tracker is the source of truth** - the agent reconciles `<ticket_links>` to the tracker's state and posts an explicit "GDD observed an external status change; reconciling" note, rather than force-overwriting the human transition. (ROADMAP Phase-35 open-Q default.)
 
 ## Redaction (mandatory)
 
-Every body written to a ticket — the status comment, the summary — passes through `scripts/lib/redact.cjs` (11 secret/token patterns) before the MCP call. The agent is the single egress chokepoint; no raw artifact excerpt reaches Linear/Jira.
+Every body written to a ticket - the status comment, the summary - passes through `scripts/lib/redact.cjs` (11 secret/token patterns) before the MCP call. The agent is the single egress chokepoint; no raw artifact excerpt reaches Linear/Jira.
 
 ## Kill-switches (per system)
 
@@ -52,8 +52,8 @@ A system is a noop when **either** `GDD_DISABLE_LINEAR=1` / `GDD_DISABLE_JIRA=1`
 
 ## Degrade-to-noop (never blocks the cycle)
 
-`not_configured` (MCP absent) / disabled / no link / an MCP error → the agent skips that system and **never throws** into the pipeline — ticket-sync is a best-effort side surface, never a cycle gate (D-04).
+`not_configured` (MCP absent) / disabled / no link / an MCP error → the agent skips that system and **never throws** into the pipeline - ticket-sync is a best-effort side surface, never a cycle gate (D-04).
 
 ## Out of scope (per Phase 35 split)
 
-PR-inline (35.1); Slack/Discord notifications (35.2); issue **creation**/triage (Phase 30 territory — this is sync of an already-linked ticket); a bundled Linear/Jira SDK (MCP-based, D-02); `pseudonymize.cjs` (Phase 30 — redact for secrets is the must here); Microsoft Teams / Asana.
+PR-inline (35.1); Slack/Discord notifications (35.2); issue **creation**/triage (Phase 30 territory - this is sync of an already-linked ticket); a bundled Linear/Jira SDK (MCP-based, D-02); `pseudonymize.cjs` (Phase 30 - redact for secrets is the must here); Microsoft Teams / Asana.