@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/design-systems-catalog.md

@@ -1,12 +1,12 @@
-# Design Systems Catalog — Quick Reference
+# Design Systems Catalog - Quick Reference
 
-An opinionated index of the 18 major design systems most relevant to digital product work. For each system, the entry covers core philosophy, distinctive strengths, canonical documentation URL, and the clearest signal for when to reach for it. This catalog is not exhaustive — it is a decision aid for the planning and research phases.
+An opinionated index of the 18 major design systems most relevant to digital product work. For each system, the entry covers core philosophy, distinctive strengths, canonical documentation URL, and the clearest signal for when to reach for it. This catalog is not exhaustive - it is a decision aid for the planning and research phases.
 
 ---
 
 ## 1. Material Design 3 (Google)
 
-Material Design 3 (M3) is Google's most expressive design system to date, built around dynamic color — an algorithm that generates a full 5-palette color scheme (primary, secondary, tertiary, error, neutral) from a single seed color, enabling personalization and accessibility without manual token work. M3 introduced the concept of "tonal surfaces," where elevation is communicated through color tint rather than shadow depth, producing designs that work well in both light and dark environments. The component library is built on tokens and roles rather than hardcoded values, making it straightforward to implement across Android, web, and Flutter from a single specification. Reach for M3 when building products that will ship on Android, need to feel native to the Google ecosystem, or require automatic dark mode with a systematic color science approach.
+Material Design 3 (M3) is Google's most expressive design system to date, built around dynamic color - an algorithm that generates a full 5-palette color scheme (primary, secondary, tertiary, error, neutral) from a single seed color, enabling personalization and accessibility without manual token work. M3 introduced the concept of "tonal surfaces," where elevation is communicated through color tint rather than shadow depth, producing designs that work well in both light and dark environments. The component library is built on tokens and roles rather than hardcoded values, making it straightforward to implement across Android, web, and Flutter from a single specification. Reach for M3 when building products that will ship on Android, need to feel native to the Google ecosystem, or require automatic dark mode with a systematic color science approach.
 
 **Canonical URL:** https://m3.material.io
 
@@ -14,7 +14,7 @@ Material Design 3 (M3) is Google's most expressive design system to date, built
 
 ## 2. Apple Human Interface Guidelines (HIG)
 
-The Apple HIG is the definitive authority for UI on iOS, macOS, watchOS, visionOS, and tvOS. Unlike most design systems, the HIG is primarily a platform-convention guide — it documents the standard behaviors, controls, and interaction patterns that users expect on Apple hardware, rather than providing a token-based component system. Its core philosophy is that software should feel native to the platform: tapping into system behaviors (swipe-to-go-back, live text, share sheets) creates immediate familiarity that no custom UI can replicate as efficiently. The HIG is essential reading for any team building native Swift applications, and it also informs the right abstraction level for cross-platform apps — understanding platform conventions before deciding which to override.
+The Apple HIG is the definitive authority for UI on iOS, macOS, watchOS, visionOS, and tvOS. Unlike most design systems, the HIG is primarily a platform-convention guide - it documents the standard behaviors, controls, and interaction patterns that users expect on Apple hardware, rather than providing a token-based component system. Its core philosophy is that software should feel native to the platform: tapping into system behaviors (swipe-to-go-back, live text, share sheets) creates immediate familiarity that no custom UI can replicate as efficiently. The HIG is essential reading for any team building native Swift applications, and it also informs the right abstraction level for cross-platform apps - understanding platform conventions before deciding which to override.
 
 **Canonical URL:** https://developer.apple.com/design/human-interface-guidelines
 
@@ -22,7 +22,7 @@ The Apple HIG is the definitive authority for UI on iOS, macOS, watchOS, visionO
 
 ## 3. Radix UI + WAI-ARIA Authoring Practices Guide
 
-Radix UI is a headless React component library built on the principle that accessibility should be the floor, not a feature to add later. Every Radix primitive — Dialog, Dropdown Menu, Tooltip, Select, Combobox — implements the corresponding WAI-ARIA authoring pattern exactly, including full keyboard navigation, focus management, and ARIA attribute wiring. Because Radix is headless (no styles included), it gives design teams complete visual control while eliminating the most error-prone aspect of component development: the accessibility behavior layer. The WAI-ARIA Authoring Practices Guide (APG) from the W3C is the authoritative specification that Radix implements — reading both together gives the complete picture of why each interaction pattern is designed as it is. Reach for Radix when building a custom design system from scratch, adopting shadcn/ui, or needing confidence that interactive components will pass WCAG 2.1 AA audit without custom accessibility engineering.
+Radix UI is a headless React component library built on the principle that accessibility should be the floor, not a feature to add later. Every Radix primitive - Dialog, Dropdown Menu, Tooltip, Select, Combobox - implements the corresponding WAI-ARIA authoring pattern exactly, including full keyboard navigation, focus management, and ARIA attribute wiring. Because Radix is headless (no styles included), it gives design teams complete visual control while eliminating the most error-prone aspect of component development: the accessibility behavior layer. The WAI-ARIA Authoring Practices Guide (APG) from the W3C is the authoritative specification that Radix implements - reading both together gives the complete picture of why each interaction pattern is designed as it is. Reach for Radix when building a custom design system from scratch, adopting shadcn/ui, or needing confidence that interactive components will pass WCAG 2.1 AA audit without custom accessibility engineering.
 
 **Canonical URLs:** https://www.radix-ui.com / https://www.w3.org/WAI/ARIA/apg
 
@@ -30,7 +30,7 @@ Radix UI is a headless React component library built on the principle that acces
 
 ## 4. shadcn/ui
 
-shadcn/ui is not a traditional component library — it is a collection of copy-paste components built on Radix UI primitives, styled with Tailwind CSS, and distributed as source files rather than npm packages. The key insight is ownership: when you install a shadcn component, you own the code and can modify it freely without forking a library. Components are pre-wired with Radix's accessible behaviors and follow a consistent theming system using CSS custom properties for color tokens. The default aesthetic is clean, modern, and neutral — intentionally generic so that a brand layer can be applied on top. It has become the de facto starting point for new React applications that need accessible, customizable components quickly. Reach for shadcn/ui for SaaS products, dashboards, and admin interfaces where Tailwind is already in use and rapid iteration on component behavior is needed.
+shadcn/ui is not a traditional component library - it is a collection of copy-paste components built on Radix UI primitives, styled with Tailwind CSS, and distributed as source files rather than npm packages. The key insight is ownership: when you install a shadcn component, you own the code and can modify it freely without forking a library. Components are pre-wired with Radix's accessible behaviors and follow a consistent theming system using CSS custom properties for color tokens. The default aesthetic is clean, modern, and neutral - intentionally generic so that a brand layer can be applied on top. It has become the de facto starting point for new React applications that need accessible, customizable components quickly. Reach for shadcn/ui for SaaS products, dashboards, and admin interfaces where Tailwind is already in use and rapid iteration on component behavior is needed.
 
 **Canonical URL:** https://ui.shadcn.com
 
@@ -38,7 +38,7 @@ shadcn/ui is not a traditional component library — it is a collection of copy-
 
 ## 5. Polaris (Shopify)
 
-Polaris is Shopify's design system for merchant-facing admin interfaces. Its core philosophy is that merchant clarity always wins over visual novelty — Polaris components are deliberately conservative in style to ensure that merchants can focus on their tasks rather than learning a new UI language. The system has deep expertise in e-commerce-specific patterns: product data tables with bulk actions, multi-step onboarding flows, fee and pricing displays, order status timelines, and multi-currency number formatting. Polaris's React components have granular TypeScript props that encode business logic (e.g., `criticalAction`, `destructive`, `loading`) as semantic variants rather than styling choices. Reach for Polaris when building Shopify apps or when the product domain is merchant-facing e-commerce operations — its patterns encode years of learnings about how merchants process information and make decisions.
+Polaris is Shopify's design system for merchant-facing admin interfaces. Its core philosophy is that merchant clarity always wins over visual novelty - Polaris components are deliberately conservative in style to ensure that merchants can focus on their tasks rather than learning a new UI language. The system has deep expertise in e-commerce-specific patterns: product data tables with bulk actions, multi-step onboarding flows, fee and pricing displays, order status timelines, and multi-currency number formatting. Polaris's React components have granular TypeScript props that encode business logic (e.g., `criticalAction`, `destructive`, `loading`) as semantic variants rather than styling choices. Reach for Polaris when building Shopify apps or when the product domain is merchant-facing e-commerce operations - its patterns encode years of learnings about how merchants process information and make decisions.
 
 **Canonical URL:** https://polaris.shopify.com
 
@@ -46,7 +46,7 @@ Polaris is Shopify's design system for merchant-facing admin interfaces. Its cor
 
 ## 6. Carbon Design System (IBM)
 
-Carbon is IBM's enterprise design system, optimized for data-heavy, information-dense interfaces in business, analytics, and scientific computing contexts. Its defining strength is the data table — Carbon's data table component supports sorting, filtering, batch actions, inline editing, pagination, and nested rows with a level of completeness that other systems do not approach. The system is built on a strict 8-column responsive grid and a precise 4px base-8 spacing scale, which makes pixel-perfect implementation across breakpoints reliable. Carbon has comprehensive dark theme support and strong accessibility compliance across its entire component set. Reach for Carbon when building enterprise dashboards, admin consoles, analytics platforms, or any interface where users will spend hours per day working with structured data at high information density.
+Carbon is IBM's enterprise design system, optimized for data-heavy, information-dense interfaces in business, analytics, and scientific computing contexts. Its defining strength is the data table - Carbon's data table component supports sorting, filtering, batch actions, inline editing, pagination, and nested rows with a level of completeness that other systems do not approach. The system is built on a strict 8-column responsive grid and a precise 4px base-8 spacing scale, which makes pixel-perfect implementation across breakpoints reliable. Carbon has comprehensive dark theme support and strong accessibility compliance across its entire component set. Reach for Carbon when building enterprise dashboards, admin consoles, analytics platforms, or any interface where users will spend hours per day working with structured data at high information density.
 
 **Canonical URL:** https://carbondesignsystem.com
 
@@ -54,7 +54,7 @@ Carbon is IBM's enterprise design system, optimized for data-heavy, information-
 
 ## 7. Fluent 2 (Microsoft)
 
-Fluent 2 is Microsoft's design language for Office 365, Windows 11, and cross-platform Microsoft products. It represents the evolution of the Fluent Design System toward a more expressive, accessible, and motion-rich visual language — particularly notable for its implementation of "emotional design" through subtle depth, layering, and light effects. Fluent 2's component library covers the full complexity of Office-class applications: ribbon toolbars, multi-pane layouts, collaborative presence indicators, and right-to-left language support. It ships implementations for React, Web Components, Blazor, iOS, and Android. Reach for Fluent 2 when building Microsoft Teams extensions, Office Add-ins, Microsoft 365 integrations, or Windows application software where visual alignment with the Microsoft ecosystem creates credibility and user familiarity.
+Fluent 2 is Microsoft's design language for Office 365, Windows 11, and cross-platform Microsoft products. It represents the evolution of the Fluent Design System toward a more expressive, accessible, and motion-rich visual language - particularly notable for its implementation of "emotional design" through subtle depth, layering, and light effects. Fluent 2's component library covers the full complexity of Office-class applications: ribbon toolbars, multi-pane layouts, collaborative presence indicators, and right-to-left language support. It ships implementations for React, Web Components, Blazor, iOS, and Android. Reach for Fluent 2 when building Microsoft Teams extensions, Office Add-ins, Microsoft 365 integrations, or Windows application software where visual alignment with the Microsoft ecosystem creates credibility and user familiarity.
 
 **Canonical URL:** https://fluent2.microsoft.design
 
@@ -62,7 +62,7 @@ Fluent 2 is Microsoft's design language for Office 365, Windows 11, and cross-pl
 
 ## 8. Primer (GitHub)
 
-Primer is GitHub's design system, optimized for developer tools, code review interfaces, and markdown-heavy content rendering. Its core philosophy is density with clarity — GitHub's users are experts who value information density and resent unnecessary visual chrome, so Primer components lean toward compact spacing and minimal decoration. Primer has particularly strong implementations of code-related components: syntax-highlighted code blocks, diff views, commit graphs, and inline comment threads. The markdown rendering system is comprehensive and well-tested across edge cases that arise in developer content. Primer also has deep investment in color accessibility — its color system was designed to meet WCAG AA across all combinations. Reach for Primer when building developer tools, code hosting features, documentation systems, or any product whose primary users are software engineers.
+Primer is GitHub's design system, optimized for developer tools, code review interfaces, and markdown-heavy content rendering. Its core philosophy is density with clarity - GitHub's users are experts who value information density and resent unnecessary visual chrome, so Primer components lean toward compact spacing and minimal decoration. Primer has particularly strong implementations of code-related components: syntax-highlighted code blocks, diff views, commit graphs, and inline comment threads. The markdown rendering system is comprehensive and well-tested across edge cases that arise in developer content. Primer also has deep investment in color accessibility - its color system was designed to meet WCAG AA across all combinations. Reach for Primer when building developer tools, code hosting features, documentation systems, or any product whose primary users are software engineers.
 
 **Canonical URL:** https://primer.style
 
@@ -70,7 +70,7 @@ Primer is GitHub's design system, optimized for developer tools, code review int
 
 ## 9. Atlassian Design System
 
-The Atlassian Design System governs the visual and interaction language of JIRA, Confluence, Trello, and Bitbucket — a family of products built around complex project management and collaborative workflows. Its defining expertise is in high-complexity form patterns: multi-step wizards, permission matrices, workflow configuration editors, and nested task hierarchies. The system provides comprehensive guidance on progressive disclosure — how to surface advanced configuration options without overwhelming occasional users — as well as patterns for collaborative real-time interfaces where multiple users edit the same content simultaneously. Atlassian's design tokens are production-ready and cover light and dark modes. Reach for the Atlassian system when designing products with JIRA-like complexity: multiple user roles, configurable workflows, permission systems, and nested content hierarchies.
+The Atlassian Design System governs the visual and interaction language of JIRA, Confluence, Trello, and Bitbucket - a family of products built around complex project management and collaborative workflows. Its defining expertise is in high-complexity form patterns: multi-step wizards, permission matrices, workflow configuration editors, and nested task hierarchies. The system provides comprehensive guidance on progressive disclosure - how to surface advanced configuration options without overwhelming occasional users - as well as patterns for collaborative real-time interfaces where multiple users edit the same content simultaneously. Atlassian's design tokens are production-ready and cover light and dark modes. Reach for the Atlassian system when designing products with JIRA-like complexity: multiple user roles, configurable workflows, permission systems, and nested content hierarchies.
 
 **Canonical URL:** https://atlassian.design
 
@@ -78,7 +78,7 @@ The Atlassian Design System governs the visual and interaction language of JIRA,
 
 ## 10. Ant Design
 
-Ant Design is China's most widely deployed enterprise React component library, produced by Alibaba's Ant Group. It is extraordinarily feature-complete — the component library contains over 60 components covering every conceivable enterprise UI pattern, from complex data pickers and cascader inputs to statistical charts and map integrations. The visual language is formal and structured, with a consistent use of gray, blue, and red that reads as professional in enterprise business software contexts. Ant Design has dedicated design guidance for Chinese business conventions (date formats, number systems, address fields, bank card inputs) that is not available in Western-focused systems. Reach for Ant Design when building enterprise SaaS for business users, when the development team is comfortable with a mature but opinionated React API, or when the product targets Chinese markets where Ant Design patterns carry high recognition.
+Ant Design is China's most widely deployed enterprise React component library, produced by Alibaba's Ant Group. It is extraordinarily feature-complete - the component library contains over 60 components covering every conceivable enterprise UI pattern, from complex data pickers and cascader inputs to statistical charts and map integrations. The visual language is formal and structured, with a consistent use of gray, blue, and red that reads as professional in enterprise business software contexts. Ant Design has dedicated design guidance for Chinese business conventions (date formats, number systems, address fields, bank card inputs) that is not available in Western-focused systems. Reach for Ant Design when building enterprise SaaS for business users, when the development team is comfortable with a mature but opinionated React API, or when the product targets Chinese markets where Ant Design patterns carry high recognition.
 
 **Canonical URL:** https://ant.design
 
@@ -86,7 +86,7 @@ Ant Design is China's most widely deployed enterprise React component library, p
 
 ## 11. Mantine
 
-Mantine is a full-featured React component and hooks library notable for the quality and breadth of its custom hooks alongside its component library. Beyond standard UI components, Mantine provides production-ready hooks for form management, clipboard access, scroll state, viewport detection, and OS-level preferences detection — hooks that typically require separate libraries. The component library has strong TypeScript support, a flexible theming system based on CSS custom properties, and first-class dark mode. Mantine's Form library is one of its differentiators: type-safe, nested form support with async validation without the boilerplate of React Hook Form or Formik. Reach for Mantine when building complex form-driven applications or data entry tools where the hook ecosystem adds as much value as the component library.
+Mantine is a full-featured React component and hooks library notable for the quality and breadth of its custom hooks alongside its component library. Beyond standard UI components, Mantine provides production-ready hooks for form management, clipboard access, scroll state, viewport detection, and OS-level preferences detection - hooks that typically require separate libraries. The component library has strong TypeScript support, a flexible theming system based on CSS custom properties, and first-class dark mode. Mantine's Form library is one of its differentiators: type-safe, nested form support with async validation without the boilerplate of React Hook Form or Formik. Reach for Mantine when building complex form-driven applications or data entry tools where the hook ecosystem adds as much value as the component library.
 
 **Canonical URL:** https://mantine.dev
 
@@ -94,7 +94,7 @@ Mantine is a full-featured React component and hooks library notable for the qua
 
 ## 12. Chakra UI
 
-Chakra UI is a modular, accessible React component library built on the constraint-based styling principle: every layout and spacing prop maps to a design token, making it difficult to use arbitrary values that break the system. Its style props API (`mt`, `px`, `bg`, `color`) creates a tight coupling between design tokens and component props that enforces consistency at the implementation layer without requiring linter rules. Chakra has strong accessibility defaults across its component set and a straightforward theme extension system. Its dark mode implementation is one of the simplest in the ecosystem — toggling color mode is a one-line API call. Reach for Chakra UI when the design system's token enforcement needs to happen at the component-API level rather than in a separate linting layer, or when rapid prototyping with token-constrained styling is the priority.
+Chakra UI is a modular, accessible React component library built on the constraint-based styling principle: every layout and spacing prop maps to a design token, making it difficult to use arbitrary values that break the system. Its style props API (`mt`, `px`, `bg`, `color`) creates a tight coupling between design tokens and component props that enforces consistency at the implementation layer without requiring linter rules. Chakra has strong accessibility defaults across its component set and a straightforward theme extension system. Its dark mode implementation is one of the simplest in the ecosystem - toggling color mode is a one-line API call. Reach for Chakra UI when the design system's token enforcement needs to happen at the component-API level rather than in a separate linting layer, or when rapid prototyping with token-constrained styling is the priority.
 
 **Canonical URL:** https://chakra-ui.com
 
@@ -102,7 +102,7 @@ Chakra UI is a modular, accessible React component library built on the constrai
 
 ## 13. Base Web (Uber)
 
-Base Web is Uber's open-source React component library, built for applications that prioritize data density, table-heavy interfaces, and complex form patterns at production scale. Its defining architectural feature is the "Overrides" pattern — every component exposes an override prop that allows any internal sub-component to be replaced or styled without forking the library. This makes Base Web uniquely flexible for organizations that need a coherent component system but have strict visual requirements that differ from any library's defaults. The data grid component is particularly capable, supporting row virtualization, column pinning, inline editing, and multi-sort. Reach for Base Web when building operations dashboards, logistics interfaces, or any data-intensive application where table density and performance at 10,000+ rows are primary requirements.
+Base Web is Uber's open-source React component library, built for applications that prioritize data density, table-heavy interfaces, and complex form patterns at production scale. Its defining architectural feature is the "Overrides" pattern - every component exposes an override prop that allows any internal sub-component to be replaced or styled without forking the library. This makes Base Web uniquely flexible for organizations that need a coherent component system but have strict visual requirements that differ from any library's defaults. The data grid component is particularly capable, supporting row virtualization, column pinning, inline editing, and multi-sort. Reach for Base Web when building operations dashboards, logistics interfaces, or any data-intensive application where table density and performance at 10,000+ rows are primary requirements.
 
 **Canonical URL:** https://baseweb.design
 
@@ -110,7 +110,7 @@ Base Web is Uber's open-source React component library, built for applications t
 
 ## 14. Nord (Trivago)
 
-Nord is Trivago's clean, minimal design system for travel and hospitality product interfaces. It is characterized by a restrained visual palette (predominantly white, light gray, and a single accent color), generous whitespace, and a focus on content legibility — appropriate for interfaces where the primary job is helping users compare options and make decisions. Nord's component documentation is exceptionally clear and includes detailed usage rationale and anti-pattern guidance alongside component specs. The system is smaller than enterprise-scale alternatives but is well-suited to consumer-facing products where visual sophistication and content clarity are more important than component count. Reach for Nord when building consumer products in travel, hospitality, or marketplace contexts where the brand aesthetic is premium, minimal, and content-forward.
+Nord is Trivago's clean, minimal design system for travel and hospitality product interfaces. It is characterized by a restrained visual palette (predominantly white, light gray, and a single accent color), generous whitespace, and a focus on content legibility - appropriate for interfaces where the primary job is helping users compare options and make decisions. Nord's component documentation is exceptionally clear and includes detailed usage rationale and anti-pattern guidance alongside component specs. The system is smaller than enterprise-scale alternatives but is well-suited to consumer-facing products where visual sophistication and content clarity are more important than component count. Reach for Nord when building consumer products in travel, hospitality, or marketplace contexts where the brand aesthetic is premium, minimal, and content-forward.
 
 **Canonical URL:** https://norddesignsystem.com
 
@@ -118,7 +118,7 @@ Nord is Trivago's clean, minimal design system for travel and hospitality produc
 
 ## 15. Spectrum (Adobe)
 
-Spectrum is Adobe's design system for Creative Cloud applications — Photoshop, Illustrator, Acrobat, XD, and the broader Adobe ecosystem. Its core philosophy is "density over decoration" — creative tool users need maximum canvas space and minimal chrome, so Spectrum components are compact, keyboard-navigable, and optimized for expert-user workflows rather than onboarding. Spectrum has particularly strong guidance for non-destructive editing patterns, panel layouts, property inspector interfaces, and contextual toolbars — patterns that rarely appear in general-purpose design systems. The Web Components implementation allows Spectrum to work across frameworks. Reach for Spectrum when building creative tools, editing interfaces, or professional applications where users are domain experts who value speed and control over visual novelty.
+Spectrum is Adobe's design system for Creative Cloud applications - Photoshop, Illustrator, Acrobat, XD, and the broader Adobe ecosystem. Its core philosophy is "density over decoration" - creative tool users need maximum canvas space and minimal chrome, so Spectrum components are compact, keyboard-navigable, and optimized for expert-user workflows rather than onboarding. Spectrum has particularly strong guidance for non-destructive editing patterns, panel layouts, property inspector interfaces, and contextual toolbars - patterns that rarely appear in general-purpose design systems. The Web Components implementation allows Spectrum to work across frameworks. Reach for Spectrum when building creative tools, editing interfaces, or professional applications where users are domain experts who value speed and control over visual novelty.
 
 **Canonical URL:** https://spectrum.adobe.com
 
@@ -126,7 +126,7 @@ Spectrum is Adobe's design system for Creative Cloud applications — Photoshop,
 
 ## 16. Lightning Design System (Salesforce)
 
-The Salesforce Lightning Design System governs the visual and behavioral language of Salesforce CRM and the Force.com platform. It is purpose-built for complex CRM patterns: record detail layouts, activity timelines, relationship panels, approval workflows, and configurable page builders. The system has deep guidance on form layout for dense data entry, which is the core user task in CRM — entering leads, logging calls, updating opportunity stages. Lightning's component implementations are available for Aura (Salesforce's older component model), LWC (Lightning Web Components), and React. Reach for Lightning when building Salesforce AppExchange products, Salesforce platform integrations, or CRM-adjacent applications where users switch between Salesforce and your product and visual consistency reduces cognitive switching cost.
+The Salesforce Lightning Design System governs the visual and behavioral language of Salesforce CRM and the Force.com platform. It is purpose-built for complex CRM patterns: record detail layouts, activity timelines, relationship panels, approval workflows, and configurable page builders. The system has deep guidance on form layout for dense data entry, which is the core user task in CRM - entering leads, logging calls, updating opportunity stages. Lightning's component implementations are available for Aura (Salesforce's older component model), LWC (Lightning Web Components), and React. Reach for Lightning when building Salesforce AppExchange products, Salesforce platform integrations, or CRM-adjacent applications where users switch between Salesforce and your product and visual consistency reduces cognitive switching cost.
 
 **Canonical URL:** https://lightningdesignsystem.com
 
@@ -134,7 +134,7 @@ The Salesforce Lightning Design System governs the visual and behavioral languag
 
 ## 17. Evergreen (Segment)
 
-Evergreen is Segment's React UI framework for building B2B SaaS products. It was built to serve the Segment customer data platform — a product used by technical users (engineers and data analysts) who need to configure data pipelines, schema mappings, and integrations. Evergreen's components have a clean, professional aesthetic that signals "serious business tool" without the heaviness of traditional enterprise systems like Carbon or Lightning. The library is smaller and more focused than many alternatives, which makes it easier to learn completely and extend systematically. Reach for Evergreen when building developer-adjacent B2B SaaS — products used by technical business users who want a professional, efficient interface without the complexity of a full enterprise framework.
+Evergreen is Segment's React UI framework for building B2B SaaS products. It was built to serve the Segment customer data platform - a product used by technical users (engineers and data analysts) who need to configure data pipelines, schema mappings, and integrations. Evergreen's components have a clean, professional aesthetic that signals "serious business tool" without the heaviness of traditional enterprise systems like Carbon or Lightning. The library is smaller and more focused than many alternatives, which makes it easier to learn completely and extend systematically. Reach for Evergreen when building developer-adjacent B2B SaaS - products used by technical business users who want a professional, efficient interface without the complexity of a full enterprise framework.
 
 **Canonical URL:** https://evergreen.segment.com
 
@@ -142,7 +142,7 @@ Evergreen is Segment's React UI framework for building B2B SaaS products. It was
 
 ## 18. Gestalt (Pinterest)
 
-Gestalt is Pinterest's design system, purpose-built for visual discovery and image-heavy content interfaces. Its defining expertise is in masonry grid layouts, image card components, and the interaction patterns around visual content — save, collection, board management, and visual search. Gestalt's pin component and board grid are among the most refined implementations of image-based browsing patterns in any open-source design system. The system also has strong documentation of hover and focus states in image-grid contexts, which are notoriously difficult to implement accessibly without disrupting visual flow. Reach for Gestalt when building visual discovery products, mood board tools, image collection managers, or any interface where the primary content unit is an image in a variable-height masonry grid.
+Gestalt is Pinterest's design system, purpose-built for visual discovery and image-heavy content interfaces. Its defining expertise is in masonry grid layouts, image card components, and the interaction patterns around visual content - save, collection, board management, and visual search. Gestalt's pin component and board grid are among the most refined implementations of image-based browsing patterns in any open-source design system. The system also has strong documentation of hover and focus states in image-grid contexts, which are notoriously difficult to implement accessibly without disrupting visual flow. Reach for Gestalt when building visual discovery products, mood board tools, image collection managers, or any interface where the primary content unit is an image in a variable-height masonry grid.
 
 **Canonical URL:** https://gestalt.pinterest.systems
 

package/reference/design-variants.md

@@ -1,6 +1,6 @@
 # Design Variants + the `design_arms` Outcome Loop
 
-How `/gdd:design --variants N` generates competing, hypothesis-tagged design variants, and how external outcomes (A/B experiments + user research) feed the `design_arms` posterior so the design stage learns **which patterns win with users** — not just which pass lint/test. The posterior math lives in `scripts/lib/ds-arms/design-arms-store.cjs`; the ingest agents are `agents/experiment-result-ingester.md` (A/B) + `agents/user-research-synthesizer.md` (research).
+How `/gdd:design --variants N` generates competing, hypothesis-tagged design variants, and how external outcomes (A/B experiments + user research) feed the `design_arms` posterior so the design stage learns **which patterns win with users** - not just which pass lint/test. The posterior math lives in `scripts/lib/ds-arms/design-arms-store.cjs`; the ingest agents are `agents/experiment-result-ingester.md` (A/B) + `agents/user-research-synthesizer.md` (research).
 
 ---
 
@@ -15,16 +15,16 @@ When `--variants N` is set (default **N = 2**, the A/B baseline), the design sta
          hypothesis="A lower-pressure outline CTA reduces accidental taps" />
 ```
 
-- **`id`** — A, B, C… (stable within a cycle).
-- **`component`** — the `component_type` the arm is keyed on (e.g. `primary-cta`, `pricing-card`, `signup-form`).
-- **`pattern`** — a short pattern slug → hashed to `variant_pattern_hash` via `variantKey(component, pattern)`.
-- **`hypothesis`** — a falsifiable prediction in user-outcome terms (conversion, completion, error rate). This is the contract an A/B test or research finding later resolves.
+- **`id`** - A, B, C… (stable within a cycle).
+- **`component`** - the `component_type` the arm is keyed on (e.g. `primary-cta`, `pricing-card`, `signup-form`).
+- **`pattern`** - a short pattern slug → hashed to `variant_pattern_hash` via `variantKey(component, pattern)`.
+- **`hypothesis`** - a falsifiable prediction in user-outcome terms (conversion, completion, error rate). This is the contract an A/B test or research finding later resolves.
 
-A variant without a hypothesis is not a variant — it's an opinion. The stage refuses to tag one without it.
+A variant without a hypothesis is not a variant - it's an opinion. The stage refuses to tag one without it.
 
 ## The `design_arms` posterior (advisory)
 
-Each `(component_type, variant_pattern_hash)` is an **arm** with a Beta posterior, conservative **Beta(2, 8)** prior (posterior mean 0.2 — a pattern must EARN trust from real outcomes; the Phase 29 fairness-gate pattern). Distinct from the routing bandit's `routing_arms` (`scripts/lib/bandit-router.cjs`) — design_arms learn from **users**, not from internal pass/fail.
+Each `(component_type, variant_pattern_hash)` is an **arm** with a Beta posterior, conservative **Beta(2, 8)** prior (posterior mean 0.2 - a pattern must EARN trust from real outcomes; the Phase 29 fairness-gate pattern). Distinct from the routing bandit's `routing_arms` (`scripts/lib/bandit-router.cjs`) - design_arms learn from **users**, not from internal pass/fail.
 
 **Before generation**, the design stage may consult the posterior:
 
@@ -34,13 +34,13 @@ const arm = pull('primary-cta', variantKey('primary-cta', 'cta-bold-filled'));
 // arm.mean = 0.70  → "cta-bold-filled has a 70% win rate — bias toward it"
 ```
 
-**D-03 — advisory, never directive.** The posterior *biases* which patterns the stage proposes (and how it orders variants), but the **user always wins**: if the posterior favors A and the user asks for B, generate B. Surface the posterior as a note ("heads-up: pattern A has won 7/10 prior experiments"), never as a veto.
+**D-03 - advisory, never directive.** The posterior *biases* which patterns the stage proposes (and how it orders variants), but the **user always wins**: if the posterior favors A and the user asks for B, generate B. Surface the posterior as a note ("heads-up: pattern A has won 7/10 prior experiments"), never as a veto.
 
 ## Closing the loop (outcome ingest)
 
-1. **A/B** — `experiment-result-ingester` reads a LaunchDarkly / Statsig / GrowthBook result, maps each variant to a win/lose, and calls `observe(component, hash, { won, source: 'ab' })`. Emits an `experiment_result` event (Phase 22 chain).
-2. **Research** — `user-research-synthesizer` reads UserTesting / Maze / Hotjar reports (**pseudonymized first** — D-05), extracts findings, and folds qualitative signal as `observe(..., { source: 'research', weight })`.
-3. **Dev-time** (Phase 47, later) — live-accepted variants observe with `source: 'dev_time'` under a conservative discount.
+1. **A/B** - `experiment-result-ingester` reads a LaunchDarkly / Statsig / GrowthBook result, maps each variant to a win/lose, and calls `observe(component, hash, { won, source: 'ab' })`. Emits an `experiment_result` event (Phase 22 chain).
+2. **Research** - `user-research-synthesizer` reads UserTesting / Maze / Hotjar reports (**pseudonymized first** - D-05), extracts findings, and folds qualitative signal as `observe(..., { source: 'research', weight })`.
+3. **Dev-time** (Phase 47, later) - live-accepted variants observe with `source: 'dev_time'` under a conservative discount.
 
 `observe(won: true)` increments `alpha`; `won: false` increments `beta`. Over many experiments the posterior mean converges on the pattern's true win rate, and the design stage's bias tracks reality.
 

package/reference/domains/civic-patterns.md

@@ -1,6 +1,6 @@
 # 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.
+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
 
@@ -8,7 +8,7 @@ In the private sector, accessibility, plain language, and translation are often
 
 ## 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.
+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:
 
@@ -18,7 +18,7 @@ Concretely, every civic UI must satisfy at least:
 | 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. |
+| 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. |
@@ -34,7 +34,7 @@ A practical US minimum is **English + Spanish + Simplified Chinese (`zh-Hans`)**
 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.
+- **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.
@@ -55,7 +55,7 @@ The **Plain Writing Act of 2010** requires US federal agencies to write public-f
 
 - **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.
+- **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.
@@ -75,10 +75,10 @@ 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
+  - `@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.
@@ -95,7 +95,7 @@ The auditor agent runs these against a civic UI. Each item is concrete and verif
 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.
+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

@@ -25,12 +25,12 @@ Financial UIs are table-first: positions, orders, ledgers, transaction histories
 ## 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.
+- 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.
+- 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.
 
@@ -46,14 +46,14 @@ The governing principle from advertising rules (SEC, FINRA) is proximity: a disc
 
 | Context | Disclosure |
 |---|---|
-| Margin trading / leverage | Reg-T margin risk disclosure and current margin requirements, shown in the margin/borrow flow |
+| Margin trading / use | 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.
+- 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)
@@ -61,7 +61,7 @@ The governing principle from advertising rules (SEC, FINRA) is proximity: a disc
 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 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.
@@ -71,7 +71,7 @@ PCI-DSS governs how cardholder data is handled in the UI and beyond. Design must
 
 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.
+- 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.
@@ -81,7 +81,7 @@ Honest, locale-correct number formatting is a trust signal in finance. Use the p
 ## 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.
+- 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.
 
@@ -111,12 +111,12 @@ 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.
+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.
+8. Margin/use 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.

package/reference/domains/gaming-patterns.md

@@ -16,7 +16,7 @@ The canonical model is the four-quadrant scheme from Fagerholt & Lorentzon ("Bey
 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).
+- 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).
 
@@ -26,7 +26,7 @@ Guidance:
 
 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.
+- 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.
@@ -35,7 +35,7 @@ Provide **in-game toggles** for each of the following AND honor the OS / platfor
 ### 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.
+- 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.
 
@@ -47,13 +47,13 @@ Provide **in-game toggles** for each of the following AND honor the OS / platfor
 
 ## 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.
+- **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
+## Input model - controller-first vs touch-first vs KB/M
 
 Detect the **active** input device and adapt; never assume mouse hover exists.
 
@@ -67,9 +67,9 @@ Detect the **active** input device and adapt; never assume mouse hover exists.
 
 ## 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).
+- **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.
+- **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
@@ -100,12 +100,12 @@ The presence of a game engine dep plus any HUD/player keyword should auto-route
 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.
+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.
+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

@@ -1,21 +1,21 @@
 # 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.
+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.
+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.
+- **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.
+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.
@@ -29,9 +29,9 @@ Patient portals (MyChart, Athenahealth, Healow-style) share a recognizable set o
 | 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). |
+| 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. |
+| 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. |
 
@@ -42,7 +42,7 @@ Healthcare reaches the broadest, most impaired population of any domain: elderly
 - **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`).
+- **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.
 
@@ -50,9 +50,9 @@ Healthcare reaches the broadest, most impaired population of any domain: elderly
 
 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.
+- **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.
+- **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.
 
@@ -81,7 +81,7 @@ Any FHIR/HL7/Medplum/Redox dependency, or a cluster of the keywords above, shoul
 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.
+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.
@@ -90,7 +90,7 @@ Concrete, verifiable items for reviewing a healthcare UI:
 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.
+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