Loading states (skeleton UI)¶

Keprix uses shape-accurate skeleton placeholders while API data loads. Slow responses are acceptable; layout collapse and blank screens are not.

Module location¶

frontend/src/components/ui/loading/
  SkeletonBlock.tsx
  SkeletonText.tsx
  SkeletonList.tsx
  SkeletonTable.tsx
  SkeletonStatGrid.tsx
  SkeletonChart.tsx
  SkeletonDetailPanel.tsx
  AsyncView.tsx
  index.ts

Import from the barrel:

import { AsyncView, SkeletonList, SkeletonTable } from "@/components/ui/loading";

Decision table¶

Keep PageHeader, tabs, and filters visible during load. Skeleton only the data region.

Primitives¶

SkeletonBlock¶

Single rounded block. Base primitive; respects prefers-reduced-motion.

<SkeletonBlock height={120} />
<SkeletonBlock height={16} width="60%" />

SkeletonText¶

Stacked lines; last line shorter (default 3 lines).

<SkeletonText lines={4} />

SkeletonList¶

Vertical row placeholders (default 5 rows, 72px height).

<SkeletonList rows={6} rowHeight={72} />

SkeletonTable¶

Table inside TableContainer (default 6 rows, 4 columns).

<SkeletonTable rows={8} columns={5} />

SkeletonStatGrid¶

Responsive grid of stat-card blocks (~120px tall).

<SkeletonStatGrid count={4} />

SkeletonChart¶

Chart panel placeholder (default height 280).

<SkeletonChart height={280} />

SkeletonDetailPanel¶

Title, status pill, field rows, action buttons.

<SkeletonDetailPanel fields={6} />

AsyncView¶

Standard loading / error / content switch.

const { data, isLoading, error } = useSWR("tasks", fetchTasks);

return (
  <AsyncView
    loading={isLoading}
    error={error?.message}
    errorTitle="Could not load tasks"
    skeleton={<SkeletonList rows={6} />}
  >
    <TaskList tasks={data ?? []} />
  </AsyncView>
);

Reduced motion¶

usePrefersReducedMotion (frontend/src/hooks/usePrefersReducedMotion.ts) disables skeleton wave animation when the user prefers reduced motion.

Shared components (upgraded in Prompt 168)¶

Reference page¶

/tasks uses SkeletonList rows={6} under tabs while fetchTasks runs.

Migration status¶

Series prompts: 167 (architecture), 168 (primitives), 169 (workspace), 170 (admin + contract).

Batch A: Workspace core (169)¶

Batch B: Settings and billing (169)¶

Batch C: Feature workspaces (169)¶

Batch D: Shell and auth (169)¶

Deferred to Prompt 170: admin dashboard widgets, admin/mcp, admin/backup, admin/cron, chat bootstrap spinner.

Batch E: Admin and usage (170)¶

Allowed spinners: chat/page.tsx (bootstrap), analytics/page.tsx (upload), button actions with @loading-contract-ignore.

Tests¶

cd frontend && pnpm test -- loading
cd .. && .venv/bin/python -m pytest tests/ui/test_loading_contract.py -q

CI runs tests/ui/test_loading_contract.py via the backend pytest job.