Don't Just Spin: Skeleton Screens for Your Vibe Project
Of 800 page loads only 356 feel fast to users: a skeleton screen does not make an app genuinely faster — it makes waiting visible, with shapes copied from the real thing, heights locked still, and failures stated plainly. All example projects, people, and numbers in this guide are fictional.

Xiao Xing built a reading app called StarChart Reading List. Its home page is rows of book-list cards: a cover, a title, one line of recommendation, and how many people read it. Two months after launch, users were growing nicely — and so were the one-star reviews, almost all saying the same thing: "Opening the home page takes forever, the screen is blank white, I thought the app had frozen." Xiao Xing checked the data: home-page data took 2 seconds on average to arrive, and for those 2 seconds the screen showed nothing but a small circle spinning in the middle. His first instinct was to make the loading animation bigger: a larger spinner, plus a line saying "Loading, please wait." The complaints did not drop. Instead a new one appeared: "It spun for ages — how much longer?" That was when he understood: the problem was not that the circle was too subtle. For those 2 seconds users could see nothing — not what the page looked like, not how long remained, not whether the app had frozen. He tried something else: before the data arrived, draw the shape of the cards first — gray squares for covers, gray bars for titles, a gray line for the recommendation, like a pencil sketch before the paint. When the data arrived, each block filled in with real content. In the first week after the change, the home page bounce rate dropped, and the comments changed: "It feels like it opens instantly." The data still took 2 seconds — not one second faster. What changed was what users saw during those 2 seconds.
Two things to make clear first. First, the walkthrough project "StarChart Reading List," its maker "Xiao Xing," and every date and number in this guide are fictional, invented only to make the process concrete. Second, the boundary: this site has already published a loading progress guide — progress bars and percentages, telling users "how much longer"; a loading, empty, and error states guide — how the three states switch; and performance optimization and performance budget guides — how to make things genuinely faster. This guide is none of those. It is about one specific craft: before the data arrives, show users the shape of the content, so waiting feels like "things growing in" instead of "stuck."

Step one: Know what skeletons, spinners, and progress bars are each for
There are four common loading patterns, and people often pick one at random and ship it — in the wrong situation. The first is a blank page: nothing shows until the data arrives and the content appears all at once. It is the worst of the four; faced with blankness, users can only guess, and their guess is usually "it broke." The second is a spinner: a circle turning in the middle, saying "working on it." It communicates exactly one thing — not ready yet — and says nothing about how long remains or what the page will look like. The third is a progress bar: a line crawling from 0 to 100%, sometimes with a percentage. It beats the spinner because it gives an expectation of "how much longer," but it says nothing about shape — users still have no idea what they are waiting for. The fourth is a skeleton screen: draw the shape of the content first — square covers, two lines of title, one short line of recommendation — then fill in real data as it arrives. It answers two questions at once: "the page looks like this" and "things are filling in."
Which one to pick depends on two conditions. First, does what you are waiting for have a fixed shape? Lists, cards, and detail pages do, so skeletons fit them best; uploading a file or generating an image has no fixed shape, and a progress bar fits those better. Second, how long is the wait? Under half a second, add nothing — it flashes past. From half a second to 3 seconds, skeletons are the most comfortable. Past 3 seconds, a skeleton alone is not enough — add a progress hint or load in stages. My judgement is this: a skeleton is not an upgraded spinner; it is a different idea. A spinner says "please wait." A skeleton says "look, things are growing in." Xiao Xing's home page is a fixed-shape card list with a 2-second wait — right in the skeleton's sweet spot.
Step two: Four rules for drawing skeletons — copy the real content
How good a skeleton looks depends entirely on how much it resembles the real content. Rule one: copy the shapes. If the cover is square, draw a square; if the avatar is round, draw a circle; if the title runs two lines, draw two lines. Never fob a page off with a row of generic bars. Users memorize shapes during the skeleton phase, and when the data lands and the shape does not match, their eyes jump — that jump is the feeling of "flicker." Rule two: match the gray tones and the spacing to the real content. The gray must not be too dark — too dark looks like real content and users mistake it for loaded — nor too pale, or it disappears in sunlight. Spacing matters even more: if real cards sit 16 pixels apart, the gray blocks must sit 16 pixels apart too, so that when the data fills in, nothing moves and the eye never has to find its place again.
Rule three: do not draw more than the first screen holds. If four cards fit on the first screen, draw four — one extra is a lie. Xiao Xing's first version drew 8 skeleton cards when only 4 fit on screen; when the data arrived, the bottom 4 vanished, the page height shrank suddenly, and users flickered again. 4 cards, and the moment they filled in, everything lined up exactly. Rule four: never use a skeleton to hide an error. If the data request fails, the skeleton should leave and an error state should take its place — one plain sentence and a "Retry" button. Letting the skeleton spin forever as if it were still loading is the most trust-destroying move there is: users wait 10 seconds before realizing nothing was loading at all, and next time they will not wait.
Step three: Keep the motion light — a glaring shimmer is worse than none
The usual skeleton animation is a soft light sweeping left to right, signalling "loading." Done well it helps; done badly the whole page flashes. Three rules from my experience. First, make the shimmer slow — one sweep takes about 1.2 to 1.6 seconds. Faster looks like a warning light; slower looks stuck. Second, keep the brightness contrast small. The gray blocks are already visible enough; the shimmer should only brush past gently. Bright enough to dazzle is too bright. Third, move the whole page's skeletons together — do not let each card sweep on its own rhythm, or the chaos is worse than stillness. There is also a simpler option that works fine: do not move at all. A static skeleton is perfectly good in many cases, especially on dense pages, where still gray blocks are calmer.
One thing you must not forget: some users have "Reduce motion" turned on in their system settings, and your skeleton animation must respect it. It is not complicated — read the system preference, and when reduced motion is on, switch the shimmer off and leave a static skeleton. This is not a nice extra; it is basic courtesy. For people sensitive to motion, a page full of sweeping light is not a hint — it is torture. Xiao Xing learned this the hard way: he added a bright sweeping animation to his skeleton, and a user wrote in saying the home page made them dizzy every time they opened it. The complaints stopped when the animation was turned off. A loading animation is for the user, not for the author's self-expression.
Step four: The handover moment decides whether the skeleton worked
The most important moment for a skeleton is the instant real content fills in. There are two ways to hand over. One is to swap the whole screen at once: when all the data arrives, the skeleton leaves in one go and the content appears in one go. The other is to replace block by block: whichever piece of data arrives first fills in first — cover first, then title. Whole-screen is simple and clean, and fits pages where all the data arrives together; block-by-block feels faster and fits data that arrives in stages, but watch the rhythm — a cover with no title for half a second makes the page feel "missing a piece." Xiao Xing's home data arrives all at once, so he chose the whole-screen swap, with one detail: no fade-in animation when the content appears — it just appears. A fade sounds elegant, but it makes users wait another half second before they can read the words. In a loading scene, direct beats elegant.
The thing to guard against at handover is layout shift: the content arrives, the page height changes, everything below gets pushed down, and the line the user was reading suddenly runs away. There is only one defence: lock the heights. Whatever height the gray blocks occupy in the skeleton phase, the real content must occupy the same height. Before an image finishes loading, hold its place with a fixed-ratio placeholder block, then fill the image in without moving anything. The lazy-loading guide on this site makes the same point about placeholders: reserve the space first, fill it later. Xiao Xing's card covers are 3 by 4, so every cover slot gets a 3-by-4 gray block; the image drops straight in, and the whole page stays perfectly still. Users never feel the shift — that is what "fast" feels like.
Step five: Check it with a funnel — fix whichever step leaks most
A skeleton cannot be judged by feel — "it seems faster now." It needs numbers. Xiao Xing's method is to take 800 home-page loads as the funnel's starting point and count down step by step. Of 800 loads, the skeleton appeared in time 671 times — 129 short. Sometimes the skeleton code itself waited for the data before rendering, so it was late; sometimes the page loaded in a flash and the skeleton never had a chance to appear — that is not really a leak, but Xiao Xing records it anyway, because until you can tell "no need to appear" from "too late to appear," you cannot improve it. Of those 671, the skeleton matched the real layout 548 times — 123 short. Sometimes the skeleton drew 3 cards when the real content brought 5; sometimes the title was drawn as one line when it needed two. Of those 548, the loading passed with no layout shift 439 times — 109 short, mostly because images had no reserved space and pushed the cards below them down when they arrived. Of those 439, users ended up feeling it was "fast" 356 times — 83 short. Nothing was wrong with those loads, but the skeleton appeared too late or flashed past too quickly for users to even register it, so it still felt like "waiting a bit." 800, 671, 548, 439, 356; the losses are 129, 123, 109, and 83, which add up to exactly 444 — the same as 800 minus 356. The books balance.

The step-by-step conversion rates are worth reading too: 671 out of 800 is 84%, 548 out of 671 is 82%, 439 out of 548 is 80%, 356 out of 439 is 81%, and overall 356 out of 800 is 44.5%. The numbers told Xiao Xing three things. First, the losses were evenly spread — no step fell off a cliff — which meant no single part was broken; every part had a small flaw. Second, steps two and three were the most worth fixing first: skeleton not matching real content, and images pushing cards down — 232 together, both caused by not drawing the skeleton carefully enough, and both cheap to fix. Third, the 83 in the last step were a reminder that feeling has its own rhythm: a skeleton that flashes past might as well not have appeared, and one that arrives too late is wasted work — a skeleton has to stay on screen long enough to be seen. Xiao Xing fixed two things first: he changed the skeleton's card count and line counts to match the real content item by item, gave every image slot a fixed-ratio placeholder, and moved the skeleton's trigger from "when the data request starts" to "when the page starts rendering," so it arrived half a second earlier. On re-check, matching rose from 82% to 91%, no-shift rose from 80% to 89%, and users who felt it was "fast" rose from 356 to 431. The data still took 2 seconds — not one second faster — but it felt fast. That is the whole point of a skeleton screen.
Pre-launch checklist: tick every box before you ship
Before the skeleton goes live, walk this list and tick every box. First, the skeleton's shapes, counts, and line counts match the real content item by item — compare screenshots side by side once. Second, the skeleton appears before the data request, not after the data comes back. Third, image slots hold fixed-ratio placeholders, so the page height does not move when content fills in. Fourth, when loading fails, the skeleton leaves and a plain sentence plus a "Retry" button take its place — never spin forever pretending to be busy. Fifth, the shimmer is slow and gentle enough, and switches off automatically when the system has reduced motion turned on. Sixth, dark mode gets its own dark-gray skeleton — a light-gray skeleton on a dark background glares. Seventh, pages that load within half a second get no skeleton at all — a flash is worse than blank. Eighth, test on a real phone on a slow network — "feels fast" in a simulator does not count. If any one of these eight is not done, do not ship yet. A skeleton is a craft of details, and if the details are wrong, it is just a pile of gray blocks.
Where skeletons do not belong
Not every wait suits a skeleton. The first is a load whose result is uncertain: search, filters, recommendations — the number and shape of results change every time, so a skeleton would be a guess, and a wrong guess flickers worse than nothing. Those pages do better with a plain status first, like "Finding 12 books for you," then showing everything at once when the results arrive. The second is the wait after an action: half a second after tapping "Save," or waiting for a receipt after tapping "Send." What users want there is "did it work?" — not "what does the page look like?" — and a clear success message beats a skeleton. The third is a page whose skeleton would be more complicated than its content: some pages are so deeply structured that the skeleton needs a dozen gray blocks, and one glance makes users dizzy — a simple loading hint is better. Xiao Xing's rule is to use skeletons only on pages where the shape is fixed, the content arrives in pieces, and the wait is longer than half a second. Miss any one of the three, and pick another pattern. A tool exists to solve a problem, not to be shown off on every page.
The five most common traps — do not walk into them
The first trap is a skeleton that looks nothing like the real content. Two lines drawn for a title that is really one line; a square drawn for a cover that is really portrait. The moment the data fills in, the page jolts, and users instantly feel "that was fake." The second is a skeleton that flashes past in 0.1 seconds. The data came back too fast, the skeleton appeared for a blink, and the screen flicker feels worse than blank. The fix is a minimum display time — say 0.3 seconds — so even fast data waits for the skeleton to stand still before swapping. The third is an endless skeleton list. Someone draws 100 skeleton cards for a 100-item list, and the page is all gray blocks down to the bottom. Remember: skeletons only cover the first screen; beyond that, draw nothing. The fourth is using a skeleton to cover up a failed load. The request failed and the skeleton keeps spinning; users wait 10 seconds before realizing nothing was loading, and the trust is gone in one go. The fifth is forgetting dark mode. A light-gray skeleton on a dark background has such high contrast it glares, and the whole page seems to flash. Dark mode needs its own shade of skeleton gray — do not lazily share one set.
One honest sentence to end on. A skeleton screen will never make your app genuinely faster — it only makes waiting bearable. But between "bearable" and "stuck" lies the difference between a user who stays and one who leaves. After the redesign, StarChart Reading List still took 2 seconds for home data, yet users who felt it was "fast" rose from 356 to 431 — not because of a faster server, but because of more honest gray blocks: shapes copied from the real thing, heights locked still, and failures stated plainly. Users do not mind waiting 2 seconds. What they cannot stand is 2 seconds of not knowing what they are waiting for. A skeleton screen exists to explain those 2 seconds.
The project, people, and numbers in this guide are fictional walkthrough examples; the wait times and conversion figures are examples, not the performance of any real product.
Comments (0)
Related articles
One page should stand up on a phone, a tablet, and a computer. This guide follows MDN's Responsive web design, Using media queries, and the viewport meta reference: fluid HTML, the viewport tag, fluid grids and max-width, images that never burst their container, media query syntax, breakpoints set by content, mobile first, responsive type, testing capability instead of width, and a pre-launch checklist.
On 19 November 2026, OpenAI disclosed its internal Performance Factory: Codex agents automatically investigate ChatGPT performance regressions, running 1,700+ investigations in three months and finding 600+ root causes. Yet only about 15 fixes were merged exactly as Codex wrote them — agents can take over the investigating, but fixing still needs a human.
localStorage only stores strings and has no indexes. IndexedDB is a real database in the browser: structured data, far larger capacity, indexes, and transactions. Following MDN's Using IndexedDB, IDBDatabase, and IDBObjectStore: the five-step routine, opening, upgrades, keys, indexes, transactions, add versus put, get, cursors, ranges, and multi-tab upgrades.