sveltelean Primitives
Version v0.18.0
A card that is loading

Loading the team

Code
<script lang="ts">
	// Nothing to import at runtime: the placeholders are CSS. The stylesheets are optional.
	import '@svelte-lean/styles/progress.css';
	import '@svelte-lean/styles/skeleton.css';
</script>

<!-- The loading state in words, outside the busy region. -->
<p class="status" role="status">
	<progress data-slean="progress" data-variant="circular" data-size="small" aria-hidden="true"></progress>
	Loading the team
</p>
<div class="card" aria-busy="true">
	<div class="person">
		<span data-slean="skeleton" data-variant="circular" aria-hidden="true"></span>
		<div class="lines">
			<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
			<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
		</div>
	</div>
	<span data-slean="skeleton" data-variant="rounded" aria-hidden="true"></span>
	<div class="lines">
		<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
		<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
		<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
	</div>
</div>

<style>
	.status {
		display: flex;
		align-items: center;
		gap: var(--slean-space-2);
		margin-block: 0 var(--slean-space-3);
	}

	.card {
		display: grid;
		gap: var(--slean-space-4);
		max-inline-size: 24rem;
	}

	.person {
		display: flex;
		align-items: center;
		gap: var(--slean-space-3);
	}

	.lines {
		flex: 1;
	}
</style>
The placeholders are aria-hidden; the status line outside the busy region carries the text. Under reduced motion they stay flat.

Examples

Swapping in the content

Reload a profile

Amara Okafor

Design lead, Istanbul

Works on the design system and the documentation site. Reviews every new primitive.

Code
<script lang="ts">
	import '@svelte-lean/styles/button.css';
	import '@svelte-lean/styles/progress.css';
	import '@svelte-lean/styles/skeleton.css';

	let loading = $state(false);

	function reload() {
		loading = true;
		// Stands in for a request.
		setTimeout(() => (loading = false), 1800);
	}
</script>

<div class="toolbar">
	<button type="button" data-slean="button" data-variant="outlined" data-color="neutral" onclick={reload}>Reload</button>
	<!-- In the page from the start and empty: the text written into it is read. -->
<p class="status" role="status">
	{#if loading}
		<progress data-slean="progress" data-variant="circular" data-size="small" aria-hidden="true"></progress>
		Loading the profile
	{/if}
</p>
</div>
<div class="card" aria-busy={loading}>
	{#if loading}
		<div class="person">
			<span data-slean="skeleton" data-variant="circular" aria-hidden="true"></span>
			<div class="lines">
				<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
				<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
			</div>
		</div>
		<div class="lines">
			<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
			<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
		</div>
	{:else}
		<div class="person">
			<span class="avatar" aria-hidden="true">AO</span>
			<div class="lines">
				<strong>Amara Okafor</strong>
				<p>Design lead, Istanbul</p>
			</div>
		</div>
		<p>Works on the design system and the documentation site. Reviews every new primitive.</p>
	{/if}
</div>

<style>
	.toolbar {
		display: flex;
		align-items: center;
		gap: var(--slean-space-3);
		margin-block-end: var(--slean-space-4);
	}

	.card {
		display: grid;
		gap: var(--slean-space-4);
		max-inline-size: 24rem;
	}

	.person {
		display: flex;
		align-items: center;
		gap: var(--slean-space-3);
	}

	.lines {
		flex: 1;
	}

	.card p {
		margin: 0;
	}

	.lines p {
		color: var(--slean-fg-muted);
		font-size: var(--slean-text-sm);
	}

	.avatar {
		display: grid;
		place-items: center;
		inline-size: 2.5rem;
		block-size: 2.5rem;
		border-radius: var(--slean-radius-full);
		background: var(--slean-muted);
		font-size: var(--slean-text-sm);
		font-weight: var(--slean-font-weight-medium);
	}
</style>
The placeholders and the content are replaced in one update; the status line says what is loading.

A list

Messages
Code
<script lang="ts">
	import '@svelte-lean/styles/skeleton.css';
</script>

<ul class="rows" aria-busy="true" aria-label="Messages">
	{#each [1, 2, 3] as row (row)}
		<li>
			<span data-slean="skeleton" data-variant="circular" data-size="small" aria-hidden="true"></span>
			<div class="lines">
				<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
				<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
			</div>
		</li>
	{/each}
</ul>

<style>
	.rows {
		display: grid;
		gap: var(--slean-space-4);
		max-inline-size: 24rem;
		margin: 0;
		padding: 0;
		list-style: none;
	}

	.rows li {
		display: flex;
		align-items: center;
		gap: var(--slean-space-3);
	}

	.lines {
		flex: 1;
	}
</style>

Looks

circular, text, rectangular and rounded
Code
<script lang="ts">
	import '@svelte-lean/styles/skeleton.css';
</script>

<div class="shapes" aria-hidden="true">
	<div class="circles">
		<span data-slean="skeleton" data-variant="circular" data-size="small"></span>
		<span data-slean="skeleton" data-variant="circular"></span>
		<span data-slean="skeleton" data-variant="circular" data-size="large"></span>
	</div>
	<div>
		<span data-slean="skeleton" data-variant="text"></span>
		<span data-slean="skeleton" data-variant="text"></span>
	</div>
	<!-- rectangular and rounded take their size from the application's CSS. -->
	<div class="circles">
		<span data-slean="skeleton" data-variant="rectangular" class="thumbnail"></span>
		<span data-slean="skeleton" data-variant="rounded" class="thumbnail"></span>
	</div>
</div>

<style>
	.shapes {
		display: grid;
		gap: var(--slean-space-4);
		max-inline-size: 24rem;
	}

	.circles {
		display: flex;
		align-items: center;
		gap: var(--slean-space-3);
	}

	.thumbnail {
		inline-size: 8rem;
		block-size: 5rem;
	}
</style>
The last of several text lines is shorter; a circular one takes the small or large size.

Usage

Plain markup with a stylesheet: install @svelte-lean/styles. No JavaScript runs.

npm install @svelte-lean/styles
stylesheets
import '@svelte-lean/styles/skeleton.css';

Render the placeholders inside the element the content will fill, give it aria-busy="true", and replace them with the content in one update.

Say that the region is loading in text outside the busy region, in a status region that is in the page before the wait begins: a screen reader may skip the content of a busy region.

Anatomy

PartElementdata-slean-partRequiredNotes
root<span data-slean="skeleton" aria-hidden="true">–yesdata-variant="text|rectangular|rounded|circular"; data-size="small|large" on a circular one.
busy region<div aria-busy="true">–yesThe element the content will fill. The loading text stays outside it.
status<p role="status">–yesSays what is loading, in words, outside the busy region; in the page before the wait begins. A small circular progress beside the text may be aria-hidden.

Keyboard

KeyWhenResult
TabanywhereSkips the placeholders: they are not focusable

Styling

skeleton.css gives each shape the muted tint and a band of the hover tint in a background three times the box’s width. A keyframe animation moves the band across; at rest, and under reduced motion, the band sits outside the box. The last of several text lines is shorter. Under forced colors the shapes become outlines. The tokens it reads:

TokenDefault (light)Applies to
--slean-radius-smcalc(var(--slean-radius) * 0.6)border-radius
--slean-mutedvar(--slean-neutral-3)background-color
--slean-muted-hovervar(--slean-neutral-4)background-image
--slean-duration-slow240msanimation
--slean-control-height-md2.25reminline-size, block-size
--slean-control-height-sm2reminline-size, block-size
--slean-radius-mdvar(--slean-radius)border-radius

State selectors the stylesheet targets, all from the platform or ARIA: :dir(rtl), :first-child, :last-child.

Variant attributes: data-variant (text, circular, rectangular, rounded); data-size (small, large).

Controlled integration

The application owns the loading state. With {#await} the placeholders are the pending branch and the content the resolved one, so they are replaced in one update.

team.svelte
<script lang="ts">
	import Team from './Team.svelte';

	const team = fetch('/api/team').then((response) => response.json());
</script>

{#await team}
	<p class="status" role="status">
	<progress data-slean="progress" data-variant="circular" data-size="small" aria-hidden="true"></progress>
	Loading the team
</p>
	<div aria-busy="true">
		<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
		<span data-slean="skeleton" data-variant="text" aria-hidden="true"></span>
	</div>
{:then members}
	<div aria-busy="false"><Team {members} /></div>
{/await}

Under the hood

Runtime and size
Tier
0 · Native
Behavior JS
0 B brotli · 0 B gzip · fixtures/results.json (native-only) · method
Platform features
aria-hidden, aria-busy, prefers-reduced-motion, :dir(rtl)
Shared listeners
none
Per-instance listeners
none
Lazy state
none
Native base
aria-hidden placeholders in an aria-busy region

Tier 0: the skeleton has no behavior module, the Vite plugin maps skeleton to no module, and the page ships no Svelte Lean JavaScript for it. The shimmer is a CSS animation.

Why this implementation

A skeleton keeps the layout in place while content loads, so the page does not jump when it arrives. It is a visual device: an empty shape means nothing to a screen reader, and a list of empty shapes read aloud is noise.

Svelte Lean ships the shapes as CSS, hidden with aria-hidden, and a contract that puts the meaning elsewhere: aria-busy on the region that will hold the content, and the loading state in text outside that region.

The browser owns

  • removing the placeholders from the accessibility tree (aria-hidden)
  • telling assistive technology that the region is updating (aria-busy)
  • running the CSS animation, and reporting the reduced motion preference

Svelte Lean owns

  • skeleton.css: the text, rectangular, rounded and circular shapes, the shorter last line, the sizes
  • the shimmer, flat at rest and under reduced motion
  • the contract
  • documentation
Accessibility
  • Each placeholder is empty and aria-hidden="true".
  • The region that is loading carries aria-busy="true" until the content is in place.
  • The loading state is said in text outside the busy region.
  • Under reduced motion the duration tokens are zero and the placeholders are a flat tint.
Platform features
FeatureBaselineOutside the target
aria-hidden, aria-busyARIA 1.1 states, exposed by every current browserNot applicable; screen readers differ in their use of aria-busy
:dir()Baseline 2023The shimmer moves from left to right under RTL as well
Without JavaScript

The placeholders are CSS and render; they stay until the application’s script replaces them. A page whose content arrives only through the script needs a server-rendered alternative.

Server rendering and hydration

Render the placeholders on the server when the content is fetched in the browser. Content the server renders needs no skeleton.

Nothing is attached. The placeholders rendered on the server stay until the application replaces them.

Compatibility

aria-hidden and aria-busy are ARIA 1.1 states, exposed by every current browser; screen readers differ in what they do with aria-busy. :dir() (Baseline 2023) reverses the shimmer under RTL.

Tests and source