Page Layout and Action Guidelines

This document defines the binding composition grammar for headed GovOPlaN pages. Core owns the reusable anatomy; each module owns its domain actions, wording, authorization, consequences, and data state.

Required Page Frame

Use PageLayout for every headed standalone, workspace, or embedded page.
Use WorkspaceFrame for a full-height module surface and WorkspaceLayout only where navigation/content or list/detail panes are genuinely part of the interaction.
Put page-wide feedback in PageLayout notices. Use DismissibleAlert for a recoverable warning or failure and StatePanel when the entire surface is loading, empty, unavailable, or blocked.
Do not reproduce shared page padding, heading, toolbar, form-grid, section, table, dialog, or breakpoint CSS in a module.

Page Action Archetypes

Pass one PageActionBar to the PageLayout actions slot. The variant makes the page's intent inspectable and preserves the same keyboard and visual order across modules.

Page kind	Leading group	Trailing group
Collection	Reload, then collection context such as export	Help, then Create at the far right
Detail	Reload, then object context	Help, ordinary primary actions, then consequential actions
Editor	Reload, then editor context such as preview	Help, Discard, then Save at the far right

Reload means re-fetch or re-evaluate the current surface. It remains present when the page can become stale. Create is a collection-wide action and is not duplicated in a persistent side panel. Save is present only where the page owns an editable draft; a read-only detail page must not display a disabled or inert Save merely to fill the slot.

PageActionBar controls placement only. Actions continue to use central Button, IconButton, or TableActionGroup components. When an action is visible but unavailable because of permission, target, policy, state, or validation, keep it in its stable slot and supply disabledReason. Do not silently hide a normally applicable action.

Forms and Dialogs

Compose forms from FormLayout/FormGrid, FormSection, and FormField.
Use FieldLabel through FormField for every field that is not genuinely self-explanatory; record justified omissions in the owning UI ledger.
Use Dialog, DialogForm, DialogSection, and DialogActions for modal work. A dialog can be domain-specific while its anatomy remains central.
Use useUnsavedDraftGuard for explicit Discard and guarded navigation on an editable page or dialog.
Explain irreversible or operationally consequential actions before the commit button, including reversibility and durable evidence.

Collections and Details

Use FilterBar for collection query controls and DataGrid for tabular collections. Keep a single ordered TableActionGroup action set per table.
Use MetricGrid/MetricCard for summary measures, Card or ContentSection for logical sections, and DescriptionList for labelled facts.
Preserve loaded data after a refresh failure and mark it stale; offer Reload as the recovery action. Distinguish initial loading, empty, unavailable, permission-blocked, conflict, success, and retry states.

Review Evidence

Every new or changed page should have structural evidence for its page frame, semantic action archetype and slot order, shared component usage, stable disabled actions, and module-owned help identity. Keyboard and narrow-layout checks must confirm that all commands remain reachable in DOM order and that the trailing group stays visually trailing after wrapping.

3.6 KiB Raw Blame History