Accessibility in Cratis Components
This skill covers what @cratis/components actually implements and enforces
in its own source. It is deliberately narrow. It is not a WCAG conformance
guide, and it does not claim the library is conformant.
Read the honest boundary at the end before promising a user any behavior beyond
what is written here.
Verified product sources
| Package |
Verified from |
@cratis/components |
Source/Dialogs/* (DialogInitialFocus, DialogImplementation), Source/CommandForm/fields/fieldAccessibility.tsx, Source/for_accessibility/*, Source/SchemaEditor/*, Source/ObjectNavigationalBar/*, Source/MIGRATION.md, Documentation/Styling/pass-through.md, Documentation/Common/cratis-components-provider.md, Documentation/renderers/index.md |
Focus, overlay and collection behavior come from React Aria internally — the
dialog is a React Aria Modal inside a ModalOverlay; you never import React
Aria yourself, and its class names are not a styling or testing hook.
1. Dialog focus discipline
A modal must move focus into itself when it opens. Leaving focus on the document
body strands keyboard and screen-reader users, so Dialog has no "focus
nothing" option — DialogInitialFocus has exactly three members and one of
them always applies.
enum DialogInitialFocus { Confirm = 1, Cancel = 2, Content = 3 }
| Member |
Effect |
Use for |
Confirm |
focuses the confirm button — the default |
ordinary, safe dialogs |
Cancel |
focuses the least destructive action |
anything irreversible |
Content |
focuses the dialog title, arming nothing |
a dialog that should commit to nothing |
The armed-Enter hazard
Confirm arms the confirm button. A browser fires click from the keydown
of Enter or Space, so an Enter that is still held — or repeating — from the
action that opened the dialog can confirm it immediately, before the user has
read anything.
Any dialog whose confirm action is destructive or irreversible must set
initialFocus.
<CommandDialog
command={DeleteAccount}
title='Delete account'
okLabel='Delete'
initialFocus={DialogInitialFocus.Cancel}>
Cancel degrades to Content automatically when the chosen button set has
nothing to dismiss with, so it is always safe to ask for.
DialogInitialFocus imports from @cratis/components/Dialogs. While isBusy
is set the dialog marks its content inert and disables every dismissal path,
so a user cannot interact with a half-committed form.
2. Every accessible name is a prop or a provider message — never a baked-in English string
This is the library's strongest and most consistent convention: any string a
screen reader will read is exposed as an overridable, localizable prop, and the
library-wide ones also come from CratisComponentsProvider's messages. The
precedence is always the same: a named component prop wins, then the matching
provider message, then the English default. Set the provider messages once for
the application's locale, and the per-instance props where one control needs a
different name.
| Component |
Prop |
Provider message |
Dialog / CommandDialog / StepperCommandDialog |
closeAriaLabel; okLabel, cancelLabel, yesLabel, noLabel |
messages.dialog (ok, cancel, yes, no, close) |
CommandStepper / StepperCommandDialog |
nextLabel, previousLabel |
messages.stepper (next, previous, submit) |
DataPage |
actionsAriaLabel, globalSearchAriaLabel, paginatorAriaLabels |
messages.dataTable, messages.paginator |
DataTableForQuery / DataTableForObservableQuery |
paginatorAriaLabels |
messages.paginator (navigation, first, previous, next, last) |
Column (filter menu) |
filterLabels — match mode, clear, apply, true, false |
messages.columnFilter |
Toaster |
dismissAriaLabel |
messages.notifications (dismiss, region) |
Dropdown |
aria-label, aria-labelledby, aria-describedby |
messages.dropdown (showOptions, clearSelection) |
DatePickerInput / CalendarField |
aria-label / aria-labelledby for the segmented group; todayLabel, clearLabel |
messages.datePicker (today, clear, openCalendar, previousMonth, nextMonth, label) |
| Every CommandForm field |
aria-label (falls back to the field title), aria-describedby, id |
— |
SchemaEditor |
labels |
— |
ObjectNavigationalBar |
backLabel — tooltip and accessible name |
— |
ToolbarButton |
title — required; the accessible name and the tooltip |
— |
Toolbar |
aria-label, aria-labelledby |
messages.toolbar (label, default 'Tools') |
ToolbarFolder drawer |
closeLabel |
messages.toolbar.closeDrawer |
FilterPanel |
aria-label, searchAriaLabel |
messages.filter (label, searchAriaLabel) |
ToolbarFanOutItem / ToolbarFolder |
tooltip / title — required |
— |
RatingField |
starAriaLabel |
— |
ChipsField |
removeAriaLabel |
— |
In a localized application, treat any component whose accessible name you have
not supplied — and any provider message group left at its English default — as
a defect.
3. Put the name on the focusable element, not the wrapper
An accessible name has to land on the element that actually receives focus and
carries the role. Dropdown demonstrates the rule: id and the aria-*
attributes route to the trigger (data-cratis-part='trigger'), not to the
layout wrapper, and the control id is deliberately not duplicated onto the
wrapper so an external <label htmlFor> associates correctly. A single select
follows the button/listbox pattern and a filtered one is a combobox — so in a
test, query the trigger by its accessible name or its part, not by
role="combobox".
<label htmlFor='role'>Advisory role</label>
<Dropdown id='role' value={role} options={roles} aria-describedby='role-help' />
DatePickerInput is a segmented field: its id identifies the focus group,
not a native text input, so name it with aria-label/aria-labelledby on the
group. Tooltip enhances exactly one real focusable child so focus, hover and
aria-describedby stay together — wrap text, fragments or several siblings in
one native control first. Several RadioButtonFields bound to one property need
the same explicit name for native arrow-key group navigation.
Apply the same rule to your own wrapper components: forward id, tabIndex,
and aria-* down to the focusable child rather than putting them on a
container.
4. Field errors are announced — do not duplicate them
Every CommandForm field runs its title and validation messages through one
helper: the control's accessible name falls back to the field title, and when
the field has errors a visually hidden <span id="…-errors"> is rendered and
linked from the control's aria-describedby (merged with any aria-describedby
you pass). Arc renders the visible error text; the hidden span exists only for
assistive technology. Do not render a second announcement or wire your own
aria-describedby to the visible error — you would announce it twice.
5. Decorative icons are hidden
Icons and loading spinners inside a labelled control are marked
aria-hidden='true' so a button's accessible name is exactly its label and not
the icon's text. Do the same in application components: an icon that sits beside
a text label carries no information of its own (<FaPlus aria-hidden='true' />).
6. Customize through parts without fighting the component's ARIA
Parts (pt and data-cratis-part) are for presentation. The component owns
the role, the name and the state attributes on its elements: named behavior
props override conflicting part attributes, so a role or aria-* value you
push through pt onto a part the component already labels is either overridden
or produces two competing semantics. Put identity and ARIA on the documented
behavior props (§2, §3) and keep pt to className, style and data
attributes. State is expressed through valid ARIA plus a data attribute
(aria-invalid + data-invalid, data-disabled, data-selected) — express your
own component state the same way, never through made-up attributes.
One focus lifecycle per interactive surface: never nest a second modal or focus
trap inside a Components dialog to borrow another look, and never combine two
keyboard-selection owners for one control. A presentation adapter must preserve
the Components contract without adding a second semantic control.
What Cratis Components does — and does not — give you
Be accurate about this — over-promising accessibility is worse than saying
nothing.
- There is an automated scan, on representative surfaces. The library runs
axe-core (WCAG 2 A and AA rules) over a set of representative foundation
surfaces in its own specs, and Storybook carries the accessibility addon. That
proves those surfaces have no automated violations; it is not a conformance
certification, it does not cover every component, and it cannot see keyboard
order, focus restoration, screen-reader phrasing or color relationships the
product introduces.
- Modal focus management is real: focus moves in per §1, the backdrop and the
document behind are handled by the React Aria modal, Escape and backdrop
dismissal follow
dismissable, and busy content is inert. Verify keyboard
order, initial focus, focus restoration and screen-reader output in the
application's supported browsers and assistive technologies — Components does
not certify them for you.
- Breadcrumbs and drill-ins in
SchemaEditor, ObjectContentEditor and
ObjectNavigationalBar are native <button>s (with aria-current on the
current crumb), so they are focusable and keyboard-activatable. Anything beyond
that — shortcut keys, arrow-key grid navigation — is not implemented; verify
against the component source before documenting it.
- A custom design still owns visible focus, contrast, target size, reduced
motion, forced colors and responsive behavior. Components supplies semantic
behavior and the
--cratis-focus-ring token; it cannot infer the product's
color relationships.
- Query state is announced. Loading rows contain
role='status'; failure
and unauthorized rows contain role='alert'. empty-row is only for a real
empty result. Message live={false} avoids double announcement inside an
existing live region.
- FilterPanel is a named non-modal dialog. It uses the overlay environment,
and Escape returns focus to its anchor. Localize
messages.filter.
- Toolbars navigate by keyboard.
ToolbarFocusMode.Arrows is the default
(arrows/Home/End, each tool retains its Tab stop); SingleTabStop implements
the WAI-ARIA toolbar pattern, while None keeps native focus. ToolbarButton
exposes aria-pressed when active is supplied. Tabs, toggle groups, tag
groups and breadcrumbs also provide keyboard semantics; name each control.
- ErrorBoundary uses neutral recovery copy, never exception text. Supply
fallback (node or (reset) => node) to localize it; onError reports
diagnostics, onReset runs before retry remounts only the protected section.
- Application layouts still own skip links and announcements. Library
status regions and focus behavior do not certify the surrounding application.
Verify
- Every dialog whose confirm action is destructive or irreversible sets
initialFocus to DialogInitialFocus.Cancel or Content.
CratisComponentsProvider carries the locale and every messages group the
application renders; no accessible name in application code is a hard-coded
English string.
id, tabIndex, and aria-* on a wrapper component reach the focusable
child, not the container; a DatePickerInput is named on its group.
- Icons beside a text label are
aria-hidden.
- No
role/aria-* is injected through pt; no CSS or test targets a React Aria
class name.
- Field errors are not announced twice.
- No claim of keyboard support, automated coverage, or WCAG conformance is made
that the source does not back.
1---2name: cratis-components-accessibility-23description: Use when fixing Cratis Components focus, keyboard submission, accessible names, field announcements or decorative icons. Not for claiming general WCAG conformance or choosing a visual theme.4license: MIT5metadata:6 source: https://skillmd.com/skills/cratis/cratis-components-accessibility-27---89# Accessibility in Cratis Components1011This skill covers what `@cratis/components` **actually implements and enforces**12in its own source. It is deliberately narrow. It is not a WCAG conformance13guide, and it does not claim the library is conformant.1415Read the honest boundary at the end before promising a user any behavior beyond16what is written here.1718## Verified product sources1920| Package | Verified from |21| --- | --- |22| `@cratis/components` | `Source/Dialogs/*` (`DialogInitialFocus`, `DialogImplementation`), `Source/CommandForm/fields/fieldAccessibility.tsx`, `Source/for_accessibility/*`, `Source/SchemaEditor/*`, `Source/ObjectNavigationalBar/*`, `Source/MIGRATION.md`, `Documentation/Styling/pass-through.md`, `Documentation/Common/cratis-components-provider.md`, `Documentation/renderers/index.md` |2324Focus, overlay and collection behavior come from React Aria **internally** — the25dialog is a React Aria `Modal` inside a `ModalOverlay`; you never import React26Aria yourself, and its class names are not a styling or testing hook.2728## 1. Dialog focus discipline2930A modal must move focus into itself when it opens. Leaving focus on the document31body strands keyboard and screen-reader users, so `Dialog` has **no "focus32nothing" option** — `DialogInitialFocus` has exactly three members and one of33them always applies.3435```ts36enum DialogInitialFocus { Confirm = 1, Cancel = 2, Content = 3 }37```3839| Member | Effect | Use for |40| --- | --- | --- |41| `Confirm` | focuses the confirm button — **the default** | ordinary, safe dialogs |42| `Cancel` | focuses the least destructive action | anything irreversible |43| `Content` | focuses the dialog title, arming nothing | a dialog that should commit to nothing |4445### The armed-Enter hazard4647`Confirm` *arms* the confirm button. A browser fires `click` from the `keydown`48of Enter or Space, so an Enter that is still held — or repeating — from the49action that opened the dialog can confirm it immediately, before the user has50read anything.5152**Any dialog whose confirm action is destructive or irreversible must set53`initialFocus`.**5455```tsx56<CommandDialog57 command={DeleteAccount}58 title='Delete account'59 okLabel='Delete'60 initialFocus={DialogInitialFocus.Cancel}>61```6263`Cancel` degrades to `Content` automatically when the chosen button set has64nothing to dismiss with, so it is always safe to ask for.6566`DialogInitialFocus` imports from `@cratis/components/Dialogs`. While `isBusy`67is set the dialog marks its content `inert` and disables every dismissal path,68so a user cannot interact with a half-committed form.6970## 2. Every accessible name is a prop or a provider message — never a baked-in English string7172This is the library's strongest and most consistent convention: any string a73screen reader will read is exposed as an overridable, localizable prop, and the74library-wide ones also come from `CratisComponentsProvider`'s `messages`. The75precedence is always the same: **a named component prop wins, then the matching76provider message, then the English default.** Set the provider messages once for77the application's locale, and the per-instance props where one control needs a78different name.7980| Component | Prop | Provider message |81| --- | --- | --- |82| `Dialog` / `CommandDialog` / `StepperCommandDialog` | `closeAriaLabel`; `okLabel`, `cancelLabel`, `yesLabel`, `noLabel` | `messages.dialog` (`ok`, `cancel`, `yes`, `no`, `close`) |83| `CommandStepper` / `StepperCommandDialog` | `nextLabel`, `previousLabel` | `messages.stepper` (`next`, `previous`, `submit`) |84| `DataPage` | `actionsAriaLabel`, `globalSearchAriaLabel`, `paginatorAriaLabels` | `messages.dataTable`, `messages.paginator` |85| `DataTableForQuery` / `DataTableForObservableQuery` | `paginatorAriaLabels` | `messages.paginator` (`navigation`, `first`, `previous`, `next`, `last`) |86| `Column` (filter menu) | `filterLabels` — match mode, clear, apply, true, false | `messages.columnFilter` |87| `Toaster` | `dismissAriaLabel` | `messages.notifications` (`dismiss`, `region`) |88| `Dropdown` | `aria-label`, `aria-labelledby`, `aria-describedby` | `messages.dropdown` (`showOptions`, `clearSelection`) |89| `DatePickerInput` / `CalendarField` | `aria-label` / `aria-labelledby` for the segmented **group**; `todayLabel`, `clearLabel` | `messages.datePicker` (`today`, `clear`, `openCalendar`, `previousMonth`, `nextMonth`, `label`) |90| Every CommandForm field | `aria-label` (falls back to the field `title`), `aria-describedby`, `id` | — |91| `SchemaEditor` | `labels` | — |92| `ObjectNavigationalBar` | `backLabel` — tooltip **and** accessible name | — |93| `ToolbarButton` | `title` — required; the accessible name and the tooltip | — |94| `Toolbar` | `aria-label`, `aria-labelledby` | `messages.toolbar` (`label`, default `'Tools'`) |95| `ToolbarFolder` drawer | `closeLabel` | `messages.toolbar.closeDrawer` |96| `FilterPanel` | `aria-label`, `searchAriaLabel` | `messages.filter` (`label`, `searchAriaLabel`) |97| `ToolbarFanOutItem` / `ToolbarFolder` | `tooltip` / `title` — required | — |98| `RatingField` | `starAriaLabel` | — |99| `ChipsField` | `removeAriaLabel` | — |100101In a localized application, treat any component whose accessible name you have102not supplied — and any provider message group left at its English default — as103a defect.104105## 3. Put the name on the focusable element, not the wrapper106107An accessible name has to land on the element that actually receives focus and108carries the role. `Dropdown` demonstrates the rule: `id` and the `aria-*`109attributes route to the **trigger** (`data-cratis-part='trigger'`), not to the110layout wrapper, and the control id is deliberately not duplicated onto the111wrapper so an external `<label htmlFor>` associates correctly. A single select112follows the button/listbox pattern and a filtered one is a combobox — so in a113test, query the trigger by its accessible name or its part, **not** by114`role="combobox"`.115116```tsx117<label htmlFor='role'>Advisory role</label>118<Dropdown id='role' value={role} options={roles} aria-describedby='role-help' />119```120121`DatePickerInput` is a segmented field: its `id` identifies the **focus group**,122not a native text input, so name it with `aria-label`/`aria-labelledby` on the123group. `Tooltip` enhances exactly one real focusable child so focus, hover and124`aria-describedby` stay together — wrap text, fragments or several siblings in125one native control first. Several `RadioButtonField`s bound to one property need126the same explicit `name` for native arrow-key group navigation.127128Apply the same rule to your own wrapper components: forward `id`, `tabIndex`,129and `aria-*` down to the focusable child rather than putting them on a130container.131132## 4. Field errors are announced — do not duplicate them133134Every CommandForm field runs its title and validation messages through one135helper: the control's accessible name falls back to the field `title`, and when136the field has errors a visually hidden `<span id="…-errors">` is rendered and137linked from the control's `aria-describedby` (merged with any `aria-describedby`138you pass). Arc renders the visible error text; the hidden span exists only for139assistive technology. Do **not** render a second announcement or wire your own140`aria-describedby` to the visible error — you would announce it twice.141142## 5. Decorative icons are hidden143144Icons and loading spinners inside a labelled control are marked145`aria-hidden='true'` so a button's accessible name is exactly its label and not146the icon's text. Do the same in application components: an icon that sits beside147a text label carries no information of its own (`<FaPlus aria-hidden='true' />`).148149## 6. Customize through parts without fighting the component's ARIA150151Parts (`pt` and `data-cratis-part`) are for **presentation**. The component owns152the role, the name and the state attributes on its elements: *named behavior153props override conflicting part attributes*, so a `role` or `aria-*` value you154push through `pt` onto a part the component already labels is either overridden155or produces two competing semantics. Put identity and ARIA on the documented156behavior props (§2, §3) and keep `pt` to `className`, `style` and data157attributes. State is expressed through valid ARIA plus a data attribute158(`aria-invalid` + `data-invalid`, `data-disabled`, `data-selected`) — express your159own component state the same way, never through made-up attributes.160161One focus lifecycle per interactive surface: never nest a second modal or focus162trap inside a Components dialog to borrow another look, and never combine two163keyboard-selection owners for one control. A presentation adapter must preserve164the Components contract without adding a second semantic control.165166## What Cratis Components does — and does not — give you167168Be accurate about this — over-promising accessibility is worse than saying169nothing.170171- **There is an automated scan, on representative surfaces.** The library runs172 `axe-core` (WCAG 2 A and AA rules) over a set of representative foundation173 surfaces in its own specs, and Storybook carries the accessibility addon. That174 proves those surfaces have no *automated* violations; it is not a conformance175 certification, it does not cover every component, and it cannot see keyboard176 order, focus restoration, screen-reader phrasing or color relationships the177 product introduces.178- **Modal focus management is real**: focus moves in per §1, the backdrop and the179 document behind are handled by the React Aria modal, Escape and backdrop180 dismissal follow `dismissable`, and busy content is `inert`. Verify keyboard181 order, initial focus, focus restoration and screen-reader output in the182 application's supported browsers and assistive technologies — Components does183 not certify them for you.184- **Breadcrumbs and drill-ins in `SchemaEditor`, `ObjectContentEditor` and185 `ObjectNavigationalBar` are native `<button>`s** (with `aria-current` on the186 current crumb), so they are focusable and keyboard-activatable. Anything beyond187 that — shortcut keys, arrow-key grid navigation — is not implemented; verify188 against the component source before documenting it.189- **A custom design still owns visible focus, contrast, target size, reduced190 motion, forced colors and responsive behavior.** Components supplies semantic191 behavior and the `--cratis-focus-ring` token; it cannot infer the product's192 color relationships.193- **Query state is announced.** Loading rows contain `role='status'`; failure194 and unauthorized rows contain `role='alert'`. `empty-row` is only for a real195 empty result. `Message live={false}` avoids double announcement inside an196 existing live region.197- **FilterPanel is a named non-modal dialog.** It uses the overlay environment,198 and Escape returns focus to its anchor. Localize `messages.filter`.199- **Toolbars navigate by keyboard.** `ToolbarFocusMode.Arrows` is the default200 (arrows/Home/End, each tool retains its Tab stop); `SingleTabStop` implements201 the WAI-ARIA toolbar pattern, while `None` keeps native focus. `ToolbarButton`202 exposes `aria-pressed` when `active` is supplied. Tabs, toggle groups, tag203 groups and breadcrumbs also provide keyboard semantics; name each control.204- **ErrorBoundary uses neutral recovery copy**, never exception text. Supply205 `fallback` (node or `(reset) => node`) to localize it; `onError` reports206 diagnostics, `onReset` runs before retry remounts only the protected section.207- **Application layouts still own skip links and announcements.** Library208 status regions and focus behavior do not certify the surrounding application.209210## Verify211212- Every dialog whose confirm action is destructive or irreversible sets213 `initialFocus` to `DialogInitialFocus.Cancel` or `Content`.214- `CratisComponentsProvider` carries the locale and every `messages` group the215 application renders; no accessible name in application code is a hard-coded216 English string.217- `id`, `tabIndex`, and `aria-*` on a wrapper component reach the focusable218 child, not the container; a `DatePickerInput` is named on its group.219- Icons beside a text label are `aria-hidden`.220- No `role`/`aria-*` is injected through `pt`; no CSS or test targets a React Aria221 class name.222- Field errors are not announced twice.223- No claim of keyboard support, automated coverage, or WCAG conformance is made224 that the source does not back.