Accessibility (a11y) Documentation
- Adam Stankiewicz
- Peter Kulko
- Vladyslav Zadorozhnii
What accessibility information should be more explicitly called out on the Paragon documentation website (e.g.,
ariaattributes, etc.).
Questions on a component by component level
A11y implementation details (using
ariawhich does XYZ)Content a11y for someone just dropping the component in the design (e.g., no 2 inputs with same labels).
Usage guidance of when to use which component, or not at all (e.g., checkboxes vs. radios).
Be upfront about what components don’t support (e.g., a callback).
MATTHEW LEPAGE: DEMOING SPECIFIC EXAMPLE AT PWG TOMORROW..
“Good practice” vs. “Bad practice”
Some of these exist in Figma (but could be expanded). Should consider bringing these to the docs site.
Separate header for a11y on each components
Table with implementation details with additional contextual information.
Attributes used (e.g.,
aria-label).
“Relevant info followed by usage.”
2 tasks
A11y header on each component
A11y information filled out in a table in this doc (@Jeff Witt to create a table for each component)
Useful to have in Figma, too, but a challenge to keep in sync.
Long term, we want “source of truth” to be in the docs site only.
Spreadsheet to track? Also can track usage guidance.
WCAG 2 conformant essentials but these are the documented additional a11y “best practices”.
Should we create a GitHub issue?
Yes. We’ll discuss on Friday sync and prioritize for next sprint.
A11y overview page under “Foundations” (@Jeff Witt has a WIP high-level a11y doc)
[question] How much time do designers spend in Figma vs. docs site?
Can we build better pathways for designers to access the docs site?
Is there an equivalent to “Dev resources” in Figma to link to docs site / GitHub code for devs?
Can designers/etc. self-serve update content if it only exists in the docs site?
CMS?
“Edit this page” CTA in docs site pages (this will be prioritized/implemented).
Includes additional good / bad examples?
Smaller components may be tricky to have a “good” vs. “bad”.
Component template page redesign for later once we have baseline a11y info in place:
Some pages (like DataTable) are quite long. How do we make these more understandable / not as overwhelming?
Tabs (design vs. dev.)?
Could be different usage checklists between different personas.
Mini UX focused approach:
Who are the user personas of the docs site?
Design docs.
Engineers.
Etc.?
How do we best serve each group?
Separate
.mdfile for a11y docs vs. technical docs to reduce the barrier to edit pages?Interesting idea. Might be worth exploring.
Preview? Deploy previews.
Testing a11y.
react-axeComponent specific info thats not covered by automated tools.
- 1 ActionRow
- 2 Alert
- 2.1.1 Accessibility attributes
- 2.2 Attribute
- 2.2.1 Accessible text
- 2.3 Alert.Link
- 2.3.1 Keyboard support
- 3 AlertModal
- 4 Annotation
- 5 Avatar
- 6 AvatarButton
- 7 Badge
- 8 Breadcrumbs
- 9 Bubble
- 10 Button
- 10.1 Accessibility attributes
- 10.2 Keyboard support
- 11 ButtonGroup
- 12 Card
- 12.1 Card.ImageCap
- 12.1.1 Accessibility attributes
- 12.2 CardCarusel
- 12.2.1 Accessible text
- 12.3 Clickable card
- 12.3.1 Keyboard support
- 12.4 CardCarousel (Navigation arrows)
- 12.4.1 Keyboard support
- 12.5 CardCarousel (Cards inside the carousel)
- 12.5.1 Keyboard support
- 12.1 Card.ImageCap
- 13 Carousel
- 13.1 Accessibility attributes
- 13.2 Accessible text
- 13.3 Keyboard support
- 14 Chip
- 14.1 Accessibility attributes
- 14.2 Keyboard support
- 15 ChipCarousel
- 15.1 Accessibility attributes
- 15.2 Accessible text
- 15.3 Keyboard support
- 16 Collapsible
- 16.1 Collapsible.Trigger
- 16.1.1 Accessibility attributes
- 16.1.2 Keyboard support
- 16.1 Collapsible.Trigger
- 17 ColorPicker
- 17.1 Accessibility attributes
- 17.2 Keyboard support
- 18 Container
- 19 DataViews
- 20 DataTable
- 20.1.1 Accessibility attributes
- 20.1.2 Accessible text
- 20.1.3 Keyboard support
- 20.2 DataTable.TableControlBar
- 20.2.1 Accessibility attributes
- 20.2.2 Accessible text
- 20.2.3 Keyboard support
- 20.3 DataTable.TableFooter
- 20.3.1 Accessibility attributes
- 20.3.2 Accessible text
- 20.3.3 Keyboard support
- 21 Dropdown
- 21.1 DropdownButton
- 21.1.1 Accessibility attributes
- 21.1.2 Keyboard support
- 21.2 Dropdown.Item
- 21.2.1 Keyboard support
- 21.3 Dropdown.Header
- 21.3.1 Accessibility attributes
- 21.4 Dropdown.Divider
- 21.4.1 Accessibility attributes
- 21.1 DropdownButton
- 22 Dropzone
- 22.1 Accessibility attributes
- 22.2 Accessible text
- 22.3 Keyboard support
- 23 Figure
- 24 Form.Autosuggest
- 24.1 Accessibility attributes
- 24.2 Keyboard support
- 25 Form.Checkbox
- 25.1 CheckboxControl
- 25.1.1 Accessibility attributes
- 25.2 Form.Checkbox
- 25.2.1 Keyboard support
- 25.1 CheckboxControl
- 26 Form.Control
- 26.1 Accessibility attributes
- 26.2 Keyboard support
- 27 Form.Control.Feedback
- 28 Form.Group
- 29 Form.Label
- 30 Form.Radio
- 30.1.1 Accessibility attributes
- 30.1.2 Keyboard support
- 30.2 Form.RadioSet
- 30.2.1 Accessibility attributes
- 31 Form.Switch
- 31.1 Form.Switch
- 31.1.1 Accessibility attributes
- 31.2 SwitchControl
- 31.2.1 Accessibility attributes
- 31.2.2 Keyboard support
- 31.1 Form.Switch
- 32 Forms
- 33 FullscreenModal
- 33.1 Accessibility attributes
- 33.2 Keyboard support
- 34 Hyperlink
- 34.1 Accessible text
- 34.2 Keyboard support
- 35 Icon
- 36 IconButton
- 36.1.1 Accessibility attributes
- 36.2 IconButtonWithTooltip
- 36.2.1 Keyboard support
- 37 IconButtonToggle
- 37.1 Accessibility attributes
- 37.2 Keyboard support
- 38 Image
- 39 InputGroup
- 40 Layout
- 41 MailtoLink
- 41.1 Accessible text
- 41.2 Keyboard support
- 42 MarketingModal
- 42.1 Accessibility attributes
- 42.2 Keyboard support
- 43 Menu
- 43.1 Keyboard support
- 44 ModalDialog
- 44.1 Accessibility attributes
- 44.2 Keyboard support
- 45 ModalLayer
- 45.1 Accessibility attributes
- 45.2 Accessible text
- 45.3 Keyboard support
- 46 ModalPopup
- 46.1 Keyboard support
- 47 Nav
- 47.1 Nav.Link
- 47.1.1 Accessibility attributes
- 47.2 NavDropdown
- 47.2.1 Accessibility attributes
- 47.2.2 Keyboard support
- 47.3 NavDropdown.Item
- 47.3.1 Accessibility attributes
- 47.3.2 Keyboard support
- 47.4 NavDropdown.Divider
- 47.4.1 Accessibility attributes
- 47.1 Nav.Link
- 48 Navbar
- 48.1.1 Accessibility attributes
- 48.2 NavDropdown
- 48.2.1 Accessibility attributes
- 48.2.2 Keyboard support
- 48.3 NavDropdown.Item
- 48.3.1 Keyboard support
- 49 OverflowScroll
- 49.1 Accessibility attributes
- 49.2 Keyboard support
- 50 Overlays
- 51 PageBanner
- 51.1 Accessibility attributes
- 51.2 Keyboard support
- 52 Pagination
- 52.1 Accessibility attributes
- 52.2 Accessible text
- 52.3 Keyboard support
- 53 Popover
- 53.1 Accessibility attributes
- 53.2 Keyboard support
- 54 ProductTour
- 54.1 Accessibility attributes
- 54.2 Accessible text
- 54.3 Keyboard support
- 55 ProgressBar
- 56 Scrollable
- 56.1 Accessibility attributes
- 56.2 Keyboard support
- 57 SearchField
- 57.1 Accessibility attributes
- 57.2 Accessible text
- 57.3 Keyboard support
- 58 SelectMenu
- 58.1 Accessibility attributes
- 58.2 Keyboard support
- 59 SelectableBox
- 59.1 SelectableBox.Set
- 59.1.1 Accessibility attributes
- 59.2 SelectableBox
- 59.2.1 Accessibility attributes
- 59.2.2 Keyboard support
- 59.1 SelectableBox.Set
- 60 Sheet
- 60.1 Accessibility attributes
- 60.2 Keyboard support
- 61 Skeleton
- 62 Spinner
- 62.1 Accessibility attributes
- 62.2 Accessible text
- 63 Stack
- 64 StandardModal
- 64.1 Accessibility attributes
- 64.2 Keyboard support
- 65 StatefulButton
- 65.1 Accessibility attributes
- 65.2 Keyboard support
- 66 Stepper
- 66.1 Stepper.Header
- 66.1.1 Accessibility attributes
- 66.1 Stepper.Header
- 67 Sticky
- 68 TableFilters
- 69 TableControlBar
- 69.1 Accessibility attributes
- 69.2 Keyboard support
- 70 TableFooter
- 70.1 Accessibility attributes
- 70.2 Keyboard support
- 71 Tabs
- 71.1.1 Accessibility attributes
- 71.2 Tab
- 71.2.1 Accessibility attributes
- 71.2.2 Accessible text
- 71.2.3 Keyboard support
- 71.2.4 Keyboard support with More tab
- 72 Toast
- 72.1 Accessibility attributes
- 72.2 Keyboard support
- 73 Tooltip
- 73.1 Accessibility attributes
- 73.2 Keyboard support
- 74 TransitionReplace
- 75 Truncate
ActionRow
no a11y attributes
Alert
Accessibility attributes
Attribute | Description |
|---|---|
| Used to communicate an important and usually time-sensitive message to the user. |
Accessible text
Element | Text |
|---|---|
|
|
Alert.Link
Keyboard support
Key | Description |
|---|---|
| Moves focus to the next focusable element. |
| Triggers the button |
| Moves focus to the next focusable element. |
AlertModal
Accessibility attributes
Attribute | Description |
|---|---|
| Used to mark up an HTML-based application dialog that separates content or UI from the rest of the web application or page. |
| Defines a string value that labels an interactive element. |
| Indicates whether the element is exposed to an accessibility API. |
Keyboard support
Key | Description |
|---|---|
| Closes the modal window. |
Annotation
no a11y attributes
Avatar
Accessibility attributes
Attribute | Description |
|---|---|
| Used to provide alternative text for an image. |
AvatarButton
Accessibility attributes
Attribute | Description |
|---|---|
| Indicates that the element is a button. |
| Used to provide alternative text for an image. |
Keyboard support
Key | Description |
|---|---|
| Moves focus to the next focusable element. |
| Moves focus to the next focusable element. |
| Triggers the button action. |
| Triggers the button action. |
Badge
no a11y attributes
Breadcrumbs
Accessibility attributes
Attribute | Description |
|---|---|
| Defines a string value that labels an interactive element. |
| Indicates that the element should not be considered part of the available semantics. |
| Used to indicate the current element or page in the navigation context. |
Keyboard support
Key | Description |
|---|---|
| Moves focus to the next focusable element. |
| Moves focus to the next focusable element. |
| Triggers the button action. |
Bubble
no a11y attributes
Button
Accessibility attributes
Attribute | Description |
|---|---|
| Indicates that the element is a button. |
| Defines a string value that labels an interactive element. |
Keyboard support
Key | Description |
|---|---|
| Moves focus to the next focusable element. |
| Moves focus to the next focusable element. |
| Triggers the button action. |
| Triggers the button action. |
ButtonGroup
Accessibility attributes
Attribute | Description |
|---|---|
| Used to create a group of elements that are visually and functionally related together. |
| Defines a string value that labels an interactive element. |
| Indicates that a certain element is a toolbar. |
Card
Card.ImageCap
Accessibility attributes
Attribute | Description |
|---|---|
| Used to provide alternative text for an image. |
| Is used to tell the browser to download the image immediately, without waiting for the entire page to be fully loaded. |
CardCarusel
Accessible text
Element | Text |
|---|---|
|
|
|
|
Clickable card
Keyboard support
Key | Description |
|---|---|
| Moves focus to the next focusable element. |
| Moves focus to the next focusable element. |
CardCarousel (Navigation arrows)
Keyboard support
Key | Description |
|---|---|
| Moves focus to the next focusable element. |
| Moves focus to the next focusable element. |
| Triggers the button action. |
| Triggers the button action. |
CardCarousel (Cards inside the carousel)
Keyboard support
Key | Description |
|---|---|
| Moves focus to the next carousel element. |
| Moves focus to the next carousel element. |
Carousel
Accessibility attributes
Attribute | Description |
|---|