/
Accessibility (a11y) Documentation

Accessibility (a11y) Documentation

  • What accessibility information should be more explicitly called out on the Paragon documentation website (e.g., aria attributes, etc.).

  • Questions on a component by component level

    • A11y implementation details (using aria which 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:

    • Paragon Design System

    • 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 .md file 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-axe

    • Component specific info thats not covered by automated tools.

ActionRow

no a11y attributes

Alert

Accessibility attributes

Attribute

Description

Attribute

Description

role="alert" editable

Used to communicate an important and usually time-sensitive message to the user.

Accessible text

Element

Text

Element

Text

Close button

Dismiss

Alert.Link

Keyboard support

Key

Description

Key

Description

Tab

Moves focus to the next focusable element.

Enter

Triggers the button <Alert.Link /> action.

Shift+Tab

Moves focus to the next focusable element.

AlertModal

Accessibility attributes

Attribute

Description

Attribute

Description

role="dialog" editable

Used to mark up an HTML-based application dialog that separates content or UI from the rest of the web application or page.

aria-label editable

Defines a string value that labels an interactive element.

aria-hidden

Indicates whether the element is exposed to an accessibility API.

Keyboard support

Key

Description

Key

Description

Escape

Closes the modal window.

Annotation

no a11y attributes

Avatar

Accessibility attributes

Attribute

Description

Attribute

Description

alt editable

Used to provide alternative text for an image.

AvatarButton

Accessibility attributes

Attribute

Description

Attribute

Description

type="button" editable

Indicates that the element is a button.

alt (Icon)

Used to provide alternative text for an image.

Keyboard support

Key

Description

Key

Description

Tab

Moves focus to the next focusable element.

Shift+Tab

Moves focus to the next focusable element.

Space

Triggers the button action.

Enter

Triggers the button action.

Badge

no a11y attributes

Breadcrumbs

Accessibility attributes

Attribute

Description

Attribute

Description

aria-label editable

Defines a string value that labels an interactive element.

role="presentation"

Indicates that the element should not be considered part of the available semantics.

aria-current

Used to indicate the current element or page in the navigation context.

Keyboard support

Key

Description

Key

Description

Tab

Moves focus to the next focusable element.

Shift+Tab

Moves focus to the next focusable element.

Enter

Triggers the button action.

Bubble

no a11y attributes

Button

Accessibility attributes

Attribute

Description

Attribute

Description

type="button" editable

Indicates that the element is a button.

aria-label editable

Defines a string value that labels an interactive element.

Keyboard support

Key

Description

Key

Description

Tab

Moves focus to the next focusable element.

Shift+Tab

Moves focus to the next focusable element.

Enter

Triggers the button action.

Space

Triggers the button action.

ButtonGroup

Accessibility attributes

Attribute

Description

Attribute

Description

role="group" editable

Used to create a group of elements that are visually and functionally related together.

aria-label editable

Defines a string value that labels an interactive element.

role="toolbar" editable

Indicates that a certain element is a toolbar.

Card

Card.ImageCap

Accessibility attributes

Attribute

Description

Attribute

Description

alt editable

Used to provide alternative text for an image.

loading="eager"

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

Element

Text

Next button

Scroll to next

Previous button

Scroll to previous

Clickable card

Keyboard support

Key

Description

Key

Description

Tab

Moves focus to the next focusable element.

Shift+Tab

Moves focus to the next focusable element.

CardCarousel (Navigation arrows)

Keyboard support

Key

Description

Key

Description

Tab

Moves focus to the next focusable element.

Shift+Tab

Moves focus to the next focusable element.

Enter

Triggers the button action.

Space

Triggers the button action.

CardCarousel (Cards inside the carousel)

Keyboard support

Key

Description

Key

Description

Tab+RightArrow

Moves focus to the next carousel element.

Tab+LeftArrow

Moves focus to the next carousel element.

Carousel

Accessibility attributes

Attribute

Description

Attribute

Description

role="button" (Navigation buttons)

Used to indicate that a particular element acts as a button, even if it is not a standard <button> element.

aria-hidden (Navigation buttons)

Indicates whether the element is exposed to an accessibility API.

Accessible text

Element

Text

Element

Text

Next button

Next

Previous button

Previous

Keyboard support

Key

Description

Key

Description

Enter (Previous/Next arrow)

Moves focus to the next/previous slide.

Space (Previous/Next arrow)

Moves focus to the next/previous slide.

RightArrow

Moves focus to the next slide.

LeftArrow

Moves focus to the previous slide.

Tab

Moves focus to the carousel navigation arrows.

Shift+Tab

Moves focus from the Next arrow to the Previous or the next focusable element.

Chip

Accessibility attributes

Attribute

Description

Attribute

Description

role="button" (Action button)

Used to indicate that a particular element acts as a button, even if it is not a standard <button> element.

Keyboard support

Key

Description

Key

Description

Tab (Close button)

Moves focus to the next focusable element.

ChipCarousel

Accessibility attributes

Attribute

Description

Attribute

Description

role="region"

Used to indicate that a specific element is an area or region of content on a web page that has a specific meaning or functionality.

aria-label editable

Defines a string value that labels an interactive element.

type="button" (Navigation buttons)

Indicates that the element is a button.

Accessible text

Element

Text

Element

Text

Next button

Scroll to next

Previous button

Scroll to previous

Keyboard support

Key

Description

Key

Description

Tab

Moves focus to the carousel navigation arrows.

Enter (Previous/Next arrow)

Scrolls the chip carousel to the next/previous element.

Space (Previous/Next arrow)

Scrolls the chip carousel to the next/previous element.

Shift+Tab

Moves focus from the Next arrow to the Previous or the next focusable element.

Collapsible

Collapsible.Trigger

Accessibility attributes

Attribute

Description

Attribute

Description

role="button"

Used to indicate that a particular element acts as a button, even if it is not a standard <button> element.