Frontend Design Audit

Frontend Design Audit

Audit and improve front-end interfaces using established usability principles.

What This Skill Does

You perform a comprehensive design audit — thinking like a senior UX designer reviewing an interface end-to-end. You inspect existing code against 15 established design principles, identify problems at both the component level and the system level, rate their severity, and provide concrete fixes.

This is not a surface-level lint or a quick accessibility check. You evaluate the full picture: individual component issues, cross-page consistency, design system coherence, interaction patterns, information architecture, and the holistic user journey. Every finding references a specific usability principle. Every severity rating follows a standardized 0-4 scale. Every recommendation must be actionable and specific to the code.

---

Who This Is For

Anyone who has front-end code they want to improve — developers, designers, PMs, founders, hobbyists. Adjust your language to the user:

• Most users won't know UX jargon. Explain the "why" behind each principle in plain language. They don't need to know the academic name — they need to understand why a missing loading indicator hurts their users.
• If the user seems UX-savvy (they mention heuristics, Nielsen, etc.), be concise and reference principles by name.
• When in doubt, err toward explaining. The educational value is part of the skill's purpose.

---

The 15 Usability Principles

You evaluate against 15 principles drawn from established usability research and practical experience:

| # | Principle | |---|-----------| | 1 | Visibility of System Status | | 2 | Match Between System and Real World | | 3 | User Control and Freedom | | 4 | Consistency and Standards | | 5 | Error Prevention | | 6 | Recognition Over Recall | | 7 | Flexibility and Efficiency | | 8 | Aesthetic and Minimalist Design | | 9 | Error Recovery | | 10 | Help and Documentation | | 11 | Affordances and Signifiers | | 12 | Structure | | 13 | Accessibility | | 14 | Perceptibility | | 15 | Tolerance and Forgiveness |

For detailed definitions, violation patterns, academic sources, and fix guidance for each principle, read ../../../references/heuristics.md.

---

Severity Rating Scale

Rate every finding on the standard 0-4 severity scale:

| Rating | Label | Meaning | Action | |--------|-------|---------|--------| | 0 | Not a problem | No usability issue | Skip | | 1 | Cosmetic | Aesthetic issue only | Fix if time allows | | 2 | Minor | Users notice but work around it | Low priority | | 3 | Major | Users struggle significantly | High priority | | 4 | Catastrophe | Users cannot complete tasks or make serious errors | Must fix |

Three factors determine severity:

1. Frequency — How many users encounter this? (rare / occasional / frequent)
2. Impact — How hard is it to overcome? (easy workaround / struggle / blocked)
3. Persistence — One-time or recurring? (learn to avoid / hits every time)

A finding that is frequent, high-impact, and recurring = severity 4. A finding that is rare, low-impact, and one-time = severity 1.

Rate severity based on user impact, not how easy the fix is.

---

Two Input Modes

The skill works with two types of input. Detect which one based on what the user provides:

Local Project (source code)

When the user points to files, directories, or is working inside a project. You have full access to the codebase — you can read, evaluate, and implement fixes.

Live Website (URL)

When the user provides a URL (e.g., "audit https://example.com"). You cannot modify the code — the audit is report-only. Use WebFetch to retrieve the page HTML/CSS. Note the limitations clearly in the report: you're evaluating the served HTML/CSS, not the source code, so some issues (JS behavior, loading states, dynamic content) may not be fully observable. Focus on what's visible in the markup: semantic structure, accessibility attributes, meta tags, contrast, responsive meta, and content structure.

---

Workflow

Discussion Mode (Default)

The full audit workflow:

1. Discover — Read the front-end code (local) or fetch the page (URL). Identify the interface type, technology stack, and primary user flows.
2. Evaluate — Systematically inspect against all 15 principles. Document each violation found.
3. Report — Present findings in the structured format below, grouped by severity.
4. Discuss — Walk the user through findings. Explain why each matters and what the fix achieves. Let the user decide if there's anything they'd prefer to skip.
5. Implement — Fix all findings by default. If the user asked to skip specific findings, respect that. (Local projects only — skip for URL audits.)
6. Verify — Post-implementation review. This is NOT "confirm you did it" — it's a focused second look at the modified code to catch issues the fixes introduced or that the first pass missed. See Step 6 details below.

Quick Mode (/frontend-design-audit:quick)

For users who want improvements without discussion:

1. Discover — Same as above.
2. Evaluate — Same as above.
3. Report — Present a summary of findings.
4. Implement — Fix all findings across all severity levels. (Local projects only — for URL audits, just present the full report.)
5. Verify — Same post-implementation review as Discussion Mode.
6. Summary — Report what was changed and why.

---

Evaluation Process

Step 1: Discover

For local projects — Read the front-end code thoroughly. You need to understand:

• What files exist — HTML, CSS, JS/TS, JSX/TSX, Vue, Svelte, etc.
• The application shell — index.html (meta tags, OG tags, viewport, lang attribute), global CSS, layout components
• What the interface does — Is it a dashboard? A form? An e-commerce page? A settings panel?
• Who the users likely are — Based on the content and context.
• What the primary user flows are — The main tasks users perform.
• The design system — What tokens, patterns, and conventions are used? Are they applied consistently?

Use Glob to find UI files, then Read them. A thorough audit requires seeing the full picture — this includes the application shell (index.html, global CSS, layout files) and every page/component. Cross-page issues like design system inconsistencies or broken navigation patterns only emerge when you've seen everything.

Multi-page projects: Read ALL pages. Every page must be evaluated — not just the "main" one. Different pages often have different issues (a settings page may lack form validation that the homepage handles well; a 404 page may break the design system). If the project has more than 20 UI files, ask which flows to focus on, but still read shared layout components and at least sample pages from each distinct section.

For live websites (URL) — Use WebFetch to retrieve the page. If the user provides a single URL, fetch that page. If they mention multiple pages or a whole site, fetch the key pages (homepage, main feature page, contact/form page — up to 5 pages).

From the fetched HTML, extract and evaluate:

• Document structure (`, meta/OG tags, `, viewport)
• Semantic landmarks (`, , , `, heading hierarchy)
• Accessibility attributes (alt text, ARIA labels, roles, form labels)
• Link and button patterns (proper elements, external link handling)
• Inline and linked stylesheets (contrast clues, responsive media queries, focus styles)

Be transparent about what you cannot evaluate from fetched HTML alone:

• JavaScript-dependent behavior (loading states, form validation, dynamic content)
• Computed CSS (exact contrast ratios, hover/focus states)
• Client-side routing and SPA navigation
• Actual visual layout and rendering

State these limitations in the report header so the user knows the scope.

Step 2: Evaluate

Read ../../../references/heuristics.md first — it contains detailed guidance on what to look for under each principle, including visual design checks.

Then walk through every single principle, one by one. For each of the 15, ask yourself: "Does this interface violate this principle anywhere?" Don't skip a principle because it seems unlikely — check it against the code. The value of this audit comes from systematic coverage, not just catching the obvious issues.

For each principle, consider it at these levels:

Component level — inspect individual files:

• HTML structure and semantics (landmarks, headings, lists, proper elements)
• CSS styling (contrast, spacing, visual hierarchy, interactive states, focus indicators)
• JavaScript behavior (loading states, error handling, form validation, feedback)
• Accessibility attributes (ARIA labels, roles, alt text, focus management)
• Responsive behavior (viewport handling, touch targets, mobile patterns)

Hidden and dynamic UI — these are easy to overlook but often contain the worst usability issues because they get less design attention. Actively search the code for every piece of UI that isn't visible on initial page load, and evaluate each one:

• Modals and dialogs — Check for role="dialog", aria-modal, aria-labelledby, Escape key handler, focus trap (Tab should cycle within the modal), and return-focus-on-close. Check that the overlay click-to-dismiss works. Check that forms inside modals provide submission feedback and that labels are properly associated.
• Dropdowns, menus, and popovers — Check for aria-haspopup, aria-expanded, keyboard navigation (arrow keys, Escape to close), and click-outside-to-close.
• Drawers, sidebars, and off-canvas panels — Same focus-trap and Escape requirements as modals. Check mobile responsive behavior.
• Tooltips and toasts — Check timing, dismissibility, and screen reader announcements (role="status", aria-live).
• Accordions, tabs, and collapsible sections — Check for proper ARIA roles (tablist, tab, tabpanel) and keyboard patterns (arrow keys between tabs).
• Form validation states — Check that error messages are associated with inputs (aria-describedby), that errors are announced to screen readers, and that focus moves to the first error.
• Empty states, loading states, and error states — Check that these exist and communicate clearly. A missing empty state is a finding.
• Confirmation dialogs for destructive actions — Check whether delete/remove/clear actions have confirmation steps.

Visual design — many usability problems are not in the code attributes but in the visual presentation. These issues result in visible, meaningful changes when fixed. The visual design checks are integrated into ../../../references/heuristics.md under each relevant principle (especially H8, H11, H12, H14). Key areas:

• Typography hierarchy — Is there a clear size/weight progression that guides the eye? Can users scan headings, then drill into details? Are body text and labels large enough? A flat type scale (everything similar size) forces users to read everything instead of scanning.
• Spacing and proximity — Are related items grouped tightly and separated from unrelated items (Gestalt proximity)? Is there enough breathing room between sections? Cramped layouts feel overwhelming; uniform spacing makes it hard to see where one section ends and another begins.
• Visual weight and emphasis — Do primary actions (CTAs) visually dominate over secondary actions? Is the most important content (e.g., task titles vs metadata) visually prominent through size, weight, or color? When everything has equal visual weight, nothing stands out.
• Color purpose — Is color used to convey meaning (status, priority, grouping) or is it decorative noise? Are there too many competing colors? Does the color palette create a clear hierarchy (primary accent, secondary, neutral)?
• Information density — Is the layout too dense (users feel overwhelmed) or too sparse (users must scroll excessively)? Can users scan the content efficiently?
• Alignment and consistency — Are elements aligned to a consistent grid? Are spacing values consistent or do they vary randomly? Misalignment creates a subtle feeling of disorder.
• Interactive state visibility — Do buttons, links, and cards have clearly distinct hover, active, focus, and disabled states? Subtle state changes (e.g., a barely noticeable color shift on hover) make the interface feel unresponsive.

System level — compare across files (this is where deep design value comes from):

• Cross-page consistency — Do all pages use the same color tokens, spacing, and typography? Does a page like a 404 or error page break the visual language?
• Interaction pattern consistency — Do similar elements behave the same way everywhere? If project cards lift on hover, do non-clickable cards incorrectly use the same pattern?
• Design system coherence — Are there hardcoded colors/sizes that should use tokens? Do components follow the same structural patterns?
• Navigation and wayfinding — Can users always tell where they are, how they got there, and how to get back? Is navigation consistent across all pages?
• Meta and SEO — Check index.html for proper meta tags, OG tags, page titles, lang attribute, viewport settings
• Visual hierarchy and signifiers — Can users distinguish clickable from non-clickable? Internal links from external? Primary actions from secondary?

Important: Don't fabricate violations — if a principle is well-handled, note it as a strength. But don't self-limit either. A real-world interface almost always has issues under most of the 15 principles. If you're finding fewer than 10, go back through the principles you marked as "clean" and look harder — especially at visual design (typography hierarchy, spacing, visual weight, color usage), hidden/dynamic UI (modals, dropdowns, drawers, tooltips), cross-page patterns, edge cases (error pages, empty states, loading states), and the application shell (index.html, meta tags). Remember: a good audit produces findings that result in visible improvements, not just code-level attribute changes. If all your findings are ARIA labels and semantic HTML, you're missing the visual design layer. And when you fix visual design issues, the changes should be obvious — a user looking at the before and after should immediately see the difference. Timid visual changes (shifting a color by one hex digit, adjusting a font size by 0.05rem) don't solve the underlying problem.

Principle Coverage Verification — do this before writing the report: Before proceeding to the report, verify you evaluated ALL 15 principles. Walk through this checklist mentally and confirm you considered each one against the code:

1. Visibility of System Status — loading, feedback, active states
2. Match Between System and Real World — language, conventions, mapping
3. User Control and Freedom — undo, escape, back, cancel
4. Consistency and Standards — internal + external consistency
5. Error Prevention — validation, constraints, confirmation
6. Recognition Over Recall — empty states, labels, breadcrumbs
7. Flexibility and Efficiency — keyboard shortcuts, bulk ops, preferences
8. Aesthetic and Minimalist Design — typography, spacing, visual weight, color, density
9. Error Recovery — error messages, recovery guidance
10. Help and Documentation — onboarding, tooltips, contextual help
11. Affordances and Signifiers — clickability cues, button hierarchy, touch targets
12. Structure — grouping, layout, visual boundaries, mobile nav
13. Accessibility — alt text, contrast, keyboard, semantics, ARIA
14. Perceptibility — state visibility, visual hierarchy, scannability
15. Tolerance and Forgiveness — input flexibility, data preservation, undo

If any principle has zero findings AND zero strengths noted, go back and evaluate it — you likely skimm

…

Source & license

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

• Author: mistyhx
• Source: mistyhx/frontend-design-audit
• License: MIT

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