Warp Design System

Appearance

Box - Elements ​

Box is a layout component used for separating content areas on a page.

AndroidreleasedElementsreleasediOSreleasedReactreleasedVuereleased

Accessibility ​

Box wraps its slotted content in a section tag by default which is equivalant to role="region" for the purposes of screen readers.

Do Not Rely On Visual Treatment Alone ​

The info, neutral, bordered, and bleed properties are visual only. They do not change the meaning of the content for assistive technologies.

Always use headings, text, and semantic HTML inside the box to communicate structure and purpose.

Landmark Behaviour For Meaningful Sections ​

By default, w-box behaves as a landmark for screen readers. This means it represents a section of the page that users may want to navigate to directly.

We strongly suggest you provide a heading and an accessible landmark name to ensure that screen readers properly treat it as a landmark.

html
  <w-box aria-labelledby="delivery-heading">
    <h2 id="delivery-heading">Delivery</h2>
    <p>Choose how you want the item delivered.</p>
  </w-box>

If you must use box for a purely visual grouping, set role none:

html
<w-box role="none">
  <p>This box is only a visual container.</p>
</w-box>

Usage ​

Box is a layout component for visually separating a section of content from the surrounding page.

Use w-box for grouped content that needs padding, a background, or a border. The component does not add heading structure, spacing between children, or interactive behavior. Those you must provide yourself.

Basic Box ​

html
<w-box aria-labelledby="delivery-heading">
  <h2 id="deliver-heading">Delivery</h2>
  <p>Choose how you want the item delivered.</p>
</w-box>

Visual Treatments ​

Use one visual treatment at a time:

  • neutral: a quiet sunken surface for grouped content
  • info: a subtle information background
  • bordered: a bordered surface with the default background
html
<w-box neutral role="none">
  <p>Neutral content area</p>
</w-box>

<w-box info role="none">
  <p>Informational content area</p>
</w-box>

<w-box bordered role="none">
  <p>Bordered content area</p>
</w-box>

Bleed ​

Use bleed when a box sits inside a page gutter but should extend to the container edge on narrow screens. bleed is commonly combined with a visual treatment such as neutral or info.

html
<w-box neutral bleed aria-labelledby="summary-heading">
  <h2 id="summary-heading">Summary</h2>
  <p>This box extends into the horizontal gutter on narrow screens.</p>
</w-box>

Examples ​

Basic ​

html
<w-box aria-labelledby="delivery-heading">
  <h2 id="delivery-heading">Delivery</h2>
  <p>Choose how you want the item delivered.</p>
</w-box>

Neutral ​

html
<w-box neutral aria-labelledby="order-summary-heading">
  <h2 id="order-summary-heading">Order summary</h2>
  <p>Review the item price, delivery, and total before continuing.</p>
</w-box>

Info ​

html
<w-box info aria-labelledby="good-to-know-heading">
  <h2 id="good-to-know-heading">Good to know</h2>
  <p>You can change the delivery method before payment.</p>
</w-box>

Bordered ​

html
<w-box bordered aria-labelledby="contact-seller-heading">
  <h2 id="contact-seller-heading">Contact seller</h2>
  <p>Send a message to ask about pickup times.</p>
</w-box>

Bleed ​

html
<div style="padding: 0 16px;">
  <w-box neutral bleed aria-labelledby="summary-heading">
    <h2 id="summary-heading">Summary</h2>
    <p>This box extends into the horizontal gutter on narrow screens.</p>
  </w-box>
</div>

Visual Grouping Without Accessibility Landmarking ​

html
<w-box role="none">
  <p>This box is only a visual container.</p>
</w-box>

Styling API ​

<w-box> API ​

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

Properties ​

NameTypeDefaultSummary
bleedbooleanfalseMakes the box bleed to the container edge.
borderedbooleanfalseShows the box as a bordered surface.
infobooleanfalseShows the box with information styling.
neutralbooleanfalseShows the box with neutral styling.
rolestring'region'ARIA role for the box wrapper.

Property Details ​

bleed ​

Makes the box bleed to the container edge. Extends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up.

  • Type: boolean
  • Default: false

bordered ​

Shows the box as a bordered surface. Use this when the content needs a clear visual boundary from the surrounding page.

  • Type: boolean
  • Default: false

info ​

Shows the box with information styling. Use this for supporting informational content that should be visually separated from the surrounding page.

  • Type: boolean
  • Default: false

neutral ​

Shows the box with neutral styling. Use this for quiet grouped content that needs a background without strong emphasis.

  • Type: boolean
  • Default: false

role ​

ARIA role for the box wrapper. Defaults to a role of region. Set role="none" to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose.

  • Type: string
  • Default: 'region'

Questions? ​

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