UI Design Quality

Design Taste

This skill enforces intentional, high-quality visual design decisions across frontend implementations. It provides concrete rules for typography, color, spacing, motion, and micro-interactions — preventing generic "AI slop" output and ensuring every visual choice is deliberate and refined.

When to Use

• Building new UI components that require visual design decisions (color, typography, spacing, animation)
• Implementing animations, transitions, or micro-interactions for any frontend component
• Creating or extending a design system, design tokens, or visual foundations
• Polishing existing UI for production — improving visual quality, consistency, and feel
• Reviewing UI code for design quality issues

When NOT to Use

• Pure backend, API, or infrastructure work — use the appropriate domain skill
• Pixel-perfect matching against an existing, complete design spec — use ui-verification instead
• Performance-only optimization with no visual changes — use performance-profiling

Design Parameters

Three tunable parameters allow calibrating the visual direction. Set at the start of a task or use defaults.

Design Parameters (defaults: VARIANCE=5, MOTION=6, DENSITY=4):
- DESIGN_VARIANCE (1–10): 1 = Strict symmetry, grid-locked → 10 = Asymmetric, editorial, experimental
- MOTION_INTENSITY (1–10): 1 = Static, minimal transitions → 10 = Rich physics, spring animations, gestures
- VISUAL_DENSITY (1–10): 1 = Airy, generous whitespace → 10 = Dense, data-rich, information-packed

How parameters affect decisions:

Delivery Workflow

Design taste progress:
- [ ] Step 1: Analyze project context (existing design system, tokens, typography, palette)
- [ ] Step 2: Calibrate design parameters (VARIANCE / MOTION / DENSITY) — use defaults or user-specified
- [ ] Step 3: Establish or extend design tokens (colors, typography scale, spacing, easing, shadows)
- [ ] Step 4: Implement components with intentional design decisions
- [ ] Step 5: Add motion and micro-interactions appropriate to MOTION_INTENSITY
- [ ] Step 6: Verify against Design Quality Checklist

Core Philosophy

1. Intentionality — Every pixel is a deliberate choice, not a framework default. If you cannot explain why a value is what it is, it needs to change.
2. Restraint — Remove before adding. Simplicity is sophistication. An element earns its place or gets cut.
3. Feel — An interface that works is not enough — it must feel right. The difference between good and great is in the micro-details.
4. Subtlety — The best animations are barely noticed consciously. They guide without demanding attention.
5. Consistency — Visual language must be uniform across the entire interface. One border-radius token, one shadow system, one spacing scale.
6. Conscious font choice — If you choose a common font like Inter or Roboto, document why it serves this project. Don't pick defaults because they're familiar — pick them because they're right.

Typography System

Type Scale

Use a modular scale to generate all font sizes. Never use arbitrary values.

Generate sizes: base × ratio^n where n ranges from -2 to +5.

Rules

Fluid Typography

Use clamp() for responsive font sizes instead of fixed pixels:

/* Heading — scales from 1.5rem to 2.5rem */
font-size: clamp(1.5rem, 1rem + 2vw, 2.5rem);

/* Body — scales from 1rem to 1.25rem */
font-size: clamp(1rem, 0.875rem + 0.5vw, 1.25rem);

Color Architecture

Palette Construction

Contrast Requirements

Never rely on color alone to convey information — always pair with icons, text, or patterns.

Token Implementation

:root {
  /* Semantic tokens — reference primitive scale */
  --color-primary: var(--blue-600);
  --color-surface: var(--gray-50);
  --color-text: var(--gray-900);
  --color-text-muted: var(--gray-500);
  --color-border: var(--gray-200);
  --color-error: var(--red-600);
  --color-success: var(--green-600);
}

All colors as CSS custom properties — never hardcode hex values inline in components.

Spacing & Layout

Grid System

8px base grid with 4px for fine adjustments. All spacing values must be multiples.

:root {
  --space-xs:  4px;   /* 0.5 × base */
  --space-sm:  8px;   /* 1 × base */
  --space-md:  16px;  /* 2 × base */
  --space-lg:  24px;  /* 3 × base */
  --space-xl:  32px;  /* 4 × base */
  --space-2xl: 48px;  /* 6 × base */
  --space-3xl: 64px;  /* 8 × base */
  --space-4xl: 96px;  /* 12 × base */
}

Layout Rules

Motion & Animation

Decision Framework: Should This Animate?

Every animation must serve one clear purpose:

• Spatial consistency — elements enter/exit from the same direction
• State indication — visual feedback for state changes
• Preventing jarring changes — smoothing appearance/disappearance
• Feedback — confirming user actions

Easing Curves

Never use: linear (except progress bars), default ease, or ease-in for UI entry.

:root {
  --ease-out:    cubic-bezier(0.22, 1, 0.36, 1);
  --ease-in:     cubic-bezier(0.55, 0, 1, 0.45);
  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
  --ease-hover:  cubic-bezier(0.25, 0.1, 0.25, 1);

  --duration-fast:   100ms;
  --duration-normal: 200ms;
  --duration-slow:   300ms;
  --duration-slower: 500ms;
}

Duration Rules

Performance

• Only animate transform and opacity — these are compositor-only, GPU-accelerated
• Never animate width, height, top, left, margin, padding — triggers layout recalculation
• Use will-change sparingly — set only during animation, remove after
• Animations must be interruptible — if user acts mid-animation, transition smoothly to new state
• Prefer CSS transitions over keyframes for interruptibility

Stagger Patterns

• 30–50ms between staggered children
• Never exceed 50ms per item — slow staggers feel sluggish
• Total stagger sequence should complete within 300ms
• Stagger direction should follow reading order (top-to-bottom, left-to-right in LTR)

Enter / Exit Patterns

• Enter: fade in + slight translate (8–16px from direction of origin)
• Never animate from scale(0) — start from scale(0.95) or scale(0.96) minimum
• Exit: same pattern reversed, ~25% faster duration
• Transform origin: matches trigger point (dropdown scales from button, tooltip from hover target)

Spring Animations (MOTION_INTENSITY ≥ 7)

Use springs for spatial movement, gestures, and drag interactions:

Keep mass at 1 in most cases. Never use bounce type unless building a playful/game-like UI.

Accessibility

• prefers-reduced-motion: reduce is mandatory — disable non-essential animations, replace with instant state changes or simple opacity fades
• prefers-reduced-transparency — reduce backdrop-filter: blur() intensity
• Test with motion preferences enabled in OS settings

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

Micro-Interactions & Component Craft

Buttons

Inputs

Cards

Modals / Dialogs

Tooltips

Dropdowns / Popovers

Tabs

Loading States

• Skeletons > Spinners > Text-only (preference order)
• Skeleton shape should match the content it replaces
• Pulse animation: opacity between 0.4 and 0.8, 1.5s infinite, ease-in-out
• Reserve space to prevent layout shift (use aspect-ratio for media)

Toasts

• Slide in from edge + fade
• Stack with translateY and scale reduction for depth illusion
• Auto-dismiss: 5000ms default, pause on hover
• Swipe to dismiss on touch devices

Dark Mode

@media (prefers-color-scheme: dark) {
  :root {
    --color-surface: hsl(220, 15%, 10%);
    --color-surface-raised: hsl(220, 15%, 14%);
    --color-surface-overlay: hsl(220, 15%, 18%);
    --color-text: hsl(220, 15%, 92%);
    --color-text-muted: hsl(220, 15%, 60%);
    --color-border: hsl(220, 15%, 20%);
  }
}

Responsive Strategy

Breakpoints

Rules

/* Fluid spacing example */
padding: clamp(var(--space-md), 3vw, var(--space-2xl));

Framework-Specific Notes

React / Next.js

Vue / Nuxt

Anti-Patterns to Avoid

Design Quality Checklist

Design Quality Gates:
- [ ] Typography uses a defined modular scale (not arbitrary sizes)
- [ ] Color palette uses semantic tokens (no inline hex values)
- [ ] Spacing follows 8px grid with spacing tokens
- [ ] Font choice is conscious and documented if using a common font
- [ ] Custom easing curves used (no default ease-in, linear, or ease)
- [ ] All state transitions have intentional animation with clear purpose
- [ ] Exit animations exist for every enter animation
- [ ] `prefers-reduced-motion` is respected and tested
- [ ] All interactive elements have hover + focus-visible states
- [ ] Touch targets ≥ 44px on mobile
- [ ] Dark mode is elevation-based (not just inverted colors)
- [ ] Responsive tested at 320px, 768px, 1024px, 1440px
- [ ] WCAG AA contrast ratios verified (4.5:1 text, 3:1 UI components)
- [ ] Loading, error, and empty states designed (not just happy path)
- [ ] No hardcoded colors, sizes, or spacing outside token system
- [ ] Animations run at 60fps (transform + opacity only)
- [ ] No anti-patterns from the registry present in output

Connected Skills

• frontend-implementation — design system tokens, performance optimization, semantic HTML
• accessibility — full WCAG 2.1 AA depth, keyboard navigation, ARIA patterns
• react — React component patterns, hooks, state management
• vue — Vue component patterns, Composition API, reactivity
• shadcn-tailwind — Shadcn/UI + Tailwind CSS component library patterns
• ui-verification — verifying implementation matches approved design specification