Practice
Accessibility Principles
The rules of thumb every designer, engineer, and content editor at CYD follows. Each principle maps back to specific WCAG success criteria and to the policy that makes them binding.
Aligned with the accessibility policy · last reviewed 2026-07-01
Use semantic color tokens, not raw hex or gray-*
All color comes from design-system tokens so contrast holds across themes.
Never hardcode text-white, bg-black, or arbitrary Tailwind grays. Use text-foreground, bg-background, text-muted-foreground, border-border, etc. These are audited for contrast on every theme.
- Do: <p className='text-muted-foreground'>
- Don't: <p className='text-gray-400'>
Every interactive element has a visible focus state
Keyboard users must always know where they are.
Never remove the default focus ring without providing a stronger replacement. Custom widgets need focus-visible styles that meet 3:1 contrast against adjacent colors.
- Do: focus-visible:ring-2 focus-visible:ring-ring
- Don't: outline-hidden with no replacement
Every form control has a programmatic label
Placeholder text is not a label.
Use <Label htmlFor=…> or aria-label. Icon-only buttons need aria-label. Group related inputs with <fieldset><legend>.
- Do: <Button size='icon' aria-label='Close menu'><X /></Button>
- Don't: <button><X /></button>
Meaningful alt text — or alt='' if decorative
Say what the image conveys, not what it is.
For decorative images, use alt=''. For content images, describe purpose. Skip 'image of'.
- Do: <img alt='Students collaborating at a hackathon table' />
- Do: <img alt='' /> for a background flourish
Full keyboard operability
Every interaction works with Tab, Shift+Tab, Enter, Space, and arrow keys.
Prefer Radix / shadcn primitives — they get keyboard behavior right. Never put onClick on a <div> without also handling role, tabIndex, and key events.
- Do: use shadcn <Dialog>, <DropdownMenu>, <Combobox>
- Don't: rebuild a modal on a <div onClick=…>
One <main>, semantic headings, meaningful landmarks
Screen readers rely on structure.
Exactly one <main> per route in the layout that renders <Outlet />. Don't skip heading levels. Use <nav>, <header>, <footer>, <section aria-labelledby=…>.
- Do: h1 → h2 → h3 in order
- Don't: h1 → h4 for visual size — use classes for size
Respect prefers-reduced-motion
Animation is decoration, not required.
Wrap non-essential animations in a reduced-motion check, or use Tailwind's motion-safe: variants. Never auto-play more than 5s of motion without a pause control.
- Do: motion-safe:animate-in
- Don't: infinite auto-carousel with no pause
Tap targets at least 44×44 CSS pixels on mobile
Fingers are bigger than mouse cursors.
shadcn's default Button is fine; icon-only variants need min-h-11 min-w-11 for primary actions.
- Do: <Button size='icon' className='min-h-11 min-w-11' aria-label='…'>
Never rely on color alone to convey meaning
Pair color with icon, text, or shape.
Error states get an icon and text, not just red. Status dots need a label.
- Do: <AlertTriangle /> Required
- Don't: red border with no message
Use h-dvh, not h-screen, for full-height layouts on mobile
h-screen breaks with the mobile browser chrome.
Dynamic viewport units account for the appearing/disappearing address bar.
- Do: className='min-h-dvh'
- Don't: className='h-screen' on mobile flows
How we verify
Automated audits (axe-core plus in-house probes) run against every public route. Findings feed the live conformance report. Manual reviews cover keyboard and screen-reader flows that automation can't judge.
