Accessibility

WCAG AA is the baseline for all Ledger UI components and templates. Low-literacy and low-bandwidth contexts are first-class design constraints.

Standards

Built-in Features

Color Contrast

All semantic color tokens meet WCAG AA contrast ratios (4.5:1 for normal text, 3:1 for large text). The dark theme maintains the same contrast guarantees.

// Token system enforces contrast
import { semanticColors } from '@gtcx/tokens';
 
// These pairs are guaranteed AA-compliant:
// semanticColors.text.primary on semanticColors.bg.default
// semanticColors.text.onPrimary on semanticColors.primary

Keyboard Navigation

Every interactive component supports full keyboard operation:

Focus Management

• Focus trap — Dialogs, Sheets, and AlertDialogs trap focus within the overlay
• Focus restoration — Focus returns to the trigger element when overlays close
• Focus indicators — Visible focus rings on all interactive elements (2px solid, primary color)
• Skip links — MetronicLayout includes a skip-to-content link

Screen Readers

• All components use semantic HTML elements where possible
• ARIA attributes are applied automatically (roles, labels, descriptions, live regions)
• Status changes are announced via aria-live regions
• The toast system uses role="status" for non-critical and role="alert" for errors

Reduced Motion

Components respect prefers-reduced-motion:

@media (prefers-reduced-motion: reduce) {
  /* Transitions are shortened to near-instant */
  /* Animations are disabled */
  /* Scroll behavior becomes instant */
}

Testing

Storybook Addon

Every story includes the @storybook/addon-a11y panel with automated axe-core checks:

pnpm --filter @gtcx/storybook dev  # Check a11y panel per story

Automated Suite

Run axe checks across all stories:

pnpm --filter @gtcx/storybook test:a11y

In CI, Storybook a11y runs as a blocking gate (storybook-a11y-audit). Latest full run on February 20, 2026: 70 suites passed and 202 tests passed with no accessibility violations.

Manual Checklist

For each new component or template, verify:

• Tab order follows visual order
• All interactive elements are reachable via keyboard
• Focus indicator is visible
• Color is not the only means of conveying information
• Text alternatives exist for non-text content
• Content is readable at 200% zoom
• Works with screen reader (VoiceOver on macOS)

RTL Support

All components support right-to-left layouts via CSS logical properties. Enable RTL through GtcxConfigProvider:

<GtcxConfigProvider direction="rtl" locale="ar">
  <App />
</GtcxConfigProvider>

See the RTL guide for details.

Resources

• WCAG 2.1 Quick Reference (opens in a new tab)
• ARIA Authoring Practices (opens in a new tab)
• axe-core Rules (opens in a new tab)