7onicDESIGN SYSTEM

Accessibility

Guidelines for automatic accessibility support via Radix Primitives and the Field system.

WCAG 2.2 AA
Radix Primitives
Field System

Focus Management

focus-visible:focus-ring for unified focus styling. Input / Textarea apply independent keyboard-detection-based control.

Normal focus--color-focus-ring
user@example.com
Error focus--color-focus-ring-error
invalid-email

:focus-visible fires only on keyboard focus. The focus ring is not shown on mouse clicks. Input / Textarea additionally detect keyboard focus and display the ring only on Tab navigation.

Keyboard Navigation

Radix Primitives automatically manages keyboard interactions for each component.

Button / Toggle
TabEnterSpace

Tab to move, Enter/Space to activate

Checkbox
TabSpace

Tab to move, Space to toggle

Switch
TabSpace

Tab to move, Space to toggle

RadioGroup
Tab↑↓←→

Tab to move between groups, arrow keys to select (roving focus)

ToggleGroup
Tab↑↓←→

Tab to move between groups, arrow keys to switch

Slider
Tab↑↓←→HomeEnd

Arrow keys to change value, Home/End for min/max

Color Contrast

WCAG 2.2 AA requires minimum contrast ratios for text and UI components.

4.5:1AA

Text (normal)

3:1AA

Text (large)

18px+ / 14px bold+

3:1AA

UI elements

7:1AAA

Text (enhanced)

Good

Heading text

text-foreground on bg-background-muted

Action label

text-background on bg-foreground

Bad

Heading text

Low contrast — opacity-30

Heading text

Even lower contrast — opacity-40

Touch Targets

WCAG 2.5.8 recommends a minimum of 24px. The default size (40px) and above meets this. On desktop, smaller sizes are practical for mouse use.

xs
28px
sm
32px
default
40px
lg
48px
xl
56px

Tips for better usability:

  • • Ensure sufficient spacing between elements (8px or more)
  • • Checkbox / Switch / RadioGroup can be toggled by clicking the label — the label area complements the touch target
  • • Consider lg size or larger for mobile screens

Screen Reader

A list of ARIA attributes automatically managed by each component.

Button
aria-busyAuto-applied when loading=true
aria-pressedAuto-applied when selected=true
disabledNative disabled attribute (not aria-disabled)
IconButton
aria-labelRequired — no visible textManual
aria-hiddenAuto-applied to inner SVG icon
Input (Field-connected)
aria-invalidAuto-applied when error=true
aria-describedbyAuto-connected to FieldError inside Field
Checkbox / Switch / Radio
roleAuto-set by Radix (checkbox / switch / radiogroup)
aria-checkedAutomatically managed based on state
FieldError
role="alert"Immediately announces error messages to screen readers
Decorative SVG
aria-hidden="true"Auto-applied via Button leftIcon/rightIcon

Web Guidelines

Accessibility best practices recommended broadly for the web, not just components.

Semantic HTML

  • • Use appropriate elements like <button>, <nav>, <main>
  • • Use <button> instead of <div onClick>
  • • Mark up lists with <ul> / <ol>

Heading Hierarchy

  • • Follow h1 → h2 → h3 order (don't skip levels)
  • • Only one h1 per page
  • • Headings become navigation points for screen readers

Landmarks

  • • Use <header>, <footer>, <aside> to define page structure
  • • Wrap main content in <main>
  • • Enables screen readers to jump to different page sections

Alternative Text

  • • Set alt attribute on all meaningful images
  • • Use alt="" to hide decorative images
  • • alt text should briefly describe the image content

Don't Rely on Color Alone

  • • Combine color + icon + text for error indicators
  • • Distinguish charts with patterns or labels
  • • Differentiate links with underlines or icons, not just color

Dynamic Content

  • • Use aria-live to notify screen readers of dynamic updates
  • • Use role="alert" or role="status" for toasts and notifications
  • • Manage focus appropriately on page transitions