Semantics(
  label: 'Event details',
  hint: 'Double tap to view',
  button: true,
  child: CustomWidget(),
)

// Informative
Image.asset('hero.png', semanticLabel: 'Dancer performing ballet')

// Decorative
Image.asset('pattern.png', excludeFromSemantics: true)

IconButton(
  icon: const Icon(Icons.delete),
  tooltip: 'Delete event',  // REQUIRED
  onPressed: _delete,
)

// Minimum 48x48
SizedBox(
  width: 48,
  height: 48,
  child: IconButton(icon: Icon(Icons.close), onPressed: _close),
)

// Or use padding
InkWell(
  onTap: _tap,
  child: Padding(
    padding: const EdgeInsets.all(12),  // Expand hit area
    child: Icon(Icons.star, size: 24),
  ),
)

// Check in theme
final primary = Theme.of(context).colorScheme.primary;
final onPrimary = Theme.of(context).colorScheme.onPrimary;
// onPrimary is designed to have 4.5:1 contrast with primary

// Combine into single announcement
MergeSemantics(
  child: ListTile(
    leading: const Icon(Icons.event),
    title: const Text('Ballet Performance'),
    subtitle: const Text('Tomorrow at 7pm'),
  ),
)
// Announces: "Ballet Performance, Tomorrow at 7pm"

ExcludeSemantics(
  child: DecorativeWidget(),  // Skip in screen reader
)

Semantics(
  liveRegion: true,
  child: Text(statusMessage),  // Announced when changed
)

# iOS: Settings > Accessibility > VoiceOver
# Android: Settings > Accessibility > TalkBack

# In tests
testWidgets('has semantic label', (tester) async {
  await tester.pumpWidget(MyWidget());
  expect(find.bySemanticsLabel('Delete event'), findsOneWidget);
});

class AccessibleButton extends StatefulWidget {
  final VoidCallback onPressed;
  final Widget child;

  const AccessibleButton({required this.onPressed, required this.child});

  @override
  State<AccessibleButton> createState() => _AccessibleButtonState();
}

class _AccessibleButtonState extends State<AccessibleButton> {
  final FocusNode _focusNode = FocusNode();
  bool _isFocused = false;

  @override
  void initState() {
    super.initState();
    _focusNode.addListener(() {
      setState(() {
        _isFocused = _focusNode.hasFocus;
      });
    });
  }

  @override
  void dispose() {
    _focusNode.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Focus(
      focusNode: _focusNode,
      child: Container(
        decoration: _isFocused
            ? BoxDecoration(
                border: Border.all(
                  color: Theme.of(context).colorScheme.primary,
                  width: 3,  // WCAG 2.2: Minimum 2px
                ),
                borderRadius: BorderRadius.circular(8),
              )
            : null,
        child: ElevatedButton(
          onPressed: widget.onPressed,
          focusNode: _focusNode,
          child: widget.child,
        ),
      ),
    );
  }
}

// ❌ BAD: Drag-only interaction
Draggable(
  data: item,
  child: ItemWidget(item),
  feedback: ItemWidget(item),
);

// ✅ GOOD: Drag with tap alternative
class AccessibleDraggable extends StatelessWidget {
  final Item item;
  final VoidCallback onTap;  // Tap alternative

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: onTap,  // Tap to move/select
      onLongPress: () {
        // Show context menu with move options
        showMenu(
          context: context,
          position: RelativeRect.fill,
          items: [
            PopupMenuItem(
              child: Text('Move to top'),
              onTap: () => moveItem(item, 0),
            ),
            PopupMenuItem(
              child: Text('Move to bottom'),
              onTap: () => moveItem(item, -1),
            ),
          ],
        );
      },
      child: Draggable(
        data: item,
        child: Semantics(
          hint: 'Drag to reorder, or tap for options',
          child: ItemWidget(item),
        ),
        feedback: ItemWidget(item),
      ),
    );
  }
}

// ✅ ALWAYS use MediaQuery.textScaleFactor
class AccessibleText extends StatelessWidget {
  final String text;

  @override
  Widget build(BuildContext context) {
    final textScaleFactor = MediaQuery.of(context).textScaleFactor;

    return Text(
      text,
      style: TextStyle(
        fontSize: 16,  // Base size - will scale automatically
      ),
      // Flutter respects textScaleFactor automatically
    );
  }
}

// ❌ BAD: Fixed size that ignores user preference
Text(
  'Fixed text',
  textScaleFactor: 1.0,  // Don't do this!
);

// ✅ GOOD: Respect user's text size preference
Text(
  'Scales with user preference',
  // textScaleFactor uses MediaQuery by default
);

// Handle layout overflow with text scaling
LayoutBuilder(
  builder: (context, constraints) {
    final textScaleFactor = MediaQuery.of(context).textScaleFactor;

    return SingleChildScrollView(
      child: Text(
        longText,
        style: TextStyle(fontSize: 16),  // Scales automatically
      ),
    );
  },
);

# Enable TalkBack
Settings > Accessibility > TalkBack > On

# Test navigation
# - Swipe right: Next element
# - Swipe left: Previous element
# - Double tap: Activate
# - Two-finger swipe: Scroll

# Enable VoiceOver
Settings > Accessibility > VoiceOver > On

# Test navigation
# - Swipe right: Next element
# - Swipe left: Previous element
# - Double tap: Activate
# - Three-finger swipe: Scroll

// Enable semantics debugger in dev
void main() {
  runApp(
    MaterialApp(
      showSemanticsDebugger: true,  // Shows semantic tree overlay
      home: MyApp(),
    ),
  );
}