Docs stable
Loading skeletons
When to use it
useContent that is genuinely async: media cards while the catalog loads, the header while the session resolves, footer socials before hydration.
avoidWhole-surface waits with no known layout. A skeleton promises a shape; if you cannot promise the shape, use a Spinner.
spinneravoidInstant content. A skeleton that flashes for one frame is worse than nothing.
Guidelines
mustSkeleton shapes are color.bg.secondary on the component's own surface. — One quiet color keeps loading states calm and theme-safe in both modes.
mustThe skeleton mirrors the layout it replaces: same footprint, same radius, text bars with varied widths. — Nothing may jump when content lands.
mustMotion is code's job: one slow opacity pulse, disabled under prefers-reduced-motion. Figma shows the resting frame only. — Shimmer effects date fast and fail reduced-motion users.
must-notNo spinners inside skeletons, and no skeleton-within-skeleton nesting. — One loading vocabulary per surface.