Design Review
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
- Discover the codebase structure — identify component directories, pages, layouts, stylesheets, and Tailwind config.
- Run each audit category below — search source files for the patterns described using grep, AST-level reasoning over file contents, and Tailwind config analysis.
- 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-4while siblings usep-[18px] - Inconsistent gap values in flex/grid layouts across similar containers
- Arbitrary values (
-[Npx]) that duplicate an existing Tailwind spacing step
Example — inconsistent spacing
// 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
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
// 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
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-whitewithoutdark:bg-*,text-gray-900withoutdark:text-* - Opacity applied to colors inconsistently (
/50vsopacity-50)
Example — hardcoded colors
// 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
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, othersh-10 px-6, otherspy-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
// 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
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-3withoutsm:grid-cols-1ormd:grid-cols-2 - Touch targets below 44x44px — buttons/links with
h-6,w-6,p-1or 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 responsivesizesattribute - Tables without horizontal scroll wrapper on mobile
Example — missing responsive breakpoints
// 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
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:, ordisabled:states - No loading indicator on buttons that trigger async operations — look for
onClickhandlers withawaitorfetchbut 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
// 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
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-xlon similar-level containers - Shadow system inconsistencies —
shadow-smon one card,shadow-mdon an identical sibling - Icon sizes that don't match adjacent text (
h-4 w-4icon next totext-lgtext) - Alignment issues — text not vertically centered with icons in buttons (
items-centermissing on flex containers) - Ring/outline styles that differ across similar interactive elements
- Inconsistent divider/separator styling
Example — border-radius inconsistency
// 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
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
onClickhandlers 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
// 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
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-300across similar interactions - Missing
motion-reduce:(orprefers-reduced-motionmedia query) on animations - Layout shift on page load — elements that jump as fonts/images/data load (missing
min-h-*, missingaspect-ratio, missing skeleton placeholders) - Janky animations —
transition-allon elements with many properties (use specific properties liketransition-colors,transition-transform) - CSS animations without
will-changeon expensive properties (transform, opacity)
Example — missing reduced-motion support
// 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
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-6on the same element,text-red-500 text-blue-500 - Arbitrary values that duplicate Tailwind defaults —
w-[16rem]instead ofw-64,p-[1rem]instead ofp-4 - Custom CSS that Tailwind could handle — separate
.cssfiles with simple spacing/color rules - Overly specific selectors —
.container > div.card:first-child > h2instead of utility classes !importantusage (in CSS or Tailwind!prefix) — almost always a sign of specificity issues- Unused or redundant
@applydirectives that re-implement existing utilities - Large inline
style={}objects that should be Tailwind classes
Example — conflicting classes
// 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
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:
### [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
Related
Accessibility Check
Make your app usable by everyone, including keyboard navigation, screen readers, and color contrast.
Brand Consistency
Extract your app's brand colors, typography, and visual identity from your homepage and apply them consistently everywhere.
Content & Documentation
Write clear documentation and content together with an AI co-author.