Page states¶

Status: Placeholder — to be developed. Last reviewed: — Reference structural sibling: guidelines/ui/forms.md (mirror its sectioning + length: Status banner → Sources of truth → Scope → Hard rules → Required structure → conventions → Anti-patterns → Known deviations → When to break the rules; aim for 200-280 lines).

Scope (when this guideline lands)¶

System-wide patterns for non-happy-path page states: empty (no rows yet, no permission, search returned nothing), loading (initial render, HTMX fetches, long jobs), error (4xx, 5xx, partial failure), and no-permission. Independent of the component the state appears in.

Goal: every list, detail, and dashboard page handles these four states consistently — same icon style, same copy structure, same call-to-action placement.

Out of scope (cross-refs to other guidelines — do NOT duplicate)¶

List-page two-empty-states distinction ("no records" vs "filters returned nothing") → already documented in guidelines/ui/lists.md "Empty states". This guideline generalises across all page types; reference but don't restate the list-page specifics.
Toast / banner / modal feedback channels → guidelines/ux/feedback-and-confirmation.md (placeholder). Page states cover passive render conditions; feedback covers post-action signalling.
Microcopy and tone for empty/error messages → guidelines/ux/microcopy.md (placeholder). This file documents structure (icon + caption + CTA placement); microcopy.md owns wording.

Sources to mine when writing this¶

Existing empty-state implementations across templates/ (grep for empty, aucun, no, bi-search, text-center py-5).
Loading patterns currently in use: HTMX hx-indicator attributes, spinners in templates/components/, the _progress-card pattern in apps/dataquality/templates/dataquality/scan_detail.html.
Django error templates: templates/404.html, templates/500.html, plus any templates/errors/ (the relocated roadmap/done/i18n-audit.md flagged some as English-only — verify still true).
Recent dataquality and imports pages — likely the most-iterated examples.
templates/skeletons/skeleton_list.html and skeleton_detail.html — already encode some empty-state conventions.

Starter hard rules to investigate¶

Empty state structure: centered icon (style="font-size: 4rem;") + muted-color caption + optional CTA. Already in ui/lists.md for list pages — generalise.
Loading state structure: spinner-border-sm + caption + progress bar where applicable. Reference the dataquality progress-card pattern.
Error state: alert-danger block with icon, structured <ul> for multi-error cases (mirrors form form.errors block in ui/forms.md).
No-permission: redirect to / or render a 403 page? Verify current behaviour. Should be consistent.
All copy translatable per guidelines/i18n/translation-rules.md (French source).

Decision points to settle¶

Loading-state placement: full-page overlay vs inline replacement vs sticky banner — the codebase mixes these. Pick a canonical default.
Error-state retry: when does an error state offer a "Retry" button vs just a "Back to safety" link? Define the policy.
Empty-state CTA copy: "Create the first one" / "Importer des données" / no CTA — define when each applies.
Skeleton screens vs spinners for HTMX-driven content: ui-design-audit.md mentions skeleton loading states landed; verify current state and document.

Known deviations to look for during writing¶

Pages with bare "No data" text outside any structured empty-state pattern.
Loading states that block UI without an hx-indicator (silent freeze).
Error messages echoed from raw Exception text (PII risk — also see guidelines/security/pii-and-logging.md placeholder).

If found, file as roadmap/backlog/ui-page-states-drift-2026-MM.md and reference from the new guideline's "Known deviations" section.