Accessibility from day one
All components MUST integrate with platform accessibility APIs from initial implementation:
- Semantic roles and labels on all interactive elements
- VoiceOver (Apple) / TalkBack (Android) / screen reader (Web) full support
- Keyboard and switch control navigation
- Dynamic Type / font scaling — layouts MUST NOT break at larger text sizes
- WCAG AA minimum contrast (4.5:1 for text, 3:1 for large text)
- Meaningful focus order following visual layout
Platform-specific tooling:
- Windows: UI Automation patterns, Narrator testing, Accessibility Insights, minimum 40x40 epx recommended touch targets
Respect accessibility display options
Components MUST respond to platform accessibility and display settings including reduced motion, high contrast, color inversion, bold text, and grayscale. See platform-specific files for the full list of settings and environment keys.
Accessibility
All components MUST integrate with platform accessibility APIs from initial implementation. Requirements:
- Semantic roles and labels on all interactive elements
- Screen reader full support (VoiceOver, TalkBack, Narrator, ARIA)
- Keyboard and switch control navigation
- Dynamic Type / font scaling — layouts MUST NOT break at larger text sizes
- WCAG AA minimum contrast (4.5:1 for text, 3:1 for large text)
- Meaningful focus order following visual layout
- Components MUST respond to platform accessibility and display settings including reduced motion, high contrast, color inversion, bold text, and grayscale
Swift
Components MUST respond to these SwiftUI environment values:
| Setting | Environment Key | Action |
|---|---|---|
| Reduce Motion | \.accessibilityReduceMotion |
Replace animations with crossfades or instant transitions |
| Reduce Transparency | \.accessibilityReduceTransparency |
Use opaque backgrounds instead of blurs/vibrancy |
| Differentiate Without Color | \.accessibilityDifferentiateWithoutColor |
Add icons/shapes/patterns alongside color indicators |
| Increase Contrast | \.colorSchemeContrast |
Use higher-contrast color pairs |
| Invert Colors | isInvertColorsEnabled |
Mark images/video with accessibilityIgnoresInvertColors |
| Cross-Fade Transitions | prefersCrossFadeTransitions |
Use cross-fade instead of slide/zoom transitions |
Kotlin
Components MUST respond to these Android accessibility settings:
| Setting | API | Action |
|---|---|---|
| Remove Animations | animator_duration_scale == 0 |
Disable all custom animations |
| Font Scale | Configuration.fontScale |
Ensure layouts handle 2x font size |
| High Contrast Text | System setting | Ensure text meets WCAG AA contrast ratios |
| Color Inversion | ACCESSIBILITY_DISPLAY_INVERSION_ENABLED |
Mark media with importantForAccessibility |
| TalkBack | AccessibilityManager |
All elements have contentDescription and proper roles |
| Switch Access | AccessibilityManager |
All interactive elements are focusable and reachable |
| Dark Theme | Configuration.uiMode |
Full dark theme support |
| Display Size | displayMetrics.density |
Layouts must not break at larger display sizes |
TypeScript
Standards
- WCAG 2.1 — minimum AA conformance for all components.
- WAI-ARIA Authoring Practices — correct ARIA roles, states, and properties.
CSS Media Queries
Components MUST respond to these user preferences:
| Setting | Media Query | Action |
|---|---|---|
| Reduced Motion | prefers-reduced-motion: reduce |
Disable/simplify CSS animations and JS transitions |
| High Contrast | prefers-contrast: more |
Increase border widths, use higher-contrast colors |
| Forced Colors | forced-colors: active |
Respect system color palette (Windows High Contrast) |
| Dark Mode | prefers-color-scheme: dark |
Full dark theme support |
| Reduced Transparency | prefers-reduced-transparency: reduce |
Use opaque backgrounds |
| Reduced Data | prefers-reduced-data: reduce |
Lazy-load images, reduce asset sizes |
Screen reader support: use ARIA roles, aria-live for dynamic content, proper landmark regions.
Windows
WinUI 3 controls expose UI Automation patterns automatically. Set AutomationProperties.Name on interactive elements that lack visible text labels.
- Use
AutomationProperties.LabeledByfor form fields - Use
AutomationProperties.LiveSettingfor dynamic content regions - High contrast support is automatic when using
ThemeResource— never hard-code colors - Test with Accessibility Insights for Windows
- Keyboard navigation: all interactive elements must be reachable via Tab, actionable via Enter/Space
Components MUST respond to these Windows accessibility settings:
| Setting | API / Detection | Action |
|---|---|---|
| High Contrast | AccessibilitySettings.HighContrast |
Automatic via ThemeResource — verify custom visuals adapt |
| Animations Disabled | UISettings.AnimationsEnabled |
Disable all custom animations and transitions |
| Text Scaling | UISettings.TextScaleFactor |
Layouts must not break up to 225% text scale |
| Color Filters | System setting | Ensure UI is usable with color vision deficiency filters |
| Narrator | UI Automation tree | All elements have Name, Role, and appropriate patterns |
| Keyboard Navigation | Focus management | All interactive elements reachable via Tab, actionable via Enter/Space |
| Dark Theme | Application.RequestedTheme |
Full dark theme support via ThemeResource |
| Caret Browsing | System setting | Non-interactive text should be navigable |