web-design-guidelines

# Web Design Guidelines ## Accessibility (WCAG 2.1 AA) ### Color Contrast Requirements - Normal text (< 18pt): minimum **4.5:1** contrast ratio - Large text (≥ 18pt or 14pt bold): minimum **3:1** - UI components and graphical objects: minimum **3:1** ```tsx // Use a utility to check contrast at runtime in dev // Install: npm i color2k import { parseToRgb, getLuminance } from 'color2k' function getContrastRatio(fg: string, bg: string): number { const l1 = getLuminance(fg) const l2 = getLuminance(bg) const lighter = Math.max(l1, l2) const darker = Math.min(l1, l2) return (lighter + 0.05) / (darker + 0.05) } // In Storybook stories or tests: // expect(getContrastRatio('#2563eb', '#ffffff')).toBeGreaterThan(4.5) ``` ### Semantic HTML ```tsx // Good: semantic structure export function PageLayout() { return ( <> <header role="banner"> <nav aria-label="Main navigation"> <ul role="list"> <li><a href="/">Home</a></li> <li><a href="/about">About</a></li> </ul> </nav> </header> <main id="main-content" tabIndex={-1}> <h1>Page Title</h1> {/* Skip-to-main link target */} </main> <aside aria-label="Related content"> {/* Sidebar */} </aside> <footer role="contentinfo"> {/* Footer */} </footer> </> ) } // Skip link — must be the very first focusable element function SkipToMain() { return ( <a href="#main-conte...