@hegemonart/get-design-done 1.14.8 → 1.16.0

package/reference/anti-patterns.md

@@ -334,3 +334,72 @@ grep -rn "bounce\|elastic" src/ --include="*.css"
 - [ ] Bounce or elastic easing anywhere?
 
 If YES to any → rewrite that element before proceeding.
+
+---
+
+### BAN-10: Same Border-Radius on Nested Surfaces
+
+Applying the same `border-radius` to a container and an element inside it (when the element is separated by padding) makes the inner element appear to "float" — the radii should be concentric, not equal.
+
+**Grep (Tailwind):**
+```
+(rounded-\w+)[^"]*"[^>]*>\s*<[^>]*\1
+```
+**Grep (CSS):** Look for identical `border-radius` values in parent and child selectors within the same component.
+
+**Fix:** Apply the concentric formula: `innerRadius = outerRadius − padding`. See `reference/surfaces.md`.
+
+Source: jakubkrehel/make-interfaces-feel-better (MIT)
+
+---
+
+### BAN-11: Tinted Image Outline
+
+Using a colored outline on images (e.g., `outline-slate-200`, `outline-gray-300`, or a hex-value outline color) competes visually with the image content and creates color contamination.
+
+**Grep (Tailwind):**
+```
+outline-(slate|zinc|neutral|gray|stone|blue|red|green|yellow|purple)-\d+
+```
+applied to `<img>` elements.
+
+**Grep (CSS):**
+```
+img\s*\{[^}]*outline:\s*[^}]*#[0-9a-fA-F]{3,8}
+```
+
+**Fix:** Use `outline: 1px solid rgba(0,0,0,0.08)` (light) or `outline: 1px solid rgba(255,255,255,0.08)` (dark). Pure black or white at low opacity only. See `reference/surfaces.md`.
+
+Source: jakubkrehel/make-interfaces-feel-better (MIT)
+
+---
+
+### BAN-12: `transition: all`
+
+`transition: all` animates every animatable CSS property on the element, including layout-triggering properties (width, height, padding, margin). This causes layout recalculation on EVERY transition, creating jank and unexpected visual effects (e.g., a hover transition that also animates the element's size if any dimensions change).
+
+**Grep (CSS):**
+```
+transition:\s*all
+transition-property:\s*all
+```
+**Grep (Tailwind):** bare `\btransition\b` class (without a modifier like `transition-transform` or `transition-[specific-property]`).
+
+**Fix:** Specify the exact properties to animate. For hover effects: `transition: background-color 150ms, color 150ms, opacity 150ms`. For motion: `transition: transform 200ms, opacity 200ms`.
+
+Source: jakubkrehel/make-interfaces-feel-better (MIT)
+
+---
+
+### BAN-13: `will-change: all`
+
+`will-change: all` promotes every animatable property to its own GPU compositor layer, consuming GPU memory for each property. On complex components this can allocate hundreds of MB of texture memory per instance, causing performance degradation and potential crashes on mobile.
+
+**Grep:**
+```
+will-change:\s*all
+```
+
+**Fix:** Restrict to specific compositing-safe properties: `will-change: transform`, `will-change: opacity`, `will-change: filter`, or `will-change: clip-path`. Remove entirely after animation completes. See `reference/motion.md` will-change section.
+
+Source: jakubkrehel/make-interfaces-feel-better (MIT)

package/reference/audit-scoring.md

@@ -124,7 +124,7 @@ Check for:
 - Content max-width enforced (prose: 65ch, layout: 1200–1440px)
 - Mobile breakpoint respected (no horizontal scroll)
 
-### 6. Anti-Pattern Compliance (Weight: 10%)
+### 6. Anti-Pattern Compliance (Weight: 5%)
 
 Score = 10 − (number of hard-ban violations × 3) − (number of AI-slop tells × 1), minimum 0.
 
@@ -155,8 +155,9 @@ Score = (Accessibility × 0.25)
       + (Typography × 0.15)
       + (Color × 0.15)
       + (Layout × 0.10)
-      + (Anti-Patterns × 0.10)
+      + (Anti-Patterns × 0.05)
       + (Motion × 0.05)
+      + (Micro-polish × 0.05)
 ```
 
 | Grade | Score | Meaning |
@@ -184,8 +185,9 @@ Baseline score: [N/100]
 | Typography | /10 | 15% | |
 | Color | /10 | 15% | |
 | Layout | /10 | 10% | |
-| Anti-Patterns | /10 | 10% | |
+| Anti-Patterns | /10 | 5% | |
 | Motion | /10 | 5% | |
+| Micro-polish | /10 | 5% | |
 | **Total** | | | **/100** |
 
 ### Findings
@@ -203,3 +205,32 @@ Baseline score: [N/100]
 | ... | | |
 | **Total** | /40 | **= NNG Score:** /100 |
 ```
+
+---
+
+<!-- BREAKING: Anti-Pattern Compliance pillar weight changed 10%→5% in v1.15.0; Micro-polish pillar added at 5%. Cross-cycle score comparisons should account for this change. -->
+
+### 8. Micro-polish (Weight: 5%)
+
+Text-wrap, font-smoothing, tabular-nums, concentric radius, image outlines, hit areas, canonical press scale, will-change discipline.
+
+| Score | Criteria |
+|---|---|
+| 10 | All 14 micro-polish checklist items pass |
+| 7–9 | 2–3 violations found |
+| 4–6 | 7 or more violations, core items failing (press scale, transition:all) |
+| 0–3 | Most items fail or not considered |
+
+Check for (see `reference/checklists.md` Micro-Polish Check gate):
+- Headings: `text-wrap: balance`; body/captions: `text-wrap: pretty`
+- Font smoothing at `:root` only
+- Dynamic numbers: `font-variant-numeric: tabular-nums`
+- Nested elements: concentric radius (`innerRadius = outerRadius − padding`)
+- Images: `outline: 1px solid rgba(0,0,0,0.08)` — no tinted outlines
+- Interactive elements <40px: `::after` hit-area extension to 40×40
+- Press feedback: `scale(0.96)` exactly
+- `AnimatePresence` on persistent UI: `initial={false}`
+- Icon cross-fade spring: `bounce: 0`
+- No `transition: all` (BAN-12)
+- No `will-change: all` (BAN-13)
+- `prefers-reduced-motion` respected

package/reference/brand-voice.md

@@ -0,0 +1,199 @@
+# Brand Voice
+
+<!-- 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.
+
+---
+
+## 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.
+
+### Axis 1: Formal ↔ Casual
+
+**Formal pole:** Language is structured, precise, and impersonal. Sentences are grammatically complete. Contractions are avoided. Passive voice is acceptable when it de-emphasizes agency. Examples: "Submit your application for review." / "Your session has expired. Please authenticate to continue."
+
+**Casual pole:** Language is conversational, friendly, and direct. Contractions appear naturally. Second-person is preferred. Colloquialisms are acceptable when they do not confuse. Examples: "Send it over." / "You're in! Let's get started."
+
+**When to move toward Formal:** Finance, legal, healthcare, government, and enterprise compliance products benefit from formal language because it signals seriousness, reduces ambiguity in high-stakes decisions, and matches the institutional register users expect. A banking app that says "Send it over" for a wire transfer erodes trust.
+
+**When to move toward Casual:** Social apps, consumer lifestyle products, gaming, fitness trackers, and food-delivery apps benefit from casual language because it reduces friction, makes the product feel approachable, and builds an emotional connection. A meditation app that speaks like a compliance manual creates the wrong affective atmosphere.
+
+**Copy examples:**
+- Formal: "Enter your eight-digit verification code to proceed."
+- Casual: "Type the 8-digit code we just sent you."
+
+---
+
+### Axis 2: Serious ↔ Playful
+
+**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? 🙏"
+
+**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.
+
+**When to move toward Playful:** Lifestyle apps, kids' platforms, fitness and wellness products, food apps, and consumer gaming should embrace playfulness because the use context is low-stakes, habitual, or recreational. Playfulness here reduces abandonment and increases retention by making interaction inherently enjoyable.
+
+**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?"
+
+---
+
+### Axis 3: Expert ↔ Approachable
+
+**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."
+
+**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.
+
+**When to move toward Approachable:** Consumer finance apps, health tracking for general audiences, first-time-user onboarding in any category, and civic technology should be maximally approachable because the audience includes users with wide variation in technical or domain literacy. Inaccessible language creates drop-off and confusion.
+
+**Copy examples:**
+- Expert: "Set `cache-control: no-store` on API responses to bypass the CDN edge layer."
+- Approachable: "Turn off caching here so your users always see the latest version."
+
+---
+
+### Axis 4: Reverent ↔ Irreverent
+
+**Reverent pole:** Language is deferential, careful, and tradition-respecting. It signals that the product understands gravity and heritage. Excess is avoided. Nothing is done with a wink. Example: "Crafted with care since 1897. Every detail considered."
+
+**Irreverent pole:** Language challenges conventions, uses unexpected angles, and does not take received wisdom at face value. It signals confidence and originality. It can be deliberately provocative. Example: "Most investment apps are built for banks. This one isn't."
+
+**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.
+
+**Copy examples:**
+- Reverent: "Each piece is hand-finished by our atelier in Lyon."
+- Irreverent: "Your bank charges you to hold your own money. We don't."
+
+---
+
+### Axis 5: Authoritative ↔ Collaborative
+
+**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."
+
+**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.
+
+**When to move toward Collaborative:** Creative tools, community platforms, collaborative document editors, and any product built around co-creation or exploration benefit from collaborative language because it respects user agency, signals trust, and aligns with the product's core value proposition of shared work.
+
+**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."
+
+---
+
+## Archetype Library
+
+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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+---
+
+### Design-Oriented Archetype Variants
+
+Beyond the 12 canonical archetypes, products can adopt a design-register variant that shapes visual and typographic expression independently of archetype:
+
+**Brutalist:** Raw, unpolished, deliberately anti-refined. Grid-breaking, heavy type, exposed structure. Signals authenticity and rejection of commercial smoothness.
+
+**Editorial:** Typography-forward, content-as-design. White space is generous; hierarchy is entirely typographic. Signals intelligence, taste, and editorial authority.
+
+**Technical:** Precision over elegance. Monospace type, dense data grids, minimal decoration. Signals accuracy, depth, and professional competence.
+
+**Romantic:** Warmth, craft, and human touch. Texture, handmade-feeling elements, warm typography. Signals care, artisanship, and emotional presence.
+
+**Utilitarian:** Efficiency over expression. Maximum information density, minimal visual ornament. Signals that function is the point and nothing is wasted.
+
+**Experimental:** Pushes form conventions deliberately. Unusual composition, unexpected animation, non-standard grid. Signals originality and a willingness to challenge assumption.
+
+---
+
+## 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.
+
+| 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.") |
+
+---
+
+## Industry Context
+
+<!-- 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.
+
+---
+
+| 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 |
+| **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 |
+| **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 |
+| **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/checklists.md

@@ -13,7 +13,7 @@ Use this before any design artifact goes to the user or into a PR.
 - [ ] Cited references in output so user can redirect
 
 ### Context check
-- [ ] `.impeccable.md` exists at project root
+- [ ] `DESIGN-CONTEXT.md` (or `DESIGN.md`) exists at project root with direction stated
 - [ ] `DESIGN.md` exists at project root
 - [ ] Design direction explicitly stated (brutalist / editorial / …)
 - [ ] User approved direction before Phase 3
@@ -66,7 +66,7 @@ Use this before any design artifact goes to the user or into a PR.
 ### Technical check (code artifacts)
 - [ ] Browser: running in preview; no console errors
 - [ ] Dev server responds with HTTP 200 on expected routes
-- [ ] Mobile viewport tested (or `impeccable-adapt` run)
+- [ ] Mobile viewport tested (320px, 375px, 390px, 428px breakpoints)
 - [ ] Tap delay removed (`touch-action: manipulation`)
 - [ ] Images use WebP/AVIF + `srcset` + lazy-loading where appropriate
 
@@ -83,7 +83,7 @@ Use this before any design artifact goes to the user or into a PR.
 When the change is a single-screen tweak, use this shortened list:
 
 - [ ] Pulled 1–2 references before touching code
-- [ ] Change respects `.impeccable.md` direction (didn't sneak in a different tone)
+- [ ] Change respects stated brand direction from `DESIGN-CONTEXT.md` (no tone drift)
 - [ ] Interactive element has all 8 states
 - [ ] No item on the absolute-ban list (anti-patterns.md)
 - [ ] Contrast AA
@@ -135,3 +135,30 @@ For flagship work:
 8. **Reduced motion test.** Enable it at OS level. Functional animations preserved, spatial ones killed?
 9. **Mobile test.** Real device or Chrome DevTools mobile emulation. Touch targets? Safe areas? Viewport zoom allowed?
 10. **The AI-slop self-check** (see anti-patterns.md). Honest answer: would someone believe this was AI-generated? If yes, which elements? Fix those.
+
+---
+
+## Micro-Polish Check
+Source: jakubkrehel/make-interfaces-feel-better (MIT)
+
+Use this checklist after the main design review for pixel-level craft verification:
+
+### Typography micro
+- [ ] Headings use `text-wrap: 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
+- [ ] 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
+- [ ] `AnimatePresence` on persistent UI has `initial={false}`
+- [ ] Icon cross-fade spring has `bounce: 0`
+- [ ] No `transition: all` anywhere (see BAN-12 transition-all)
+- [ ] No `will-change: all` anywhere (see BAN-13 will-change-all)
+- [ ] `prefers-reduced-motion` respected via `MotionConfig` or `useReducedMotion()`

package/reference/components/README.md

@@ -0,0 +1,90 @@
+# Component Benchmark Corpus
+
+Per-component design specifications harvested from 18 major design systems.
+Each spec is ≤350 lines, greppable, diff-friendly, and agent-consumable.
+
+**Spec shape**: `TEMPLATE.md` — Purpose · Anatomy · Variants · States · Sizing ·
+Typography · Keyboard/a11y · Motion · Do/Don't · Anti-patterns · Citations · Grep signatures
+
+**Harvest source list**: `connections/design-corpora.md` (18 systems)
+**Tooling**: `agents/component-benchmark-harvester.md` → `agents/component-benchmark-synthesizer.md`
+**CLI**: `/gdd:benchmark <component>` — see `skills/benchmark/SKILL.md`
+
+---
+
+## Wave 1 — Inputs (foundational)
+
+| Component | Spec | Purpose |
+|-----------|------|---------|
+| Button | [button.md](button.md) | Triggers actions; primary, secondary, ghost, destructive variants |
+| Input | [input.md](input.md) | Single-line text entry with label, error, helper text |
+| Select / Combobox | [select-combobox.md](select-combobox.md) | Choose one option from a list; keyboard-navigable dropdown |
+| Checkbox | [checkbox.md](checkbox.md) | Binary or indeterminate choice; groupable with fieldset |
+| Radio | [radio.md](radio.md) | Mutually exclusive choice within a group |
+| Switch | [switch.md](switch.md) | Binary toggle with immediate effect (vs. checkbox form submission) |
+| Link | [link.md](link.md) | Navigation anchor; inline or standalone; external-link pattern |
+| Label | [label.md](label.md) | Accessible association between caption and form control |
+
+---
+
+## Wave 2 — Containers
+
+| Component | Spec | Purpose |
+|-----------|------|---------|
+| Card | [card.md](card.md) | Contained content surface; clickable or static |
+| Modal / Dialog | [modal-dialog.md](modal-dialog.md) | Blocking overlay with focus trap and backdrop |
+| Drawer / Sheet | [drawer.md](drawer.md) | Side or bottom sliding panel |
+| Popover | [popover.md](popover.md) | Anchored overlay; dismisses on outside-click or Escape |
+| Tooltip | [tooltip.md](tooltip.md) | Hover/focus-triggered label; no interactive content |
+| Accordion | [accordion.md](accordion.md) | Collapsible content sections; single or multi-open |
+| Tabs | [tabs.md](tabs.md) | Horizontal/vertical tab navigation with keyboard support |
+
+---
+
+## Wave 3 — Feedback *(Phase 17)*
+
+| Component | Spec | Purpose |
+|-----------|------|---------|
+| Toast / Snackbar | — | Ephemeral status notification |
+| Alert / Banner | — | Persistent inline status message |
+| Progress | — | Linear and circular completion indicator |
+| Skeleton | — | Loading placeholder matching content shape |
+| Badge | — | Numeric or status indicator overlaid on another element |
+| Chip / Tag | — | Compact, dismissible label |
+
+---
+
+## Wave 4 — Navigation *(Phase 17)*
+
+| Component | Spec | Purpose |
+|-----------|------|---------|
+| Breadcrumb | — | Hierarchical location trail |
+| Pagination | — | Page-set navigation |
+| Stepper | — | Sequential multi-step progress indicator |
+| Navigation Menu | — | Top-level or sidebar navigation |
+| Command Menu | — | Keyboard-first search + action launcher |
+
+---
+
+## Wave 5 — Data & Advanced *(Phase 17)*
+
+| Component | Spec | Purpose |
+|-----------|------|---------|
+| Table / Data Grid | — | Tabular data with sorting, filtering, selection |
+| Date Picker | — | Calendar-based date/range selection |
+| File Upload | — | Drag-drop or browse file input |
+| Rich Text Editor | — | WYSIWYG content authoring |
+| Virtualized List | — | Windowed rendering for large datasets |
+
+---
+
+## Coverage Summary
+
+| Wave | Specs | Status |
+|------|-------|--------|
+| Wave 1 — Inputs | 8 | v1.16.0 |
+| Wave 2 — Containers | 7 | v1.16.0 |
+| Wave 3 — Feedback | 6 | Phase 17 |
+| Wave 4 — Navigation | 5 | Phase 17 |
+| Wave 5 — Data & Advanced | 5 | Phase 17 |
+| **Total** | **31** | — |