metabuilder/docs/PHASE5.4_ACCESSIBILITY_PERFORMANCE.md

Phase 5.4: Accessibility & Performance Optimization

Status: ✅ IMPLEMENTATION PHASE - MVP Launch Preparation Date: January 21, 2026 Focus: WCAG AA Compliance + Core Web Vitals Optimization

---

Executive Summary

Phase 5.4 focuses on achieving WCAG AA compliance for accessibility and optimizing Core Web Vitals for production readiness. This phase ensures MetaBuilder meets industry standards for inclusive design and performance, preparing the MVP for public launch.

Key Deliverables

1. Accessibility Audit (WCAG AA) - Comprehensive compliance verification
2. Performance Optimization - Code splitting, image optimization, bundle analysis
3. Core Web Vitals - LCP, FID, CLS measurements and optimization
4. Testing & Validation - E2E testing, cross-browser compatibility, responsive design
5. Documentation - Guidelines, baselines, and MVP launch checklist

---

1. Accessibility Audit (WCAG AA)

1.1 ARIA Labels & Semantic HTML

Status: IMPLEMENTATION REQUIRED

Target Components:

• All interactive elements (buttons, links, inputs, checkboxes, radios)
• Form labels and error messages
• Navigation landmarks
• Page regions (main, header, footer, aside)
• Page headings and hierarchy

Implementation Guidelines:

// ✅ CORRECT: Semantic HTML with ARIA labels
export function Button({ label, onClick, disabled = false }: Props) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      aria-label={label}
      aria-disabled={disabled}
      type="button"
    >
      {label}
    </button>
  )
}

// ✅ CORRECT: Form with labels and error states
export function TextField({ label, name, error, required = false }: Props) {
  const inputId = `input_${name}`
  return (
    <div>
      <label htmlFor={inputId} aria-required={required}>
        {label}
        {required && <span aria-label="required">*</span>}
      </label>
      <input
        id={inputId}
        name={name}
        aria-describedby={error ? `error_${name}` : undefined}
        aria-invalid={!!error}
      />
      {error && (
        <div id={`error_${name}`} role="alert">
          {error}
        </div>
      )}
    </div>
  )
}

Checklist:

• All buttons have aria-label or visible text
• All inputs have associated <label> elements
• Form errors use role="alert" and aria-describedby
• Page regions use semantic <main>, <header>, <footer>, <nav>, <aside>
• Headings use proper hierarchy (<h1> → <h2> → <h3>, no skipping levels)
• Images have meaningful alt text
• Links have descriptive text (not "click here")
• Icon-only buttons have aria-label or title attribute

1.2 Keyboard Navigation

Status: IMPLEMENTATION REQUIRED

Target Elements:

• All interactive components (buttons, links, inputs, tabs, dialogs, modals)
• Tab order follows visual flow (left-to-right, top-to-bottom)
• Focus trap in modals/dialogs
• Escape key closes modals

Implementation Guidelines:

// ✅ CORRECT: Keyboard-navigable component
export function Modal({ isOpen, onClose, children }: Props) {
  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === 'Escape') {
        onClose()
      }
    }

    if (isOpen) {
      document.addEventListener('keydown', handleKeyDown)
      // Set focus to modal content
      const modal = document.querySelector('[role="dialog"]')
      if (modal instanceof HTMLElement) {
        modal.focus()
      }
      return () => document.removeEventListener('keydown', handleKeyDown)
    }
  }, [isOpen, onClose])

  if (!isOpen) return null

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
      tabIndex={-1}
    >
      <h2 id="modal-title">{title}</h2>
      {children}
    </div>
  )
}

// ✅ CORRECT: Tab navigation with arrow keys
export function TabBar({ tabs, activeTab, onTabChange }: Props) {
  const tabRefs = useRef<(HTMLButtonElement | null)[]>([])

  const handleKeyDown = (e: KeyboardEvent, index: number) => {
    let nextIndex = index
    if (e.key === 'ArrowRight') {
      nextIndex = (index + 1) % tabs.length
    } else if (e.key === 'ArrowLeft') {
      nextIndex = (index - 1 + tabs.length) % tabs.length
    }
    if (nextIndex !== index) {
      tabRefs.current[nextIndex]?.focus()
      onTabChange(nextIndex)
    }
  }

  return (
    <div role="tablist">
      {tabs.map((tab, index) => (
        <button
          key={tab.id}
          ref={(el) => { tabRefs.current[index] = el }}
          role="tab"
          aria-selected={activeTab === index}
          aria-controls={`panel_${tab.id}`}
          tabIndex={activeTab === index ? 0 : -1}
          onKeyDown={(e) => handleKeyDown(e as unknown as KeyboardEvent, index)}
          onClick={() => onTabChange(index)}
        >
          {tab.label}
        </button>
      ))}
    </div>
  )
}

Checklist:

• Tab order follows visual flow (use tabIndex only when necessary)
• Focus visible on all interactive elements
• Modals trap focus (Tab cycles within modal, Escape closes)
• Dropdowns support arrow keys to navigate options
• Tab bars support arrow keys (left/right or up/down)
• No keyboard traps (user can always tab out)
• Skip links for navigation (optional but recommended)

1.3 Color Contrast Verification

Status: MEASUREMENT REQUIRED

WCAG AA Standards:

• Text/Images of text: 4.5:1 minimum contrast ratio
• Large text (18pt+ or 14pt+ bold): 3:1 minimum contrast ratio
• Graphical components: 3:1 minimum

Testing Tools:

• WebAIM Contrast Checker (https://webaim.org/resources/contrastchecker/)
• Lighthouse DevTools (Accessibility tab)
• axe DevTools browser extension
• Color Contrast Analyzer (standalone app)

Implementation Strategy:

// Utility function to calculate contrast ratio
export function getContrastRatio(foreground: string, background: string): number {
  const fgLum = getRelativeLuminance(parseColor(foreground))
  const bgLum = getRelativeLuminance(parseColor(background))
  const lighter = Math.max(fgLum, bgLum)
  const darker = Math.min(fgLum, bgLum)
  return (lighter + 0.05) / (darker + 0.05)
}

export function meetsWCAGAA(ratio: number): boolean {
  return ratio >= 4.5
}

export function meetsWCAGAALargeText(ratio: number): boolean {
  return ratio >= 3.0
}

Checklist:

• All body text: 4.5:1 contrast minimum
• All link text: 4.5:1 contrast minimum
• All button text: 4.5:1 contrast minimum
• Placeholder text (if non-disabled): 4.5:1 contrast minimum
• Icon text: 4.5:1 contrast minimum
• Graphical elements: 3:1 contrast minimum
• Disabled state still meets 3:1 (if perceivable)

1.4 Screen Reader Testing

Status: SETUP REQUIRED

Tools:

• macOS: VoiceOver (built-in)
• Windows: NVDA (free) or JAWS (paid)
• iOS: VoiceOver (built-in)
• Android: TalkBack (built-in)
• Browser: ARIA DevTools extension

Testing Protocol:

# 1. Enable screen reader on macOS
CMD + F5  # Toggle VoiceOver

# 2. Common keyboard shortcuts (VoiceOver)
VO + Arrow Right      # Next element
VO + Arrow Left       # Previous element
VO + Space            # Activate button/link
VO + U                # Open rotor (headings, links, etc.)
VO + Down             # Read web rotor

# 3. Test checklist
- [ ] All content is readable
- [ ] Form labels are announced
- [ ] Buttons are announced as interactive
- [ ] Images have alt text
- [ ] Page structure is clear (headings, landmarks)
- [ ] Links have descriptive text
- [ ] Error messages are announced
- [ ] Loading states are announced

Implementation Example:

// ✅ Proper ARIA for screen reader announcement
export function DataTable({ data, loading, error }: Props) {
  return (
    <div aria-live="polite" aria-busy={loading} role="region" aria-label="Data table">
      {loading && <p>Loading data...</p>}
      {error && <p role="alert">Error: {error}</p>}
      {data && (
        <table>
          <caption>Table of users with email and role</caption>
          <thead>
            <tr>
              <th scope="col">Name</th>
              <th scope="col">Email</th>
              <th scope="col">Role</th>
            </tr>
          </thead>
          <tbody>
            {data.map((row) => (
              <tr key={row.id}>
                <td>{row.name}</td>
                <td>{row.email}</td>
                <td>{row.role}</td>
              </tr>
            ))}
          </tbody>
        </table>
      )}
    </div>
  )
}

Checklist:

• Page title is meaningful and first announcement
• Page structure announced (main, navigation, sidebar)
• All form fields have labels
• Error messages announced with role="alert"
• Loading states announced with aria-busy or aria-live
• Buttons/links announced with purpose clear
• Tables have caption and proper scope attributes
• Images have meaningful alt text (or marked as decorative)

1.5 Focus Indicators

Status: IMPLEMENTATION REQUIRED

Requirements:

• Focus outline visible on all interactive elements
• Minimum 2px outline or clear visual indicator
• Sufficient color contrast from background
• Not removed with outline: none without replacement

Implementation:

/* ✅ CORRECT: Clear focus indicators */
button:focus,
a:focus,
input:focus,
textarea:focus,
select:focus {
  outline: 2px solid #0066cc; /* Clear blue outline */
  outline-offset: 2px;
}

/* ✅ For dark mode */
@media (prefers-color-scheme: dark) {
  button:focus,
  a:focus,
  input:focus,
  textarea:focus,
  select:focus {
    outline: 2px solid #99ccff; /* Lighter blue for dark backgrounds */
  }
}

/* ✅ CORRECT: Custom focus state with visible indicator */
.custom-button:focus-visible {
  box-shadow: 0 0 0 3px rgba(0, 102, 204, 0.5); /* Blue glow around button */
  border-color: #0066cc;
}

/* ❌ WRONG: Removing focus without replacement */
button:focus {
  outline: none; /* DON'T DO THIS */
}

Checklist:

• All interactive elements have visible focus state
• Focus outline is at least 2px
• Focus outline contrasts with background (4.5:1 minimum)
• Focus is not removed with outline: none without replacement
• Focus outline visible in high contrast mode
• Focus trap in modals (Tab cycles within modal)

1.6 Semantic HTML Structure

Status: VERIFICATION REQUIRED

Proper HTML Hierarchy:

// ✅ CORRECT: Semantic structure
export function Page() {
  return (
    <>
      {/* Page title (first heading on page) */}
      <h1>Page Title</h1>

      {/* Navigation */}
      <nav aria-label="Main navigation">
        <ul>
          <li><a href="/">Home</a></li>
          <li><a href="/about">About</a></li>
        </ul>
      </nav>

      {/* Main content */}
      <main>
        <section aria-labelledby="section1-title">
          <h2 id="section1-title">Section 1</h2>
          <p>Content here...</p>
        </section>

        <section aria-labelledby="section2-title">
          <h2 id="section2-title">Section 2</h2>
          <p>More content...</p>
        </section>
      </main>

      {/* Sidebar */}
      <aside aria-label="Related information">
        <h2>Related Links</h2>
        <ul>
          <li><a href="/related1">Related 1</a></li>
        </ul>
      </aside>

      {/* Footer */}
      <footer>
        <p>&copy; 2026 MetaBuilder. All rights reserved.</p>
      </footer>
    </>
  )
}

Checklist:

• Page starts with <h1> (not multiple <h1>s)
• Heading hierarchy never skips levels
• <main> landmark for primary content
• <nav> for navigation regions
• <header> for page header
• <footer> for page footer
• <aside> for supplementary content
• Use <form> for form groups
• Use <button> for buttons, not <div onclick>
• Use <a> for links, not <span onclick>

1.7 Form Labels & Error Messages

Status: IMPLEMENTATION REQUIRED

Form Validation Pattern:

export function LoginForm() {
  const [errors, setErrors] = useState<Record<string, string>>({})
  const [touched, setTouched] = useState<Record<string, boolean>>({})

  const handleBlur = (field: string) => {
    setTouched({ ...touched, [field]: true })
  }

  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)
    const username = formData.get('username') as string
    const password = formData.get('password') as string

    const newErrors: Record<string, string> = {}
    if (!username) newErrors.username = 'Username is required'
    if (!password) newErrors.password = 'Password is required'

    setErrors(newErrors)
    if (Object.keys(newErrors).length === 0) {
      // Submit form
    }
  }

  return (
    <form onSubmit={handleSubmit} noValidate>
      {/* Username field */}
      <div>
        <label htmlFor="username" className="required">
          Username
        </label>
        <input
          id="username"
          name="username"
          type="text"
          aria-describedby={touched.username && errors.username ? 'error-username' : undefined}
          aria-invalid={touched.username && !!errors.username}
          onBlur={() => handleBlur('username')}
        />
        {touched.username && errors.username && (
          <div id="error-username" role="alert" className="error-message">
            {errors.username}
          </div>
        )}
      </div>

      {/* Password field */}
      <div>
        <label htmlFor="password" className="required">
          Password
        </label>
        <input
          id="password"
          name="password"
          type="password"
          aria-describedby={touched.password && errors.password ? 'error-password' : undefined}
          aria-invalid={touched.password && !!errors.password}
          onBlur={() => handleBlur('password')}
        />
        {touched.password && errors.password && (
          <div id="error-password" role="alert" className="error-message">
            {errors.password}
          </div>
        )}
      </div>

      <button type="submit">Login</button>
    </form>
  )
}

Checklist:

• Every input has associated <label> with htmlFor
• Required fields marked with aria-required="true" and visual indicator
• Error messages use role="alert" for immediate announcement
• Errors linked to inputs with aria-describedby
• Invalid inputs marked with aria-invalid="true"
• Form validation happens on blur (not just submit)
• Success/validation messages announced with aria-live="polite"

---

2. Performance Optimization

2.1 Code Splitting Analysis

Status: BASELINE ESTABLISHED

Current Bundle Analysis:

Build Performance:
├── Build Time: 2.4-2.6 seconds
├── Static Bundle: ~1.0 MB
├── Routes Built: 17 total
├── TypeScript Errors: 0
└── Type Checking: Pass

Optimization Opportunities:

1. Route-based Code Splitting (Next.js Automatic)

   • Already implemented via dynamic imports
   • Each route loads only necessary code
   • Admin tools (database_manager, user_manager, package_manager) lazy-loaded

2. Component Code Splitting

   // ✅ Lazy-load heavy admin components
   import dynamic from 'next/dynamic'
   
   const DatabaseManager = dynamic(
     () => import('@/components/admin/DatabaseManager'),
     { loading: () => <LoadingSkeleton /> }
   )
   
   const UserManager = dynamic(
     () => import('@/components/admin/UserManager'),
     { loading: () => <LoadingSkeleton /> }
   )
   

3. Vendor Code Splitting

   • Material-UI (fakemui): ~150KB (necessary)
   • React Query: ~40KB (necessary for data fetching)
   • Prisma Client: ~300KB (server-side only)

Implementation Plan:

• Analyze bundle with next/bundle-analyzer
• Identify components with >50KB size
• Implement dynamic imports for heavy components
• Test route-specific bundle sizes
• Measure Core Web Vitals impact

2.2 Image Optimization

Status: PREPARATION

Current Status:

• No image assets detected in current codebase
• Using Material Design icons from fakemui

When Adding Images:

// ✅ CORRECT: Use Next.js Image component
import Image from 'next/image'

export function ProfileCard({ imageUrl, name }: Props) {
  return (
    <article>
      <Image
        src={imageUrl}
        alt={`${name}'s profile picture`}
        width={300}
        height={300}
        loading="lazy"
        quality={80}
        // WebP + JPEG fallback (automatic)
        // Responsive sizing (automatic)
        // Lazy loading (automatic)
      />
      <h3>{name}</h3>
    </article>
  )
}

// ✅ CORRECT: SVG icon optimization
export function IconButton({ icon: Icon, label }: Props) {
  return (
    <button aria-label={label} title={label}>
      <Icon aria-hidden="true" />
    </button>
  )
}

Checklist:

• Use Next.js <Image> component for all images
• Provide meaningful alt text
• Use loading="lazy" for below-the-fold images
• Set appropriate width and height
• Use WebP format where supported
• Responsive image sizing (multiple breakpoints)
• Icons as SVG (no raster images)
• Compress images: max 80% quality for JPEG, 8-bit PNG

2.3 Font Optimization

Status: CURRENT

Current Implementation:

• System fonts preferred (optimal performance)
• No web fonts loaded (excellent for Web Vitals)
• Font stack: system-ui, -apple-system, sans-serif

Future Web Font Usage (if needed):

/* ✅ CORRECT: Web font optimization */
@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-var.woff2') format('woff2-variations');
  font-weight: 100 900;
  font-display: swap; /* Use system font while loading */
}

/* Use font-display: swap for all web fonts */
body {
  font-family: 'Inter', system-ui, -apple-system, sans-serif;
  font-feature-settings: 'kern' 1;
  text-rendering: optimizeLegibility;
  -webkit-font-smoothing: antialiased;
}

Web Font Best Practices:

• Use font-display: swap to prevent layout shift
• Limit to 2 font weights (regular + bold)
• Use WOFF2 format (best compression)
• Self-host fonts (no third-party CDN delays)
• Use variable fonts for multiple weights
• Preload critical fonts: <link rel="preload" as="font">

2.4 Tree-Shaking Effectiveness

Status: VERIFICATION REQUIRED

Analysis Commands:

# Analyze bundle composition
npm run build -- --analyze

# Check for unused exports
npm run lint -- --inspect-unused-exports

# Verify tree-shaking is working
npm run build -- --verbose

Optimization Checklist:

• All imports use ES modules (not CommonJS)
• No wildcard imports (import * as)
• Tree-shaking enabled in Next.js (default: yes)
• Side-effect-free modules marked in package.json
• No circular dependencies

2.5 Unused Dependency Audit

Status: VERIFICATION REQUIRED

# Find unused dependencies
npm ls --all | grep -E "^├─|^└─" | awk '{print $2}' | sort | uniq

# Manual check for common unused packages
npm ls | grep -E "@testing-library|@types|vitest"

# Verify all dependencies are used
ls /Users/rmac/Documents/metabuilder/node_modules | \
  while read pkg; do
    grep -r "$pkg" frontends/nextjs/src --include="*.ts" --include="*.tsx" | wc -l
  done

Optimization Plan:

• Remove unused @testing-library packages (E2E uses Playwright)
• Remove unused vitest (tests use Playwright)
• Review @types/* packages for alignment
• Consolidate duplicate versions

2.6 Bundle Analysis

Status: BASELINE MEASUREMENT

Expected Bundle Breakdown:

Total: ~1.0 MB
├── React & React DOM: ~150KB
├── Next.js Runtime: ~100KB
├── Fakemui (Material UI): ~150KB
├── React Query: ~40KB
├── Application Code: ~300KB
├── Vendor Chunk: ~150KB
└── CSS/Assets: ~10KB

Measurement Tools:

• Next.js built-in bundle analyzer
• Webpack Bundle Analyzer
• Import Cost VS Code extension
• Bundle Buddy (comparison tool)

Optimization Strategy:

• Bundle size < 1.5 MB (critical)
• JS payload < 500KB (after gzip)
• Identify packages > 100KB
• Evaluate tree-shaking potential
• Consider alternative libraries if > 2x smaller

---

3. Core Web Vitals

3.1 Largest Contentful Paint (LCP)

Target: < 2.5 seconds

Optimization Strategies:

1. Reduce Main Thread Work

   • Move heavy computations to Web Workers
   • Defer non-critical JavaScript
   • Use requestIdleCallback for low-priority tasks

2. Optimize Images (if added)

   • Use Next.js Image with priority for above-the-fold
   • Proper sizing and format
   • Lazy loading for below-the-fold

3. Reduce Server Response Time

   • Use database indexes
   • Cache static assets
   • Pre-render pages when possible

4. Preload Critical Assets

   <!-- In layout.tsx or _document.tsx -->
   <link rel="preload" as="style" href="/styles/critical.css" />
   <link rel="preload" as="script" href="/js/app.js" />
   

3.2 First Input Delay (FID) / Interaction to Next Paint (INP)

Target: < 100ms for FID, < 200ms for INP

Optimization Strategies:

1. Break Up Long Tasks

   // ✅ CORRECT: Break long task into chunks
   async function processLargeDataset(data: unknown[]) {
     const chunkSize = 100
     for (let i = 0; i < data.length; i += chunkSize) {
       const chunk = data.slice(i, i + chunkSize)
       // Process chunk
       await new Promise(resolve => setTimeout(resolve, 0))
     }
   }
   

2. Use Web Workers for Heavy Computation

   // Main thread: send data to worker
   const worker = new Worker('/workers/processor.ts')
   worker.postMessage(largeDataset)
   worker.onmessage = (event) => {
     // Process results
   }
   

3. Defer Non-Critical JavaScript

   // ✅ CORRECT: Defer analytics/tracking scripts
   if (typeof window !== 'undefined') {
     window.addEventListener('load', () => {
       // Load tracking script after page is interactive
       const script = document.createElement('script')
       script.src = '/analytics.js'
       script.defer = true
       document.head.appendChild(script)
     })
   }
   

3.3 Cumulative Layout Shift (CLS)

Target: < 0.1

Prevention Strategies:

1. Set Size Attributes for Media

   // ✅ CORRECT: Set width/height to prevent layout shift
   <Image src={url} width={300} height={300} alt="description" />
   
   // ✅ CORRECT: Use aspect-ratio for responsive images
   <div style={{ aspectRatio: '16/9' }}>
     <Image src={url} fill alt="description" />
   </div>
   

2. Avoid Inserting Content Above Existing Content

   // ❌ WRONG: Banner inserted above content
   {showBanner && <BannerAd />}
   <MainContent />
   
   // ✅ CORRECT: Banner inserted in fixed position
   {showBanner && (
     <BannerAd style={{ position: 'fixed', bottom: 0 }} />
   )}
   <MainContent />
   

3. Use transform Instead of Layout Changes

   /* ✅ CORRECT: Use transform for animations */
   .button {
     transition: transform 0.2s ease;
   }
   .button:hover {
     transform: translateY(-2px);
   }
   
   /* ❌ WRONG: top/margin causes layout shift */
   .button:hover {
     top: -2px;
   }
   

4. Reserve Space for Ads/Embeds

   // ✅ CORRECT: Reserve space with aspect-ratio
   <div style={{ aspectRatio: '300/250' }}>
     <AdComponent />
   </div>
   

---

4. Testing & Validation

4.1 E2E Test Suite Execution

# Run full E2E test suite
npm run test:e2e

# Expected Results:
# Total: 179 tests
# Target: >90% passing (>160 tests)
# Current: 74/179 passing (59%)

Critical Test Categories (Priority Order):

Category	Tests	Status	Fix Priority
Package Rendering	3	2/3 ✅	Low
Navigation	4	1/4	Medium
Login/Auth	4	1/4	High
CRUD Operations	26	5/26	High
Pagination	10	0/10 ❌	Critical
API Operations	Mixed	Mixed	Medium

Fix Strategy:

1. Fix pagination timeout issues (likely selector/timing)
2. Improve login/auth tests (likely state management)
3. Fix CRUD operation tests (likely data setup)
4. Address navigation issues (likely routing)

4.2 Cross-Browser Testing

// Test in:
// - Chrome/Chromium (primary)
// - Firefox (secondary)
// - Safari (Apple platforms)
// - Edge (Windows alternative)

// Automated testing checklist:
const browsers = [
  { name: 'Chrome', versions: ['latest', 'latest-1'] },
  { name: 'Firefox', versions: ['latest'] },
  { name: 'Safari', versions: ['latest'] },
  { name: 'Edge', versions: ['latest'] },
]

// Manual testing checklist:
const testCases = [
  'Homepage loads correctly',
  'Navigation works',
  'Login form functions',
  'Data tables display properly',
  'Forms submit data',
  'Error messages display',
  'Loading states show',
  'Images render (if present)',
]

4.3 Responsive Design Verification

Breakpoints (from fakemui Material Design):

• Mobile: 320px - 480px
• Tablet: 481px - 768px
• Desktop: 769px - 1024px
• Large: 1025px+

// Test checklist
const responsiveTests = [
  { viewport: '375x667', name: 'iPhone SE' },
  { viewport: '390x844', name: 'iPhone 15' },
  { viewport: '810x1080', name: 'iPad' },
  { viewport: '1024x768', name: 'Desktop' },
  { viewport: '1440x900', name: 'Large Desktop' },
  { viewport: '2560x1440', name: 'Ultra-wide' },
]

// Verification checklist:
const checks = [
  'Text readable without scrolling horizontally',
  'Buttons/controls large enough to tap (44px min)',
  'Images scale proportionally',
  'Navigation is accessible',
  'Forms are usable on small screens',
  'No horizontal overflow',
  'Layout adapts to viewport',
]

---

5. Documentation

5.1 Accessibility Guidelines

For Developers:

# Accessibility Guidelines for MetaBuilder

## Quick Reference

1. **Forms**: Always use `<label>` with `htmlFor`
2. **Buttons**: Use `<button>` element, not `<div>`
3. **Links**: Use descriptive text, not "click here"
4. **Images**: Provide meaningful `alt` text
5. **Colors**: Don't rely on color alone for information
6. **Focus**: Always visible, never removed
7. **Errors**: Use `role="alert"` for error messages
8. **Headings**: Start with `<h1>`, maintain hierarchy

## Common Patterns

### Form Validation
[See section 1.7 above]

### Modal Dialogs
[See keyboard navigation section above]

### Data Tables
[See screen reader testing section above]

## Testing

1. Use keyboard only (Tab, Enter, Escape, Arrow keys)
2. Enable screen reader (VoiceOver on Mac: CMD+F5)
3. Check color contrast (WebAIM Contrast Checker)
4. Verify focus indicators visible
5. Test with browser zoom at 200%

## Resources

- WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
- WebAIM: https://webaim.org/
- MDN Accessibility: https://developer.mozilla.org/en-US/docs/Web/Accessibility
- ARIA Practices: https://www.w3.org/WAI/ARIA/practices/

5.2 Performance Optimization Report

# Performance Optimization Report

## Core Web Vitals Baseline

### Pre-Optimization
| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| LCP | TBD | <2.5s | ⏳ To Measure |
| FID/INP | TBD | <100ms | ⏳ To Measure |
| CLS | TBD | <0.1 | ⏳ To Measure |

### Optimization Applied
- [x] System fonts (no web fonts)
- [x] Semantic HTML
- [x] Lazy loading for images (when added)
- [x] Dynamic code splitting
- [x] Minified CSS/JS
- [ ] Further optimization TBD

## Build Performance

| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| Build Time | 2.4-2.6s | <5s | ✅ Pass |
| Bundle Size | ~1.0 MB | <2 MB | ✅ Pass |
| TypeScript Errors | 0 | 0 | ✅ Pass |
| Type Checking | Pass | Pass | ✅ Pass |

## Optimization Opportunities

1. **Code Splitting**: Admin tools lazy-loaded
2. **Image Optimization**: Use Next.js Image when adding images
3. **Font Optimization**: Continue using system fonts
4. **CSS Optimization**: Consider atomic CSS (future)
5. **Caching**: Enable HTTP caching headers

5.3 Lighthouse Baseline Reports

How to Generate:

# Install Lighthouse CLI
npm install -g @lhci/cli@<latest-version>

# Run Lighthouse audit
lhci autorun

# Or via browser DevTools:
# 1. Open DevTools (F12)
# 2. Click Lighthouse tab
# 3. Click "Analyze page load"
# 4. Wait for report

Expected Scores:

• Performance: 85-90
• Accessibility: 90-95 (after implementing Phase 5.4 improvements)
• Best Practices: 90-95
• SEO: 90-95
• PWA: N/A (not applicable for web app)

5.4 Core Web Vitals Measurements

Measurement Tools:

• Web Vitals npm package
• Google Analytics
• PageSpeed Insights
• Chrome DevTools

Implementation in Next.js:

// pages/_app.tsx
import { useEffect } from 'react'
import { getCLS, getFID, getFCP, getLCP, getTTFB } from 'web-vitals'

export default function App({ Component, pageProps }: AppProps) {
  useEffect(() => {
    getCLS(console.log)
    getFID(console.log)
    getFCP(console.log)
    getLCP(console.log)
    getTTFB(console.log)
  }, [])

  return <Component {...pageProps} />
}

5.5 MVP Launch Readiness Checklist

# MVP Launch Readiness Checklist

## Accessibility (WCAG AA)
- [ ] All interactive elements have ARIA labels
- [ ] Keyboard navigation works (Tab, Enter, Escape, Arrow keys)
- [ ] Color contrast 4.5:1 for text, 3:1 for graphics
- [ ] Screen reader tested with VoiceOver/NVDA
- [ ] Focus indicators visible on all elements
- [ ] Semantic HTML structure throughout
- [ ] Form labels and error messages properly marked

## Performance
- [ ] Build time < 5 seconds
- [ ] Bundle size < 2 MB
- [ ] Zero TypeScript errors
- [ ] Type checking passes
- [ ] LCP < 2.5 seconds
- [ ] FID < 100ms
- [ ] CLS < 0.1

## Testing
- [ ] E2E test pass rate > 90%
- [ ] Cross-browser testing complete (Chrome, Firefox, Safari)
- [ ] Responsive design verified (mobile, tablet, desktop, large)
- [ ] Loading states display correctly
- [ ] Error states display correctly
- [ ] Empty states display correctly

## Code Quality
- [ ] ESLint passing (or documented exclusions)
- [ ] No console errors or warnings
- [ ] No accessibility violations
- [ ] Code formatting consistent (Prettier)

## Documentation
- [ ] Accessibility guidelines documented
- [ ] Performance baseline established
- [ ] Lighthouse reports generated
- [ ] Core Web Vitals measured
- [ ] Deployment guide complete

## Security
- [ ] HTTPS/SSL configured
- [ ] CSP headers configured
- [ ] No hardcoded secrets
- [ ] Input validation on all forms
- [ ] XSS protection enabled

## Deployment
- [ ] Production database configured
- [ ] Environment variables set
- [ ] Build process tested
- [ ] Rollback procedure documented
- [ ] Monitoring/alerting configured

---

6. Implementation Roadmap

Phase 5.4.1: Accessibility Foundation (Week 1)

Tasks:

1. Add ARIA labels to all interactive elements
2. Implement semantic HTML structure
3. Fix form labels and error messaging
4. Add focus indicators to all interactive elements
5. Test keyboard navigation (Tab, Enter, Escape)
6. Screen reader testing with VoiceOver

Expected Outcome: WCAG AA compliance foundation

Phase 5.4.2: Performance Optimization (Week 2)

Tasks:

1. Analyze bundle with @next/bundle-analyzer
2. Identify and lazy-load heavy components
3. Implement responsive image optimization
4. Verify tree-shaking effectiveness
5. Audit unused dependencies
6. Generate bundle size baseline

Expected Outcome: Performance baseline established

Phase 5.4.3: Testing & Validation (Week 3)

Tasks:

1. Run full E2E test suite
2. Fix critical test failures (pagination, auth)
3. Cross-browser testing (Chrome, Firefox, Safari)
4. Responsive design verification
5. Load testing and performance profiling
6. Generate Lighthouse reports

Expected Outcome: > 90% test pass rate, >85 Lighthouse score

Phase 5.4.4: Documentation & Launch Prep (Week 4)

Tasks:

1. Document accessibility guidelines
2. Create performance optimization guide
3. Generate Lighthouse baseline reports
4. Measure Core Web Vitals
5. Create MVP launch checklist
6. Final QA and sign-off

Expected Outcome: Ready for MVP launch

---

7. Success Criteria

Criterion	Target	Current	Status
Accessibility
WCAG AA Compliance	100%	0%	⏳ To Implement
Keyboard Navigation	100%	0%	⏳ To Implement
Screen Reader Compatible	100%	0%	⏳ To Test
Color Contrast	100% (4.5:1)	TBD	⏳ To Verify
Focus Indicators	100% visible	0%	⏳ To Implement
Performance
Build Time	<5s	2.4-2.6s	✅ Met
Bundle Size	<2 MB	~1.0 MB	✅ Met
LCP	<2.5s	TBD	⏳ To Measure
FID/INP	<100ms	TBD	⏳ To Measure
CLS	<0.1	TBD	⏳ To Measure
Testing
E2E Pass Rate	>90%	59%	⏳ In Progress
Cross-Browser Coverage	3+ browsers	1	⏳ To Expand
Responsive Design	All breakpoints	TBD	⏳ To Verify
Code Quality
TypeScript Errors	0	0	✅ Met
Type Checking	Pass	Pass	✅ Met
ESLint	Pass	254 pre-existing	⏳ To Address

---

8. References

Accessibility Standards

• WCAG 2.1 Level AA: https://www.w3.org/WAI/WCAG21/quickref/
• ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/practices-1.1/
• WebAIM Articles: https://webaim.org/articles/

Performance Monitoring

• Web Vitals: https://web.dev/vitals/
• Lighthouse: https://developers.google.com/web/tools/lighthouse
• PageSpeed Insights: https://pagespeed.web.dev/

Testing Tools

• Axe DevTools: https://www.deque.com/axe/devtools/
• WAVE: https://wave.webaim.org/
• NVDA Screen Reader: https://www.nvaccess.org/
• VoiceOver (macOS): Built-in

Tools & Configuration

• Next.js Bundle Analyzer: @next/bundle-analyzer
• ESLint A11y Plugin: eslint-plugin-jsx-a11y
• Prettier: Code formatting

---

Conclusion

Phase 5.4 delivers comprehensive accessibility and performance optimization for the MetaBuilder MVP. By implementing WCAG AA compliance and optimizing Core Web Vitals, the application will meet industry standards for inclusive design and user experience performance.

Next Steps: Execute implementation roadmap phases 5.4.1-5.4.4 over the next 4 weeks, targeting MVP launch readiness by end of Q1 2026.

Status: ✅ Ready for Phase 5.4.1 Implementation