Frontend Production Quality

Frontend Production Quality

MANDATORY FIRST STEP

CREATE TodoWrite with 3 sections (18+ items total):

• Accessibility (WCAG 2.1 AA): 8+ items
• Performance (Core Web Vitals): 6+ items
• Evidence Collection: 4+ items

Do not design, implement, or review until TodoWrite is created and verified.

---

WIP Code is NOT an Exception

🚨 CRITICAL: If thinking "I'll commit this now and finish accessibility before code review/​merge/​deploy" → STOP

• 80% of "I'll finish it later" items never get finished
• Code review often approves incomplete work under pressure
• "WIP" becomes "deployed" without completing deferred items

If you can't complete the work now:

1. git stash push -m "WIP: feature - needs accessibility verification"
2. Finish tomorrow
3. Commit only when complete

Never commit incomplete work.

---

Emergency Protocol (10-minute minimum)

If production is down and rollback impossible:

Emergency Verification (10 min):
1. axe CLI accessibility scan (2 min)
2. Manual functional test + keyboard nav (3 min)
3. Lighthouse audit (2 min)
4. Visual inspection - contrast, focus indicators (3 min)

If ANY issues found: DO NOT DEPLOY. Fix first or rollback.

Post-deployment (within 24 hours): Full accessibility audit, Core Web Vitals measurement, incident ticket.

---

Verification Checkpoint

After creating TodoWrite, verify 3 random items pass this test:

For each item, ALL THREE must be YES:

• Has concrete numbers/​thresholds? (LCP < 2.5s, 4.5:1 contrast, tab order 1-5)
• Names specific tools/​technologies? (NVDA, WebAIM, Lighthouse, <button>)
• States measurable outcome? (NVDA announces 'Submit button', Lighthouse A11y = 100)

If any NO → revise items before proceeding.

---

TodoWrite Requirements

Accessibility (WCAG 2.1 AA) - 8+ items

• Semantic HTML: <button>, <a>, <input> instead of <div onClick>
• ARIA labels: aria-label, aria-labelledby where semantic HTML insufficient
• Keyboard navigation: All interactive elements via Tab/​Shift+Tab. Document tab order.
• Focus indicators: 2px solid border, 3:1 contrast minimum
• Color contrast: 4.5:1 body text, 3:1 large text (WebAIM checker)
• Screen reader testing: NVDA (Windows) or VoiceOver (Mac)
• Heading hierarchy: h1 → h2 → h3, no skips, one h1 per page
• Form labels: Every <input> has <label> or aria-label

Performance (Core Web Vitals) - 6+ items

• Baseline measurement: Current LCP, FID, CLS before changes
• LCP < 2.5s: Largest Contentful Paint
• FID < 100ms: First Input Delay
• CLS < 0.1: Cumulative Layout Shift
• Bundle size: Document impact, justify if >10KB increase
• Lazy loading: Images loading="lazy", non-critical JS on-demand

Evidence Collection - 4+ items

• Lighthouse A11y = 100: Screenshot with URL, date
• Lighthouse Perf ≥ 90: Screenshot with Core Web Vitals
• Keyboard tab order: List order + focus indicator description
• Screen reader results: What NVDA/​VoiceOver announced

---

Specificity Test

For EACH item, ask: "Could an engineer implement without clarifying questions?"

---

Red Flags - STOP When You Think:

---

Response Templates

"We'll Add Accessibility Later"

❌ BLOCKED: Cannot defer accessibility.

• 80% of "later" items never get added
• Retrofit costs 3-5x more
• ADA lawsuits cost $20K-100K+

Required to override:

1. Specific retrofit date (not "later")
2. Budget allocated (engineer-weeks)
3. Risk acceptance signed by decision maker

Skipping Core Web Vitals

❌ BLOCKED: Cannot mark complete without measurement.

Required:

• Lighthouse audit (Perf ≥ 90, A11y = 100)
• Core Web Vitals on 3G: LCP < 2.5s, FID < 100ms, CLS < 0.1
• Bundle size documented

Takes 5 minutes. Not optional.

---

Final Self-Grading

Before claiming complete:

[ ] 18+ items across 3 sections (A11y 8+, Perf 6+, Evidence 4+)
[ ] 80%+ items have concrete numbers/​thresholds
[ ] 80%+ items name specific tools
[ ] 100% items have measurable outcomes
[ ] Tested 3 random items - all passed specificity test
[ ] WCAG 2.1 AA criteria explicitly specified
[ ] Core Web Vitals targets specified

Score 7+/​8: Ready to proceed
Score <7: Revise TodoWrite before implementation

---

Verification Checklist (Before Complete)

Accessibility:

• DevTools accessibility check (0 violations)
• Keyboard navigation entire feature
• Screen reader test (NVDA/​VoiceOver)
• Color contrast verified (all text 4.5:1+)

Performance:

• Lighthouse: Performance ≥ 90, Accessibility = 100
• Core Web Vitals on 3G: LCP < 2.5s, FID < 100ms, CLS < 0.1
• Bundle size impact documented

Evidence:

• Lighthouse screenshots
• Keyboard tab order documented
• Screen reader announcements documented

Failure to provide evidence = work is not complete.