Design Audit React

React Web Design-to-Build Audit

Systematic visual QA workflow for comparing built React web applications against their original UI/UX design specifications.

Overview

Audit process:

1. Collect reference materials (design mockups + built app screenshots)
2. Create visual inventory (design vs. build side-by-side)
3. Audit by category (colors, typography, spacing, components, layout, states, responsive)
4. Classify findings by severity
5. Generate structured gap report

Step 1: Collect Materials

Required inputs:

• Design reference: Figma files, mockup images, or design system documentation
• Built app screenshots: Screenshots of the running React web app (multiple viewports)
• Design system spec (optional): Color tokens, type scale, spacing scale, component library spec

If user provides only one side (design only or build only), ask for the other.

Step 2: Create Visual Inventory

Use a split-screen approach:

1. List every page/screen shown in the design reference
2. For each design screen/page, locate the corresponding built page
3. Note any pages present in design but missing from build
4. Note any pages present in build but not in design (scope creep)

Inventory template (create a checklist):

Page Inventory:
- [ ] Page Name (Design) → Page/Route Name (Build) — Status: [Matched / Missing / Partial]
- Modals / dialogs / drawers:
- Navigation flows:
- Empty states / error states / loading states:

Step 3: Category Audit

Read references/react-audit-categories.md for the full checklist. Audit each category systematically.

Category Summary

| Category | What to Compare | Common Gaps | |----------|----------------|-------------| | Color | Hex/rgb/hsl values, CSS variables, theme tokens | Missing dark mode, wrong background colors, incorrect brand colors | | Typography | Font family, weights, sizes, line heights, letter spacing | System font instead of custom, wrong heading hierarchy, missing responsive type scale | | Spacing | Padding, margin, gap, grid gaps | Inconsistent spacing scale, missing responsive spacing, wrong container max-width | | Border & Radius | Border width, style, color, border-radius | Missing border on inputs, wrong card radius, sharp corners where rounded expected | | Shadow | Box-shadow values (x, y, blur, spread, color, opacity) | Missing shadow on cards, incorrect shadow depth, wrong shadow color | | Icons | Icon library (Lucide/FontAwesome/custom), sizes, stroke width | Wrong icon library, incorrect size, wrong variant (outlined vs filled) | | Components | Buttons, Cards, Inputs, Modals, Dropdowns, Tabs, Tables | Wrong button size/padding, missing outlined variant, incorrect input height, missing table row hover | | Layout | Flexbox/Grid alignment, responsive breakpoints, container widths | Misaligned items, wrong breakpoint behavior, missing container padding | | Responsive | Behavior at sm/md/lg/xl breakpoints | Missing mobile menu, horizontal scroll on mobile, content overflow | | Animations | Transitions, keyframes, hover effects, page transitions | Missing hover states, no loading skeleton, abrupt page changes | | Interaction States | Hover, focus, active, disabled, error, loading | Missing focus ring, no disabled opacity, missing form error styling |

For each category: compare pixel-to-pixel where possible. Note exact values from the design and the actual implemented values.

Step 4: React-Specific Checks

Read references/react-patterns.md for React/Tailwind/CSS-specific implementation audit patterns.

Key React-specific areas:

• Tailwind class audit: Are arbitrary values (w-[123px]) replacing design tokens? Are !important overrides scattered?
• CSS-in-JS / CSS Modules: Are styles co-located and scoped? Is there style duplication across components?
• Component props: Are design variations exposed as props (variant, size, color) or duplicated as separate components?
• Theme provider: Is a theme context/provider used consistently, or are colors hardcoded in components?
• CSS variables: Are design tokens exposed as CSS custom properties for runtime theming?
• Responsive hooks: Are useMediaQuery or similar hooks used correctly for responsive behavior?

Step 5: Severity Classification

Classify each finding:

| Severity | Definition | Example | |----------|-----------|---------| | P0 - Critical | Design system violation, user-facing broken layout | Wrong primary color, missing navigation, layout breaking at standard viewport | | P1 - Major | Noticeable visual deviation from design | Incorrect heading font, wrong card shadow, missing responsive behavior | | P2 - Minor | Small visual polish gap | Slightly off padding, missing hover transition, wrong border color | | P3 - Trivial | Pixel-perfect nitpick | 1-2px difference, subtle opacity mismatch | | Missing | Element exists in design but not in build at all | Missing page, missing component variant, missing state |

Step 6: Generate Report

Use the template in assets/audit-report-template.md. The report includes:

1. Executive Summary: Overall compliance percentage, critical issues count
2. Page Inventory: All pages mapped with match status
3. Findings by Category: Detailed per-category findings with severity
4. Missing Elements Checklist: Items present in design but absent from build
5. React-Specific Issues: Tailwind class issues, theme violations, component structure problems
6. Responsive Audit Results: Per-breakpoint findings
7. Recommendations: Prioritized fix list with component/file pointers where possible

Reference Files

• references/react-audit-categories.md — Full per-category audit checklist with web-specific inspection points
• references/react-patterns.md — Common React/Tailwind/CSS implementation patterns and anti-patterns to flag
• assets/audit-report-template.md — Report template for output formatting

Best Practices

• Audit pages at multiple viewport widths (mobile 375px, tablet 768px, desktop 1440px)
• Check both light and dark themes if both are specified in design
• Test actual rendered output (browser screenshots), not just code review
• Note when the build deviates from design for valid web platform reasons (e.g., scrollbar width, safe area insets)
• Prioritize P0 and Missing items over pixel-perfect P3 nits
• Cross-reference with the design system library (shadcn/ui, Material UI, etc.) being used
• Check browser dev tools computed styles when values are ambiguous

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RyanMakesAndBreaksStuff
• Source: RyanMakesAndBreaksStuff/Custom-Codex-Claude-Plugins-and-Skills
• License: MIT

Install and usage instructions live in the source repository linked above.