Primitive contract

Skeleton

Preserves approximate layout during a truthful loading context without implying that content is loaded, verified, or complete.

Layout-preserving loading placeholder · @sanchika/primitives

Purpose and semantics

Preserves approximate layout during a truthful loading context without implying that content is loaded, verified, or complete.

Recommended semantic: Place aria-busy on the owning region; skeleton shapes are normally aria-hidden and have no role.

Anatomy

owning region

Consumer region carrying aria-busy.

shape

Assistive-hidden layout placeholder.

Finite variants and important states

Variant · form: text, block, row, avatar
Required states: loading, reduced-motion, forced-colors
Class hooks: .sk-skeleton · .sk-skeleton-text · .sk-skeleton-block · .sk-skeleton-row · .sk-skeleton-avatar

Composed synthetic exemplar

Rendered state matrix

Skeleton: 3 required states

Each specimen starts from the package-owned example and contract state inventory. Simulated pointer and focus frames are labelled; consumers still verify real interaction in context.

loadingThe owner exposes busy state while geometry stays stable.

reduced motionThe same settled state remains without movement.

forced colorsSystem colors retain boundaries and focus semantics.

Accessibility and consumer responsibility

Keyboard and screen reader

Skeleton shapes are never focusable.
Use aria-busy on owner
Hide decorative shapes
Provide truthful loading text when needed

Consumer owns

Own aria-busy and loading label
Replace placeholders with real content
Avoid uncontrolled layout shift

Mobile

Shapes stay within available width and avoid layout shift

Reduced motion and forced colors

Animation is removed and the static outline remains.

CanvasText outline remains; filled shimmer is removed

Compact API reference

Package: @sanchika/primitives
CSS: @sanchika/primitives/styles.css
Contract: primitiveSpecs.find((contract) => contract.name === "Skeleton")
Primary class: .sk-skeleton