Actions & feedback

Skeleton

A decorative loading placeholder that reserves the final content footprint.

SkeletonSkeletonProps

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

import { Skeleton } from '@ai-created/ui';

export function Example() {
  return <Skeleton className="h-40 w-full max-w-full" />;
}

Import

tsx

import { Skeleton } from '@ai-created/ui';

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Placeholder block

Required

Consumer-sized pulse surface matching future content.

div

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Feedback/Skeleton

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish primitive shape presets but require authored compositions to match final content.

Auto layout

Direction: vertical
Gap: 8px for composition examples
Padding: 0px
Alignment: Stretch or align to target content
Wrap: Composition controlled

The exported code component is one block; multi-line examples are grouped instances.

Resizing

Width: fill
Height: fixed
Minimum width: 16px
Maximum width: Parent controlled
Minimum height: 4px
Maximum height: Target content height
Overflow: clip

Width and height must match the content being reserved.

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
Shape preset	variant	content	className sizing and radius utilities	content, text, avatar
Width preset	variant	full	className width utility	short, medium, full

Nested assets and slots

Placeholder block

primitive / required

One decorative loading surface.

<Skeleton className="..." />

Content limits

Composition

Represent only the primary visible structure, usually three to seven blocks

Overflow: Remove low-value decorative placeholders.

Too many shapes create noise and inaccurate expectations.

Localization and RTL

Primitive geometry is direction-neutral; compositions follow content reading order.
Verify placeholder widths are not based only on English copy.
Test reduced motion.

Responsive behavior

Dimensions follow the final responsive content.

Use the same breakpoints as the resolved component

Update shape count and widths with the final layout.
Prevent layout shift at every supported width.

Authoring limits

Figma animation is illustrative and does not validate reduced-motion behavior.
The primitive does not announce loading; the surrounding region must do so.

Accountable owner

Design systems feedback owner

Canonical source: src/components/Skeleton.tsx

New presets must correspond to repeated production content footprints.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Radius

6px by default

Width and height

Consumer-defined

Animation

Tailwind pulse; disabled for reduced motion

Rules

Match the dimensions and shape of the content being loaded.
Preserve stable layout between placeholder and resolved content.

Token dependencies

--color-surface2

Placeholder fill.

--radius-md

Default radius.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

loading

Trigger: Content is pending.
Visual response: Surface2 block pulses unless reduced motion is requested.
Behavior: Reserves layout only.
Accessibility: Hidden from the accessibility tree.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Decorative <div aria-hidden="true">.
Accessible name: No accessible name; the surrounding loading region owns status.

Provide a separate loading announcement when users need one.
Do not put focusable content inside the skeleton.
Respect reduced-motion behavior.

Keyboard behavior

No component-specific keyboard behavior. Native document behavior remains unchanged.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { Skeleton } from '@ai-created/ui';

Server Component compatible

Set dimensions and alternate shapes with className.
The placeholder is always aria-hidden and forwards div attributes.

tsx

<Skeleton className="h-5 w-32" />

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
className	string	undefined	Controls size and shape with utility classes.
...props	HTMLAttributes<HTMLDivElement>	undefined	Native div attributes.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Approximate the final content structure.
Use a small group of meaningful shapes.

Do not

Do not use arbitrary decorative skeleton grids.
Do not leave skeletons visible after loading fails.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Forwards className, ref, and div attributes.
Always emits aria-hidden true.

Interaction

Replaced content does not cause large layout shift.

Accessibility

Loading status exists outside the hidden placeholder when required.

Visual

Compare content and skeleton dimensions; verify reduced-motion rendering.

Related specifications

empty-state notice