skeleton-loaders

Name: skeleton-loaders
Author: gaia-react

20stars3forks

How to install skeleton-loaders?

gaia-react/gaia/skeleton-loaders

$npx -y skills add gaia-react/gaia --skill skeleton-loaders

Installs into the current project.

Summary

For building skeleton loading states that are pixel-perfect matches of real content. Use this skill whenever adding loading states to components, building skeletons for async data, handling pending loader states in route transitions, or implementing the shimmer animation pattern.

Files · 1

View on GitHub

SKILL.md

1	# Skeleton Loaders
2
3	Build skeleton loading states that are pixel-perfect matches of real content.
4
5	## Transparent Text Technique
6
7	Use real HTML elements (`<p>`, `<span>`, `<h2>`, `<button>`) with the same font classes as the real component, plus shimmer + transparency classes. This makes skeletons inherit exact line-height, font-size, and weight, producing pixel-perfect dimensions without hardcoded `h-`/`w-` values.
8
9	### Shimmer class constant
10
11	Define a shared class string at the top of the skeleton component:
12
13	```tsx
14	const shimmer =
15	'animate-shimmer rounded-sm bg-linear-to-r from-slate-950 via-slate-900 to-slate-950 bg-size-[200%_100%] text-transparent select-none';
16	```
17
18	### Text elements
19
20	Copy the real component's element type and font classes, add `shimmer`. How you fill the text depends on whether the real text is static or dynamic:
21
22	- Static, translatable text (labels, headings, button text): use the same `t()` value the real component uses. The text is transparent, but reusing `t()` makes the skeleton width match the revealed text exactly.
23	- Dynamic runtime values (`{data.name}`, API content): you cannot know the real value, so use hardcoded placeholder text of similar character count to approximate its width.
24
25	```tsx
26	import {twJoin} from 'tailwind-merge';
27
28	// Real component
29	<h2 className="text-lg font-bold text-white">{t('profile.heading')}</h2> // static
30	<p className="truncate text-sm font-semibold text-white">{data.name}</p> // dynamic
31	<p className="text-xs text-slate-400">{data.value}</p> // dynamic
32
33	// Skeleton
34	<h2 className={twJoin('text-lg font-bold', shimmer)}>{t('profile.heading')}</h2> // same t(), exact width
35	<p className={twJoin('truncate text-sm font-semibold', shimmer)}>Name</p> // approximate
36	<p className={twJoin('text-xs', shimmer)}>Example value</p> // approximate
37	```
38
39	### Non-text elements (images, icons, avatars)
40
41	Keep as empty divs with the shimmer class, no text needed:
42
43	```tsx
44	<div className={twJoin('size-14 shrink-0', shimmer)} />
45	```
46
47	### Interactive elements (buttons)
48
49	Use the real element type with `tabIndex={-1}` to prevent focus. Button labels are static text, so use the real `t()` value (exact width on reveal):
50
51	```tsx
52	<button
53	className={twJoin('w-full py-2 text-xs font-medium', shimmer)}
54	tabIndex={-1}
55	type="button"
56	>
57	{t('common.submit')}
58	</button>
59	```
60
61	## 200ms Delay Pattern
62
63	Avoid skeleton flash on fast loads. Show stale/empty content for 200ms before revealing the skeleton:
64
65	```tsx
66	const [showSkeleton, setShowSkeleton] = useState(false);
67
68	// Valid Effect: synchronizing component state with a timer (external system).
69	// The cleanup prevents a state update after unmount.
70	useEffect(() => {
71	const timer = setTimeout(() => setShowSkeleton(true), 200);
72	return () => clearTimeout(timer);
73	}, []);
74
75	if (!showSkeleton) return null; // or return stale content
76	return <MySkeleton />;
77	```
78
79	## When to Use
80
81	- Lazy-loaded panels (side panels, detail views)
82	- Fetcher-driven content swaps
83	- Async data sections (lists, profiles, detail views)
84	- Route transitions with pending loader data
85
86	## Accessibility
87
88	Skeleton text is transparent, but screen readers still announce it (placeholder text and any `t()` labels). Hide the skeleton from assistive tech and announce loading instead:
89
90	- Put `aria-hidden` on the skeleton's root element so assistive tech skips the decorative placeholders.
91	- Mark the region that will receive the content with `aria-busy="true"` while loading, or render a visually-hidden `role="status"` "Loading" message so screen-reader users know content is on the way.
92
93	## Full Example Implementation
94
95	```tsx
96	import {twJoin} from 'tailwind-merge';
97
98	const shimmer =
99	'animate-shimmer rounded-sm bg-linear-to-r from-slate-950 via-slate-900 to-slate-950 bg-size-[200%_100%] text-transparent select-none';
100
101	const ExampleSkeleton = () => (
102	<div aria-hidden className="border border-slate-700 bg-slate-900">
103	<div className="flex items-center gap-3 p-3">
104	<div className={twJoin('size-14 shrink-0', shimmer)} />
105	<div className="min-w-0 flex-1">
106	<p className={twJoin('truncate text-sm font-semibold', shimmer)}>
107	Name
108	</p>
109	<p className={twJoin('truncate text-xs', shimmer)}>Example value</p>
110	</div>
111	</div>
112	</div>
113	);
114
115	export default ExampleSkeleton;
116	```

People who liked this also viewed

6 picks

Type

skeleton-loaders

20stars3forks

View on GitHub

How to install skeleton-loaders?

gaia-react/gaia/skeleton-loaders

$npx -y skills add gaia-react/gaia --skill skeleton-loaders

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Skeleton Loaders
2
3	Build skeleton loading states that are pixel-perfect matches of real content.
4
5	## Transparent Text Technique
6
7	Use real HTML elements (`<p>`, `<span>`, `<h2>`, `<button>`) with the same font classes as the real component, plus shimmer + transparency classes. This makes skeletons inherit exact line-height, font-size, and weight, producing pixel-perfect dimensions without hardcoded `h-`/`w-` values.
8
9	### Shimmer class constant
10
11	Define a shared class string at the top of the skeleton component:
12
13	```tsx
14	const shimmer =
15	'animate-shimmer rounded-sm bg-linear-to-r from-slate-950 via-slate-900 to-slate-950 bg-size-[200%_100%] text-transparent select-none';
16	```
17
18	### Text elements
19
20	Copy the real component's element type and font classes, add `shimmer`. How you fill the text depends on whether the real text is static or dynamic:
21
22	- Static, translatable text (labels, headings, button text): use the same `t()` value the real component uses. The text is transparent, but reusing `t()` makes the skeleton width match the revealed text exactly.
23	- Dynamic runtime values (`{data.name}`, API content): you cannot know the real value, so use hardcoded placeholder text of similar character count to approximate its width.
24
25	```tsx
26	import {twJoin} from 'tailwind-merge';
27
28	// Real component
29	<h2 className="text-lg font-bold text-white">{t('profile.heading')}</h2> // static
30	<p className="truncate text-sm font-semibold text-white">{data.name}</p> // dynamic
31	<p className="text-xs text-slate-400">{data.value}</p> // dynamic
32
33	// Skeleton
34	<h2 className={twJoin('text-lg font-bold', shimmer)}>{t('profile.heading')}</h2> // same t(), exact width
35	<p className={twJoin('truncate text-sm font-semibold', shimmer)}>Name</p> // approximate
36	<p className={twJoin('text-xs', shimmer)}>Example value</p> // approximate
37	```
38
39	### Non-text elements (images, icons, avatars)
40
41	Keep as empty divs with the shimmer class, no text needed:
42
43	```tsx
44	<div className={twJoin('size-14 shrink-0', shimmer)} />
45	```
46
47	### Interactive elements (buttons)
48
49	Use the real element type with `tabIndex={-1}` to prevent focus. Button labels are static text, so use the real `t()` value (exact width on reveal):
50
51	```tsx
52	<button
53	className={twJoin('w-full py-2 text-xs font-medium', shimmer)}
54	tabIndex={-1}
55	type="button"
56	>
57	{t('common.submit')}
58	</button>
59	```
60
61	## 200ms Delay Pattern
62
63	Avoid skeleton flash on fast loads. Show stale/empty content for 200ms before revealing the skeleton:
64
65	```tsx
66	const [showSkeleton, setShowSkeleton] = useState(false);
67
68	// Valid Effect: synchronizing component state with a timer (external system).
69	// The cleanup prevents a state update after unmount.
70	useEffect(() => {
71	const timer = setTimeout(() => setShowSkeleton(true), 200);
72	return () => clearTimeout(timer);
73	}, []);
74
75	if (!showSkeleton) return null; // or return stale content
76	return <MySkeleton />;
77	```
78
79	## When to Use
80
81	- Lazy-loaded panels (side panels, detail views)
82	- Fetcher-driven content swaps
83	- Async data sections (lists, profiles, detail views)
84	- Route transitions with pending loader data
85
86	## Accessibility
87
88	Skeleton text is transparent, but screen readers still announce it (placeholder text and any `t()` labels). Hide the skeleton from assistive tech and announce loading instead:
89
90	- Put `aria-hidden` on the skeleton's root element so assistive tech skips the decorative placeholders.
91	- Mark the region that will receive the content with `aria-busy="true"` while loading, or render a visually-hidden `role="status"` "Loading" message so screen-reader users know content is on the way.
92
93	## Full Example Implementation
94
95	```tsx
96	import {twJoin} from 'tailwind-merge';
97
98	const shimmer =
99	'animate-shimmer rounded-sm bg-linear-to-r from-slate-950 via-slate-900 to-slate-950 bg-size-[200%_100%] text-transparent select-none';
100
101	const ExampleSkeleton = () => (
102	<div aria-hidden className="border border-slate-700 bg-slate-900">
103	<div className="flex items-center gap-3 p-3">
104	<div className={twJoin('size-14 shrink-0', shimmer)} />
105	<div className="min-w-0 flex-1">
106	<p className={twJoin('truncate text-sm font-semibold', shimmer)}>
107	Name
108	</p>
109	<p className={twJoin('truncate text-xs', shimmer)}>Example value</p>
110	</div>
111	</div>
112	</div>
113	);
114
115	export default ExampleSkeleton;
116	```

People who liked this also viewed

6 picks

Type