# Visual Quality

> Applies project visual personality and quality rules. Use while building or reviewing user-facing UI components.

- Skill: `telum-ai/visual-quality` (Agent Skill)
- Install (CLI): `npx skillmds@latest add telum-ai/visual-quality`
- Raw SKILL.md: https://api.skillmd.com/api/skills/telum-ai/visual-quality/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: telum-ai (https://skillmd.com/u/telum-ai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/telum-ai/visual-quality

---


# 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.

> **This skill is the TASTE axis's universal anchor.** The *Universal Design Quality Principles* below are Anchor B of the dual-anchored TASTE (connoisseur) readiness axis. The connoisseur-hostile pass (`/speck-larp` Job C) reads them here rather than re-authoring them; the product-relative Anchor A lives in `product-contract.md` §6b + `design-system.md`.

## 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 **TASTE axis** — the connoisseur-hostile pass (Job C in `/speck-larp`). This skill's *Universal Design Quality Principles* ARE that axis's **universal anchor (Anchor B)**; `product-contract.md` §6b Aesthetic Contract + `design-system.md` are the **product-relative anchor (Anchor A)**. A severe BAD or a named-rule violation caps the readiness state.
- **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