components / skeleton

Skeleton

Loading placeholder blocks for text, cards, and avatar spaces with tokenized shimmer and restrained motion.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Skeleton provides a consistent loading placeholder language so products do not improvise grey boxes and inconsistent shimmer each time.
  • It is intentionally calm and structural, designed to hold space rather than entertain.

Aliases

placeholder, loading skeleton

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Skeleton when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Skeleton contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Skeleton label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Skeleton behind decorative copy or overloaded surface treatments.
  • Do not stretch Skeleton into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Skeleton when the layout is known but the content has not loaded yet.
  • Match the placeholder shape to the surface that will appear so layout shift stays low.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use Skeleton for short operations where a loading state would flash too quickly to help.
  • Do not use Skeleton when the system cannot predict the layout shape at all.

Anti-patterns

  • Using Skeleton as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy skeleton usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

placeholder block

root

Carries placeholder size, shape, and shimmer treatment.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
variant'text' | 'card' | 'avatar''text'Chooses the placeholder shape family.
size'sm' | 'md' | 'lg''md'Chooses the compiled size recipe for the component.
linesnumber1Number of lines to render for text placeholders.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Slots

NameDescription
defaultSkeleton is prop-driven in v1 and does not expose content slots.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • text: Line-based placeholder for body copy or metadata.
  • card: Block placeholder for grouped content surfaces.
  • avatar: Circular or rounded placeholder for identity surfaces.

Sizes

  • sm: Compact placeholder.
  • md: Default placeholder size.
  • lg: Larger placeholder for wider surfaces.

States

  • loading: Visible while content is pending.

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Skeleton is presentational and should not replace meaningful progress messaging when users need explicit status.

Keyboard

  • Skeleton is non-interactive.

Screen readers

  • Treat skeletons as decorative; pair them with a separate status message when loading needs to be announced.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-skeleton-bg
#e5e8ed
--dk-skeleton-shimmer
#f2f5fb
--dk-skeleton-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-skeleton-gap
clamp(0.563rem, 0.5156rem + 0.208vw, 0.703rem)
--dk-skeleton-block-size
0.875rem
--dk-skeleton-inline-size
100%

line

--dk-skeleton-line-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

Implementation notes

  • Use skeletons to preserve layout and calm loading states, not to hide uncertain system behavior.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: loading text

A few lines of loading body copy.

Copy snippet

<Skeleton variant="text" size="sm" lines={3} />

Common patterns

1 example

common

Common: loading summary card

Hold the space for a forthcoming card surface.

Copy snippet

<Skeleton variant="card" size="md" />

Edge cases

1 example

edge

Edge: identity loading state

A placeholder for user or team identity surfaces.

Copy snippet

<Skeleton variant="avatar" size="lg" />

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

text-md

pass

size=md|variant=text

  • Layout: 0 / 120, 240, 360

block-md

pass

size=md|variant=block

  • Layout: 0 / 120, 240, 360

avatar-lg

pass

size=lg|variant=avatar

  • Layout: 0 / 120, 240, 360