Visual Quality Gate

Core principle: Functionally correct is NOT done. Aesthetically excellent is done.

Make deliberate, creative design choices that express the design system's personality instead of producing a generic or boilerplate UI.

Source of Truth

Before implementing any UI, load the project's design-system.md and extract:

1. •Design Philosophy — Core principle, emotional keywords, visual vibe, what-it-is-NOT
2. •Bold Choices (Non-Negotiable) — The 10-15 rules that DEFINE this product's personality
3. •What Success Looks Like — The feel test that determines if implementation is done

If design-system.md doesn't have these sections, flag it — the project needs a design system upgrade.

Universal Design Quality Principles

Apply these in EVERY UI implementation, adapted to the project's design system:

1. Typography as Hero

• •Typography is a primary design element, not just functional text
• •Create clear visual hierarchy: display → heading → subheading → body → caption
• •Use size, weight, letter-spacing, and line-height contrasts deliberately
• •Headlines should have PRESENCE — not just be bigger body text
• •Consider: tracking (letter-spacing), case transforms, font pairing tension

2. Deliberate Negative Space

• •Whitespace is an active design element, not emptiness
• •Generous padding creates perceived quality and luxury
• •Group related items tightly; separate unrelated items generously
• •Let content breathe — cramped layouts feel cheap
• •Use asymmetric spacing for visual interest where appropriate

3. Consistent Motion Philosophy

• •Every animation must follow the project's motion philosophy
• •"Minimal and instant" means NO gratuitous transitions
• •"Fluid and delightful" means purposeful easing and choreography
• •Never add random animations — motion must serve communication
• •Respect prefers-reduced-motion always

4. Texture and Depth

• •Flat, solid-color backgrounds feel generic and lifeless
• •Consider: subtle gradients, noise textures, background patterns, grain overlays
• •Use layered shadows (not a single box-shadow) for realistic depth
• •Borders can be replaced with shadow/contrast for more sophistication
• •Dark modes benefit especially from subtle texture to avoid "dead screen"

5. State-Specific Styling

• •Default state is just the starting point — hover, focus, active, disabled ALL need design
• •Hover states should feel intentional: scale, color shift, shadow lift, border change
• •Focus states must be visually distinct AND accessible (not just browser default)
• •Active/pressed states should provide tactile feedback (scale down, darken, etc.)
• •Loading states need skeleton screens or shimmer — never blank space
• •Error states should be designed, not just red text

6. Color with Purpose

• •Use color for hierarchy and drama, not just decoration
• •Consider color inversion patterns for emphasis (dark section amid light, or vice versa)
• •Accent colors should POP — used sparingly for maximum impact
• •Avoid "all one temperature" — use warm/cool contrast deliberately
• •Background color variations create natural section separation

7. Component Personality

• •Buttons should have CHARACTER: weight, presence, satisfying interaction
• •Cards should feel like real objects: weight, shadow, surface texture
• •Inputs should feel inviting: generous padding, clear focus states, smooth transitions
• •Empty states are design opportunities, not afterthoughts
• •Every component should feel like it belongs to THIS product, not any product

Self-Check Before Committing

Before considering any UI implementation complete, ask:

1. •Design Philosophy: Does this screen embody the core principle from design-system.md?
2. •Bold Choices: Are ALL non-negotiable design rules honored? (Check each one)
3. •Typography: Is there dramatic, intentional hierarchy — or is it flat/boring?
4. •Negative Space: Is whitespace active and deliberate — or cramped/random?
5. •Interaction States: Do hover/focus/active feel designed — or browser-default?
6. •Motion: Does animation match the motion philosophy — or is it random/missing?
7. •Texture: Does the UI have depth and surface quality — or is it flat/lifeless?
8. •Color Drama: Is there intentional visual emphasis — or uniform blandness?
9. •Component Character: Do buttons, cards, inputs feel designed — or generic?
10. •The Feel Test: Would this pass the "What Success Looks Like" description?

If ANY answer is "no" or "not sure" — iterate before marking done.

Common Anti-Patterns to Reject

• •❌ All text the same size/weight (no hierarchy)
• •❌ Default browser focus rings with no custom styling
• •❌ Solid flat backgrounds with no texture or depth
• •❌ Components that look like they came from a generic UI kit
• •❌ Padding/margin that's uniform everywhere (no rhythm)
• •❌ Animations added "because" rather than to communicate
• •❌ Color palette used but without emphasis/drama
• •❌ Hover states that are just opacity changes
• •❌ Empty states with just text and no design
• •❌ Forms that feel like spreadsheets instead of conversations

Integration with Speck Workflow

• •story-implement: Load design-system.md Bold Choices BEFORE implementing any UI task
• •story-validate: UI must pass the Aesthetic Quality Gate (BEAUTIFUL or ACCEPTABLE grade)
• •story-ui-spec: This is where design taste gets injected — never skip for UI stories
• •Design tokens: Use them, but tokens alone don't create beauty — personality does