Opinionated reorganization/rewriting of our flex docs

- it's one of our most used (and sometimes most misused) components, so we might as well spend more time here

- flex usage has also changed somewhat since the docs were first written (we use `gap` now instead of negative margins, and flex grid uses CSS grid instead of flexbox), so some of this copy needed updating

packages/eui/src/components/flex/flex_group.tsx

@@ -64,14 +64,9 @@ export type EuiFlexGroupProps<TComponent extends ElementType = 'div'> =
        * such as `'div'` or `'span'`, a React component (a function, a class,
        * or an exotic component like `memo()`).
        *
-       * `<EuiFlexGroup>` accepts and forwards all extra props to the custom
+       * `EuiFlexGroup` accepts and forwards all extra props to the custom
        * component.
        *
-       * @example
-       * // Renders a <button> element
-       * <EuiFlexGroup component="button">
-       *   Submit form
-       * </EuiFlexGroup>
        * @default "div"
        */
       component?: TComponent;