Box - Accessibility

Box is a layout component used for separating content areas on a page. It groups related information inside a subtle surface so users can tell where one block of content ends and the next begins.

AndroidreleasedElementsreleasediOSreleasedReactreleasedVuereleased

General

The grouping a Box creates is visual. A subtle background or a border tells sighted users "these things belong together", but it communicates nothing to a screen reader, and nothing to someone who cannot distinguish the surface from the page background.

If the grouping carries meaning, express it in the content — with a heading, a list, or a sentence — and not in the surface alone.

Box is never interactive. It takes no focus and has no states. Accessibility work therefore concentrates on two things: the semantics of the container, and the accessibility of the content you put inside it.

Role and semantics

On web, Box applies role="region" by default. You can override it with the role property, or remove it entirely by passing an empty string (role="").

The default is worth thinking about rather than accepting:

• An unnamed region is not useful. ARIA requires every region to have an accessible name, and screen readers generally do not expose an unnamed region as a landmark. A default role="region" with no name adds a semantic wrapper that most users never perceive.
• Too many regions create noise. Landmarks are a navigation aid. A page with eight region landmarks is harder to navigate than a page with two meaningful ones.

Recommendation: if the box is purely visual grouping, set role="" and structure the content with a heading instead. Reserve role="region" for a genuinely significant, named section of the page, and pick a more specific role from the MDN WAI-ARIA Roles reference when one fits better.

Naming the region

How you name the region depends on the framework, because the two implementations put the role in different places:

Prefer aria-labelledby pointing at a visible heading inside the box over aria-label. A visible name helps everyone, not just screen reader users.

Heading structure

• Use a real heading element inside the box when the content needs a name. Do not fake it with bold text — bold is not announced as a heading and cannot be navigated to.
• Keep the heading level correct for the surrounding page outline. The box does not create a new document section, so do not restart at h2 inside a page that is already several levels deep.
• Do not skip levels to get a smaller heading. Use the Warp typography classes to control size instead.

Keyboard interaction

Box adds nothing to the tab order — it is not focusable, and it should not be.

• Interactive elements inside the box follow normal DOM order. Keep the visual order and the DOM order the same.
• Every link and button inside the box must show a visible focus indicator. Warp components handle this — do not remove the outline with custom CSS.
• Do not add tabindex to the box. A focusable element with no role and no action is a dead stop for keyboard users.
• Do not attach a click handler to the box. A click target that is not a button or link cannot be reached by keyboard at all.

Screen reader considerations

• With role="", the box is transparent to assistive technology: users hear the content, in order, with no wrapper. For purely visual grouping this is the correct outcome.
• With a named region, screen reader users can jump to the box via the landmarks list and hear its name on entry.
• With an unnamed region, most screen readers announce nothing extra, so the box neither helps nor hurts — it is just an unused wrapper.
• Box has no live region behaviour and announces nothing on its own. If content inside the box updates and users need to know, use Alert or Snackbar, which are built for that.
• An icon inside the box is decorative in most cases. If it carries meaning that the text does not, give it a text alternative; otherwise hide it from assistive technology so it is not announced as a stray graphic.

Visual accessibility

Colour and contrast

• Text inside the box must meet at least 4.5:1 against the box surface, or 3:1 for large text (18.66px bold, or 24px and above).
• Interactive elements and meaningful graphics inside the box need at least 3:1 against the surface.
• Use the Warp surface and text tokens together and do not override them. The neutral, info, and bordered surfaces are defined per brand and per theme, so a hard-coded text colour that passes in one brand or in light mode can fail in another.
• The border on the bordered variant is a visual aid, not information. Do not rely on it to convey meaning, and do not treat it as a substitute for a heading.

Colour independence

Neutral and info differ only by surface colour. Users with low vision or colour vision deficiency may not distinguish them at all, and neither variant carries a status. Never use the choice between them to communicate anything — say it in the text.

Text resizing and reflow

• Content must remain readable and usable at 200% zoom, and no content may be lost when text is enlarged.
• The box grows with its content. Do not set a fixed height — text that outgrows a fixed box gets clipped, which is a WCAG failure.
• Long words and URLs wrap inside the box rather than overflowing horizontally.

Platform-specific accessibility

Web

• Default role="region"; opt out with role="".
• Interactive elements inside the box should be at least 44×44px.

iOS

• VoiceOver reads the box contents in visual order: heading, then body text, then link, then button.
• Support Dynamic Type. Do not constrain the box height, so text can grow with the user's preferred size.
• Interactive elements need a minimum touch target of 44×44pt.
• The tooltip image shown by shouldShowToolTipImage is decorative. Make sure the meaning it suggests is also in the text.

Android

• TalkBack reads the box contents in visual order.
• When you supply an icon, always supply a content description with it — both in Compose and in the legacy WarpBoxView, which exposes boxIconContentDescr for this purpose. If the icon is decorative, pass a null content description rather than an empty description string.
• Support scalable text (sp units) and avoid fixed heights.
• Interactive elements need a minimum touch target of 48×48dp.

Motion and animation

Box has no animation and no transitions, so there is nothing to reduce. If you animate content inside the box, respect prefers-reduced-motion on web and the equivalent Reduce Motion setting on iOS and Android.

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system