UX Audit Process

Production-tested audit methodology from the ActiveWizards Astro site. Two complete audit rounds, 147 pages, zero design regressions in production.

1. Audit Cycle

Build -> Deploy Staging -> Audit Round N -> Fix -> Redeploy -> Re-Audit -> Approve
                                ^                                  |
                                |                                  |
                                +---- repeat until PRODUCTION_READY

Round Types

Never ship after Round 1 alone. The structural round catches obvious breaks, but design system violations only surface in a dedicated visual audit.

2. Reviewer Handoff Format

When handing staging to a reviewer, provide:

## Staging Review Request

URL: https://staging.aw-site.pages.dev
Branch: feature/astro-migration
Pages to audit: 147 (115 blog, 12 cases, 5 services, index pages)
Design spec: docs/DESIGN_SYSTEM.md (Visual Doctrine section)

### Page types to check:
1. Homepage (/)
2. Blog index (/blog)
3. Blog post (/blog/sample-post) -- pick 5 random posts
4. Case study index (/case-studies)
5. Case study detail (/case-studies/sample-case)
6. Service index (/services)
7. Service detail (/services/ai-agents)
8. Contact (/contact-us)
9. 404 page (/nonexistent)

### Known issues:
- [ ] Blog diagrams pending dark theme regeneration (57 SVGs)
- [ ] Footer external links may 404 (expected, not our domain)

3. Audit Report Format

Each finding is a structured record:

### [Page Name] — v[version]

Status: NEEDS_WORK | APPROVED | PRODUCTION_READY

| # | Finding | Severity | Status |
|---|---------|----------|--------|
| 1 | Hero image missing loading="eager" | Tactile Error | FIXED |
| 2 | Accent color on body links exceeds budget | Doctrine Violation | FIXED |
| 3 | Tag pills should use font-mono | Doctrine Violation | FIXED |
| 4 | Add reading time to blog cards | High-Signal Win | DEFERRED |

Example Finding Detail

#### Finding #2: Link color leak on blog prose

Page: /blog/* (all posts)
Severity: Doctrine Violation
Root cause: Global a { color: var(--color-accent) } applies inside prose blocks,
making every link teal. Accent budget allows max 3 teal elements per viewport.
Fix: Scope accent links to navigation and CTAs only. Prose links use
--color-text-secondary with underline, teal on hover.
Regression risk: HIGH -- affects all 115 blog posts.

4. Severity Levels

Doctrine Violation (P0)

The design system spec is violated. These are non-negotiable and block production.

Examples:

• Accent color (#00D4AA) used on more than 3 elements per viewport
• Box shadows present (banned in Cyber-Brutalist doctrine)
• Rounded corners on cards (must be sharp: border-radius: 0)
• Wrong font family (serif where Geist Sans is required)
• "Solutions" or "Services" used instead of prescribed terminology

Information Architecture (P1)

Content hierarchy, navigation, or page structure issues. Block production if they affect findability.

Examples:

• Breadcrumbs missing on detail pages
• Heading hierarchy broken (H1 -> H3, skipping H2)
• Navigation links point to wrong pages
• Related posts section shows irrelevant content
• Case study metrics display in wrong order

Tactile Error (P2)

Visual or interaction issues that degrade the experience but do not violate the design system.

Examples:

• Hover state missing on interactive element
• Image not lazy-loaded (performance, not correctness)
• Code block overflows horizontally without scroll
• Mobile menu does not close on link click
• Table scrolls but no visual indicator of overflow

High-Signal Win (P3)

Improvements that would meaningfully improve the experience but are not bugs. Can be deferred to post-launch.

Examples:

• Add estimated reading time to blog cards
• Add "copy" button to code blocks
• Add "back to top" button on long posts
• Testimonial photos could be grayscale for consistency
• Terminal-style animation on hero metrics

5. False Positive Identification

Not every finding is valid. Push back on:

Intentional Design Decisions

If the design spec explicitly calls for a pattern, it is not a bug even if the reviewer dislikes it.

Example: "The footer has too much whitespace" -- check the spec. If the spec says py-20, it is correct.

Browser-Specific Rendering

Test on Chrome, Firefox, and Safari before accepting a rendering finding. Some CSS (like backdrop-filter) renders differently across browsers.

Content Issues vs Design Issues

"This blog post has a bad title" is an editorial issue, not a UX finding. Keep the audit focused on the design system and interaction patterns.

Performance Findings in Audit Context

"The page loads slowly" is not a UX audit finding -- it belongs in the Performance playbook. Unless the slow load causes visible layout shift, defer it.

6. Common Root Causes

One bug often masquerades as multiple findings across different pages. Identify the root cause before fixing individual symptoms.

Global CSS Leak

/* Before: global leak */
a { color: var(--color-accent); }

/* After: scoped to navigation and CTAs */
.nav-link, .cta-link, .footer-link {
  color: var(--color-accent);
}
.prose a {
  color: var(--color-text-secondary);
  text-decoration: underline;
}
.prose a:hover {
  color: var(--color-accent);
}

Template Inheritance Bug

Tailwind Class Order

Missing Design Token

# Find all hardcoded accent colors
grep -rn "#00D4AA" src/ --include="*.astro" --include="*.css"
# Should only appear in global.css @theme block

7. Page-by-Page Systematic Audit

Audit Order

Per-Page Checklist

For each page, verify:

• [ ] Correct