# Quality Checklist

Run through this checklist after generating or modifying a mockup. Three layers; run all that apply.

## Layer 1: Structural Check (Always Run)

### Semantic HTML
- [ ] Uses `nav`, `main`, `section`, `article`, `aside`, `footer` — not just `div`
- [ ] Single `h1` per page
- [ ] Heading hierarchy follows h1 → h2 → h3 without skipping levels
- [ ] Lists use `ul`/`ol`/`li`, not styled `div`s
- [ ] Interactive elements are `button` or `a`, not clickable `div`s

### Design Tokens
- [ ] CSS custom properties defined in `<style>` block
- [ ] Colors in HTML reference tokens (e.g., `var(--color-accent)`) not raw hex
- [ ] Spacing follows the defined scale, not arbitrary pixel values
- [ ] Font family matches DESIGN.md, not browser default or Inter/Roboto

### Responsive Design
- [ ] Mobile-first: base styles work at 375px
- [ ] Content readable without horizontal scroll at all breakpoints
- [ ] Navigation adapts: full nav on desktop, collapsed on mobile
- [ ] Images/media have max-width: 100%
- [ ] Touch targets minimum 44px on mobile

### Interaction States
- [ ] All buttons have hover, focus, active states
- [ ] All links have hover and focus states
- [ ] At least one loading state example (skeleton loader preferred)
- [ ] At least one empty state with illustration + CTA
- [ ] Disabled elements have visual indicator + explanation (title attribute)
- [ ] Form inputs have focus ring using accent color

### Component Quality
- [ ] Button hierarchy: one primary per visible area, secondary and ghost variants present
- [ ] Forms: labels above inputs, not placeholder-only
- [ ] Error states: inline message below field with icon
- [ ] No hamburger menu on desktop
- [ ] No modal inside modal
- [ ] No "Click here" links

### Code Quality
- [ ] Valid HTML (no unclosed tags, no duplicate IDs)
- [ ] Tailwind classes are valid (no made-up utilities)
- [ ] No inline styles that duplicate token values
- [ ] File is self-contained (single HTML file, no external dependencies except Tailwind CDN)
- [ ] Total file size under 50KB

## Layer 2: Visual Check (When Browser Tool Available)

Take a screenshot and examine:

### Spacing & Alignment
- [ ] Consistent margins between sections
- [ ] Elements within the same row are vertically aligned
- [ ] Padding within cards/containers is consistent
- [ ] No orphan text (single word on its own line in headings)
- [ ] Grid alignment: elements on the same row have matching heights or intentional variation

### Typography
- [ ] Heading sizes create clear hierarchy (visible difference between h1, h2, h3)
- [ ] Body text is comfortable reading size (not tiny)
- [ ] Font rendering looks correct (font loaded or appropriate fallback)
- [ ] Line length: body text 50-75 characters per line

### Color & Contrast
- [ ] Primary accent is visible but not overwhelming
- [ ] Text is readable over all backgrounds
- [ ] No elements blend into their backgrounds
- [ ] Status colors (success/error/warning) are distinguishable

### Overall Composition
- [ ] Visual weight is balanced (not all content on one side)
- [ ] Clear focal point on the page (hero, headline, or primary CTA)
- [ ] Appropriate whitespace: not cramped, not excessively empty
- [ ] Consistent visual language throughout the page

### Atmosphere Match
- [ ] Overall feel matches the DESIGN.md atmosphere description
- [ ] Not generic "AI generated" look
- [ ] Color palette is cohesive (no unexpected color outliers)
- [ ] Typography choice matches the intended mood

## Layer 3: Compliance Check (When MCP Tools Available)

### AccessLint MCP
- [ ] Run `audit_html` on the generated file
- [ ] Fix all violations with fixability "fixable" or "potentially_fixable"
- [ ] Document any remaining violations that require manual judgment
- [ ] Re-run `diff_html` to confirm fixes resolved violations

### RenderLens MCP
- [ ] Render at 1440px and 375px widths
- [ ] Lighthouse accessibility score ≥ 80
- [ ] Lighthouse performance score ≥ 70
- [ ] Lighthouse best practices score ≥ 80
- [ ] If iterating: run diff between previous and current version

## Severity Classification

When reporting issues found during the checklist:

| Severity | Criteria | Action |
|----------|----------|--------|
| **Critical** | Broken layout, invisible content, no mobile support | Fix immediately before showing to user |
| **High** | Missing interaction states, accessibility violations, token misuse | Fix before showing to user |
| **Medium** | Minor spacing inconsistency, non-ideal font weight, slight alignment issue | Note in assessment, fix if easy |
| **Low** | Style preference, minor polish opportunity | Note in assessment, fix during /design-polish |