Skeleton
Loading-state placeholder. ONE component, many shapes — the `variant` prop picks the silhouette of the resting component being loaded so the page layout doesn't jump when real data arrives.
Preview
Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.
Install
Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.
npx shadcn@latest add https://ds.interlace.tools/r/skeleton.jsonnpx shadcn@latest add @interlace/skeletonBehavior
What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.
Measured contrast
packages/ui/__tests__/theme-contract-lock.test.ts ↗Every semantic colour pair this component's own source uses, measured against the shipped hexes in all 4 theme × scheme combinations. The tightest is muted-foreground on muted at 7.34:1 (harbor · light), against a floor of 4.5:1.
| Pair | interlacelight | interlacedark | harborlight | harbordark | Floor |
|---|---|---|---|---|---|
| muted-foreground on mutedcopy on a muted surface | 8.81:1 | 10.48:1 | 7.34:1 | 8.64:1 | 4.5:1SC 1.4.3 |
| muted-foreground on backgroundsecondary copy | 9.41:1 | 11.32:1 | 7.82:1 | 9.52:1 | 4.5:1SC 1.4.3 |
| muted-foreground on cardsecondary copy in a card | 9.41:1 | 10.48:1 | 8.25:1 | 8.64:1 | 4.5:1SC 1.4.3 |
Text pairs are held to 4.5:1 (WCAG 2.2 SC 1.4.3); borders, rings and chart axes to 3:1 (SC 1.4.11 non-text). Bold is the worst cell in the row — the one a brand fork has to keep an eye on.
Runtime contract
packages/ui/vitest.config.ts ↗Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.
- Render boundary
server componentRenders during SSR / RSC with no hydration cost. It can be imported from a server component without pulling the page into the client.
- Minimum viewport
MIN_VIEWPORT = 320Declared, not assumed. Below 320 CSS px the preflight contract draws a dev-mode outline — how to switch it on.
- Coverage gate
100% × 4Inside the v8 gate: lines 100, statements 100, functions 100, branches 100. A threshold under 100 only records how much you stopped caring, so there isn't one.
History
This component is at v1.8.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.
@interlace/ui 1.1.03 entries
- Addedminor
Absence becomes a first-class value.
DataStategrows from four states to nine, and two new primitives consume the union as a contract rather than each re-deriving it from a boolean ladder. The states areloading · error · not-applicable · not-counted · empty · partial · truncated · first-measurement · idle, and that list is also the precedence order — lowest wins. Error beats empty, because a failed fetch is not "no results". Truncated is not empty at all: it qualifies a body that still renders. States co-occur, soresolveDataStatereturns the winner AND every loser asqualifiers, the wrapper publishes them asdata-qualifiers, and the announcement says all of them — a list that is both partially covered and truncated is wrong twice and now says so twice. Each state is drawn distinctly and, more importantly, **announced**. A diagonal hatch means no run happened; a dashed outline means not yet real; the accent is spent onfirst-measurementalone, because it is the only absence a reader can act on. Every one of those carries a sentence viaannounceDataState— "Not counted. No measurement was taken; this is not a zero." A hatch that exists only in pixels keeps the distinction for sighted readers and destroys it for everyone else, and axe scores that green.StatStripis the dense measurement grid that appeared in all six of the audited artifacts, hand-rolled four times: mono micro-label,tabular-numsvalue, optional note, optional delta, on a<dl>so every number keeps its label. It renders the three-state null honestly — a metric withprior: nullshows "first measurement" and the caller's delta node is **not rendered at all**, so there is no path by which a missing prior reaches the DOM as+0%.Meterabsorbs three hand-rolled bars (an odds bar, a score meter, a reviewer bar). Magnitude is carried by length AND by the printed number, never by hue, and the number is not optional.value: nullhatches by default rather than drawing an empty bar, because an empty bar and a measured zero are the same picture.variant="dead"recedes without vanishing, for a dormant row that still holds its rank.RankedBarListis the repeated-row composition and supports a labelled log scale, so a 10k row and a 10M row can share an axis. Pure logic ships alongside asdata-state-modelandmeter-scale— the union, the precedence, the announcements, the scale maths — with no React import, exported for callers wiring their own state.Skeletongainsmeterandstat-stripvariants, both composites, so the loading state reserves the real silhouette on the real breakpoints. Not included, deliberately: the domain vocabularies these were extracted from (authority,visibility,dormant,unwritten,ungated) stay in their artifacts as labels a caller passes in. They are subject-matter, not design system — the DS ships the two axes underneath them (does it recede or does it act, and did a run happen) rather than nine nouns it cannot define. - Addedminor
New
DataTablepattern — a real<table>with column definitions, sorting, row selection, pagination, and designed loading / empty / error states. Sort and selection are the caller's state (sort/onSortChange,selected/onSelectionChange), so the whole view can live in the query string and a sorted, paged, partly-selected table can be linked to a colleague. Selection is keyed by row id, so it survives sorting and paging. Semantics are the point:<caption>,<th scope="col">, one<th scope="row">per row,aria-sorton sortable headers, and a selection checkbox whose accessible name identifies the row. Pure logic (sort cycle, comparators, page-window, selection maths) ships alongside asdata-table-modeland is exported for callers wiring their own URL state. Skeleton gains adata-tablevariant — a header row plus body rows, so the loading state reserves the real silhouette instead of collapsing to a spinner. Not included, deliberately: filtering UI, column resize/reorder, virtualization, grouping.Components - Changedpatch
The three entry animations in
styles/theme.cssnow run at 200ms with no delay, and the reduced-motion class list instyles/tokens.csscovers.animate-pulse..animate-fade-in-upwas 0.5s,.animate-slide-in-left0.5s behind a 0.3s delay, and.animate-scale-in0.4s behind a 0.2s delay — up to 800ms before the reader saw anything, against the 200ms entry ceilingMOTION_PHILOSOPHY.mdhas always set. All three are now0.2s ease-out both. The delays were the worse half: an entry animation is already laid out atopacity: 0, so a delay is time spent looking at nothing. Separately,.animate-pulse— the animationSkeletonrenders on every loading state — was missing from thetokens.cssreduced-motion list, along with.animate-meteorand.animate-meteor-effect. The universal clamp instyles/preflight.csswas already covering all three, so apps importingstyles/index.csswere never affected; apps that importtokens.cssandtheme.cssà la carte and skippreflight.csswere. All three are now listed. Both are held bypackages/ui/__tests__/motion-contract-lock.test.ts, which reads the ceiling out ofMOTION_PHILOSOPHY.mdrather than repeating it, and fails if any bareanimate-*utility inpackages/ui/srcis missing from the list.
@interlace/ui 1.0.01 entry
- Addedminor
The component floor reaches every tier: form, overlay, navigation and display primitives were modelled to the portable 26-rule floor with skeletons, locked breakpoints, and AA contrast measured per composite rather than eyeballed.
Components- @interlace/input
- @interlace/textarea
- @interlace/select
- @interlace/checkbox
- @interlace/radio-group
- @interlace/switch
- @interlace/slider
- @interlace/number-field
- @interlace/form
- @interlace/label
- @interlace/dialog
- @interlace/alert-dialog
- @interlace/sheet
- @interlace/popover
- @interlace/tooltip
- @interlace/hover-card
- @interlace/dropdown-menu
- @interlace/context-menu
- @interlace/tabs
- @interlace/accordion
- @interlace/collapsible
- @interlace/breadcrumb
- @interlace/pagination
- @interlace/toast
- @interlace/card
- @interlace/badge
- @interlace/avatar
- @interlace/alert
- @interlace/separator
- @interlace/progress
Import
5 named exports — pull the parts you need.
import { MIN_VIEWPORT, SKELETON_VARIANTS, SKELETON_VARIANT_CLASSES, Skeleton, SkeletonVariant } from '@/components/ui/skeleton';Anatomy
Extracted from the primitive's JSDoc header. The source is the only documentation that can't drift.
<Skeleton variant="rect" /> ← default, 1rect placeholder
<Skeleton variant="avatar" /> ← circular 36×36
<Skeleton variant="button" /> ← 36×96 rounded-md
<Skeleton variant="article-card" /> ← composite: img + title + meta
<Skeleton variant="rect" count={3} /> ← N placeholders, gap-sm
<Skeleton variant="rect" className="h-12 w-48" /> ← escape hatchAPI reference
Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.
SkeletonProps
Also accepts every <div> attribute.
| Prop | Type | Description |
|---|---|---|
| variant | SkeletonVariant | Silhouette to paint. Defaults to `'rect'` — a generic full-width line placeholder. Use the matching primitive/pattern name for a shape-perfect skeleton (e.g. `variant="avatar"`, `variant="article-card"`). The closed union literally equals the `SKELETON_VARIANTS` tuple in `./skeleton-variants.ts` — adding a new value there extends this type. |
| count | number | Render N copies, stacked vertically with `gap-sm`. Useful for lists (e.g. `<Skeleton variant="text" count={5} />` for a 5-line paragraph). Defaults to 1. |
| label | string | null | Accessible loading-state label exposed to screen readers via a visually hidden span. Defaults to `'Loading…'`. Set to `null` to suppress (when the surrounding region already exposes a busy state). |
Accessibility
Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.
What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.
- Focus + keyboard behaviour
- Native element semantics — no interaction layer to get wrong.
- Focus ring (WCAG 2.2 SC 2.4.13)
- Not focusable — no focus indicator required.
- Reduced motion
- No animation to gate.
- ARIA in the source
role="status"aria-busyaria-live
Examples
4 more states from the same story file.
R-rule compliance
Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.
| Rule | Concept | Where |
|---|---|---|
| R4 | Extends native el + VariantProps | `React.ComponentProps<'div'> & { variant?: SkeletonVariant }` |
| R6 | data-slot on root | `data-slot="skeleton"` + `data-variant` |
| R7 | className merged + ...rest | `cn(SKELETON_VARIANT_CLASSES[variant], className)` + `{...props}` |
| R8 | No `isXxx`; enum for variants | `variant` is the closed `SkeletonVariant` union |
| R14 | Declares min viewport | `data-min-viewport={String(MIN_VIEWPORT)}` + exported const |
| R18 | Tailwind only | Zero inline `style`; SKELETON_VARIANT_CLASSES uses utility classes |
| R19 | Tokens only | `bg-muted` / `animate-pulse` / `rounded-{sm,md,lg,full}` / `gap-md` — all DS tokens |
| R20 | AA contrast (n/a) | Skeleton is non-text — no contrast requirement |
| R25 | Server component | Pure render — no hooks |
| R26 | A11y | `role="status"` + `aria-busy="true"` + visually-hidden text |
Minimum viewport
This primitive declares MIN_VIEWPORT = 320 CSS px (DESIGN_PRINCIPLES #14). When mounted in a container narrower than this, the preflight contract draws a dev-mode outline so the regression is visible during local development.
<body data-interlace-dev>...</body>
Add the data-interlace-dev attribute to the body in development builds only — preflight then outlines any primitive whose container is below its declared data-min-viewport.
Dependencies
- Base UI primitive
- Native / no Base UI dependency
- Lucide icons
- none
- NPM dependencies
- none
- Registry dependencies
Source
The full implementation — components/ui/skeleton.tsx once installed.
import * as React from 'react';
// @interlace/skeleton v1.8.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/skeleton
// What changed since: https://ds.interlace.tools/c/skeleton#history
// Generated banner — keep it, the upgrade diff reads this version.
/**
* @interlace/ui — Skeleton
*
* Loading-state placeholder. ONE component, many shapes — the `variant`
* prop picks the silhouette of the resting component being loaded so the
* page layout doesn't jump when real data arrives.
*
* ## Why one component, not paired `<XSkeleton>` per primitive
*
* - One import path (`@interlace/ui/skeleton`), not 51.
* - One CVA-style variant table → one place to audit shapes against the
* DS catalogue.
* - The `variant` prop's TypeScript union LITERALLY equals the
…502 more lines…Registry JSON
The raw registry record — what the shadcn CLI fetches.