From 506bfd63ddcb6aa540f3f5d83aebcfe106fae99a Mon Sep 17 00:00:00 2001
From: Anders Olsson <anders.e.olsson@gmail.com>
Date: Mon, 8 Jun 2026 06:22:25 +0200
Subject: [PATCH] docs(specs): standardize loading states on Skeleton recipes
 (#53)

---
 .../2026-06-08-loading-skeletons-design.md    | 115 ++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-08-loading-skeletons-design.md

diff --git a/docs/superpowers/specs/2026-06-08-loading-skeletons-design.md b/docs/superpowers/specs/2026-06-08-loading-skeletons-design.md
new file mode 100644
index 0000000..9c45a9c
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-08-loading-skeletons-design.md
@@ -0,0 +1,115 @@
+# Standardize Loading States on Skeleton — Design
+
+**Date:** 2026-06-08
+**Status:** Approved (brainstorming) — ready for implementation planning.
+**Issue:** #53.
+
+## Context
+
+Loading is rendered three incompatible ways: good `Skeleton` (objects-table, object-detail,
+search-panel, field-list); bare "…" text in a `<li>` (vocabulary-list, vocabulary-terms,
+authorities-page) — looks half-rendered; and empty `role="status"` divs (require-auth → blank app on
+first load; object-edit-form → blank form pane). Plus the lazy-route `FormFallback` renders full-pane
+"Loading…" text → flash + layout shift on first nav to `/objects/new`, `/objects/:id/edit`, `/fields`.
+
+`Skeleton` (`ui/skeleton.tsx`) is a simple `animate-pulse rounded-md bg-muted` div. No shared
+skeleton recipes or Spinner exist. No tests assert loading markup (they `findBy` content), so retiring
+the placeholders won't break tests. The three "…" sites render a `<li>` inside a `<ul>` (so a
+`<div>`-based recipe must replace the `<ul>` when loading, not nest inside it). `AppShell` layout:
+`<div flex min-h-screen><aside w-44 border-r>…nav…</aside><div flex-1 flex-col><header border-b px-4
+py-2/><main flex-1><Outlet/></main></div></div>`.
+
+### Decisions (from brainstorming)
+1. **Shared recipes** `ListSkeleton` + `FormSkeleton` (+ `AppShellSkeleton` for boot), built on
+   `Skeleton`, each an `aria` live region.
+2. **require-auth → an app-shell-shaped skeleton** (no blank flash, no shift when the real shell mounts).
+3. Skeleton-only (no Spinner primitive).
+
+## Components
+
+### `web/src/components/ui/skeletons.tsx` (new — `ui/*` no-semicolon style)
+All recipes wrap content in a status region: `<div role="status" aria-label={t("common.loading")}
+aria-busy="true" className={…}>`. New i18n `common.loading` (en "Loading", sv "Laddar").
+- **`ListSkeleton({ rows = 6, rowClassName = "h-9 w-full", className })`** — `space-y-2 p-3` (+ `className`)
+  with `rows` × `<Skeleton className={rowClassName} />`.
+- **`FormSkeleton({ fields = 5, className })`** — `space-y-4 p-4` (+ `className`); `fields` × a
+  `space-y-1` group (`<Skeleton className="h-3 w-24" />` label + `<Skeleton className="h-8 w-full" />`
+  input) + a trailing `<Skeleton className="h-8 w-28" />` (button). Mirrors the object form to avoid shift.
+- **`AppShellSkeleton`** — mirrors `AppShell`: `<div className="flex min-h-screen">` → an `aside
+  w-44 border-r p-3 space-y-2` with ~5 `<Skeleton className="h-8 w-full" />` nav rows, and a
+  `flex-1 flex-col` with a `header border-b px-4 py-2` containing a `<Skeleton className="h-6 w-40" />`
+  and a `<main className="flex-1">` containing `<ListSkeleton />`. Single top-level `role="status"`
+  on the outer div (one live region for the whole boot screen).
+
+A `skeletons.stories.tsx` renders the three (visual check + a smoke `play` asserting a `status` region).
+
+### Apply across sites
+
+**Retire "…" (render `ListSkeleton` in place of the `<ul>` when loading — valid HTML):**
+- `vocabulary-list.tsx`: replace the loading `<li>…</li>`. The list is `<ul className="flex-1
+  overflow-auto">`; render `{isLoading ? <ListSkeleton className="flex-1" /> : null}` and keep the
+  `isError`/empty/data branches in the `<ul>` (rendered when not loading). (Keep the column layout —
+  the skeleton takes the `<ul>`'s place during load.)
+- `vocabulary-terms.tsx`: replace the loading `<li>` — render `<ListSkeleton />` when `isLoading`
+  instead of the loading `<li>` (keep the `<ul>` for the loaded/empty/error branches).
+- `authorities-page.tsx`: same — `<ListSkeleton />` when `isLoading`.
+(Concretely: `{isLoading ? <ListSkeleton/> : <ul>…error/empty/rows…</ul>}`, or render the skeleton as a
+sibling and gate the `<ul>` on `!isLoading`. Implementer picks the cleaner of the two; do not nest a
+`<div>` inside `<ul>`.)
+
+**Retire empty `role="status"` divs:**
+- `object-edit-form.tsx` (outer `ObjectEditForm`, `isLoading` branch): `return <FormSkeleton />` (wrap to
+  match the edit form's container if needed — it renders inside the objects edit pane).
+- `require-auth.tsx` (`isLoading`): `return <AppShellSkeleton />`.
+
+**`app.tsx` lazy fallbacks** — remove `FormFallback`; give each `Suspense` a tailored fallback:
+- `ObjectNewPage`, `ObjectEditForm` → `fallback={<div className="mx-auto max-w-2xl"><FormSkeleton /></div>}`
+  (mirrors the new/edit page container `mx-auto max-w-2xl`).
+- `FieldsPage` → `fallback={<ListSkeleton />}` (a simple page skeleton; FieldsPage is a 2-col page, but a
+  list skeleton in the pane is a fine, shift-light placeholder for the brief lazy load).
+
+**Retrofit the good list-like skeletons to `ListSkeleton`** (consistency):
+- `field-list.tsx`: `isLoading` → `<ListSkeleton rows={6} />` (was `space-y-2 p-3` + 6 × `h-9`). Identical output.
+- `search-panel.tsx`: the `hasQuery && search.isLoading` block → `<ListSkeleton rows={5} rowClassName="h-12 w-full" />`.
+- **Keep inline:** `objects-table.tsx` (a `<tbody>` of `<tr>`/`<td>` skeleton rows — table-specific) and
+  `object-detail.tsx` (single `h-40` block) — both already fitting; not worth forcing into a recipe.
+
+## Data flow / accessibility
+Each recipe is a `role="status" aria-busy` live region labelled `common.loading` → screen readers
+announce "Loading" (the empty `role="status"` divs announced nothing). Visual skeletons mirror the
+loaded layout so there's no jump when content arrives.
+
+## Error handling / edges
+- Don't nest `<div>` inside `<ul>` — render the list skeleton in place of the `<ul>`.
+- `AppShellSkeleton` is pre-shell (require-auth) — it must not import anything that assumes the shell/
+  router context beyond `t()` (it only needs `useTranslation`).
+- Multiple `role="status"` regions on one screen are acceptable; `AppShellSkeleton` uses ONE outer
+  region (not one per nested skeleton) to avoid SR noise.
+- `FormSkeleton` in the lazy fallback vs the object-edit-form loading branch: both render the same
+  recipe, so the Suspense fallback → loaded-but-fetching → loaded transition stays visually stable.
+
+## Testing
+- `skeletons.stories.tsx`: render `ListSkeleton`/`FormSkeleton`/`AppShellSkeleton`; a `play` asserts a
+  `role="status"` is present (smoke).
+- Existing suite stays green: no test asserts the old "…"/empty-div markup; tests `findBy` content,
+  which still resolves after loading. (If any test was implicitly relying on the empty `role="status"`
+  via `getByRole("status")` — none found — update it.) 
+- Gate: `typecheck`/`lint`/`test`/`build`/`check:size`/`check:colors`; en/sv parity (one new key
+  `common.loading`); no codename; no new dependency.
+
+## Acceptance criteria
+1. `ListSkeleton`, `FormSkeleton`, `AppShellSkeleton` exist (built on `Skeleton`, each a
+   `role="status" aria-label={t("common.loading")}` live region) with a story.
+2. The three "…" placeholders are replaced by `ListSkeleton`; the two empty `role="status"` divs are
+   replaced (object-edit-form → `FormSkeleton`, require-auth → `AppShellSkeleton`); the lazy
+   `FormFallback` is replaced by per-route skeleton fallbacks (no full-pane "Loading…").
+3. `field-list` + `search-panel` use the shared `ListSkeleton`; objects-table/object-detail keep their
+   fitting inline skeletons.
+4. Loading visuals mirror the loaded layout (no obvious shift); screen readers announce loading.
+5. `typecheck`/`lint`/`test`/`build`/`check:colors` green; `check:size` reported; en/sv parity; no
+   codename; no new dependency.
+
+## Out of scope → follow-ups
+- A `Spinner` primitive (Skeleton-only here).
+- Reworking objects-table / object-detail inline skeletons.
+- Additional route-level Suspense boundaries or data-router `HydrateFallback`s.