Repository: flutter
Issue: [documentation] Improve the documentation for building custom widgets that include semantics 
Labels: framework,a: accessibility,d: api docs,P2,team-framework,triaged-framework

## Use case

When developing custom interactive elements from scratch (i.e. a button), you need a few things:
- a `GestureDetector` for gestures
- a `FocusNode` for focus traversal
- an `Actions` + `Shortcuts` widget for keyboard shortcuts
- a `MouseRegion` if you want to to things related to the mouse cursor
- a `Semantics` widget for accessibility purposes

The `FocusNode`, `Actions`, `Shortcuts` and `MouseRegion` can be combined into a `FocusableActionDetector`.

But when looking for documentation for the `Semantics` widget, I struggled with finding what I needed.
The first thing that I did was look at an existing widget, `ElevatedButton` in this case, to see how it is built.

This points me to `ButtonStyleButton`, which boils down to the following widget tree:
```
Semantics(
  button: true,
  container: true,
  child: InkResponse( // implemented using an InkWell
    child: Actions(
      child: Focus(
        child: MouseRegion(
          child: Semantics(
            onTap: <onTap semantics handler>,
            onLongPress: <onLongPress semantics handler>,
            child: GestureDetector(
              excludeFromSemantics: true,
              child: widget.child,
            ),
          ),
        ),
      ),
    ),
  ),
)
```

Examining this widget tree raised a few questions for me:
1. The `InkResponse` widget can use an `FocusableActionDetector` to deduplicate things a bit (the shortcuts map will be null in that case)
2. Is the order of the components always like this? This order is never explained anywhere.
```
Semantics(
 // base semantics (i.e. button: true) here

 // An optional Shortcuts widget should go above the Actions & Focus, I'd refer to the shortcuts docs for that.
 child: Actions(
  child: Focus( // Swapping the focus node & mouse region is harmless I assume
   child: MouseRegion(
    child: Semantics(
     // semantics actions go here, in case the root Semantics wraps a different Stateful/Stateless widget
     // otherwise the semantics actions all go in the root one and this one can be removed.
     child: GestureDetector(
      excludeFromSemantics: true,
      // gesture handles go here, as usual
      child: child,
     ),
    ),
   ),
  ),
 ),
),
```
3. The docs for `Semantics` don't really give common examples for its properties (on the contrary, `MergeSemantics` has a small example)

## Proposal

Create a code lab or code sample that explains how to create a custom button, using all the required parts.

- Refer to the docs for `FocusableActionDetector` for the parts that it handles (as using said widget as-is is enough for the end goal)
- Document the recommended order of a fully featured widget tree that includes all parts (semantics, shortcuts and gestures)
- Provide snippets in the docs of `Semantics` that explain some of its attributes, i.e. `button` or `container`.
- Link to the `Semantics` docs from the `Focus` / `FocusableActionDetector` docs? (and the other way around)