no-ui-flash
Installation
SKILL.md
Never flash the wrong UI
Client-rendered apps have a window between first paint and the moment client-side data resolves. The classic bug is filling that window with a placeholder that bets on one outcome — and losing the bet:
- An app-shell skeleton (sidebar, nav, content cards) shown to a signed-out visitor who is about to be bounced to login. They're shown an app they'll never reach, then a jarring swap.
- A results-grid skeleton on a search/list page that resolves to "no results found" — the skeleton promised content that doesn't exist.
- A light-theme first paint that snaps to dark once a preference loads.
- A skeleton for a route that turns out to be a 404.
The rule: render the placeholder for the state you have verified, not the state you hope for. When you can't verify, render a placeholder that's correct in every outcome (neutral, layout-stable) — not the happy path's. Getting there is three layers; each makes the next one's job smaller.
Layer 1 — resolve the state at the edge, before the document is served
The server/edge that serves the SPA's HTML usually already holds what the client will spend a round trip discovering. Use it there:
- Auth: most session schemes verify with no upstream round trip — sealed/signed cookies verify with local crypto, JWTs against a cached JWKS. Gate document requests: signed out →
302 /login?returnTo=<path>before any app HTML exists. The wrong shell can't flash if it's never served. Anyone who receives the SPA at a gated path is now known to be signed in — which makes the client's skeleton honest again. - Data-shaped states: if the edge can cheaply answer "empty vs. populated" (a count, a KV flag, a cookie recording last-known state), it can serve the right variant — empty-state HTML, the populated shell, a redirect to onboarding — instead of a one-skeleton-fits-all document.
- Preferences (theme, locale, density): read the preference cookie at the edge and serve the correct variant in the initial HTML. A class on
<html>beats a client-side flip.