Skip to main content

    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

    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'>
    WCAG 1.4.3
    WCAG 1.4.11
    02

    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
    WCAG 2.4.7
    WCAG 2.4.11
    03

    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>
    WCAG 1.3.1
    WCAG 3.3.2
    WCAG 4.1.2
    04

    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
    WCAG 1.1.1
    05

    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=…>
    WCAG 2.1.1
    WCAG 2.1.2
    06

    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
    WCAG 1.3.1
    WCAG 2.4.1
    WCAG 2.4.6
    07

    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
    WCAG 2.2.2
    WCAG 2.3.3
    08

    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='…'>
    WCAG 2.5.8
    09

    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
    WCAG 1.4.1
    10

    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
    WCAG 1.4.10

    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.