annotations/.cursor/skills/ui-design/references/quality-checklist.md

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 divs
• Interactive elements are button or a, not clickable divs

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