Component Patterns

Core Building Blocks

• Page (src/components/shared/Page.tsx)
• SectionCard (src/components/shared/SectionCard.tsx)
• MetricCard (src/components/shared/MetricCard.tsx)
• UI primitives in src/components/ui/*

Page Structure Pattern

Use this default structure for new feature screens:

1. <Page title description actions>
2. High-signal metrics row (optional)
3. One or more <SectionCard> blocks
4. Split list/detail only when the workflow benefits from persistent selection

State Management Pattern

• Keep feature-local UI state in the feature component.
• Keep API serialization/deserialization close to the feature screen.
• Prefer explicit fromBackend/toPayload helpers.

Selection and Actions Pattern

• Always show a clear selected state for list items.
• Keep one obvious primary action per section.
• Reserve outline/secondary buttons for non-primary actions.

Forms Pattern

• Input labels are required.
• Save actions should show success/error status text.
• Preserve unsaved-change detection where edits span multiple fields.

Route Composition

Route files (src/routes/*) should stay thin wrappers around feature pages and avoid business logic.