Accessibility

Native elements first

Buttons are button or a, dialogs are dialog, selects are select, disclosures are details, and checkboxes, radios and switches are real inputs. Enter, Space, Escape and the arrow keys do what people expect, with no script.

Where the script adds behavior, it adds the roles that go with it. Tabs are a radio group with JavaScript off and become ARIA tabs with roving focus once the script runs; a dialog opened by the server becomes a real modal. Each component's Overview says what changes in its Mode support table.

Names and labels

• Fields render a label linked to the control, and link their hint and errors with aria-describedby. HideLabel keeps the label for screen readers when it isn't shown.
• Anything shown only as an icon needs a name: IconButton's Label is required.
• An Icon is hidden from screen readers unless you give it a Label, so it never repeats the text beside it.
• Image requires Alt; pass Alt="" for a picture that only decorates.
• Components that hold a region, such as a table, a menu or pagination, take a Label or Caption for their name, with a default from IzzyText.

Keyboard and focus

• The focus ring shows for keyboard focus only, in the focus color (--ib-color-focus, your brand color by default).
• After a failed submit, FormErrors takes focus, with JavaScript off too, so people start from the list of problems.
• Dialogs and drawers trap focus and return it to the trigger when they close; a popover opened by the user takes focus and gives it back.
• AppShell starts with a "Skip to content" link to the main area.
• When Blazor's FocusOnNavigate moves focus to the page's heading, or the skip link to the main area, no ring is drawn there: screen readers still announce it, and sighted users don't see a box they didn't ask for.

Announcements

• Danger and warning alerts are announced as soon as they appear; the others politely. A Banner isn't announced, since it's there when the page loads; set Announce when one appears later.
• Toasts are read politely, and stay until dismissed when they're errors.
• A loading button sets aria-busy and is heard as its LoadingLabel; a Spinner is heard as its Label.
• A table's "1–10 of 50" and a combobox's "No matches" are read when they change.
• A status, such as a badge's or an alert's, comes with an icon and words as well as a color, and screen readers hear its name.

Color and contrast

Text holds 4.5:1 on what it sits on, in light and dark (disabled text, as WCAG allows, is lighter), and a brand or gray color of your own is checked the same way. In Windows high-contrast mode, controls switch to the system's colors, and checkboxes and switches fall back to the browser's own. When you set colors yourself, see Tokens and customizing for the pairs to keep together.

Motion

With reduced motion set, dialogs, drawers, popovers, tooltips, disclosures, tabs and the sidebar stop moving, and spinners slow down rather than stop, since the motion says "still working". There's no page-wide reset, so your own animations are yours to handle.

With JavaScript off

Everything stays usable, but a few things are plainer: tabs are heard as radio buttons and a dialog opened by the server isn't modal. Each component's Overview lists what changes; see Render modes.

What's left to your app

• A lang on the html element, and a PageTitle on every page.
• One h1 per page and headings in order; Heading's Size changes the look, not the level.
• Link and button text that makes sense on its own, not "Click here".
• Alt text that says what a picture shows, and a unit in a field's label when it matters, as in "Price (USD)".
• Contrast for colors you set yourself, and testing with a keyboard and a screen reader.

Next steps

• Forms and validation: labels, hints and errors.
• All components: what each one does in each mode.