0059. Skeletons are derived from the layout, or remembered from the last real one
- Status: Accepted (Mik, 17 Nov 2026)
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: none (WP12)
Context
The glossary defines a boundary as "a part of a screen that shows a skeleton until its state is ready". Hand-drawn loading states (a <list each={when(feed.loading)}> of grey bars) are tedious and drift from the content they stand for.
Decision
<boundary loading={feed.loading}> shows a skeleton while loading is truthy, and its content after.
- Derived from the layout. The skeleton is the boundary's own markup built without data: every expression gives a blank value (empty text, a false condition, an empty list), a list shows three blank rows, a placed component is one block, and nothing answers to input or follows state. Text, buttons, images and icons are drawn as bones in the kit Skeleton part's colours and shimmer, which stops with reduced motion. The skeleton is hidden from assistive technology.
- Remembered. With
remember="name", once the content has shown, the boxes of its text, images and controls are stored under that name (in local storage when it is available), and the next skeleton draws those boxes instead: the shape the content last had. - Islands remember their shape without being asked (decision 0057), one per placement: under the placing file and the island's number in it. A page with route parameters keeps one shape per placement, not one per address, so the stored shapes stay as many as the app's placements.
- Content, skeleton and fallback swap with automatic motion (decision 0055).
The kit's Skeleton part remains for loading states drawn by hand; the derived bones share its look.
Native (updated): built in the engine adapter, not in crates/runtime/src/skeleton (decision 0054). A boundary's skeleton is its content drawn as blocks; a remembered one is at least as tall as the content last was. The shapes are kept per app through the storage effect's platform half (the shell's key-value storage, duolith:skeleton-shapes), at most 200, the least recently used going first, so the next launch draws the skeleton at the remembered height (packages/engine/src/shapes.ts). On native a shape is the content's height, not the boxes of each text and image; drawing each box is left for later.
Alternatives considered
| Option | Why not |
|---|---|
| Detect loading from the resources the content reads | Needs the data layer to report reads to boundaries; loading={...} is explicit and works for any state |
| Run component scripts in the skeleton | They would start loads and effects for data that is not there |
| Remember the whole DOM | Large, may hold private text; boxes are enough to draw the shape |
Consequences
A boundary with loading must not read the data in a way that throws during the skeleton build; expressions that throw there give the blank value, so most do not matter.