Flutter Web Accessibility Guide — WCAG 2.2, Semantics, and Screen Reader Support

Semantics(
  label: 'Submit button',
  hint: 'Submits the contact form',
  button: true,
  child: ElevatedButton(
    onPressed: _submit,
    child: const Text('Submit'),
  ),
)

// Lock down contrast-safe tokens in your design system
const Color _bodyText = Color(0xFF1A1A1A);    // ratio 17.1:1 on white (AAA)
const Color _secondaryText = Color(0xFF767676); // ratio 4.54:1 on white (AA)

ThemeData buildAccessibleTheme() {
  return ThemeData(
    colorScheme: const ColorScheme.light(
      onSurface: _bodyText,
      onSurfaceVariant: _secondaryText,
    ),
    textTheme: const TextTheme(
      bodyMedium: TextStyle(color: _bodyText),
      bodySmall: TextStyle(color: _secondaryText),
    ),
  );
}

FocusTraversalGroup(
  policy: OrderedTraversalPolicy(),
  child: Column(
    children: [
      FocusTraversalOrder(
        order: const NumericFocusOrder(1.0),
        child: const TextField(decoration: InputDecoration(labelText: 'Email')),
      ),
      FocusTraversalOrder(
        order: const NumericFocusOrder(2.0),
        child: const TextField(
          decoration: InputDecoration(labelText: 'Password'),
          obscureText: true,
        ),
      ),
      FocusTraversalOrder(
        order: const NumericFocusOrder(3.0),
        child: ElevatedButton(
          onPressed: _login,
          child: const Text('Sign In'),
        ),
      ),
    ],
  ),
)

// Announce status changes to screen readers
Semantics(
  liveRegion: true,
  child: Text(_statusMessage), // e.g., "Saved successfully"
)

Image.asset(
  'assets/revenue_chart.png',
  semanticLabel: 'Revenue chart: 2024 vs 2023, up 20% year-over-year',
)

IconButton(
  icon: const Icon(Icons.delete_outline),
  tooltip: 'Delete item', // becomes the accessible label automatically
  onPressed: _deleteItem,
)

ExcludeSemantics(
  child: Row(
    children: [
      Icon(Icons.star, color: Colors.amber),
      Icon(Icons.star, color: Colors.amber),
      Icon(Icons.star_half, color: Colors.amber),
    ],
  ),
)
// Pair with a text label: Semantics(label: 'Rating: 3.5 out of 5')

// Announce transient messages without changing focus
SemanticsService.announce(
  'Your message has been sent',
  TextDirection.ltr,
);

testWidgets('Login form meets basic WCAG requirements', (tester) async {
  final SemanticsHandle handle = tester.ensureSemantics();
  await tester.pumpWidget(const MaterialApp(home: LoginPage()));

  // Email field has accessible label
  expect(
    tester.getSemantics(find.byType(TextField).first),
    matchesSemantics(label: 'Email'),
  );

  // Submit button has accessible role
  expect(
    tester.getSemantics(find.byType(ElevatedButton)),
    matchesSemantics(
      label: 'Sign In',
      isButton: true,
      hasEnabledState: true,
      isEnabled: true,
    ),
  );

  handle.dispose();
});