Accessibility

Primitive UI is committed to building accessible components that work for all users.

WAI-ARIA Compliance

What is WAI-ARIA?

WAI-ARIA  (Web Accessibility Initiative - Accessible Rich Internet Applications) is a technical specification published by the W3C that specifies how to increase the accessibility of web content and web applications.

While WAI-ARIA is primarily designed for web applications, its principles apply to cross-platform frameworks like Flutter, particularly when components are used in Flutter Web applications.

Current Accessibility Features

Primitive UI components currently provide basic accessibility support:

Visual Accessibility

• High Contrast Support: Components render clearly with sufficient color contrast
• Customizable Colors: All components accept custom colors to meet contrast requirements
• Scalable Design: Components scale properly with different text sizes

Interaction

• Touch Target Size: Interactive components like PrimitiveToggleSwitch and PrimitiveSlider have adequate touch target sizes
• Visual Feedback: Clear visual states for interactions (hover, pressed, disabled)
• Focus Management: Basic focus handling through Flutter’s built-in mechanisms

Implemented Features

We have enhanced accessibility in version 0.0.4:

Semantic Markup

• ARIA Roles: Added proper semantic roles to components (Button, Slider, Switch, ProgressBar)
• ARIA Labels: Support for accessible labels via semanticsLabel
• ARIA States: Properly communicates component states (checked, value, indeterminate)

Keyboard Navigation

• Full Keyboard Support: Interactive components can be operated via keyboard semantics
• Actions: onIncrease and onDecrease actions for sliders

Screen Reader Support

• Announcements: Proper screen reader announcements for state changes
• Descriptions: Meaningful descriptions for all interactive elements

Flutter-Specific

• Semantics Widget: Integrated Flutter’s Semantics widget throughout components
• Custom Semantics: Customizable semantic properties via component constructors

Best Practices

When using Primitive UI components, follow these accessibility best practices:

Provide Labels

Always provide meaningful labels for interactive components:

Semantics(
  label: 'Enable notifications',
  child: PrimitiveToggleSwitch(
    value: notificationsEnabled,
    onChanged: (value) => setState(() => notificationsEnabled = value),
  ),
)

Use Sufficient Contrast

Ensure your color choices meet WCAG contrast requirements:

PrimitiveCard(
  color: Colors.white,  // Background
  child: Text(
    'Content',
    style: TextStyle(
      color: Colors.black87,  // Sufficient contrast with white
    ),
  ),
)

Maintain Touch Target Sizes

Keep interactive elements at least 44x44 pixels for touch accessibility:

PrimitiveToggleSwitch(
  // Default size already meets minimum requirements
  value: isEnabled,
  onChanged: (value) => setState(() => isEnabled = value),
)

Test with Assistive Technologies

Always test your application with:

• Screen readers (TalkBack on Android, VoiceOver on iOS)
• Flutter’s accessibility inspector
• Manual keyboard navigation testing

Resources

Feedback

Commitment

We are committed to making Primitive UI accessible to all users. Accessibility improvements are a priority for upcoming releases, and we aim to achieve full WAI-ARIA compliance where applicable to Flutter applications.

Last updated: November 23, 2025