SWAN targets WCAG 2.2 Level AA, and encourages Level AAA where practical, per the Site Accessibility RFC. All SWAN components and features (e.g. theming) are built to meet these standards. You can find component-specific accessibility guidelines on each component's page.
Below are general accessibility principles to follow when building with SWAN.
Correct semantics
Use the HTML element that matches the purpose of the interaction. Screen readers and other assistive technologies rely on semantic HTML to convey meaning; styling alone is not enough.
The most common gotcha: use Button for actions and Link for navigation, regardless of visuals.
- If something performs an in-page action (submitting a form, opening a dialog, toggling UI), it should be a
<button>. - If something navigates to a new page or URL, it should be an
<a>.
These two components in particular can visually look like the other, while creating the correct semantic element. In general, the correct semantic element can be achieved using as, if necessary.
Hiding content visually
The VisuallyHidden component, or visuallyHidden prop, hides content from the screen but keeps it in the browser's accessibility tree.
Alt text
All image elements must have an alt attribute.
- Informative image: Describe what the image conveys —
alt="Team collaborating around a table". - Decorative image: Use an empty alt —
alt="". The screen reader will skip it entirely. - Redundant image: If nearby text already describes the image (e.g. a product name beside a product photo), use
alt=""to avoid repetition.
An empty alt attribute (alt="") is not the same as a missing alt attribute. A missing attribute causes screen readers to announce "image" with no context; an empty attribute tells them to skip the image.
For detailed guidance, see the W3C alt Decision Tree.
Accessible names
Every interactive element, and most elements with a role, need an accessible name — the label announced by assistive technologies. There are several ways to provide one:
Visible text content
The simplest approach. If a button or link contains text, that text becomes its accessible name automatically.
aria-labelledby
Use aria-labelledby to reference another element's text as the accessible name. This is useful when a visible heading or label already describes the element.
aria-label
Use aria-label when there is no visible text. Some components require this to be appropriately labelled on the page, such as SelectionSet. Note that aria-label needs to be localised.
Covering links
When using the covering prop to expand a Link’s clickable area over a Card or Tile, only wrap the Link around the content that should form the accessible name — usually the title or call-to-action. BaseTile has a similar functionality.
