How to Audit Frontend Design Quality with AI

Mar 20, 2026

Problem

Design issues accumulate over time. Without systematic checking, problems compound until they become blockers. I’ve seen codebases where accessibility violations, performance bottlenecks, and inconsistent theming pile up quietly—then suddenly a compliance audit or user complaint forces a panicked fix session.

Traditional approaches don’t scale well. Manual code reviews miss things. Linters catch syntax but not design quality. Accessibility tools like axe-core are great but they’re just one piece of the puzzle.

I wanted a command that could scan my entire frontend and tell me exactly what’s wrong, how bad it is, and what to do about it.

The Solution

The /audit command runs diagnostic scans across 5 dimensions and generates a prioritized report with severity ratings. Each finding includes the location, impact, and a recommended fix command.

/audit

The output gives me:

Accessibility (A11y): Contrast ratios, ARIA issues, keyboard navigation gaps, semantic problems, missing alt text, form labeling
Performance: Layout thrashing, expensive animations, bundle bloat, unnecessary re-renders
Theming: Hard-coded colors, broken dark mode, inconsistent design tokens
Responsive: Fixed widths, undersized touch targets, horizontal scroll problems
Anti-patterns: Detection of common “AI slop” patterns against established design guidelines

Understanding Severity Levels

The audit uses a 4-tier severity system:

Level	Description
Critical	Blocks core functionality or violates WCAG A
High	Significant usability/accessibility impact, WCAG AA violations
Medium	Quality issues, WCAG AAA violations, performance concerns
Low	Minor inconsistencies, optimization opportunities

This matters because I can’t fix everything at once. Critical issues block me from shipping. High issues affect real users. Medium and low issues are technical debt I can schedule.

What the Output Looks Like

### Anti-Patterns Verdict
Pass/fail: Does this look AI-generated?

### Critical Issues
- [Location] Button contrast 2.3:1 (WCAG A violation)
- [Impact] Text unreadable for low-vision users
- [Fix] Use `/normalize` to apply design tokens

### High-Severity Issues
- Touch targets < 44x44px on mobile nav
- Missing focus indicators on interactive elements
- Layout shift on image load (CLS > 0.25)

### Medium-Severity Issues
- Inconsistent border-radius (3px vs 4px vs 6px)
- Hard-coded font-size on hero section
- Animation runs on main thread during scroll

The report doesn’t just tell me what’s wrong. It tells me which command to run next.

The Audit is Diagnostic, Not Prescriptive

One thing I got wrong at first: I expected /audit to fix things automatically. But that’s not its job.

The audit skill documentation makes this clear:

This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit.

The workflow I follow now:

Run /audit to discover issues
Review the severity ratings and impact descriptions
Use /normalize for design token and theming fixes
Use /optimize for performance issues
Use /harden for accessibility hardening
Re-run /audit to verify fixes

Real-World Example: Contrast Failures

I ran an audit on a dashboard component and got this:

### Critical Issue Found

[Location] `src/components/StatusBadge.tsx:23`
[Issue] Text contrast ratio 2.3:1 (required: 4.5:1)
[Impact] WCAG A violation - text unreadable for users with low vision
[Context] Light gray text (#999) on white background (#fff)

Recommended fix: `/normalize`

The issue was a hard-coded color. Running /normalize replaced it with a design token that had proper contrast. The re-audit passed.

Performance Audits: Beyond Lighthouse

Lighthouse scores are useful but they don’t catch implementation patterns that cause user-perceivable lag. The audit catches:

Layout thrashing: Sequential DOM reads and writes that force synchronous reflows
Expensive animations: CSS animations on properties that trigger paint or layout
Bundle issues: Large dependencies that could be code-split
Render patterns: Component re-renders on every parent update

### Medium-Severity Issue

[Location] `src/components/UserList.tsx:45-67`
[Issue] Layout thrashing in render loop
[Impact] Scroll jank on lists > 100 items
[Context] Reading offsetHeight inside map() without caching

Recommended fix: `/optimize --target performance`

Theming Audits: Catching Hard-Coded Values

Hard-coded colors are easy to introduce during prototyping and hard to catch in review. The audit finds them:

### Medium-Severity Issues

[Location] `src/pages/Landing.tsx:12`
[Issue] Hard-coded color #3b82f6 (should use token)
[Impact] Inconsistent appearance in dark mode

[Location] `src/components/Button.tsx:8`
[Issue] Hard-coded font-size 14px (should use token)
[Impact] Breaks user's font-size preferences

Recommended fix: `/normalize`

The /normalize command replaces hard-coded values with design tokens from my theme configuration.

Responsive Audits: Touch and Scroll Issues

Mobile problems often hide during desktop development. The audit catches:

Touch targets smaller than 44x44px
Fixed widths that cause horizontal scroll
Content that overflows viewport

### High-Severity Issue

[Location] `src/components/DataTable.tsx`
[Issue] Fixed width 1200px causes horizontal scroll
[Impact] Poor mobile experience, users must zoom and pan
[Context] Table doesn't adapt below 1200px viewport

Recommended fix: Manual review for responsive refactor

Not every issue has an automated fix. Some require judgment. The audit tells me when I need to think rather than just run a command.

Anti-Pattern Detection

The audit checks against established design guidelines—specifically the “DON’T” patterns. This catches AI-generated code that looks functional but violates design principles.

Common anti-patterns detected:

Multiple similar components that should be unified
Inconsistent spacing scales
Copy-pasted styles without token usage
Over-engineered solutions for simple problems

When to Run Audits

I run audits at three points:

Before PR: Catch issues before they reach the main branch
After refactors: Verify I didn’t introduce regressions
Periodically: Technical debt accumulates even in well-maintained codebases

The audit takes seconds to run but saves hours of debugging and rework.

Limitations

The audit is thorough but not exhaustive. It catches common patterns but can’t replace:

Manual user testing
Real device testing
Screen reader testing with actual assistive tech
Performance profiling with real user conditions

I treat audit as a first line of defense, not a complete safety net.

Key Takeaways

/audit is a diagnostic tool, not an auto-fixer—it identifies problems and recommends next steps
Severity ratings help prioritize: fix Critical and High before shipping, schedule Medium and Low
Each finding includes location, impact, and a recommended command to fix it
Run audits before PRs, after refactors, and periodically to catch accumulating issues
The audit catches patterns automated tools miss, but manual testing is still necessary for complete coverage

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 WCAG 2.1 Guidelines
👨‍💻 Web Vitals
👨‍💻 ARIA Authoring Practices

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!