Loading, empty & error states

Skeleton — text lines

Pair with aria-busy="true" on the loading region — the shimmer is the visual channel, aria-busy is the programmatic one. Widths are set inline per line so the placeholder roughly matches the real content's ragged edge.

<div class="bo-stack bo-stack--tight" role="status" aria-busy="true" aria-label="Loading purchase orders">
  <span class="bo-skeleton" style="inline-size: 40%"></span>
  <span class="bo-skeleton" style="inline-size: 90%"></span>
  <span class="bo-skeleton" style="inline-size: 75%"></span>
</div>

--circle / --block

An avatar + two-line card placeholder.

<div class="bo-cluster" style="--bo-cluster-gap: var(--bo-space-3); align-items: center" role="status" aria-busy="true" aria-label="Loading vendor">
  <span class="bo-skeleton bo-skeleton--circle"></span>
  <div class="bo-stack bo-stack--tight" style="flex: 1">
    <span class="bo-skeleton" style="inline-size: 50%"></span>
    <span class="bo-skeleton bo-skeleton--block"></span>
  </div>
</div>

Quick reference generated

API generated from CSS

• The shimmer is a continuous loop, not a one-shot transition, so it is NOT driven by the --bo-motion-duration-* tokens — it gets an explicit prefers-reduced-motion override instead (same reasoning as .bo-motion-spin in the Motion module).

Maturity generated

Introduced

v0.1.0

CSS floor

Chrome/Edge 99 · Firefox 97 · Safari 15.4

Alignment scored

2026-08-23

Assistive-tech evidence

None recorded

Pin this component's first release with npm i @busy-office/ui@0.1.0. The floor is derived from this component's stylesheet alone — set by @layer — so it sits at or below the whole framework's Chrome/Edge 119 · Firefox 129 · Safari 17.5. No assistive-technology runtime result is recorded for any component: it needs a human listening to VoiceOver and NVDA on owner hardware; no gate in this repo can simulate announcement behaviour. What automation covers instead is test:axe across every page at 1440 and 390, and check:forced-colors — see accessibility.

Design-system alignment generated

100% (15/15) — how closely this component follows the design language. Each rule is scored 0-3 against a checkable citation; rules that don't apply leave the denominator. Scored 2026-08-23.

Table first-load — skeleton rows

The #1 ERP loading case: real header (columns are known), skeleton rows sized like the data they stand in for, aria-busy on the <tbody>. For a mid-session re-fetch of a table that already has rows, use data-loading instead — keep the stale rows visible and dimmed.

<tbody aria-busy="true">
  <tr>
    <td><span class="bo-skeleton" style="inline-size: 6rem"></span></td>
    <td><span class="bo-skeleton" style="inline-size: 10rem"></span></td>
    <td class="bo-data-table__col--numeric"><span class="bo-skeleton" style="inline-size: 5rem"></span></td>
  </tr>
  …
</tbody>

The motion, and why it is timed this way

One sweep, left to right, every 1.5 seconds. Published guidance puts the comfortable band at 1.5–2s: under a second reads as glitchy and anxious, over two as broken. Slow it 4× above to see the band's path clearly — the controls are here because a loop that never stops is easy to look straight past, which is exactly how this animation shipped broken.

It used to run four times too far. The gradient is twice the width of its box, and the old keyframes moved it from 200% to −200% — four box-widths per cycle, so the highlight crossed roughly twice every 1.5s. The duration matched the guidance while the travel did not, which is what made it feel fast. Percentage background-position aligns the P% point of the image with the P% point of the box, so at 200% the band starts a full box off-screen; 100% → 0% is exactly one pass. Easing matters too: ease-in-out accelerates the band through the middle, which reads as hurried even at the right duration. A travelling highlight wants linear.

Reduced motion stops it and keeps the block. The placeholder still occupies its space and still pairs with aria-busy, so nothing is lost — only the movement. That also answers the WCAG Pause, Stop, Hide concern for animation that outlasts five seconds: the user's own OS preference is the control.

Empty

<div class="bo-state">
  <span class="bo-state__icon" aria-hidden="true">📭</span>
  <p class="bo-state__title">No purchase orders yet</p>
  <p class="bo-state__description">Orders you create will show up here.</p>
  <div class="bo-state__actions">
    <button class="bo-btn">Create purchase order</button>
  </div>
</div>

Empty — "no results match your filters"

<div class="bo-state">
  <span class="bo-state__icon" aria-hidden="true">🔍</span>
  <p class="bo-state__title">No POs match these filters</p>
  <p class="bo-state__description">Status "Rejected" + CC-4021 has no results in this period.</p>
  <div class="bo-state__actions">
    <button class="bo-btn bo-btn--secondary" type="button">Clear filters</button>
  </div>
</div>

Distinct from first-run empty: name the filters that caused it and offer the one-click way out — otherwise users assume data loss. It is the same component with different words — there is no --empty modifier and none is needed. A first-run empty says "nothing exists yet" and offers create; a filtered empty says "nothing matches" and offers clear. Getting that wrong is what makes users think their data is gone.

--error

<div class="bo-state bo-state--error">
  <span class="bo-state__icon" aria-hidden="true">⚠</span>
  <p class="bo-state__title">Couldn't load purchase orders</p>
  <p class="bo-state__description">Something went wrong on our end. Try again, or check back shortly.</p>
  <div class="bo-state__actions">
    <button class="bo-btn bo-btn--secondary">Retry</button>
  </div>
</div>

Quick reference generated

API generated from CSS

• A .bo-state is decoration around a message — the title/description TEXT is the accessible signal; the icon carries aria-hidden="true" so it is never announced as unlabeled content.

Maturity generated

Introduced

v0.1.0

CSS floor

Chrome/Edge 99 · Firefox 97 · Safari 15.4

Alignment scored

2026-08-23

Assistive-tech evidence

None recorded

Pin this component's first release with npm i @busy-office/ui@0.1.0. The floor is derived from this component's stylesheet alone — set by @layer — so it sits at or below the whole framework's Chrome/Edge 119 · Firefox 129 · Safari 17.5. No assistive-technology runtime result is recorded for any component: it needs a human listening to VoiceOver and NVDA on owner hardware; no gate in this repo can simulate announcement behaviour. What automation covers instead is test:axe across every page at 1440 and 390, and check:forced-colors — see accessibility.

Design-system alignment generated

100% (15/15) — how closely this component follows the design language. Each rule is scored 0-3 against a checkable citation; rules that don't apply leave the denominator. Scored 2026-08-23.