Accessibility

Accessibility

Flutter accessibility auditing and remediation across WCAG 2.2 conformance levels A, AA, and AAA. This file is the workflow; the reference files listed under Additional Resources are loaded on demand, and each phase below names the one it needs.

Load only the file the current phase names.

Core Standards

Apply these standards to all accessibility work:

Conformance Level — Begin every audit by asking which WCAG 2.2 conformance level the project targets (A, AA, AA + selected AAA, or AAA). Never assume AA.

Platform Selection — Begin every audit by asking which of the six platforms are targeted (iOS, Android, Web, macOS, Windows, Linux). Apply the platform rules from the matching file(s) in references/platforms/.

Image Semantics (WCAG 1.1.1) — Every Image must have semanticLabel, or be wrapped in Semantics(label:). Decorative images use excludeFromSemantics: true.

Gesture Detector (WCAG 2.1.1) — Never use bare GestureDetector for tap targets. Use InkWell, ElevatedButton, TextButton, or IconButton. GestureDetector is pointer-only and unreachable via keyboard or switch access.

Target Size (WCAG 2.5.8) — Target Size Minimum is 24x24 CSS px (≈ 24 dp) at AA. The VGV recommended minimum is 48x48 dp. Findings between 24 dp and 48 dp are flagged as VGV-style at AA, and as WCAG findings at AAA via 2.5.5 (44 dp).

Drag Alternatives (WCAG 2.5.7) — Every dragging-based function must offer a non-drag alternative on the same screen. Sliders need keyboard or stepper alternatives. Dismissible needs an explicit delete button. ReorderableListView needs up/down or "move to" controls.

Focus Not Obscured (WCAG 2.4.11) — A focused widget must not be entirely obscured by sticky headers, snackbars, bottom sheets, persistent FABs, or overlays. Use Scrollable.ensureVisible and Scaffold.resizeToAvoidBottomInset: true.

Color Differentiation (WCAG 1.4.1) — Never use color as the sole differentiator. Always pair color with a label, icon, or shape.

Animation and Motion (WCAG 2.3.3) — All animations must respect MediaQuery.disableAnimations. Gate every AnimationController, AnimatedContainer, Hero transition, and PageRouteBuilder transition on this flag.

Icon Buttons (WCAG 4.1.2) — Icon-only buttons must have a Tooltip or Semantics(label:). Screen readers have no other way to convey purpose.

Exclude Semantics (WCAG 1.1.1) — Never use ExcludeSemantics on non-decorative content. It strips its whole subtree from the semantics tree, so any button or other control inside it disappears from TalkBack and VoiceOver and its action becomes unreachable for screen reader users. State that consequence when declining a request to wrap actionable content. To stop a screen reader from stopping on every child, use MergeSemantics around the static label and value pair only, leaving interactive siblings outside it so they stay independently focusable.

Text Containers (WCAG 1.4.4) — Fixed-height containers must not wrap Text. Use minHeight constraints. Fixed heights clip text at 1.5x font scale on Android, sooner on iOS where Larger Accessibility Sizes go to ~3.1x.

Contrast (WCAG 1.4.3) — All text and UI components must meet the contrast ratio for the selected WCAG level. See references/wcag-criteria.md.

Cupertino Semantics (WCAG 4.1.2) — Cupertino widgets (CupertinoSwitch, CupertinoSlider, CupertinoSegmentedControl, CupertinoButton) ship with weaker semantic defaults than their Material equivalents. Always wrap them in Semantics(label:, value:, button:).

Autofill Hints (WCAG 1.3.5) — Every TextField collecting structured personal data (email, username, password, name, address, phone, oneTimeCode) must declare autofillHints. Required for 1.3.5 at AA and the foundation for 3.3.7 Redundant Entry at A.

Finding Format — Every audit finding carries the WCAG criterion ID together with that criterion's name (2.5.8 Target Size (Minimum), never a bare 2.5.8), a severity of exactly CRITICAL, MAJOR, or MINOR in upper case, and the fix as before-and-after Dart code. Never grade severity as High/Medium/Low or Serious/Moderate/Minor. Never ship a finding whose fix is prose only.

Async Announcements (WCAG 4.1.3) — Every async user-visible state change must announce itself via Semantics(liveRegion: true) or SemanticsService.announce.

Workflow

Every accessibility engagement follows four phases in sequence. Do not skip Phase 1 or Phase 2.

Cross-harness note. Phases 1, 2, and 4 below use AskUserQuestion. On a host without it, invoke whatever equivalent user-question tool the host provides; if it has none, ask the same question as plain numbered text. Either way, wait for the reply before proceeding.

Phase 1: Conformance Level Selection

Use AskUserQuestion to ask:

question: "Which WCAG 2.2 conformance level are you targeting?"
header: "WCAG level"
options:
  - label: "A"
    description: "Removes the most critical barriers. Includes the new 2.2 criteria 3.2.6 Consistent Help and 3.3.7 Redundant Entry."
  - label: "AA"
    description: "Standard most regulators require. Adds contrast, resize text, focus visible, plus the four new 2.2 AA criteria: 2.4.11, 2.5.7, 2.5.8, 3.3.8."
  - label: "AA + selected AAA"
    description: "AA across the app, plus specific AAA criteria scoped to flagged flows. Common: 1.4.6 enhanced contrast, 2.2.3 no timing, 2.4.13 focus appearance."
  - label: "AAA"
    description: "Full AAA. 7:1 contrast, no timing, no exceptions to keyboard. Rare for whole products."

If the user picks "AA + selected AAA", follow up with a free-text request for the AAA criterion IDs they want included (for example, "1.4.6, 2.2.3, 2.4.13").

Outcome: Record the selected level. All audit checks, criterion citations, and fix recommendations apply only the rules for that level (plus all levels below it) and any opted-in AAA criteria.

Phase 2: Platform Selection

Use AskUserQuestion (multi-select if available, otherwise one question with a comma-separated reply) to ask:

question: "Which platforms is this app targeting? Select all that apply."
header: "Platforms"
options:
  - label: "iOS"
    description: "VoiceOver, Switch Control, Dynamic Type up to 3.1x, Voice Control, Bold Text, Reduce Motion, Reduce Transparency."
  - label: "Android"
    description: "TalkBack, Switch Access, font scale up to 2x, Voice Access, color inversion."
  - label: "Web"
    description: "Flutter Web rendered to a Semantics-mapped DOM. NVDA + Chrome, JAWS + Chrome, VoiceOver + Safari."
  - label: "macOS"
    description: "VoiceOver, Full Keyboard Access, Reduce Motion, Increase Contrast."
  - label: "Windows / Linux desktop"
    description: "Narrator, NVDA, JAWS (Windows), Orca (Linux), Windows High Contrast Mode."

Outcome: Record the selected platforms. Load the matching file(s) from references/platforms/ (for example, references/platforms/ios.md for iOS, references/platforms/android.md for Android). Load only the files for platforms that were selected; do not load unnecessary files.