flutter-accessibility
/flutter-accessibility
Flutter accessibility (a11y) — Semantics widget and properties (label, button, header, liveRegion, excludeSemantics, MergeSemantics), labels for icons and images, TalkBack/VoiceOver testing, focus order and keyboard navigation (FocusTraversalGroup, Shortcuts/Actions), minimum tap targets (48x48), color contrast (WCAG 4.5:1), text scaling with TextScaler, reduced motion, and automated checks with meetsGuideline in widget tests. Use when building or reviewing UI for accessibility, fixing screen-reader issues, or adding a11y tests.
- Author
- Dee9975 ↗
- Repository
- cc-skills-flutter ↗
- Licence
- MIT
- Last repository change
- 05.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Flutter accessibility (a11y) — Semantics widget and properties (label, button, header, liveRegion, excludeSemantics, MergeSemantics), labels for icons and images, TalkBack/VoiceOver testing, focus order and keyboard navigation (FocusTraversalGroup, Shortcuts/Actions), minimum tap targets (48x48), color contrast (WCAG 4.5:1), text scaling with TextScaler, reduced motion, and automated checks with meetsGuideline in widget tests. Use when building or reviewing UI for accessibility, fixing screen-reader issues, or adding a11y tests.
Original author description
Flutter accessibility (a11y) — Semantics widget and properties (label, button, header, liveRegion, excludeSemantics, MergeSemantics), labels for icons and images, TalkBack/VoiceOver testing, focus order and keyboard navigation (FocusTraversalGroup, Shortcuts/Actions), minimum tap targets (48x48), color contrast (WCAG 4.5:1), text scaling with TextScaler, reduced motion, and automated checks with meetsGuideline in widget tests. Use when building or reviewing UI for accessibility, fixing screen-reader issues, or adding a11y tests.
How it works
- Semantics basics
- Tap targets
- Text scaling
- Contrast and color
- Focus and keyboard
- Motion
- Automated checks (widget tests)
- Manual check
SKILL.md preview
---
name: flutter-accessibility
description: "Flutter accessibility (a11y) — Semantics widget and properties (label, button, header, liveRegion, excludeSemantics, MergeSemantics), labels for icons and images, TalkBack/VoiceOver testing, focus order and keyboard navigation (FocusTraversalGroup, Shortcuts/Actions), minimum tap targets (48x48), color contrast (WCAG 4.5:1), text scaling with TextScaler, reduced motion, and automated checks with meetsGuideline in widget tests. Use when building or reviewing UI for accessibility, fixing screen-reader issues, or adding a11y tests."
license: MIT
metadata:
author: Matiss Kalnins
version: "0.5.0"
---
**Persona:** You check every screen against a screen reader, 200% text, and keyboard-only navigation before calling it done. Accessibility is a requirement, not polish.
## Semantics basics
Most Material widgets already provide semantics (buttons, text fields, switches). Gaps usually come from **custom widgets** built on `GestureDetector`/`InkWell` and from **icon-only or image-only** controls.
```dart
// Icon-only button: always give a tooltip or semantic label
IconButton(icon: const Icon(Icons.delete), tooltip: "Delete item", onPressed: _delete);
// Meaningful image
Image.asset("assets/chart.png", semanticLabel: "Sales up 12% this month");
// Decorative image: hide from screen readers
const Image(image: AssetImage("assets/divider.png"), excludeFromSemantics: true);
// Custom tappable
Semantics(
button: true,
label: "Add to favorites",
selected: isFavorite,
child: GestureDetector(onTap: _toggle, child: HeartIcon(filled: isFavorite)),
);
```
- **`MergeSemantics`**: reads a row (icon + title + subtitle) as one item. `ListTile` already does this.
- **`ExcludeSemantics`** / `excludeSemantics: true`: hides redundant children.
- **`Semantics(header: true)`**: marks section titles, so screen-reader users can jump between headings.
- **`Semantics(liveRegion: true)`**: announces dynamic status (e.g. "3 results"). Or call `SemanticsService.announce(...)` for one-off messages.
- Labels describe purpose, not appearance: "Search", not "Magnifying glass".
## Tap targets
Interactive elements need at least **48×48 dp** on Android and **44×44 pt** on iOS. Material buttons enforce this through `MaterialTapTargetSize.padded`. For custom widgets, pad them with `SizedBox`/`ConstrainedBox(constraints: BoxConstraints(minWidth: 48, minHeight: 48))`.
## Text scaling
- Never set a fixed `height` on containers that hold text. Let them grow.
- Test at large scales: `MediaQuery(data: MediaQuery.of(context).copyWith(textScaler: .linear(2.0)), ...)`, or use the device's accessibility settings.
- Don't block scaling globally. If one dense element really must be limited, clamp it there: `MediaQuery.withClampedTextScaling(maxScaleFactor: 1.5, child: ...)`.
- Make rows wrap or switch to a Column when text gets large (`Wrap`, `LayoutBuilder`, `OverflowBar`).
## Contrast and color
- Text contrast should be at least **4.5:1** (3:1 for large text and UI components). Check every text/background pair you use from `AppColors` (see `flutter-theming`) when the palette changes.
- Never use color alone to convey state. Add an icon, text, or pattern (e.g. an error icon next to red text).
## Focus and keyboard
- Logical reading/focus order follows the widget tree. Group related controls in `FocusTraversalGroup`, and override the order with `FocusTraversalOrder` only when the visual order differs.
- Every action must work by keyboard on desktop and web. Use `Shortcuts` + `Actions`, or `CallbackShortcuts`, for keyboard accelerators.
- Move focus deliberately after navigation or errors (`FocusScope.of(context).requestFocus(_errorField)`).
## Motion
Respect `MediaQuery.disableAnimationsOf(context)`: skip or shorten non-essential animations, parallax, and auto-playing motion.
## Automated checks (widget tests)
```dart
testWidgets("checkout meets a11y guidelines", (tester) async {
final SemanticsHandle handle = tester.ensureSemantics();
await tester.pumpWidget(const MaterialApp(home: CheckoutPage()));
await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
await expectLater(tester, meetsGuideline(textContrastGuideline));
expect(find.bySemanticsLabel("Place order"), findsOneWidget);
handle.dispose();
});
```
## Manual check
1. Turn on TalkBack (Android) or VoiceOver (iOS) and complete the main flow without looking at the screen.
2. Set the device font to its largest size, and check nothing is clipped or overflows.
3. On desktop/web, complete the flow with the keyboard only.
4. Use the Flutter Inspector's semantics view, or `showSemanticsDebugger: true` on `MaterialApp`, to see what the screen reader sees.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Dee9975/cc-skills-flutter | 100 | MIT |
| gabuldev/flutter-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version 9eaacf8b03af (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100accessibility
Audit and fix Flutter accessibility - screen reader labels and semantics, tap target sizes, text scaling, contrast, focus order and keyboard navigation - and add automated accessibility tests. Use when the user asks about accessibility, TalkBack, VoiceOver, large text, or an accessibility review. - 100accessibility
Audits or remediates Flutter widgets against WCAG 2.2 conformance levels A, AA, or AAA across iOS, Android, Web, macOS, Windows, and Linux, covering Semantics labels and screen reader output under VoiceOver and TalkBack, touch target sizes, dragging alternatives, focus order and… - 100accessibility-as-code
Enforces a11y labels, 44pt targets, 200% text, VoiceOver, TalkBack. Use when adding a pressable, swipe or a11y label, text clips when large, contrast fails or Reduce Motion is missed. Not for RTL (rtl-and-direction). - 100accessibility-as-code
Enforces accessibility as a correctness property authored into each widget — Semantics(button/label) or ExcludeSemantics on every node, a11y state read from MediaQuery not app state, never MediaQuery.withClampedTextScaling / textScaleFactor / FittedBox / TextOverflow.ellipsis to… - 95accessibility-testing
WCAG compliance testing and accessibility quality assurance workflows for iOS apps. Use when validating accessibility labels, testing VoiceOver compatibility, checking contrast ratios, or ensuring WCAG 2.1 compliance. Covers accessibility tree analysis, semantic validation, and… - 100mobile-a11y-test-author
Authors native mobile accessibility tests covering iOS (Accessibility Inspector, XCUITest `performAccessibilityAudit()` introduced in iOS 17, VoiceOver label/trait/hint verification) and Android (Espresso `AccessibilityChecks.enable()`, Accessibility Scanner, TalkBack traversal,…