All skills
🎯

Design Review

Design

Comprehensive design audit for your app. Reviews visual consistency, spacing, typography, color usage, layouts across screen sizes, interactive elements, empty states, loading patterns, and overall usability. Helps catch the subtle design issues that make apps feel unpolished.

Skill prompt

Design Audit Skill

Perform a comprehensive design audit of a web application's source code. Analyze TSX, CSS, and Tailwind usage for visual consistency, polish, and UX quality. Produce a categorized report with a visual consistency score and file:line references for every finding.

Audit Procedure

  1. Discover the codebase structure — identify component directories, pages, layouts, stylesheets, and Tailwind config.
  2. Run each audit category below — search source files for the patterns described using grep, AST-level reasoning over file contents, and Tailwind config analysis.
  3. Score and report — assign a visual consistency score (0–100) and list categorized findings.

1. Spacing Consistency

Look for inconsistent padding, margin, and gap values across components.

What to flag
  • Magic numbers instead of Tailwind spacing scale or design tokens (e.g. padding: 13px, margin-top: 7px)
  • Mixed spacing systems — some components using p-4 while siblings use p-[18px]
  • Inconsistent gap values in flex/grid layouts across similar containers
  • Arbitrary values (-[Npx]) that duplicate an existing Tailwind spacing step
Example — inconsistent spacing
tsx
// BAD — magic numbers and mixed systems
// file: src/components/Card.tsx:12
<div className="p-[13px] mb-[7px]">

// file: src/components/ProfileCard.tsx:8
<div className="p-4 mb-2">

// GOOD — consistent Tailwind scale
<div className="p-4 mb-2">
Bash — find arbitrary spacing values
bash
grep -rnE '(p|m|gap|space)-\[[0-9]+px\]' --include='*.tsx' --include='*.jsx' src/

2. Typography Hierarchy

Audit font sizes, weights, line heights, and heading levels for a clear, consistent hierarchy.

What to flag
  • More than 6–8 distinct font sizes in the app (sign of an undefined type scale)
  • Inconsistent heading levels — <h2> used where <h3> belongs, or skipped heading levels
  • Missing truncate / line-clamp-* on text that can overflow (titles in cards, table cells, sidebar labels)
  • Inconsistent leading-* (line-height) across body text
  • Inconsistent tracking-* (letter-spacing)
  • Overuse of font-bold / font-semibold — more than two weights in a single component
Example — inconsistent type scale
tsx
// BAD — too many one-off sizes
// file: src/pages/Dashboard.tsx:24
<h2 className="text-[22px] font-bold">Dashboard</h2>

// file: src/pages/Settings.tsx:18
<h2 className="text-xl font-semibold">Settings</h2>

// file: src/pages/Profile.tsx:30
<h2 className="text-2xl font-bold tracking-wide">Profile</h2>

// GOOD — single consistent heading style
<h2 className="text-2xl font-semibold tracking-tight">Dashboard</h2>
Bash — inventory all font sizes
bash
grep -rohE 'text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl|\[[^\]]+\])' --include='*.tsx' --include='*.jsx' src/ | sort | uniq -c | sort -rn

3. Color System

Check that colors come from a centralized palette, not ad-hoc values.

What to flag
  • Hardcoded hex (#3b82f6), rgb (rgb(59,130,246)), or hsl values instead of CSS variables or Tailwind palette classes
  • Inconsistent semantic color usage — success/warning/error/info colors that vary across components
  • Text/background combinations that fail WCAG AA contrast (4.5:1 for normal text, 3:1 for large text)
  • Missing dark mode variants — bg-white without dark:bg-*, text-gray-900 without dark:text-*
  • Opacity applied to colors inconsistently (/50 vs opacity-50)
Example — hardcoded colors
tsx
// BAD — hardcoded hex
// file: src/components/Alert.tsx:15
<div className="bg-[#ef4444] text-white">

// GOOD — semantic Tailwind color
<div className="bg-destructive text-destructive-foreground">
Bash — find hardcoded colors
bash
grep -rnE '(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\()' --include='*.tsx' --include='*.jsx' --include='*.css' src/

4. Component Consistency

Identify similar UI patterns implemented differently across the codebase.

What to flag
  • Two or more card components with different padding, border-radius, or shadow
  • Button variants with inconsistent sizing (some h-9 px-4, others h-10 px-6, others py-2 px-3)
  • Form inputs with different border styles, focus rings, or placeholder colors across pages
  • Modal/dialog implementations that differ in overlay color, animation, or close button placement
  • Badge/tag components with inconsistent rounding, padding, or font sizes
Example — button inconsistency
tsx
// BAD — different button patterns
// file: src/pages/Settings.tsx:42
<button className="h-9 px-3 rounded-md bg-blue-600 text-white text-sm">Save</button>

// file: src/pages/Profile.tsx:55
<button className="py-2 px-4 rounded-lg bg-blue-500 text-white">Save</button>

// GOOD — shared Button component with variants
<Button variant="primary" size="sm">Save</Button>
Bash — find inline button styles
bash
grep -rnE '<button\s+className=' --include='*.tsx' --include='*.jsx' src/ | head -30

5. Responsive Design

Verify the UI works across breakpoints and touch devices.

What to flag
  • Containers with fixed widths that can cause horizontal scroll on mobile (e.g. w-[800px] without responsive override)
  • Missing responsive breakpoints on layout grids — grid-cols-3 without sm:grid-cols-1 or md:grid-cols-2
  • Touch targets below 44x44px — buttons/links with h-6, w-6, p-1 or similar that shrink below minimum
  • Text below 16px (text-xs, text-[10px]) used for primary content on mobile
  • Images without w-full, max-w-full, or responsive sizes attribute
  • Tables without horizontal scroll wrapper on mobile
Example — missing responsive breakpoints
tsx
// BAD — fixed grid, breaks on mobile
// file: src/components/FeatureGrid.tsx:10
<div className="grid grid-cols-3 gap-6">

// GOOD — responsive grid
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
Bash — find fixed-width containers
bash
grep -rnE 'w-\[[0-9]+(px|rem)\]' --include='*.tsx' --include='*.jsx' src/ | grep -v 'max-w'

6. Interaction States

Check that interactive elements have complete state coverage.

What to flag
  • Buttons/links missing hover:, focus:, focus-visible:, active:, or disabled: states
  • No loading indicator on buttons that trigger async operations — look for onClick handlers with await or fetch but no loading/spinner state
  • Form fields missing error state styling (aria-invalid, red border on validation failure)
  • Lists and tables with no empty state — look for .map() without a fallback when the array is empty
  • Missing skeleton/loading states for data-fetching components
Example — missing states
tsx
// BAD — no hover, focus, disabled, or loading
// file: src/components/SubmitButton.tsx:8
<button className="bg-blue-600 text-white rounded-md px-4 py-2"
  onClick={handleSubmit}>Submit</button>

// GOOD — complete interaction states
<button
  className="bg-blue-600 text-white rounded-md px-4 py-2
    hover:bg-blue-700 focus-visible:ring-2 focus-visible:ring-blue-500
    active:bg-blue-800 disabled:opacity-50 disabled:cursor-not-allowed"
  onClick={handleSubmit}
  disabled={isLoading}
>
  {isLoading ? <Spinner /> : "Submit"}
</button>
Bash — find buttons without hover states
bash
grep -rnE '<button\s+className="[^"]*"' --include='*.tsx' --include='*.jsx' src/ | grep -v 'hover:'

7. Visual Polish

Catch the subtle details that make a UI feel unfinished.

What to flag
  • Inconsistent border-radius — mixing rounded-md, rounded-lg, rounded-xl on similar-level containers
  • Shadow system inconsistencies — shadow-sm on one card, shadow-md on an identical sibling
  • Icon sizes that don't match adjacent text (h-4 w-4 icon next to text-lg text)
  • Alignment issues — text not vertically centered with icons in buttons (items-center missing on flex containers)
  • Ring/outline styles that differ across similar interactive elements
  • Inconsistent divider/separator styling
Example — border-radius inconsistency
tsx
// BAD — mixed radii on peer components
// file: src/components/StatsCard.tsx:5
<div className="rounded-lg shadow-md p-4">

// file: src/components/ActivityCard.tsx:5
<div className="rounded-xl shadow-sm p-6">

// GOOD — consistent card pattern
<div className="rounded-lg shadow-sm p-4">
Bash — inventory border-radius usage
bash
grep -rohE 'rounded(-[a-z]+)?' --include='*.tsx' --include='*.jsx' src/ | sort | uniq -c | sort -rn

8. UX Patterns

Review user experience patterns for completeness and consistency.

What to flag
  • Destructive actions (delete, remove, reset) without a confirmation dialog — look for onClick handlers calling delete APIs directly
  • No feedback after user actions — form submissions, settings saves, or toggle changes without toast/alert/notification
  • Unclear primary CTA — pages where multiple buttons compete for attention with similar styling
  • Inconsistent navigation — some pages use breadcrumbs, others don't; sidebar active states missing
  • Missing "back" or escape path on detail/edit pages
  • Long forms without progress indication or sectioning
Example — destructive action without confirmation
tsx
// BAD — instant delete, no confirmation
// file: src/components/UserRow.tsx:22
<button onClick={() => deleteUser(user.id)}>Delete</button>

// GOOD — confirmation before destructive action
<AlertDialog>
  <AlertDialogTrigger asChild>
    <button>Delete</button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogTitle>Are you sure?</AlertDialogTitle>
    <AlertDialogDescription>This will permanently delete this user.</AlertDialogDescription>
    <AlertDialogAction onClick={() => deleteUser(user.id)}>Confirm</AlertDialogAction>
    <AlertDialogCancel>Cancel</AlertDialogCancel>
  </AlertDialogContent>
</AlertDialog>
Bash — find delete/remove handlers without confirmation
bash
grep -rnE 'onClick=\{.*delete|onClick=\{.*remove' --include='*.tsx' --include='*.jsx' src/

9. Animation & Motion

Check for smooth, consistent, and accessible motion.

What to flag
  • Inconsistent transition durations — mixing duration-150, duration-200, duration-300 across similar interactions
  • Missing motion-reduce: (or prefers-reduced-motion media query) on animations
  • Layout shift on page load — elements that jump as fonts/images/data load (missing min-h-*, missing aspect-ratio, missing skeleton placeholders)
  • Janky animations — transition-all on elements with many properties (use specific properties like transition-colors, transition-transform)
  • CSS animations without will-change on expensive properties (transform, opacity)
Example — missing reduced-motion support
tsx
// BAD — no reduced-motion consideration
// file: src/components/FadeIn.tsx:6
<div className="animate-fadeIn duration-500">

// GOOD — respects user preference
<div className="animate-fadeIn duration-500 motion-reduce:animate-none">
Bash — find animations without reduced-motion
bash
grep -rnE 'animate-|transition-' --include='*.tsx' --include='*.jsx' src/ | grep -v 'motion-reduce'

10. Tailwind / CSS Audit

Audit the CSS and Tailwind usage for cleanliness and efficiency.

What to flag
  • Conflicting utility classes — p-4 p-6 on the same element, text-red-500 text-blue-500
  • Arbitrary values that duplicate Tailwind defaults — w-[16rem] instead of w-64, p-[1rem] instead of p-4
  • Custom CSS that Tailwind could handle — separate .css files with simple spacing/color rules
  • Overly specific selectors — .container > div.card:first-child > h2 instead of utility classes
  • !important usage (in CSS or Tailwind ! prefix) — almost always a sign of specificity issues
  • Unused or redundant @apply directives that re-implement existing utilities
  • Large inline style={} objects that should be Tailwind classes
Example — conflicting classes
tsx
// BAD — conflicting padding, redundant arbitrary value
// file: src/components/Header.tsx:9
<div className="p-4 p-6 w-[16rem] mt-[1rem]">

// GOOD — clean utilities
<div className="p-6 w-64 mt-4">
Bash — find potential conflicting classes
bash
grep -rnE 'className="[^"]*\bp-[0-9]+[^"]*\bp-[0-9]+' --include='*.tsx' --include='*.jsx' src/

Output Format

After completing all audit categories, produce a report in the following structure:

Visual Consistency Score: X / 100

Calculate based on:

  • Spacing (15 points) — consistent use of spacing scale
  • Typography (15 points) — clear hierarchy, limited type scale
  • Color (15 points) — centralized palette, semantic usage, contrast
  • Components (10 points) — shared patterns, no drift
  • Responsive (10 points) — breakpoints covered, touch-friendly
  • Interaction States (10 points) — hover/focus/disabled/loading/empty
  • Visual Polish (10 points) — consistent radii, shadows, alignment
  • UX Patterns (5 points) — confirmations, feedback, navigation
  • Animation (5 points) — consistent timing, reduced-motion support
  • Tailwind/CSS (5 points) — clean utilities, no conflicts
Report Structure

For each category, list findings as:

text
### [Category Name] — X / Y points

**Finding**: [Brief description]
**File**: `src/components/Example.tsx:42`
**Severity**: high | medium | low
**Suggestion**: [How to fix]

End with a Top 5 Quick Wins section — the five changes that would most improve visual consistency with the least effort.

When to Apply This Skill

Use this skill when:

  • The user asks for a "design audit", "design review", or "UI review"
  • The user wants to improve visual polish or consistency
  • The user reports their app "looks unfinished" or "inconsistent"
  • Before a design system migration or cleanup sprint
  • After rapid prototyping to identify cleanup needed before shipping