diff --git a/docs/architecture/component-patterns.md b/docs/architecture/component-patterns.md index 6d9ff3df0812f..9efc6a06671e3 100644 --- a/docs/architecture/component-patterns.md +++ b/docs/architecture/component-patterns.md @@ -18,6 +18,9 @@ packages/react-components/react-/library/src/ ├── utils/ # Optional: shared utilities ├── testing/ │ └── isConformant.ts # Conformance tests +├── stories/src// +│ ├── Accessibility.md # Optional: concise accessibility guidance +│ └── AccessibilitySpec.mdx # Optional: full component accessibility spec ├── .ts # Root barrel per component └── index.ts # Package export ``` @@ -124,3 +127,11 @@ export const Component: ForwardRefComponent = React.forwardRef(( return renderComponent_unstable(state); }); ``` + +## Accessibility patterns + +Refer to `Accessibility.md` or `BestPractices.md` for high-importance accessibility requirements. + +Check `AccessibilitySpec.mdx` for the full description of accessibility behaviors, including keyboard interaction, assistive tech behaviors, high contrast and reduced motion styles, content restrictions, and guidance on extending the control without breaking accessibility. + +Most packages only have one `AccessibilitySpec.mdx` covering all components in the package -- for example, `MenuAccessibilitySpec.mdx` covers `Menu`, `MenuList`, `MenuItem`, `MenuItemCheckbox`, `MenuItemLink`, `MenuItemRadio`, `MenuItemSwitch`, etc. diff --git a/packages/react-components/react-button/stories/src/Button/ButtonAccessibilitySpec.mdx b/packages/react-components/react-button/stories/src/Button/ButtonAccessibilitySpec.mdx new file mode 100644 index 0000000000000..019daaacd3925 --- /dev/null +++ b/packages/react-components/react-button/stories/src/Button/ButtonAccessibilitySpec.mdx @@ -0,0 +1,173 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Button Accessibility Spec + +`Button` triggers an action or event when activated. It is the foundational building block for more specialized button variants in this package — `CompoundButton`, `MenuButton`, `SplitButton`, and `ToggleButton` — each of which has its own accessibility considerations beyond what is covered here. + +By default, `Button` renders a native HTML ` +``` + +For icon-only buttons (a `Button` with an `icon` slot but no children), an `aria-label` must be provided, since there is no visible text: + +```tsx +