🆘 Consistent help

Common mistake

A common mistake is placing help mechanisms (such as a support chat button, FAQ link, or contact details) in different locations on different screens. Users who have learned where to find help on one screen are confused or unable to locate it elsewhere in the app. For users with cognitive disabilities this inconsistency can make the app effectively unusable when they get stuck.

🎯 Relevant elements

This guideline applies when any of the following help mechanisms appear on more than one screen:

• Contact information (phone number, email address)
• Contact form or feedback button
• Live chat or support widget
• FAQ or help centre link
• Self-help / contextual help tooltips

---

WCAG Guideline

This guideline is based on WCAG 2.2 — 3.2.6 Consistent Help (Level A). If a help mechanism is provided across multiple screens, it must appear in the same relative location each time.

---

Solution

Place help mechanisms in the same position across all screens where they appear. Typically these are placed in the app bar, a persistent footer, or a floating action button. Do not move or hide them based on screen state.

// ❌ Don't - help button placement varies per screen
Scaffold(
  body: Column(
    children: [
      if (isFormScreen) HelpButton(), // only on some screens
      content,
    ],
  ),
);

// ✅ Do - help button in a consistent location (e.g. app bar action) on every screen
Scaffold(
  appBar: AppBar(
    title: Text(title),
    actions: [
      IconButton(
        icon: Icon(Icons.help_outline),
        tooltip: 'Help',
        onPressed: () => openHelp(),
      ),
    ],
  ),
  body: content,
);

---

Validation & Testing

See the Validation & Testing setup guide for tool configuration.

Manual review

Navigate through all screens of the app and verify that the help mechanism:

• Appears in the same relative position on every screen where it is present.
• Is reachable via screen reader navigation without needing to scroll first.

TalkBack & VoiceOver

Move between screens. Verify that the help element is announced at a predictable point in the navigation order on each screen.

---

flutter_test

testWidgets('help button is present and in app bar on all main screens', (tester) async {
  for (final screen in [HomeScreen(), ProfileScreen(), SettingsScreen()]) {
    await tester.pumpWidget(MaterialApp(home: screen));
    expect(
      find.descendant(
        of: find.byType(AppBar),
        matching: find.byTooltip('Help'),
      ),
      findsOneWidget,
      reason: '${screen.runtimeType} is missing the help button in the app bar',
    );
  }
});

---

🛠️ Usage baseflow-a11y-components library

🛠️ Work in progress…