UI Kit

Purpose

The frontend uses the local UI kit in frontend/src/components/ui/ as the shared view-layer foundation. Product components should compose these primitives instead of duplicating low-level button, input, table, and status markup.

Current Foundation

button.tsx with variants in button-variants.ts; it also owns shared loading and leading-icon button behavior.
input.tsx, textarea.tsx, native-select.tsx, select.tsx, checkbox.tsx, radio-group.tsx, and form.tsx for form controls.
table.tsx for structured tables.
card.tsx, alert.tsx, badge.tsx, tabs.tsx, dialog.tsx, tooltip.tsx, and other shadcn-style primitives.
state-panel.tsx with variants in state-panel-variants.ts for loading, error, and empty states.
module-header.tsx for repeated module title, icon, and description headers.

StatePanel Usage

Use StatePanel when a feature needs a standard loading, error, or empty block.

<StatePanel tone="violet" size="lg" alignment="center" loading>
  Loading assessment content...
</StatePanel>

<StatePanel tone="red" role="alert">
  Assessment content could not be loaded from the backend.
</StatePanel>

Feature-specific wrapper components may stay in their module folder when they carry product copy or workflow-specific props. Those wrappers should delegate the repeated shell to StatePanel.

Loading States: PageSkeleton vs StatePanel

There are two loading scopes, and they must not be mixed within one navigation:

Page-scope load — the whole page (or its primary content) is unavailable until the fetch resolves. Use PageSkeleton (components/ui/page-skeleton.tsx), early-returned from the page/wrapper. ModuleRouteGuard already renders the same PageSkeleton as the lazy-route Suspense fallback, so the chunk load and the data load read as one continuous skeleton instead of a skeleton that flips into a spinner. Do not use a StatePanel spinner for this.
```
if (page.isLoading) {
  return <PageSkeleton />;
}
```
Local/section load — the page chrome (header, filters, interactive controls) renders immediately and only a secondary region is still fetching. Keep a StatePanel spinner (or a Button busy state) scoped to that region. Examples: a results grid below interactive filters, a secondary compliance panel, a per-tab fetch.

Rule of thumb: if loading hides everything behind a static header, it is page-scope → PageSkeleton. If interactive chrome is already usable while one area loads, it is local → StatePanel.

Button Usage

Use Button for new clickable commands. Prefer leadingIcon, loading, and loadingLabel instead of duplicating inline spinner branches.

<Button loading={saving} loadingLabel="Saving..." leadingIcon={<Save size={14} />}>
  Save
</Button>

Feature components may pass product-specific className values while the shared component owns disabled and busy behavior.

Table Usage

Use Table, TableHeader, TableBody, TableRow, TableHead, and TableCell for structured table markup. Preserve feature-specific density and colors with className; do not duplicate native <table> shells in new code.

Form Controls

Use Input for text-like controls and NativeSelect for simple browser-native select fields. Use the Radix Select primitive only when the product requires custom dropdown behavior.

Module Headers

Use ModuleHeader for repeated module-level title blocks with a square icon and short description. Feature headers may still render additional callouts or actions around it.

Rules

Keep UI variants and class maps in dedicated non-component files.
Use StatePanel for repeated error/empty panels and local/section loading; use PageSkeleton for page-scope loading so it stays continuous with the route Suspense fallback (see Loading States above).
Use existing Button, Input, Textarea, Select, and Table primitives for new view code.
Use NativeSelect for simple select fields where native browser behavior is sufficient.
Use ModuleHeader for repeated page/module headings instead of duplicating title/icon markup.
Do not add another external UI kit unless the existing primitives cannot support a concrete product requirement.
Do not move business rules into UI primitives. UI kit components should stay presentation-focused.

Remaining Consolidation Candidates

Repeated statistic cards can be promoted to a shared metric component after at least two active modules need the same prop shape.
New structured table views should use table.tsx; existing feature tables can switch to it when product work touches those modules.
Module-specific wrapper components should stay local until the same component contract is repeated across active modules.

4.7 KiB Raw Blame History