Visual Quality Gate

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.

Also load design-system/​primitives.md → ## Rendering Gotchas table (if present). These are anti-patterns that look correct in code but break in the target runtime (e.g., gradient text clipping descenders on iOS WKWebView).

Rendering Gotchas Check (before commit)

If design-system/​primitives.md has a ## Rendering Gotchas section:

1. Parse each row's Grep signature and Canonical safe form.
2. Grep changed UI files for each signature.
3. Any match without the canonical safe form → fix before marking UI done (do not rely on unit tests — these bugs are pixel-level).

Skip if the section is absent or empty.

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 AND primitives.md Rendering Gotchas BEFORE implementing any UI task
• speck-audit: Grep Rendering Gotchas signatures against changed UI files (step 10b)
• 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