# Design Audit React

> Audit a post-build React web application against its original UI/UX design to identify all missing items, visual gaps, and implementation inconsistencies. Use when a user has a built React web app (screenshots or running instance) that needs to be compared against design mockups, Figma files, wireframes, or design system specifications. Triggers on requests like: audit React app against design, c…

- **Type:** Skill
- **Install:** `agentstack add skill-ryanmakesandbreaksstuff-custom-codex-claude-plugins-and-skills-design-audit-react`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [RyanMakesAndBreaksStuff](https://agentstack.voostack.com/s/ryanmakesandbreaksstuff)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [RyanMakesAndBreaksStuff](https://github.com/RyanMakesAndBreaksStuff)
- **Source:** https://github.com/RyanMakesAndBreaksStuff/Custom-Codex-Claude-Plugins-and-Skills/tree/main/design-audit-react

## Install

```sh
agentstack add skill-ryanmakesandbreaksstuff-custom-codex-claude-plugins-and-skills-design-audit-react
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/RyanMakesAndBreaksStuff)
- **Source:** [RyanMakesAndBreaksStuff/Custom-Codex-Claude-Plugins-and-Skills](https://github.com/RyanMakesAndBreaksStuff/Custom-Codex-Claude-Plugins-and-Skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ryanmakesandbreaksstuff-custom-codex-claude-plugins-and-skills-design-audit-react
- Seller: https://agentstack.voostack.com/s/ryanmakesandbreaksstuff
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.