[docs] Add a11y section to Tabs

docs/src/pages/components/tabs/AccessibleTabs.js

@@ -0,0 +1,93 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { makeStyles } from '@material-ui/core/styles';
+import AppBar from '@material-ui/core/AppBar';
+import FormControlLabel from '@material-ui/core/FormControlLabel';
+import Switch from '@material-ui/core/Switch';
+import Tabs from '@material-ui/core/Tabs';
+import Tab from '@material-ui/core/Tab';
+import Typography from '@material-ui/core/Typography';
+import Box from '@material-ui/core/Box';
+
+function TabPanel(props) {
+  const { children, value, index, ...other } = props;
+
+  return (
+    <div
+      role="tabpanel"
+      hidden={value !== index}
+      id={`simple-tabpanel-${index}`}
+      aria-labelledby={`simple-tab-${index}`}
+      {...other}
+    >
+      {value === index && (
+        <Box p={3}>
+          <Typography>{children}</Typography>
+        </Box>
+      )}
+    </div>
+  );
+}
+
+TabPanel.propTypes = {
+  children: PropTypes.node,
+  index: PropTypes.any.isRequired,
+  value: PropTypes.any.isRequired,
+};
+
+const useStyles = makeStyles((theme) => ({
+  root: {
+    flexGrow: 1,
+    backgroundColor: theme.palette.background.paper,
+  },
+}));
+
+export default function AccessibleTabs() {
+  const classes = useStyles();
+
+  const [value, setValue] = React.useState(0);
+  const handleChange = (event, newValue) => {
+    setValue(newValue);
+  };
+
+  const [selectionFollowsFocus, toggleSelectionFollowsFocus] = React.useReducer(
+    (flag) => !flag,
+    true,
+  );
+
+  return (
+    <div className={classes.root}>
+      <FormControlLabel
+        control={
+          <Switch
+            checked={selectionFollowsFocus}
+            onChange={toggleSelectionFollowsFocus}
+            color="secondary"
+          />
+        }
+        label="Selection follows focus"
+      />
+      <AppBar position="static">
+        <Tabs
+          selectionFollowsFocus={selectionFollowsFocus}
+          value={value}
+          onChange={handleChange}
+          aria-label="simple tabs example"
+        >
+          <Tab label="Item One" aria-controls="simple-tabpanel-0" id="simple-tab-0" />
+          <Tab label="Item Two" aria-controls="simple-tabpanel-1" id="simple-tab-1" />
+          <Tab label="Item Three" aria-controls="simple-tabpanel-2" id="simple-tab-2" />
+        </Tabs>
+      </AppBar>
+      <TabPanel value={value} index={0}>
+        Item One
+      </TabPanel>
+      <TabPanel value={value} index={1}>
+        Item Two
+      </TabPanel>
+      <TabPanel value={value} index={2}>
+        Item Three
+      </TabPanel>
+    </div>
+  );
+}

docs/src/pages/components/tabs/AccessibleTabs.tsx

@@ -0,0 +1,92 @@
+import React from 'react';
+import { makeStyles, Theme } from '@material-ui/core/styles';
+import AppBar from '@material-ui/core/AppBar';
+import FormControlLabel from '@material-ui/core/FormControlLabel';
+import Switch from '@material-ui/core/Switch';
+import Tabs from '@material-ui/core/Tabs';
+import Tab from '@material-ui/core/Tab';
+import Typography from '@material-ui/core/Typography';
+import Box from '@material-ui/core/Box';
+
+interface TabPanelProps {
+  children?: React.ReactNode;
+  index: any;
+  value: any;
+}
+
+function TabPanel(props: TabPanelProps) {
+  const { children, value, index, ...other } = props;
+
+  return (
+    <div
+      role="tabpanel"
+      hidden={value !== index}
+      id={`simple-tabpanel-${index}`}
+      aria-labelledby={`simple-tab-${index}`}
+      {...other}
+    >
+      {value === index && (
+        <Box p={3}>
+          <Typography>{children}</Typography>
+        </Box>
+      )}
+    </div>
+  );
+}
+
+const useStyles = makeStyles((theme: Theme) => ({
+  root: {
+    flexGrow: 1,
+    backgroundColor: theme.palette.background.paper,
+  },
+}));
+
+export default function AccessibleTabs() {
+  const classes = useStyles();
+
+  const [value, setValue] = React.useState(0);
+  const handleChange = (event: React.ChangeEvent<{}>, newValue: number) => {
+    setValue(newValue);
+  };
+
+  const [selectionFollowsFocus, toggleSelectionFollowsFocus] = React.useReducer(
+    (flag) => !flag,
+    true,
+  );
+
+  return (
+    <div className={classes.root}>
+      <FormControlLabel
+        control={
+          <Switch
+            checked={selectionFollowsFocus}
+            onChange={toggleSelectionFollowsFocus}
+            color="secondary"
+          />
+        }
+        label="Selection follows focus"
+      />
+      <AppBar position="static">
+        <Tabs
+          selectionFollowsFocus={selectionFollowsFocus}
+          value={value}
+          onChange={handleChange}
+          aria-label="simple tabs example"
+        >
+          <Tab label="Item One" aria-controls="simple-tabpanel-0" id="simple-tab-0" />
+          <Tab label="Item Two" aria-controls="simple-tabpanel-1" id="simple-tab-1" />
+          <Tab label="Item Three" aria-controls="simple-tabpanel-2" id="simple-tab-2" />
+        </Tabs>
+      </AppBar>
+      <TabPanel value={value} index={0}>
+        Item One
+      </TabPanel>
+      <TabPanel value={value} index={1}>
+        Item Two
+      </TabPanel>
+      <TabPanel value={value} index={2}>
+        Item Three
+      </TabPanel>
+    </div>
+  );
+}

docs/src/pages/components/tabs/tabs.md

@@ -91,6 +91,29 @@ Tab labels may be either all icons or all text.
 
 {{"demo": "pages/components/tabs/IconLabelTabs.js", "bg": true}}
 
+## Accessibility
+
+(WAI-ARIA: https://www.w3.org/TR/wai-aria-practices/#tabpanel)
+
+This section lists necessary steps to provide necessary information for assistive technology:
+
+1. label `Tabs` via `aria-label` or `aria-labelledby`
+2. `Tab`s need to be connected to their
+corresponding `[role="tabpanel"]` by setting the correct `id`, `aria-controls` and `aria-labelledby`
+
+An example for the current implementation can be found in the demos on this page. We've also published an experimental API in `@material-ui/lab` that does not require
+extra work.
+
+### Keyboard navigation
+
+The components implement keyboard navigation using the "manual activation" behavior. If you want to switch to the
+"selection automatically follows focus" behavior you have pass `selectionFollowsFocus` to the `Tabs` component. The WAI-ARIA authoring practices have a detailed guide on [how to decide then to make selection automatically follow focus](https://www.w3.org/TR/wai-aria-practices/#kbd_selection_follows_focus).
+
+### Demo
+
+{{"demo": "pages/components/tabs/AccessibleTabs.js", "bg": true}}
+
+
 ## Experimental Tabs API
 
 `@material-ui/lab` offers utility components that inject props to implement accessible tabs