frontend-audit

Frontend Audit

Overview

Frontend code is the user's direct experience. Architecture problems here manifest as bugs users can see and feel. A broken backend returns an error; a broken frontend returns confusion, frustration, and churn.

Core principle: The UI is the product. If the frontend is broken, nothing else matters to users.

The Iron Law

NO COMPONENT WITHOUT CLEAR RESPONSIBILITY. NO USER INPUT WITHOUT VALIDATION. NO ASYNC OPERATION WITHOUT ALL THREE STATES (LOADING, ERROR, EMPTY).

When to Use

• Auditing frontend architecture
• Reviewing component design
• Investigating UI bugs or inconsistencies
• Before major frontend refactoring
• Performance-related UI complaints
• During any codebase audit
• After onboarding a new frontend framework

When NOT to Use

• Pure backend API projects with no frontend
• CLI tools (use architecture-audit instead)
• Static marketing sites with no interactivity (a quick review of HTML semantics suffices)
• If only a single isolated component needs review (use code-review instead)

Anti-Shortcut Rules

YOU CANNOT:
- Say "components look fine" — open each component file and check its line count, prop count, and responsibilities
- Say "state management is handled" — trace where each piece of state lives and why
- Say "design system is consistent" — grep for hardcoded values, check token adoption
- Judge accessibility by looking at code alone — test keyboard navigation manually
- Skip the bundle analysis — measure actual sizes, not guesses
- Trust component names — read the render method to understand true responsibility
- Say "similar to above" — each component gets its own row in the audit table

Common Rationalizations (Don't Accept These)

Rationalization	Reality
"It works, so it's fine"	Working ≠ maintainable. 600-line components work but are unmaintainable.
"We'll refactor later"	Later never comes. Component debt compounds faster than financial debt.
"Only one person works on the frontend"	That person will leave. Or get sick. Or forget how it works in 6 months.
"It's just a simple form"	Forms are the most complex UI pattern — validation, error states, accessibility, submission states.
"We don't need loading states yet"	Users experience blank screens as crashes. Loading states are not optional.
"Design tokens are overkill for this project"	Hardcoded values diverge within weeks. Tokens prevent visual entropy.
"Screen readers aren't our target audience"	15% of users have disabilities. It's also a legal requirement in many jurisdictions.