@hegemonart/get-design-done 1.41.5 → 1.43.0

package/reference/brand-voice.md

@@ -2,13 +2,13 @@
 
 <!-- Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/products.csv, data/ui-reasoning.csv (industry-context section) -->
 
-Brand voice is not a single setting — it is a combination of independent axes, an archetype frame, and a sensitivity to context. Agents reading this file should treat the voice axes and archetype library as orthogonal dimensions: pick a position on each axis independently, then select an archetype to layer personality on top. Neither choice is derived from the other.
+Brand voice is not a single setting - it is a combination of independent axes, an archetype frame, and a sensitivity to context. Agents reading this file should treat the voice axes and archetype library as orthogonal dimensions: pick a position on each axis independently, then select an archetype to layer personality on top. Neither choice is derived from the other.
 
 ---
 
 ## Voice Axes
 
-Each axis is a spectrum between two poles. Moving toward one pole is not superior to moving toward the other — the correct position depends entirely on the product's audience, vertical, and context of use. Most products do not land at the extreme of any axis; they occupy a deliberate range within it.
+Each axis is a spectrum between two poles. Moving toward one pole is not superior to moving toward the other - the correct position depends entirely on the product's audience, vertical, and context of use. Most products do not land at the extreme of any axis; they occupy a deliberate range within it.
 
 ### Axis 1: Formal ↔ Casual
 
@@ -30,7 +30,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **Serious pole:** Tone is earnest and sober. Errors are acknowledged without irony. Humor is absent or very subdued. Stakes are treated as real. Example error message: "We were unable to process your payment. Please verify your card details and try again, or contact your bank."
 
-**Playful pole:** Tone uses wit, lightness, and occasionally emoji or metaphor to reduce tension and delight the user. Playfulness does not mean frivolous — it means the product enjoys its own existence. Example error message: "Something got tangled up on our end. Give it another go? 🙏"
+**Playful pole:** Tone uses wit, lightness, and occasionally emoji or metaphor to reduce tension and delight the user. Playfulness does not mean frivolous - it means the product enjoys its own existence. Example error message: "Something got tangled up on our end. Give it another go? 🙏"
 
 **When to move toward Serious:** Enterprise B2B, professional tools, medical platforms, legal services, and financial dashboards should maintain a serious register because users are performing consequential work and playful tone signals a mismatch in understanding stakes. An HR platform with whimsical error messages risks undermining managerial authority.
 
@@ -38,7 +38,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **Copy examples:**
 - Serious: "This action cannot be undone. All selected records will be permanently deleted."
-- Playful: "Heads up — once you delete this, it's gone for good. Still want to?"
+- Playful: "Heads up - once you delete this, it's gone for good. Still want to?"
 
 ---
 
@@ -46,7 +46,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **Expert pole:** Language assumes domain knowledge. Technical terms are used without definition. The product speaks as a peer to specialists. Precision is prioritized over accessibility. Example: "Configure your OAuth 2.0 PKCE flow with a 256-bit code verifier before initiating the authorization request."
 
-**Approachable pole:** Language explains concepts in plain English. Jargon is translated or avoided. The product speaks as a guide to non-specialists. Accessibility is prioritized over brevity. Example: "Connect your account securely — we use a modern login method that keeps your password private."
+**Approachable pole:** Language explains concepts in plain English. Jargon is translated or avoided. The product speaks as a guide to non-specialists. Accessibility is prioritized over brevity. Example: "Connect your account securely - we use a modern login method that keeps your password private."
 
 **When to move toward Expert:** Developer tools, ML/data platforms, DevOps dashboards, security products, and medical or legal professional tools are used by specialists who are frustrated by over-explanation. Unnecessary simplification reads as condescension and slows expert users down.
 
@@ -66,7 +66,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **When to move toward Reverent:** Luxury brands, heritage fashion houses, fine dining, premium hospitality, and cultural institutions benefit from reverent language because it honors the symbolic weight users attach to these products and does not puncture the aspirational experience they are purchasing.
 
-**When to move toward Irreverent:** Challenger brands, startup disruptors, creative tools, youth-oriented products, and any brand explicitly positioning against an incumbent benefit from irreverent language because it embodies the brand's core argument — that the old way is worth questioning. An anti-establishment fintech that writes like a bank forfeits its entire premise.
+**When to move toward Irreverent:** Challenger brands, startup disruptors, creative tools, youth-oriented products, and any brand explicitly positioning against an incumbent benefit from irreverent language because it embodies the brand's core argument - that the old way is worth questioning. An anti-establishment fintech that writes like a bank forfeits its entire premise.
 
 **Copy examples:**
 - Reverent: "Each piece is hand-finished by our atelier in Lyon."
@@ -78,7 +78,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **Authoritative pole:** The product speaks with confidence and direction. It tells users what to do. Instructions are commands, not suggestions. The relationship is expert-to-user. Example: "You must complete identity verification before withdrawing funds." / "Save your work before closing this window."
 
-**Collaborative pole:** The product speaks as a partner. It recommends and explains, framing choices as shared decisions. The relationship is peer-to-peer. Example: "We recommend verifying your identity now — it unlocks higher withdrawal limits." / "Just so you know — unsaved changes will be lost if you close."
+**Collaborative pole:** The product speaks as a partner. It recommends and explains, framing choices as shared decisions. The relationship is peer-to-peer. Example: "We recommend verifying your identity now - it unlocks higher withdrawal limits." / "Just so you know - unsaved changes will be lost if you close."
 
 **When to move toward Authoritative:** Compliance interfaces, safety-critical systems, legal workflows, and any context where users must follow a specific procedure without deviation benefit from authoritative language because ambiguity creates errors and liability. A safety checklist that says "You might want to confirm the valve is closed" is a design defect.
 
@@ -86,7 +86,7 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 
 **Copy examples:**
 - Authoritative: "Enter your password to confirm this irreversible action."
-- Collaborative: "One last check — confirm your password and we'll take it from there."
+- Collaborative: "One last check - confirm your password and we'll take it from there."
 
 ---
 
@@ -95,40 +95,40 @@ Each axis is a spectrum between two poles. Moving toward one pole is not superio
 Archetypes are personality frames, not voice axes. They describe the fundamental role the brand plays in its users' lives and the emotional contract it offers. Archetypes and voice axes are orthogonal: a Sage brand can be formal or casual, serious or playful. Select an archetype and then tune voice axes independently.
 
 ### 1. The Sage
-The Sage earns trust by sharing knowledge. It positions the product as the most informed source in the room — not arrogant, but genuinely expert. The Sage communicates in a way that makes users feel more capable after each interaction, not dependent. In UI, this means rich documentation, contextual education woven into onboarding, and copy that explains the "why" rather than just the "what." Design skews toward clarity, precision, and minimalism — nothing competes with the information itself.
+The Sage earns trust by sharing knowledge. It positions the product as the most informed source in the room - not arrogant, but genuinely expert. The Sage communicates in a way that makes users feel more capable after each interaction, not dependent. In UI, this means rich documentation, contextual education woven into onboarding, and copy that explains the "why" rather than just the "what." Design skews toward clarity, precision, and minimalism - nothing competes with the information itself.
 
 ### 2. The Hero
-The Hero is empowering and action-oriented. It frames the user as the agent of change and the product as the tool that makes the mission possible. CTAs are verbs: "Start building," "Launch your campaign," "Deploy now." The Hero archetype works best when users have a clear goal and the product gives them velocity toward it. Design is bold, directional, and high-contrast — it communicates momentum.
+The Hero is empowering and action-oriented. It frames the user as the agent of change and the product as the tool that makes the mission possible. CTAs are verbs: "Start building," "Launch your campaign," "Deploy now." The Hero archetype works best when users have a clear goal and the product gives them velocity toward it. Design is bold, directional, and high-contrast - it communicates momentum.
 
 ### 3. The Creator
-The Creator prioritizes imagination and aesthetic experience. The product itself is a canvas, and the copy celebrates what users will make rather than what the product can do. Language is evocative rather than functional. Onboarding feels like an invitation rather than a tutorial. Design is aesthetic-forward — typography, whitespace, and visual rhythm are treated as expressive elements, not just layout tools.
+The Creator prioritizes imagination and aesthetic experience. The product itself is a canvas, and the copy celebrates what users will make rather than what the product can do. Language is evocative rather than functional. Onboarding feels like an invitation rather than a tutorial. Design is aesthetic-forward - typography, whitespace, and visual rhythm are treated as expressive elements, not just layout tools.
 
 ### 4. The Caregiver
-The Caregiver is empathetic, supportive, and gentle under pressure. It anticipates user anxiety and responds with reassurance. Error messages do not blame; they comfort and guide. Onboarding is patient. The Caregiver archetype is essential for health apps, mental wellness platforms, parenting tools, and any product used during vulnerable moments. Design is warm, rounded, and low-stimulus — nothing startles or overwhelms.
+The Caregiver is empathetic, supportive, and gentle under pressure. It anticipates user anxiety and responds with reassurance. Error messages do not blame; they comfort and guide. Onboarding is patient. The Caregiver archetype is essential for health apps, mental wellness platforms, parenting tools, and any product used during vulnerable moments. Design is warm, rounded, and low-stimulus - nothing startles or overwhelms.
 
 ### 5. The Ruler
-The Ruler is premium, commanding, and authority-signaling. It does not explain itself — it presents. Copy is declarative and sparse. The Ruler archetype justifies premium pricing through an experience that communicates exclusivity and mastery. This archetype works for luxury goods, high-end B2B platforms, and any product where status is part of the value. Design is restrained, high-contrast, and architectural — every element signals control.
+The Ruler is premium, commanding, and authority-signaling. It does not explain itself - it presents. Copy is declarative and sparse. The Ruler archetype justifies premium pricing through an experience that communicates exclusivity and mastery. This archetype works for luxury goods, high-end B2B platforms, and any product where status is part of the value. Design is restrained, high-contrast, and architectural - every element signals control.
 
 ### 6. The Jester
-The Jester uses humor to disarm and delight. It understands that joy is a retention mechanism and that laughter creates loyalty. The Jester does not take itself seriously and invites users to share that lightness. This archetype works for consumer products in low-stakes categories, social tools, and brands that have earned enough trust to be self-deprecating. Design uses surprise, playful motion, and unexpected visual moments — but always purposefully, never randomly.
+The Jester uses humor to disarm and delight. It understands that joy is a retention mechanism and that laughter creates loyalty. The Jester does not take itself seriously and invites users to share that lightness. This archetype works for consumer products in low-stakes categories, social tools, and brands that have earned enough trust to be self-deprecating. Design uses surprise, playful motion, and unexpected visual moments - but always purposefully, never randomly.
 
 ### 7. The Innocent
-The Innocent is clean, optimistic, and simple. It communicates that the world is basically good and that this product exists to make it a little better. Copy is honest, unpretentious, and free of manipulation. The Innocent archetype is right for health food brands, sustainable products, children's tools, and any product positioning around purity or honesty. Design is bright, open, and generous with whitespace — nothing hidden, nothing complex.
+The Innocent is clean, optimistic, and simple. It communicates that the world is basically good and that this product exists to make it a little better. Copy is honest, unpretentious, and free of manipulation. The Innocent archetype is right for health food brands, sustainable products, children's tools, and any product positioning around purity or honesty. Design is bright, open, and generous with whitespace - nothing hidden, nothing complex.
 
 ### 8. The Explorer
 The Explorer is discovery-forward and adventurous. It communicates that the world is full of things worth finding and that this product is the best vehicle for that journey. Copy uses open-ended language: "See what's possible," "Go further," "Find your path." The Explorer archetype fits travel apps, outdoor brands, learning platforms, and curiosity-driven tools. Design uses movement, depth, and environmental imagery to evoke possibility.
 
 ### 9. The Rebel
-The Rebel challenges assumptions and frames the incumbent as the problem. It uses anti-establishment language deliberately, not carelessly. The Rebel is not angry — it is confident in its alternative. Copy names what it rejects: "Not your usual bank," "Skip the middleman," "Design without the gatekeepers." The Rebel archetype is right for challenger brands, disruptive startups, and any product that exists because the existing solution is broken. Design is unconventional — asymmetric, raw, or deliberately anti-polished to signal that the rules have changed.
+The Rebel challenges assumptions and frames the incumbent as the problem. It uses anti-establishment language deliberately, not carelessly. The Rebel is not angry - it is confident in its alternative. Copy names what it rejects: "Not your usual bank," "Skip the middleman," "Design without the gatekeepers." The Rebel archetype is right for challenger brands, disruptive startups, and any product that exists because the existing solution is broken. Design is unconventional - asymmetric, raw, or deliberately anti-polished to signal that the rules have changed.
 
 ### 10. The Lover
-The Lover creates intimacy and sensory connection. Copy is warm, personal, and physically evocative. The Lover archetype is less about romance than about deep emotional resonance — the product feels like it was made for you specifically. This archetype fits beauty brands, food and beverage, hospitality, and any product where sensory experience is central. Design is rich, textural, and emotionally warm — photography over illustration, warmth over coolness.
+The Lover creates intimacy and sensory connection. Copy is warm, personal, and physically evocative. The Lover archetype is less about romance than about deep emotional resonance - the product feels like it was made for you specifically. This archetype fits beauty brands, food and beverage, hospitality, and any product where sensory experience is central. Design is rich, textural, and emotionally warm - photography over illustration, warmth over coolness.
 
 ### 11. The Everyman
-The Everyman is relatable, unpretentious, and radically inclusive. It signals that this product is for everyone, not for a tribe or an aspirational identity. Copy avoids jargon, insider language, and exclusivity markers. The Everyman archetype is right for utility apps, mass-market consumer tools, and any product that succeeds by broad adoption rather than niche loyalty. Design is familiar and accessible — conventional enough to feel immediately understandable to any user.
+The Everyman is relatable, unpretentious, and radically inclusive. It signals that this product is for everyone, not for a tribe or an aspirational identity. Copy avoids jargon, insider language, and exclusivity markers. The Everyman archetype is right for utility apps, mass-market consumer tools, and any product that succeeds by broad adoption rather than niche loyalty. Design is familiar and accessible - conventional enough to feel immediately understandable to any user.
 
 ### 12. The Magician
-The Magician is transformation-focused. It frames the product as the mechanism by which users go from a lesser to a greater state. Copy uses before/after framing: "What used to take days takes minutes," "You used to guess. Now you know." The Magician archetype fits productivity tools, AI platforms, and any product whose core promise is that the user will be meaningfully different after using it. Design uses contrast — before states feel constrained, after states feel open and capable.
+The Magician is transformation-focused. It frames the product as the mechanism by which users go from a lesser to a greater state. Copy uses before/after framing: "What used to take days takes minutes," "You used to guess. Now you know." The Magician archetype fits productivity tools, AI platforms, and any product whose core promise is that the user will be meaningfully different after using it. Design uses contrast - before states feel constrained, after states feel open and capable.
 
 ---
 
@@ -152,18 +152,18 @@ Beyond the 12 canonical archetypes, products can adopt a design-register variant
 
 ## Tone-by-Context Table
 
-Tone is not fixed — even a consistent brand voice shifts register depending on the situation the user is in. A Jester brand should not make jokes in an error message that signals data loss. This table maps UI contexts to appropriate tone adjustments.
+Tone is not fixed - even a consistent brand voice shifts register depending on the situation the user is in. A Jester brand should not make jokes in an error message that signals data loss. This table maps UI contexts to appropriate tone adjustments.
 
 | Context | Recommended Tone | Example Copy |
 |---------|-----------------|--------------|
-| Error message | Calm, clear, helpful — never humorous for data loss or high-stakes failure | "We couldn't save your changes. Check your connection and try again." |
-| Empty state | Warm, forward-looking, actionable — explains why empty and what to do | "Nothing here yet. Add your first project to get started." |
-| Success / celebration | Positive, proportionate to stakes — brief and genuine, not excessive | "All done! Your report is ready." / "🎉 You're all set!" (casual products only) |
-| Onboarding | Welcoming, encouraging, brief — does not front-load complexity | "Let's set up your workspace. It only takes a minute." |
-| Loading state | Reassuring, informative — signals progress without being annoying | "Getting your data…" / "Almost there." |
-| Destructive action confirmation | Serious, precise, no hedging — names what will be destroyed | "Delete project 'Alpha'? This cannot be undone." |
-| Pricing page | Honest, benefit-led, no dark patterns — copy earns the price | "Everything in Pro, plus unlimited seats and priority support." |
-| Marketing headline | Archetype-forward, emotionally resonant — captures brand promise | Varies by archetype (Hero: "Ship faster." / Creator: "Make something beautiful.") |
+| Error message | Calm, clear, helpful - never humorous for data loss or high-stakes failure | "We couldn't save your changes. Check your connection and try again." |
+| Empty state | Warm, forward-looking, actionable - explains why empty and what to do | "Nothing here yet. Add your first project to get started." |
+| Success / celebration | Positive, proportionate to stakes - brief and genuine, not excessive | "All done! Your report is ready." / "🎉 You're all set!" (casual products only) |
+| Onboarding | Welcoming, encouraging, brief - does not front-load complexity | "Let's set up your workspace. It only takes a minute." |
+| Loading state | Reassuring, informative - signals progress without being annoying | "Getting your data…" / "Almost there." |
+| Destructive action confirmation | Serious, precise, no hedging - names what will be destroyed | "Delete project 'Alpha'? This cannot be undone." |
+| Pricing page | Honest, benefit-led, no dark patterns - copy earns the price | "Everything in Pro, plus unlimited seats and priority support." |
+| Marketing headline | Archetype-forward, emotionally resonant - captures brand promise | Varies by archetype (Hero: "Ship faster." / Creator: "Make something beautiful.") |
 
 ---
 
@@ -171,29 +171,29 @@ Tone is not fixed — even a consistent brand voice shifts register depending on
 
 <!-- Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/products.csv, data/ui-reasoning.csv -->
 
-**Important:** Voice axis positions and industry context are orthogonal dimensions. Industry context provides defaults and constraints; voice axis positions are still chosen deliberately within those constraints. A FinTech product can be formal but approachable, or formal and expert — industry context does not collapse those choices, it narrows the range.
+**Important:** Voice axis positions and industry context are orthogonal dimensions. Industry context provides defaults and constraints; voice axis positions are still chosen deliberately within those constraints. A FinTech product can be formal but approachable, or formal and expert - industry context does not collapse those choices, it narrows the range.
 
 ---
 
 | Vertical | Voice Axis Defaults | Color Mood | Typography Mood | Key Effects | Anti-Patterns |
 |----------|-------------------|------------|-----------------|-------------|---------------|
-| **FinTech / Banking** | Formal → Serious → Expert → Authoritative; trust must be earned through consistency | Deep navy, forest green, cool greys — signals stability and security | Clean sans-serif (Inter, DM Sans), generous line-height for readability at numeric density | Microanimations on transaction confirmation; subtle loading states; no celebration for transfers | Casual tone on high-stakes actions; bright consumer palettes; playful error messages; flashy transitions on money movement |
-| **HealthTech / Medical** | Formal → Serious → Approachable → Collaborative; clarity reduces anxiety | Soft teal, warm white, calm blues — avoids red except for genuine danger signals | Clean, large, high-contrast; body text ≥16px mandatory for compliance and accessibility | Gentle loading indicators; animated check states for completed steps; no jarring motion | Dense data without explanation; dark mode with pure black; small body text; red used decoratively |
+| **FinTech / Banking** | Formal → Serious → Expert → Authoritative; trust must be earned through consistency | Deep navy, forest green, cool greys - signals stability and security | Clean sans-serif (Inter, DM Sans), generous line-height for readability at numeric density | Microanimations on transaction confirmation; subtle loading states; no celebration for transfers | Casual tone on high-stakes actions; bright consumer palettes; playful error messages; flashy transitions on money movement |
+| **HealthTech / Medical** | Formal → Serious → Approachable → Collaborative; clarity reduces anxiety | Soft teal, warm white, calm blues - avoids red except for genuine danger signals | Clean, large, high-contrast; body text ≥16px mandatory for compliance and accessibility | Gentle loading indicators; animated check states for completed steps; no jarring motion | Dense data without explanation; dark mode with pure black; small body text; red used decoratively |
 | **SaaS / B2B** | Formal–Casual range → Serious → Expert → Authoritative–Collaborative range | Neutral greys, controlled accent (brand blue/green), white space dominant | Clean sans-serif, systematic type scale; headings earn visual weight | Skeleton loading for data tables; progressive disclosure for settings; tooltips for technical fields | Over-explaining basics to expert users; inconsistent terminology across modules; AI-slop purple palette |
 | **E-commerce / DTC** | Casual → Playful–Serious range → Approachable → Collaborative | Brand-driven palette; high saturation for CTAs; warm neutrals for product context | Expressive display for headlines; clean body for product descriptions | Product zoom hover states; cart animation on add; wishlist micro-interaction | Fake urgency copy; cluttered hierarchy; hidden total cost until checkout; tiny CTA on mobile |
 | **Gaming / Entertainment** | Casual → Playful → Approachable–Expert range → Irreverent | High saturation, dark mode dominant, neon accent on dark surface | Display/gaming typefaces for headers; clean body for UI; weight contrast is high | Motion-heavy transitions; achievement celebrations; ambient background animation | Accessibility blindspots in dark mode; pure black backgrounds (vibration); low contrast on energetic backgrounds |
 | **Social / Community** | Casual → Playful → Approachable → Collaborative | Warm neutrals, brand accent, avatar-forward UI with minimal chrome | Friendly rounded sans-serif; generous spacing; conversational scale | Reaction microanimations; real-time presence indicators; celebratory confetti for milestones | Cold enterprise-grade color in social context; heavy typography hierarchy that buries user content |
 | **Dev Tools** | Casual–Formal range → Serious → Expert → Authoritative | Dark mode default; syntax-highlight palette; cool greys; code-emphasis contrast | Monospace for code; sans-serif for prose; no decorative type | Fast, no-flash loading states; inline error syntax highlighting; keyboard shortcut visibility | Explaining basics to experts; hiding power features; light-mode-only; inconsistent CLI↔UI vocabulary |
-| **EdTech** | Casual → Playful–Serious range → Approachable → Collaborative | Warm, bright, optimistic — not childish; academic versions use cooler tone | Friendly rounded sans; large body text; generous spacing for reading context | Progress animations; streak celebration; gentle nudges for return | Overwhelming choice on first launch; punitive error framing; tests without explanation of why wrong |
-| **Legal / Compliance** | Formal → Serious → Expert → Authoritative | Navy, charcoal, neutral greys — no decorative color | Readable serif or clean sans; no display type for primary content | None beyond loading states; no celebratory states — outcomes have real weight | Casual tone on contract actions; hiding consequences; playful UI that signals legal work is trivial |
+| **EdTech** | Casual → Playful–Serious range → Approachable → Collaborative | Warm, bright, optimistic - not childish; academic versions use cooler tone | Friendly rounded sans; large body text; generous spacing for reading context | Progress animations; streak celebration; gentle nudges for return | Overwhelming choice on first launch; punitive error framing; tests without explanation of why wrong |
+| **Legal / Compliance** | Formal → Serious → Expert → Authoritative | Navy, charcoal, neutral greys - no decorative color | Readable serif or clean sans; no display type for primary content | None beyond loading states; no celebratory states - outcomes have real weight | Casual tone on contract actions; hiding consequences; playful UI that signals legal work is trivial |
 | **HR / People Ops** | Formal–Casual range → Serious → Approachable → Collaborative | Warm professional: muted teal, earth tones, warm greys | Clean sans-serif; expressive enough to feel human, not cold | Subtle check animations for onboarding; gentle feedback on form completion | Clinical coldness in employee-facing UI; hiding personal data implications; confusing benefit summaries |
 | **Real Estate** | Formal → Serious → Approachable → Authoritative | Warm greys, earth tones, occasional brand accent; photography-dominant | Clean serif or premium sans; photography does the expressive work | Map interaction states; mortgage calculator animations; image gallery transitions | Overwhelming data without hierarchy; hiding total cost; small map interaction targets on mobile |
 | **Travel / Hospitality** | Casual → Playful–Serious range → Approachable → Collaborative | Destination-driven: warm ambers, ocean blues, lush greens | Expressive display for destination content; clean sans for booking flows | Immersive imagery transitions; booking confirmation celebration; ambient destination video | Hiding fees until final step; tiny date pickers; inconsistent voice between inspiration and transactional flows |
 | **Food / Delivery** | Casual → Playful → Approachable → Collaborative | Warm appetizing tones: terracotta, golden yellow, deep greens | Rounded, friendly sans-serif; photography-heavy | Order status animation; delivery tracking real-time; add-to-cart micro-interaction | Cold clinical tone; hiding delivery costs; overwhelming menu density; slow loading states for item images |
 | **Fitness / Wellness** | Casual → Serious–Playful range → Approachable → Collaborative | High energy (fitness): deep navy + neon; Wellness: warm cream, sage, earth | Strong weight contrast for motivational moments; clean body for routine content | Workout completion celebration; streak animation; activity ring fill | Shaming language for missed goals; pure black dark mode; excessive notifications; gamification without consent |
-| **Non-profit / NGO** | Casual–Formal range → Serious → Approachable → Collaborative | Mission-driven: warm humanist tones, photography-led, restrained accent | Readable, accessible, warm — never cold or corporate | Impact counter animations; donation confirmation warmth; progress-toward-goal bars | Guilt-manipulation copy; inaccessible donation flows; slow load on donation pages; hiding overhead costs |
-| **Government / Civic** | Formal → Serious → Approachable → Authoritative | Institutional: navy, red, white variants — national palette conventions | Highly readable sans-serif; no display type; large body text mandatory | Progress bars for multi-step processes; no celebration for government services | Jargon without explanation; inaccessible forms; mobile-hostile layouts; hiding deadlines |
-| **Luxury / Fashion** | Formal → Serious → Expert → Reverent | Black, white, gold, nude — restraint signals luxury | Editorial serif or geometric sans; generous whitespace; typography is the aesthetic | Elegant fade transitions; product reveal on scroll; no click-bait motion | Playful copy that undercuts premium positioning; cluttered layout; urgent sale language; AI-slop palette |
+| **Non-profit / NGO** | Casual–Formal range → Serious → Approachable → Collaborative | Mission-driven: warm humanist tones, photography-led, restrained accent | Readable, accessible, warm - never cold or corporate | Impact counter animations; donation confirmation warmth; progress-toward-goal bars | Guilt-manipulation copy; inaccessible donation flows; slow load on donation pages; hiding overhead costs |
+| **Government / Civic** | Formal → Serious → Approachable → Authoritative | Institutional: navy, red, white variants - national palette conventions | Highly readable sans-serif; no display type; large body text mandatory | Progress bars for multi-step processes; no celebration for government services | Jargon without explanation; inaccessible forms; mobile-hostile layouts; hiding deadlines |
+| **Luxury / Fashion** | Formal → Serious → Expert → Reverent | Black, white, gold, nude - restraint signals luxury | Editorial serif or geometric sans; generous whitespace; typography is the aesthetic | Elegant fade transitions; product reveal on scroll; no click-bait motion | Playful copy that undercuts premium positioning; cluttered layout; urgent sale language; AI-slop palette |
 | **Media / Publishing** | Casual–Formal range → Serious → Approachable–Expert range → Authoritative | Publication-specific; reading UX emphasizes contrast and typography | Reading-optimized: long-form line length (60–75ch), generous line-height (1.7+) | Scroll-progress indicators; reading time estimates; article-end engagement | Distraction ads interrupting reading flow; tiny body text; low contrast for long-form content |
 | **Analytics / BI** | Formal → Serious → Expert → Authoritative | Data-focused: high contrast, neutral chrome, vivid but accessible chart palette | Dense but readable sans-serif; monospace for data values; strong heading hierarchy | Interactive chart hover states; filter animation; export confirmation | Color-blind-unsafe chart palettes; pure decoration in data visualizations; hiding data provenance |
 | **AI / ML Platform** | Casual–Formal range → Serious → Expert → Authoritative–Collaborative range | Dark mode default with vibrant accent; cool-to-neutral chrome | Clean monospace for code and prompts; sans-serif for prose; strong weight contrast | Streaming text animation; generation loading state; token cost micro-display | Anthropomorphizing in ways that mislead; hiding capability limits; magical framing that hides user responsibility |

package/reference/capability-gap-stage-gate.md

@@ -3,7 +3,7 @@
 > Phase 29 reference doc. Specifies the deterministic gate that decides when
 > the reflector has gathered enough `capability_gap` signal to surface a
 > one-time opt-in prompt for Stage-1 (incubator authoring of new agents /
-> skills). **No code path in this repository auto-flips the stage** —
+> skills). **No code path in this repository auto-flips the stage** -
 > D-01 is the discipline.
 
 ---
@@ -23,7 +23,7 @@ date or a release. The reflector aggregates events into per-cycle
 clusters (`scripts/lib/reflector-capability-gap-aggregator.cjs`) and
 evaluates a deterministic stability function against the project's
 cycle history. When the gate is crossed, `/gdd:apply-reflections`
-emits a **one-time user-facing prompt** in the cycle markdown — never
+emits a **one-time user-facing prompt** in the cycle markdown - never
 an auto-stage-flip. The user opting in is a separate explicit action,
 out of scope for this gate spec.
 
@@ -72,7 +72,7 @@ A cluster `c` is **stable** iff both conditions hold:
 
 1. **Consecutive presence.** `c` appears in `≥ M` consecutive cycles
    somewhere within the observed history. (The most recent unbroken
-   run is what matters — if a cluster missed a cycle, the run resets
+   run is what matters - if a cluster missed a cycle, the run resets
    and only the longest streak counts.)
 2. **Narrow posterior.** The closed-form posterior standard deviation
    of the Beta distribution satisfies:
@@ -129,7 +129,7 @@ Inputs:
 
 The evaluation is **deterministic** (no randomness), **idempotent**
 (no side-effects in the evaluator), and **read-only** with respect to
-`.design/config.json` — that file is only updated by the user's
+`.design/config.json` - that file is only updated by the user's
 explicit opt-in action, never by the reflector.
 
 ---
@@ -140,11 +140,11 @@ When the gate crosses for the first time, `/gdd:apply-reflections`
 appends the following verbatim block to the cycle markdown:
 
 > ```markdown
-> ## Stage-0 → Stage-1 gate crossed — opt-in required
+> ## Stage-0 → Stage-1 gate crossed - opt-in required
 >
 > Capability-gap detection has accumulated enough signal across recent
 > cycles to consider enabling Stage-1 (incubator authoring of new
-> agents / skills). The gate is informational only — **nothing has
+> agents / skills). The gate is informational only - **nothing has
 > changed in the runtime**, and Stage-1 will NOT auto-enable. Per
 > Phase 29 CONTEXT.md decision D-01, the user opts in explicitly.
 >
@@ -174,8 +174,8 @@ appends the following verbatim block to the cycle markdown:
 > `capability_gap_gate.user_prompted_at` from `.design/config.json`.
 > ```
 
-The wiring side of this — actually writing the `user_prompted_at`
-timestamp and routing the opt-in confirmation — is deferred to
+The wiring side of this - actually writing the `user_prompted_at`
+timestamp and routing the opt-in confirmation - is deferred to
 **Plan 29-05** (`/gdd:apply-reflections` extension). This document
 specifies the prompt text and behavior; 29-05 implements the
 state-machine that consumes it.
@@ -204,7 +204,7 @@ Two timestamps in `.design/config.json` track the project's gate state:
 - **`opted_in_at`** is set when the user explicitly opts into Stage-1.
   Stage-1 incubator authoring (Plans 29-04+) becomes active once this
   timestamp is present. **Stage 1 is NEVER enabled by the reflector
-  setting this timestamp itself** — D-01 lock.
+  setting this timestamp itself** - D-01 lock.
 
 Once `opted_in_at` is set, the gate stops emitting prompts entirely
 (it's a one-shot mechanism, not a continuous nudge).
@@ -222,7 +222,7 @@ Operators can manually reset the gate by editing `.design/config.json`:
 | Tighten / loosen thresholds | Edit `K` / `M` / `stddev_threshold` directly. Out-of-range values silently fall back to defaults (§ 2). |
 
 Reset is **explicit** and **idempotent**. The reflector never writes
-to these fields on its own — the only writers are (a) the
+to these fields on its own - the only writers are (a) the
 `/gdd:apply-reflections` opt-in path (Plan 29-05) and (b) the human
 operator editing the file by hand.
 
@@ -233,32 +233,32 @@ operator editing the file by hand.
 Executable examples that exercise the gate live in
 `tests/reflector-capability-gap-aggregation.test.cjs`:
 
-- **T3** — 30 cycles × 3 always-present clusters → gate crosses with
+- **T3** - 30 cycles × 3 always-present clusters → gate crosses with
   default K=3 / M=10 / stddev_threshold=0.05.
-- **T3b** — 10 cycles × 1 always-present cluster → gate does NOT
+- **T3b** - 10 cycles × 1 always-present cluster → gate does NOT
   cross (posterior stddev ≈ 0.077 with α=11, β=1 is above the 0.05
   threshold; M=10 is the lower bound on observations, not a
   sufficient condition for stability).
-- **T4** — 30 cycles, 2 always-present clusters + 1 "noisy" cluster
+- **T4** - 30 cycles, 2 always-present clusters + 1 "noisy" cluster
   present in only the first 4 cycles → gate does NOT cross
   (`stable_cluster_ids.length === 2 < K=3`).
-- **T4b** — 5 cycles total → gate does NOT cross (`cycles_observed < M`).
-- **T7** — Confirms `K` and `stddev_threshold` overrides flow through
+- **T4b** - 5 cycles total → gate does NOT cross (`cycles_observed < M`).
+- **T7** - Confirms `K` and `stddev_threshold` overrides flow through
   `normalizeConfig` and reach the evaluation.
 
 These fixtures are synthetic and inline (D-11). The gate evaluator
-never reads `.design/gep/events.jsonl` directly in CI — fixtures
+never reads `.design/gep/events.jsonl` directly in CI - fixtures
 seed the cluster lists by hand.
 
 ---
 
 ## Decisions referenced
 
-- **D-01** — Two-stage approach: Stage 0 telemetry-only ships first;
+- **D-01** - Two-stage approach: Stage 0 telemetry-only ships first;
   Stage 1 authoring gated on data; user opts in per a one-time prompt;
   no auto-flip.
-- **D-03** — Default `K=3` / `M=10` / `stddev_threshold=0.05`,
+- **D-03** - Default `K=3` / `M=10` / `stddev_threshold=0.05`,
   overridable via `.design/config.json`.
-- **D-11** — Tests use synthetic fixtures (no live event chain reads).
-- **Phase 23.5** — Posterior `stddev(Beta(α, β))` closed form and
+- **D-11** - Tests use synthetic fixtures (no live event chain reads).
+- **Phase 23.5** - Posterior `stddev(Beta(α, β))` closed form and
   Laplace prior convention reused here.

package/reference/checklists.md

@@ -1,6 +1,6 @@
 # Pre-Delivery Checklists
 
-Run these before saying "done." Each checklist below is **gated** — if any item fails, you cannot ship.
+Run these before saying "done." Each checklist below is **gated** - if any item fails, you cannot ship.
 
 ## Master pre-ship checklist
 
@@ -60,7 +60,7 @@ Use this before any design artifact goes to the user or into a PR.
 - [ ] Error messages: what happened + how to fix (not just what's wrong)
 - [ ] Empty state acknowledges state + explains value + one CTA
 - [ ] No "Oops!" / forced cheer in errors
-- [ ] No 3-adjective pile-up ("beautiful, seamless, intuitive")
+- [ ] No 3-adjective pile-up ("beautiful, smooth, intuitive")
 - [ ] Placeholders show format, not restated label
 
 ### Technical check (code artifacts)
@@ -78,7 +78,7 @@ Use this before any design artifact goes to the user or into a PR.
 
 ---
 
-## Quick checklist — Small changes
+## Quick checklist - Small changes
 
 When the change is a single-screen tweak, use this shortened list:
 
@@ -99,11 +99,11 @@ When the change is a single-screen tweak, use this shortened list:
 When adding tokens/components to the design system:
 
 - [ ] New tokens follow `[category].[variant].[property].[state]` naming
-- [ ] No primitive token used directly in a component — route through semantic
+- [ ] No primitive token used directly in a component - route through semantic
 - [ ] Component has full anatomy doc (slots + variants + states + behavior + platform notes + do/don't)
 - [ ] Figma spec frame exists OR explicit note that it doesn't
 - [ ] Component validated against: same-structure-variant rule, not-a-new-component rule
-- [ ] 30-min audit performed — no off-grid spacings, no duplicate color tokens
+- [ ] 30-min audit performed - no off-grid spacings, no duplicate color tokens
 
 ---
 
@@ -145,18 +145,18 @@ Use this checklist after the main design review for pixel-level craft verificati
 
 ### Typography micro
 - [ ] Headings use `text-wrap: balance`
-- [ ] Body/caption uses `text-wrap: pretty` (or no wrap setting — not `balance`)
+- [ ] Body/caption uses `text-wrap: pretty` (or no wrap setting - not `balance`)
 - [ ] Font smoothing applied at `:root` only, not per-element
 - [ ] Dynamic numbers (counters, prices, timers) use `font-variant-numeric: tabular-nums`
 
 ### Surfaces
 - [ ] Nested elements use concentric radius (`innerRadius = outerRadius − padding`)
 - [ ] No same-radius parent+child within padded container (see BAN-10 same-radius-nested)
-- [ ] Images have `outline: 1px solid rgba(0,0,0,0.08)` — no tinted outlines
+- [ ] Images have `outline: 1px solid rgba(0,0,0,0.08)` - no tinted outlines
 - [ ] Interactive elements <40px have `::after` hit-area extension to 40×40
 
 ### Motion
-- [ ] Press feedback uses `scale(0.96)` — not 0.95, not 0.97, not 0.98
+- [ ] Press feedback uses `scale(0.96)` - not 0.95, not 0.97, not 0.98
 - [ ] `AnimatePresence` on persistent UI has `initial={false}`
 - [ ] Icon cross-fade spring has `bounce: 0`
 - [ ] No `transition: all` anywhere (see BAN-12 transition-all)
@@ -165,30 +165,30 @@ Use this checklist after the main design review for pixel-level craft verificati
 
 ---
 
-## Rams Lens — 10 Design Questions
+## Rams Lens - 10 Design Questions
 
 Dieter Rams's 10 principles of good design (Vitsœ/Braun, 1970s–80s) applied as a self-audit lens. Each question maps to one principle.
 
-- [ ] **Innovative** — Does this design solve the problem in a way that was not possible or obvious before?
-- [ ] **Useful** — Does every element serve the primary function? Nothing decorative that doesn't earn its place?
-- [ ] **Aesthetic** — Is the visual appearance the minimum necessary for legibility and emotional resonance?
-- [ ] **Understandable** — Can the user figure out how to use this without reading documentation or a tooltip?
-- [ ] **Unobtrusive** — Does the design stay in the background and let the content or task take focus?
-- [ ] **Honest** — Does the design not imply capabilities, quality, or status that the product doesn't have?
-- [ ] **Long-lasting** — Is this design free of trend-dependent choices (gradients, micro-styles) that will age in 12 months?
-- [ ] **Thorough** — Have edge cases been considered and handled (empty states, error states, loading states, overflow text)?
-- [ ] **Environmentally friendly** — Is the performance footprint minimal? (image sizes, JS bundle, font weight)
-- [ ] **As little design as possible** — If you removed 20% of the design decisions, would the product be worse? If not, remove them.
+- [ ] **Innovative** - Does this design solve the problem in a way that was not possible or obvious before?
+- [ ] **Useful** - Does every element serve the primary function? Nothing decorative that doesn't earn its place?
+- [ ] **Aesthetic** - Is the visual appearance the minimum necessary for legibility and emotional resonance?
+- [ ] **Understandable** - Can the user figure out how to use this without reading documentation or a tooltip?
+- [ ] **Unobtrusive** - Does the design stay in the background and let the content or task take focus?
+- [ ] **Honest** - Does the design not imply capabilities, quality, or status that the product doesn't have?
+- [ ] **Long-lasting** - Is this design free of trend-dependent choices (gradients, micro-styles) that will age in 12 months?
+- [ ] **Thorough** - Have edge cases been considered and handled (empty states, error states, loading states, overflow text)?
+- [ ] **Environmentally friendly** - Is the performance footprint minimal? (image sizes, JS bundle, font weight)
+- [ ] **As little design as possible** - If you removed 20% of the design decisions, would the product be worse? If not, remove them.
 
 ---
 
-## Sonner / Component-Authoring Lens — 6 Questions
+## Sonner / Component-Authoring Lens - 6 Questions
 
 Emil Kowalski's component-authoring principles applied as a per-component self-audit. Full reference: `reference/component-authoring.md`.
 
-- [ ] **P-01 API surface** — Does this component work correctly in 1 line with zero configuration?
-- [ ] **P-02 Composability** — Does this component compose via slots/children, not via style-configuration props?
-- [ ] **P-03 Defaults** — Are the defaults so sensible that most consumers never need to pass any props?
-- [ ] **P-04 Animation** — Does every animation in this component communicate a state change? No decorative loops?
-- [ ] **P-05 Accessibility** — Does this component have a complete ARIA contract before any visual styling?
-- [ ] **P-06 Edge honesty** — Are known failure modes documented with `// KNOWN:` or `// EDGE:` comments?
+- [ ] **P-01 API surface** - Does this component work correctly in 1 line with zero configuration?
+- [ ] **P-02 Composability** - Does this component compose via slots/children, not via style-configuration props?
+- [ ] **P-03 Defaults** - Are the defaults so sensible that most consumers never need to pass any props?
+- [ ] **P-04 Animation** - Does every animation in this component communicate a state change? No decorative loops?
+- [ ] **P-05 Accessibility** - Does this component have a complete ARIA contract before any visual styling?
+- [ ] **P-06 Edge honesty** - Are known failure modes documented with `// KNOWN:` or `// EDGE:` comments?

package/reference/cli-localization.md

@@ -1,20 +1,20 @@
-# CLI Localization — GDD's Own Surface
+# CLI Localization - GDD's Own Surface
 
 Phase 40.5 contract. `reference/i18n.md` covers internationalizing *user designs*; this file covers
-**GDD's own CLI** — `--help`, the common error messages, and skill prompt headers. The goal is the
+**GDD's own CLI** - `--help`, the common error messages, and skill prompt headers. The goal is the
 lowest-effort, highest-impact subset; full skill-body translation is deferred (per-locale demand).
 
 ## Resolution
 
 `scripts/lib/i18n/index.cjs` resolves the active locale with this precedence:
 
-1. **`.design/config.json#locale`** — an explicit per-project override (set via `/gdd:locale <code>`).
-2. **`process.env`** — `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE` (normalized: `ru_RU.UTF-8` → `ru`).
-3. **`en`** — the default.
+1. **`.design/config.json#locale`** - an explicit per-project override (set via `/gdd:locale <code>`).
+2. **`process.env`** - `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE` (normalized: `ru_RU.UTF-8` → `ru`).
+3. **`en`** - the default.
 
 A `C` / `POSIX` env locale resolves to `en`. The resolved code then drives a **fallback chain**
 `locale → base → en` (e.g. `de-DE → de → en`), so a regional locale degrades to its base and finally
-to English — the complete source table.
+to English - the complete source table.
 
 ## Message tables
 
@@ -23,9 +23,9 @@ simplicity). Each is `{ "_meta": { locale, coverage, fallback }, "<key>": "<stri
 namespaced: `help.*` (usage + section headers), `error.*` (the common CLI errors), `prompt.*` (skill
 prompt headers), `status.*`.
 
-- **`en.json`** — the **complete source of truth**; every key lives here.
-- **`ru.json`** — a complete second-locale translation (covers every `en` key).
-- **`uk.json` / `de.json` / `fr.json` / `zh.json` / `ja.json`** — **placeholders**: a `_meta` marker
+- **`en.json`** - the **complete source of truth**; every key lives here.
+- **`ru.json`** - a complete second-locale translation (covers every `en` key).
+- **`uk.json` / `de.json` / `fr.json` / `zh.json` / `ja.json`** - **placeholders**: a `_meta` marker
   (`coverage: "placeholder"`) plus a starter subset. Any missing key falls back to `en` per the chain.
 
 `translate(tables, key, locale)` walks the chain and returns the first hit, or the key itself if no
@@ -35,7 +35,7 @@ table has it (a missing key is always visible, never a crash).
 
 Skills and agents may carry an **opt-in** `description_i18n: { <locale>: "<description>" }` map.
 `descriptionFor(frontmatter, locale)` returns the localized description via the fallback chain, or the
-plain English `description` when the locale is absent. The field is fully backward-compatible — a
+plain English `description` when the locale is absent. The field is fully backward-compatible - a
 skill/agent without it is unaffected, and the Phase 28.5 contract only validates it (as an object of
 locale→string) when present.
 
@@ -43,12 +43,12 @@ locale→string) when present.
 
 The completeness gate is **warn-only**. Only `en` (source) and `ru` (full) are expected to be 100%; the
 five placeholder locales are intentionally partial and rely on the English fallback. A locale is never
-required to be complete to ship — partial is better than English-only, and fallback guarantees no key
+required to be complete to ship - partial is better than English-only, and fallback guarantees no key
 is ever missing at runtime.
 
 ## Adding or completing a locale (contribution path)
 
-1. Edit `scripts/lib/i18n/messages/<locale>.json` — add the keys you can translate (any `en` key is
+1. Edit `scripts/lib/i18n/messages/<locale>.json` - add the keys you can translate (any `en` key is
    fair game; you do not need 100%).
 2. Set `_meta.coverage` to `"complete"` once every `en` key is present, else leave `"placeholder"`.
 3. Add a translator-credit line to `NOTICE` under the attributions section (name/handle + locale).
@@ -56,6 +56,6 @@ is ever missing at runtime.
 
 ## Boundaries
 
-`--help` + common errors + skill prompt headers only — not full skill bodies (deferred per demand),
+`--help` + common errors + skill prompt headers only - not full skill bodies (deferred per demand),
 not RTL terminal rendering (a terminal concern), not voice/conversational localization. English is
 always the final fallback, so the CLI is never broken by a partial translation.

package/reference/codex-tools.md

@@ -3,7 +3,7 @@
 Last verified: 2026-04-24
 
 When a GDD skill references a Claude Code tool name, the Codex runtime
-translates to the equivalent below. Skills do NOT need to branch — the tool
+translates to the equivalent below. Skills do NOT need to branch - the tool
 name in prose is authoritative; Codex resolves via this map.
 
 ## Tool-name mapping
@@ -49,5 +49,5 @@ All 11 tools exposed by the server appear as `mcp__gdd_state__*` in Codex.
 
 ---
 
-Last verified: 2026-04-24 — tool surface re-checked against Codex CLI docs
+Last verified: 2026-04-24 - tool surface re-checked against Codex CLI docs
 current to this date. Revisit whenever Codex ships a tool-vocabulary change.