Add page templates, overhaul DESIGN.md, and fix SideNav text alignment
Introduce AppShell, DashboardPage, ListPage, and FormPage template components with Storybook recipe stories for AI agent consumption. Thoroughly update DESIGN.md with all missing components, corrected token values, and page layout conventions. Fix SideNav button items defaulting to centered text. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
724
DESIGN.md
724
DESIGN.md
@@ -6,39 +6,78 @@ colors:
|
||||
# Palette (do not reference directly in components)
|
||||
blue-01: "#002664"
|
||||
blue-02: "#146CFD"
|
||||
blue-03: "#69B3E7"
|
||||
blue-03: "#8CE0FF"
|
||||
blue-04: "#CBEDFD"
|
||||
blue-05: "#EBF5FF"
|
||||
red-01: "#3E0014"
|
||||
red-01: "#630019"
|
||||
red-02: "#D7153A"
|
||||
red-03: "#F5C5D0"
|
||||
red-04: "#FDDDE5"
|
||||
red-05: "#FFF5F8"
|
||||
orange-01: "#7A3300"
|
||||
orange-02: "#EC6608"
|
||||
orange-03: "#F5B98A"
|
||||
orange-04: "#FEF0E4"
|
||||
green-01: "#005C35"
|
||||
green-02: "#00A651"
|
||||
green-03: "#89E5B3"
|
||||
green-04: "#E0F8EA"
|
||||
red-03: "#FFB8C1"
|
||||
red-04: "#FFE6EA"
|
||||
orange-01: "#941B00"
|
||||
orange-02: "#F3631B"
|
||||
orange-03: "#FFCE99"
|
||||
orange-04: "#FDEDDF"
|
||||
green-01: "#004000"
|
||||
green-02: "#00AA45"
|
||||
green-03: "#A8EDB3"
|
||||
green-04: "#DBFADF"
|
||||
teal-01: "#0B3F47"
|
||||
teal-02: "#2E808E"
|
||||
teal-03: "#8CDBE5"
|
||||
teal-04: "#D1EEEA"
|
||||
brown-01: "#523719"
|
||||
brown-02: "#B68D5D"
|
||||
brown-03: "#E8D0B5"
|
||||
brown-04: "#EDE3D7"
|
||||
purple-01: "#441170"
|
||||
purple-02: "#8055F1"
|
||||
purple-03: "#CEBFFF"
|
||||
purple-04: "#E6E1FD"
|
||||
fuchsia-01: "#65004D"
|
||||
fuchsia-02: "#D912AE"
|
||||
fuchsia-03: "#F4B5E6"
|
||||
fuchsia-04: "#FDDEF2"
|
||||
yellow-01: "#694800"
|
||||
yellow-02: "#FAAF05"
|
||||
yellow-03: "#FDE79A"
|
||||
yellow-04: "#FFF4CF"
|
||||
grey-01: "#22272B"
|
||||
grey-02: "#6D7278"
|
||||
grey-03: "#C0C0C0"
|
||||
grey-04: "#E0E0E0"
|
||||
off-white: "#F4F4F4"
|
||||
grey-02: "#495054"
|
||||
grey-03: "#CDD3D6"
|
||||
grey-04: "#EBEBEB"
|
||||
grey-05: "#F2F2F2"
|
||||
white: "#FFFFFF"
|
||||
# Semantic (use these in components)
|
||||
primary: "{colors.blue-02}"
|
||||
primary-dark: "{colors.blue-01}"
|
||||
primary: "{colors.blue-01}"
|
||||
info: "{colors.blue-02}"
|
||||
secondary: "{colors.blue-04}"
|
||||
error: "{colors.red-02}"
|
||||
success: "{colors.green-02}"
|
||||
warning: "{colors.orange-02}"
|
||||
text: "{colors.grey-01}"
|
||||
text-secondary: "{colors.grey-02}"
|
||||
border: "{colors.grey-04}"
|
||||
bg: "{colors.off-white}"
|
||||
bg: "{colors.grey-05}"
|
||||
surface: "{colors.white}"
|
||||
# Form controls
|
||||
control-border: "{colors.grey-03}"
|
||||
control-border-hover: "{colors.grey-01}"
|
||||
control-checked: "{colors.blue-01}"
|
||||
control-checked-hover: "{colors.blue-02}"
|
||||
control-focus-ring: "{colors.blue-04}"
|
||||
control-label: "{colors.blue-01}"
|
||||
control-description: "{colors.grey-02}"
|
||||
control-error: "{colors.red-02}"
|
||||
control-bg: "{colors.white}"
|
||||
control-bg-readonly: "{colors.grey-05}"
|
||||
# Button
|
||||
button-default: "{colors.blue-01}"
|
||||
button-danger: "{colors.red-02}"
|
||||
button-neutral: "{colors.grey-01}"
|
||||
button-subtle-bg: "{colors.blue-04}"
|
||||
button-subtle-text: "{colors.blue-01}"
|
||||
# Switch
|
||||
switch-on: "{colors.green-02}"
|
||||
switch-on-hover: "{colors.green-01}"
|
||||
typography:
|
||||
h1:
|
||||
fontFamily: Public Sans Variable
|
||||
@@ -92,59 +131,39 @@ typography:
|
||||
lineHeight: 1.5
|
||||
rounded:
|
||||
sm: 4px
|
||||
DEFAULT: 6px
|
||||
lg: 10px
|
||||
xl: 16px
|
||||
DEFAULT: 8px
|
||||
lg: 16px
|
||||
xl: 24px
|
||||
full: 9999px
|
||||
spacing:
|
||||
unit: 4px
|
||||
scale: "Tailwind default (4px base: 1=4px, 2=8px, 3=12px, 4=16px, 6=24px, 8=32px)"
|
||||
components:
|
||||
button-primary-default:
|
||||
backgroundColor: "{colors.primary-dark}"
|
||||
textColor: "{colors.white}"
|
||||
typography: "{typography.body}"
|
||||
rounded: "{rounded.DEFAULT}"
|
||||
height: 48px
|
||||
button-primary-danger:
|
||||
backgroundColor: "{colors.red-02}"
|
||||
textColor: "{colors.white}"
|
||||
button-secondary-default:
|
||||
backgroundColor: transparent
|
||||
textColor: "{colors.primary-dark}"
|
||||
input:
|
||||
backgroundColor: "{colors.white}"
|
||||
textColor: "{colors.text}"
|
||||
typography: "{typography.body}"
|
||||
rounded: "{rounded.DEFAULT}"
|
||||
height: 48px
|
||||
card-surface:
|
||||
backgroundColor: "{colors.surface}"
|
||||
rounded: "{rounded.xl}"
|
||||
badge-info:
|
||||
backgroundColor: "{colors.blue-02}"
|
||||
textColor: "{colors.white}"
|
||||
rounded: "{rounded.full}"
|
||||
alert-info:
|
||||
backgroundColor: "{colors.blue-05}"
|
||||
rounded: "{rounded.DEFAULT}"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
ADS 3.0 (Adaptive Design System) is a React component library based on the NSW Department of Education's digital design language. It uses Public Sans as its typeface, a structured blue/grey palette with semantic colour aliases, and consistent border radii and spacing. Components are built with React 19, TypeScript (strict), and Tailwind CSS v4.
|
||||
ADS 3.0 (Adaptive Design System) is a React component library based on the NSW Department of Education's digital design language. It uses Public Sans as its typeface, a structured colour palette with semantic aliases, and consistent border radii and spacing. Components are built with React 19, TypeScript (strict), and Tailwind CSS v4.
|
||||
|
||||
All visual values come from design tokens defined in `src/tokens/tokens.css`. Components never use raw colour values — they reference semantic or domain-specific token classes via Tailwind utilities.
|
||||
|
||||
## Colors
|
||||
|
||||
The palette is organised in three layers:
|
||||
The palette is organised in layers, from raw to consumable:
|
||||
|
||||
1. **Palette** — Raw values (`blue-01` through `blue-05`, `grey-01` through `grey-04`, etc.). Never use these directly in component code.
|
||||
2. **Semantic** — Purpose-based aliases (`primary`, `error`, `success`, `warning`, `text`, `surface`, `bg`, `border`). Use these for general UI.
|
||||
3. **Domain** — Component-specific tokens (`button-default`, `control-border`, `badge-info`, `alert-error-bg`, `tag-navy`, etc.). Use these within their respective components.
|
||||
1. **Palette** — Raw values across 10 colour families (blue, red, orange, green, teal, brown, purple, fuchsia, yellow, grey) with 4 shades each (`-01` darkest to `-04` lightest), plus grey-05 and white. Never use these directly in component code.
|
||||
2. **Semantic** — Purpose-based aliases (`primary`, `info`, `secondary`, `error`, `success`, `warning`, `text`, `text-secondary`, `surface`, `bg`, `border`). Use these for general UI.
|
||||
3. **Form control** — Shared interactive-state tokens for all form components: `control-border`, `control-border-hover`, `control-checked`, `control-checked-hover`, `control-focus-ring`, `control-label`, `control-description`, `control-error`, `control-bg`, `control-bg-readonly`.
|
||||
4. **Button** — Intent tokens: `button-default` (navy), `button-danger` (red), `button-neutral` (dark grey), `button-subtle-bg`, `button-subtle-text`.
|
||||
5. **Switch** — On-state tokens: `switch-on` (success green), `switch-on-hover`.
|
||||
6. **Badge** — Status colour tokens: `badge-navy`, `badge-info`, `badge-info-light`, `badge-success`, `badge-success-light`, `badge-error`, `badge-error-light`, `badge-warning`, `badge-warning-light`, `badge-neutral`, plus contrast text tokens (`badge-on-success-light`, `badge-on-error-light`, `badge-on-warning-light`).
|
||||
7. **Chip** — Border/fill state tokens: `chip-border`, `chip-text`, `chip-bg`, `chip-selected-bg`, `chip-selected-text`.
|
||||
8. **Tag** — 11-colour system, each with a `-light` variant: navy, blue, green, red, orange, grey, teal, brown, purple, fuchsia, yellow.
|
||||
9. **Alert** — Background, border, and icon tokens for 5 variants: `alert-{variant}-bg`, `alert-{variant}-border`, `alert-{variant}-icon` (info, warning, error, success, neutral).
|
||||
10. **Avatar** — `avatar` (background), `avatar-text`.
|
||||
11. **TopBar** — `topbar` (background, navy).
|
||||
12. **SideNav** — `nav-bg`, `nav-text`, `nav-icon`, `nav-active`, `nav-divider`.
|
||||
|
||||
The primary brand colour is `blue-01` (#002664, dark navy) for interactive elements like buttons and links. `blue-02` (#146CFD) is the brighter accent used for info states, focus rings, and highlights.
|
||||
The primary brand colour is `blue-01` (#002664, dark navy) used for buttons, links, and navigation. `blue-02` (#146CFD) is the brighter accent for info states, focus rings, and highlights.
|
||||
|
||||
## Typography
|
||||
|
||||
@@ -159,7 +178,7 @@ Spacing follows Tailwind's default 4px base scale. Common values:
|
||||
- `gap-2` (8px), `gap-3` (12px), `gap-4` (16px) for flex/grid gaps
|
||||
- `space-y-4` (16px) for stacked content
|
||||
|
||||
No custom spacing tokens are defined — the Tailwind defaults are sufficient. This may change in future.
|
||||
No custom spacing tokens are defined — the Tailwind defaults are sufficient.
|
||||
|
||||
## Elevation & Depth
|
||||
|
||||
@@ -171,14 +190,61 @@ Two shadow levels:
|
||||
|
||||
Border radii use the custom scale:
|
||||
- `rounded-sm` (4px) — small elements, tags
|
||||
- `rounded-default` (6px) — buttons, inputs, alerts
|
||||
- `rounded-lg` (10px) — cards, dialogs
|
||||
- `rounded-xl` (16px) — large containers
|
||||
- `rounded-full` (9999px) — badges, circular buttons
|
||||
- `rounded-default` (8px) — buttons, inputs, alerts, chips
|
||||
- `rounded-lg` (16px) — cards, dialogs
|
||||
- `rounded-xl` (24px) — large containers, page headers
|
||||
- `rounded-full` (9999px) — badges, avatars, circular buttons
|
||||
|
||||
## Page Layout
|
||||
|
||||
Pages are composed using the **AppShell** template, which provides the fixed TopBar, collapsible SideNav, and scrollable content area. Content within the main area follows these conventions:
|
||||
|
||||
### Shell structure
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ TopBar (h-16, fixed top, full width) │
|
||||
├────────┬────────────────────────────────┤
|
||||
│SideNav │ Content area (scrollable) │
|
||||
│(w-[360]│ │
|
||||
│ or │ PageHeader (optional) │
|
||||
│ w-20 │ │
|
||||
│collapsed│ Main content │
|
||||
│) │ │
|
||||
└────────┴────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Content patterns
|
||||
|
||||
**Dashboard** — Use a responsive grid for content cards:
|
||||
- 2-column grid at `lg` breakpoint: `grid grid-cols-1 lg:grid-cols-2 gap-6`
|
||||
- Stat cards in a horizontal row: `flex gap-4` or `grid grid-cols-3 gap-4`
|
||||
- Content padding: `p-6` or `p-8`
|
||||
- Section spacing: `space-y-6`
|
||||
|
||||
**List page** — Stat summary row above a scrollable list:
|
||||
- Stat cards row: `flex gap-4` with Card components
|
||||
- List section: Card wrapping a vertical list with `divide-y divide-border`
|
||||
- Each list item: `px-6 py-4` with flex layout for metadata
|
||||
|
||||
**Form page** — Stepped form with vertical stepper:
|
||||
- Content max-width: `max-w-3xl` for readable line length
|
||||
- Form sections: `space-y-6` between groups
|
||||
- Stepper: vertical list on left, form content fills remaining space
|
||||
- Submit actions: right-aligned with `flex justify-end gap-3`
|
||||
|
||||
### Spacing conventions
|
||||
- Page content padding: `p-6` (24px) minimum
|
||||
- Section gap: `gap-6` (24px) between major sections
|
||||
- Card internal padding: `p-5` or `p-6`
|
||||
- Form field spacing: `space-y-4` (16px) between fields, `space-y-6` (24px) between groups
|
||||
|
||||
---
|
||||
|
||||
## Components
|
||||
|
||||
### Button
|
||||
### Atoms
|
||||
|
||||
#### Button
|
||||
|
||||
Interactive button with variant/intent/size matrix.
|
||||
|
||||
@@ -199,7 +265,7 @@ import { Button } from '@/components/atoms/Button'
|
||||
<Button variant="tertiary" size="compact">Cancel</Button>
|
||||
```
|
||||
|
||||
### IconButton
|
||||
#### IconButton
|
||||
|
||||
Icon-only button with required `aria-label`.
|
||||
|
||||
@@ -220,7 +286,7 @@ import { X, Settings } from 'lucide-react'
|
||||
<IconButton icon={<Settings />} aria-label="Settings" shape="square" size="compact" />
|
||||
```
|
||||
|
||||
### Input
|
||||
#### Input
|
||||
|
||||
Text input with label, description, hint, error, and icon slots.
|
||||
|
||||
@@ -244,7 +310,7 @@ import { Search, Mail } from 'lucide-react'
|
||||
<Input label="Name" error="Name is required" />
|
||||
```
|
||||
|
||||
### Textarea
|
||||
#### Textarea
|
||||
|
||||
Multi-line text input with optional auto-resize.
|
||||
|
||||
@@ -265,7 +331,7 @@ import { Textarea } from '@/components/atoms/Textarea'
|
||||
<Textarea label="Description" autoResize error="Too short" />
|
||||
```
|
||||
|
||||
### Select
|
||||
#### Select
|
||||
|
||||
Custom dropdown select with keyboard navigation.
|
||||
|
||||
@@ -297,7 +363,41 @@ import { Select } from '@/components/atoms/Select'
|
||||
/>
|
||||
```
|
||||
|
||||
### Checkbox
|
||||
#### Autocomplete
|
||||
|
||||
Combobox input with filtering, keyboard navigation, and optional free-text entry.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `label` | `string` | — | **Required.** Visible label |
|
||||
| `description` | `string` | — | Help text below label |
|
||||
| `hint` | `string` | — | Inline hint |
|
||||
| `error` | `string` | — | Error message |
|
||||
| `placeholder` | `string` | — | Placeholder text |
|
||||
| `options` | `AutocompleteOption[]` | — | **Required.** `{ value, label, disabled? }` |
|
||||
| `value` | `string` | — | Controlled value |
|
||||
| `onChange` | `(value: string) => void` | — | Change handler |
|
||||
| `freeSolo` | `boolean` | `false` | Allow arbitrary text input |
|
||||
| `disabled` | `boolean` | `false` | Disables the input |
|
||||
| `loading` | `boolean` | `false` | Shows loading state |
|
||||
| `noResultsText` | `string` | `'No results found'` | Empty state message |
|
||||
|
||||
```tsx
|
||||
import { Autocomplete } from '@/components/atoms/Autocomplete'
|
||||
|
||||
<Autocomplete
|
||||
label="Country"
|
||||
options={[
|
||||
{ value: 'au', label: 'Australia' },
|
||||
{ value: 'nz', label: 'New Zealand' },
|
||||
{ value: 'uk', label: 'United Kingdom' },
|
||||
]}
|
||||
onChange={(val) => setCountry(val)}
|
||||
/>
|
||||
<Autocomplete label="Tags" freeSolo options={tagOptions} />
|
||||
```
|
||||
|
||||
#### Checkbox
|
||||
|
||||
Checkbox with label, description, error, and indeterminate state.
|
||||
|
||||
@@ -316,7 +416,7 @@ import { Checkbox } from '@/components/atoms/Checkbox'
|
||||
<Checkbox label="Required" error="You must agree" />
|
||||
```
|
||||
|
||||
### Radio / RadioGroup
|
||||
#### Radio / RadioGroup
|
||||
|
||||
Radio buttons grouped with shared state.
|
||||
|
||||
@@ -345,7 +445,7 @@ import { RadioGroup, Radio } from '@/components/atoms/Radio'
|
||||
</RadioGroup>
|
||||
```
|
||||
|
||||
### Switch
|
||||
#### Switch
|
||||
|
||||
Toggle switch with label and description.
|
||||
|
||||
@@ -364,7 +464,69 @@ import { Switch } from '@/components/atoms/Switch'
|
||||
<Switch label="Notifications" description="Receive email alerts" />
|
||||
```
|
||||
|
||||
### Badge
|
||||
#### Slider
|
||||
|
||||
Single-value slider with step support and keyboard navigation.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `label` | `string` | — | Visible label |
|
||||
| `value` | `number` | — | **Required.** Current value |
|
||||
| `onChange` | `(value: number) => void` | — | **Required.** Change handler |
|
||||
| `min` | `number` | `0` | Minimum value |
|
||||
| `max` | `number` | `100` | Maximum value |
|
||||
| `step` | `number` | `1` | Step increment |
|
||||
| `disabled` | `boolean` | `false` | Disables the slider |
|
||||
|
||||
```tsx
|
||||
import { Slider } from '@/components/atoms/Slider'
|
||||
|
||||
<Slider label="Volume" value={volume} onChange={setVolume} min={0} max={100} />
|
||||
<Slider label="Opacity" value={opacity} onChange={setOpacity} min={0} max={1} step={0.1} />
|
||||
```
|
||||
|
||||
#### RangeSlider
|
||||
|
||||
Dual-thumb range slider for selecting a value range.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `label` | `string` | — | Visible label |
|
||||
| `value` | `[number, number]` | — | **Required.** Current range |
|
||||
| `onChange` | `(value: [number, number]) => void` | — | **Required.** Change handler |
|
||||
| `min` | `number` | `0` | Minimum value |
|
||||
| `max` | `number` | `100` | Maximum value |
|
||||
| `step` | `number` | `1` | Step increment |
|
||||
| `disabled` | `boolean` | `false` | Disables the slider |
|
||||
|
||||
```tsx
|
||||
import { RangeSlider } from '@/components/atoms/Slider'
|
||||
|
||||
<RangeSlider label="Price range" value={[20, 80]} onChange={setRange} min={0} max={200} />
|
||||
```
|
||||
|
||||
#### FileInput
|
||||
|
||||
File picker with multi-file support and removable file tags.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `label` | `string` | — | **Required.** Visible label |
|
||||
| `description` | `string` | — | Help text |
|
||||
| `error` | `string` | — | Error message |
|
||||
| `accept` | `string` | — | Accepted file types (e.g., `.pdf,.docx`) |
|
||||
| `multiple` | `boolean` | `false` | Allow multiple files |
|
||||
| `disabled` | `boolean` | `false` | Disables the input |
|
||||
| `onChange` | `(files: File[]) => void` | — | Change handler |
|
||||
|
||||
```tsx
|
||||
import { FileInput } from '@/components/atoms/FileInput'
|
||||
|
||||
<FileInput label="Upload documents" accept=".pdf,.docx" multiple onChange={setFiles} />
|
||||
<FileInput label="Profile photo" accept="image/*" />
|
||||
```
|
||||
|
||||
#### Badge
|
||||
|
||||
Small status indicator with colour variants.
|
||||
|
||||
@@ -382,32 +544,14 @@ import { Badge } from '@/components/atoms/Badge'
|
||||
<Badge variant="info" leftIcon={<Clock />}>Pending</Badge>
|
||||
```
|
||||
|
||||
### Chip
|
||||
|
||||
Selectable/dismissible filter chip.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `children` | `ReactNode` | — | **Required.** Chip label |
|
||||
| `selected` | `boolean` | `false` | Selected state |
|
||||
| `onDismiss` | `() => void` | — | Shows dismiss icon, makes removable |
|
||||
| `rightIcon` | `ReactNode` | — | Custom right icon |
|
||||
|
||||
```tsx
|
||||
import { Chip } from '@/components/atoms/Chip'
|
||||
|
||||
<Chip selected={isActive} onClick={toggle}>Qualitative</Chip>
|
||||
<Chip onDismiss={() => removeFilter('date')}>2024</Chip>
|
||||
```
|
||||
|
||||
### Tag
|
||||
#### Tag
|
||||
|
||||
Coloured label for categorisation.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `variant` | `'outline' \| 'filled' \| 'light'` | `'outline'` | Visual style |
|
||||
| `color` | `'navy' \| 'blue' \| 'green' \| 'red' \| 'orange' \| 'grey'` | `'navy'` | Colour |
|
||||
| `color` | `'navy' \| 'blue' \| 'green' \| 'red' \| 'orange' \| 'grey' \| 'teal' \| 'brown' \| 'purple' \| 'fuchsia' \| 'yellow'` | `'navy'` | Colour |
|
||||
| `size` | `'default' \| 'sm'` | `'default'` | Tag size |
|
||||
| `icon` | `ReactNode` | — | Leading icon |
|
||||
| `onRemove` | `() => void` | — | Shows remove button |
|
||||
@@ -419,7 +563,103 @@ import { Tag } from '@/components/atoms/Tag'
|
||||
<Tag color="green" variant="filled" onRemove={handleRemove}>Complete</Tag>
|
||||
```
|
||||
|
||||
### Tooltip
|
||||
#### Chip
|
||||
|
||||
Selectable/dismissible filter chip with optional colour variants.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `children` | `ReactNode` | — | **Required.** Chip label |
|
||||
| `selected` | `boolean` | `false` | Selected state |
|
||||
| `color` | `'default' \| 'info' \| 'error' \| 'warning' \| 'success'` | — | Colour variant (unselected only) |
|
||||
| `onDismiss` | `() => void` | — | Shows dismiss icon, makes removable |
|
||||
| `rightIcon` | `ReactNode` | — | Custom right icon |
|
||||
|
||||
```tsx
|
||||
import { Chip } from '@/components/atoms/Chip'
|
||||
|
||||
<Chip selected={isActive} onClick={toggle}>Qualitative</Chip>
|
||||
<Chip onDismiss={() => removeFilter('date')}>2024</Chip>
|
||||
<Chip color="success">Approved</Chip>
|
||||
```
|
||||
|
||||
#### Tabs
|
||||
|
||||
Tab navigation with controlled selection. Compound component: `Tabs`, `TabList`, `Tab`, `TabPanel`.
|
||||
|
||||
| Prop (Tabs) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `value` | `string` | — | **Required.** Active tab value |
|
||||
| `onChange` | `(value: string) => void` | — | **Required.** Tab change handler |
|
||||
|
||||
| Prop (Tab) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `value` | `string` | — | **Required.** Tab identifier |
|
||||
| `icon` | `ReactNode` | — | Icon before label |
|
||||
| `disabled` | `boolean` | `false` | Disables the tab |
|
||||
|
||||
| Prop (TabPanel) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `value` | `string` | — | **Required.** Must match a Tab value |
|
||||
|
||||
```tsx
|
||||
import { Tabs, TabList, Tab, TabPanel } from '@/components/atoms/Tabs'
|
||||
|
||||
<Tabs value={activeTab} onChange={setActiveTab}>
|
||||
<TabList>
|
||||
<Tab value="overview">Overview</Tab>
|
||||
<Tab value="details" icon={<Info />}>Details</Tab>
|
||||
<Tab value="settings">Settings</Tab>
|
||||
</TabList>
|
||||
<TabPanel value="overview">Overview content</TabPanel>
|
||||
<TabPanel value="details">Details content</TabPanel>
|
||||
<TabPanel value="settings">Settings content</TabPanel>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
#### List
|
||||
|
||||
Vertical list with icon support, active state, and optional links. Compound component: `List`, `ListItem`, `ListSubheader`, `ListDivider`.
|
||||
|
||||
| Prop (ListItem) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `icon` | `ReactNode` | — | Leading icon |
|
||||
| `active` | `boolean` | `false` | Highlighted state |
|
||||
| `disabled` | `boolean` | `false` | Disables the item |
|
||||
| `href` | `string` | — | Renders as `<a>` instead of `<li>` |
|
||||
|
||||
```tsx
|
||||
import { List, ListItem, ListSubheader, ListDivider } from '@/components/atoms/List'
|
||||
import { Home, Settings, Users } from 'lucide-react'
|
||||
|
||||
<List>
|
||||
<ListSubheader>Navigation</ListSubheader>
|
||||
<ListItem icon={<Home />} active>Dashboard</ListItem>
|
||||
<ListItem icon={<Users />}>Team</ListItem>
|
||||
<ListDivider />
|
||||
<ListItem icon={<Settings />}>Settings</ListItem>
|
||||
</List>
|
||||
```
|
||||
|
||||
#### Avatar
|
||||
|
||||
Circular avatar showing initials or an image.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `initials` | `string` | — | **Required.** Fallback text (first 2 chars, uppercased) |
|
||||
| `src` | `string` | — | Image URL |
|
||||
| `alt` | `string` | — | Image alt text |
|
||||
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Avatar dimensions (32/40/48px) |
|
||||
|
||||
```tsx
|
||||
import { Avatar } from '@/components/atoms/Avatar'
|
||||
|
||||
<Avatar initials="JD" />
|
||||
<Avatar initials="MM" src="/photos/mary.jpg" alt="Mary McKay" size="lg" />
|
||||
```
|
||||
|
||||
#### Tooltip
|
||||
|
||||
Floating tooltip on hover/focus with arrow.
|
||||
|
||||
@@ -438,9 +678,11 @@ import { Tooltip } from '@/components/atoms/Tooltip'
|
||||
</Tooltip>
|
||||
```
|
||||
|
||||
### Card
|
||||
### Molecules
|
||||
|
||||
Container with variant styles. Composed of `Card`, `CardHeader`, `CardContent`, `CardFooter`.
|
||||
#### Card
|
||||
|
||||
Container with variant styles. Compound component: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`.
|
||||
|
||||
| Prop (Card) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
@@ -451,11 +693,12 @@ Container with variant styles. Composed of `Card`, `CardHeader`, `CardContent`,
|
||||
| `action` | `ReactNode` | — | Action element (top-right) |
|
||||
|
||||
```tsx
|
||||
import { Card, CardHeader, CardContent, CardFooter } from '@/components/molecules/Card'
|
||||
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/molecules/Card'
|
||||
|
||||
<Card variant="elevated">
|
||||
<CardHeader action={<IconButton icon={<MoreHorizontal />} aria-label="Options" variant="tertiary" />}>
|
||||
<h3>Card Title</h3>
|
||||
<CardTitle>Card Title</CardTitle>
|
||||
<CardDescription>Supporting description text</CardDescription>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
<p>Card body content goes here.</p>
|
||||
@@ -466,9 +709,9 @@ import { Card, CardHeader, CardContent, CardFooter } from '@/components/molecule
|
||||
</Card>
|
||||
```
|
||||
|
||||
### Accordion
|
||||
#### Accordion
|
||||
|
||||
Collapsible content sections. Composed of `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`.
|
||||
Collapsible content sections. Compound component: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`.
|
||||
|
||||
| Prop (Accordion) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
@@ -498,7 +741,7 @@ import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@/
|
||||
</Accordion>
|
||||
```
|
||||
|
||||
### Alert
|
||||
#### Alert
|
||||
|
||||
Contextual message with icon, title, close button, and action slot.
|
||||
|
||||
@@ -519,9 +762,9 @@ import { Alert } from '@/components/molecules/Alert'
|
||||
<Alert variant="error" title="Error">Something went wrong.</Alert>
|
||||
```
|
||||
|
||||
### Dialog
|
||||
#### Dialog
|
||||
|
||||
Modal dialog with backdrop, size options, and composed sections.
|
||||
Modal dialog with backdrop, size options, and composed sections. Uses the native `<dialog>` element. Compound component: `Dialog`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogContent`, `DialogFooter`, `DialogClose`.
|
||||
|
||||
| Prop (Dialog) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
@@ -530,14 +773,24 @@ Modal dialog with backdrop, size options, and composed sections.
|
||||
| `size` | `'sm' \| 'default' \| 'lg' \| 'full'` | `'default'` | Max width |
|
||||
| `closeOnBackdrop` | `boolean` | `true` | Close when clicking backdrop |
|
||||
|
||||
Composed with `DialogHeader`, `DialogContent`, `DialogFooter`.
|
||||
| Prop (DialogHeader) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `onClose` | `() => void` | — | Shows close button in header |
|
||||
|
||||
| Prop (DialogClose) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `onClose` | `() => void` | — | **Required.** Close handler |
|
||||
| `children` | `ReactNode` | — | **Required.** Button content |
|
||||
|
||||
```tsx
|
||||
import { Dialog, DialogHeader, DialogContent, DialogFooter } from '@/components/molecules/Dialog'
|
||||
import { Dialog, DialogHeader, DialogTitle, DialogDescription, DialogContent, DialogFooter } from '@/components/molecules/Dialog'
|
||||
|
||||
<Dialog open={isOpen} onClose={() => setIsOpen(false)} size="sm">
|
||||
<DialogHeader onClose={() => setIsOpen(false)}>Confirm</DialogHeader>
|
||||
<DialogContent>Are you sure you want to delete this?</DialogContent>
|
||||
<DialogHeader onClose={() => setIsOpen(false)}>
|
||||
<DialogTitle>Confirm deletion</DialogTitle>
|
||||
<DialogDescription>This action cannot be undone.</DialogDescription>
|
||||
</DialogHeader>
|
||||
<DialogContent>Are you sure you want to delete this item?</DialogContent>
|
||||
<DialogFooter>
|
||||
<Button variant="tertiary" onClick={() => setIsOpen(false)}>Cancel</Button>
|
||||
<Button intent="danger">Delete</Button>
|
||||
@@ -545,9 +798,9 @@ import { Dialog, DialogHeader, DialogContent, DialogFooter } from '@/components/
|
||||
</Dialog>
|
||||
```
|
||||
|
||||
### Popover
|
||||
#### Popover
|
||||
|
||||
Floating content panel triggered by a child element. Composed of `Popover`, `PopoverTrigger`, `PopoverContent`.
|
||||
Floating content panel triggered by a child element. Compound component: `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverClose`.
|
||||
|
||||
| Prop (Popover) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
@@ -555,6 +808,11 @@ Floating content panel triggered by a child element. Composed of `Popover`, `Pop
|
||||
| `open` | `boolean` | — | Controlled open state |
|
||||
| `onOpenChange` | `(open: boolean) => void` | — | Open state handler |
|
||||
|
||||
| Prop (PopoverClose) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `onClose` | `() => void` | — | **Required.** Close handler |
|
||||
| `children` | `ReactNode` | — | **Required.** Button content |
|
||||
|
||||
```tsx
|
||||
import { Popover, PopoverTrigger, PopoverContent } from '@/components/molecules/Popover'
|
||||
|
||||
@@ -568,6 +826,251 @@ import { Popover, PopoverTrigger, PopoverContent } from '@/components/molecules/
|
||||
</Popover>
|
||||
```
|
||||
|
||||
#### DataTable
|
||||
|
||||
Data table with sorting, row selection, and pagination. Generic component supporting typed row data.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `columns` | `DataTableColumn<T>[]` | — | **Required.** Column definitions |
|
||||
| `data` | `T[]` | — | **Required.** Row data array |
|
||||
| `selectable` | `boolean` | `false` | Enable row selection with checkboxes |
|
||||
| `pagination` | `boolean` | `true` | Show pagination controls |
|
||||
| `pageSize` | `number` | `5` | Initial rows per page |
|
||||
| `pageSizeOptions` | `number[]` | `[5, 10, 25]` | Page size dropdown options |
|
||||
| `loading` | `boolean` | `false` | Shows loading state |
|
||||
| `emptyMessage` | `string` | `'No data available'` | Empty state text |
|
||||
| `onSelectionChange` | `(selected: T[]) => void` | — | Selection change handler |
|
||||
|
||||
**DataTableColumn:**
|
||||
|
||||
| Property | Type | Default | Description |
|
||||
|----------|------|---------|-------------|
|
||||
| `key` | `string` | — | **Required.** Row data key |
|
||||
| `header` | `string` | — | **Required.** Column header text |
|
||||
| `sortable` | `boolean` | `false` | Enable column sorting |
|
||||
| `align` | `'left' \| 'center' \| 'right'` | `'left'` | Text alignment |
|
||||
| `render` | `(value, row, index) => ReactNode` | — | Custom cell renderer |
|
||||
|
||||
```tsx
|
||||
import { DataTable } from '@/components/molecules/DataTable'
|
||||
|
||||
<DataTable
|
||||
columns={[
|
||||
{ key: 'name', header: 'Name', sortable: true },
|
||||
{ key: 'email', header: 'Email' },
|
||||
{ key: 'role', header: 'Role', sortable: true },
|
||||
{ key: 'status', header: 'Status', render: (val) => <Badge variant={val === 'active' ? 'success' : 'neutral'}>{val}</Badge> },
|
||||
]}
|
||||
data={users}
|
||||
selectable
|
||||
pageSize={10}
|
||||
onSelectionChange={setSelected}
|
||||
/>
|
||||
```
|
||||
|
||||
### Organisms
|
||||
|
||||
#### TopBar
|
||||
|
||||
Fixed application header with logo, title, and action slots.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `title` | `string` | — | **Required.** Application title |
|
||||
| `leading` | `ReactNode` | — | Leading element (e.g., hamburger menu) |
|
||||
| `logo` | `ReactNode` | — | Logo element next to title |
|
||||
| `children` | `ReactNode` | — | Trailing actions (e.g., notifications, avatar) |
|
||||
|
||||
```tsx
|
||||
import { TopBar } from '@/components/organisms/TopBar'
|
||||
|
||||
<TopBar
|
||||
title="Performance and development plan"
|
||||
leading={<IconButton icon={<Menu />} aria-label="Menu" variant="tertiary" />}
|
||||
logo={<img src="/nsw-logo.svg" alt="NSW" className="h-7" />}
|
||||
>
|
||||
<IconButton icon={<Bell />} aria-label="Notifications" variant="tertiary" />
|
||||
<Avatar initials="MM" size="sm" />
|
||||
</TopBar>
|
||||
```
|
||||
|
||||
#### SideNav
|
||||
|
||||
Collapsible sidebar navigation with grouped items, badges, and alert indicators. Compound component: `SideNav`, `SideNavItem`, `SideNavGroup`, `SideNavDivider`.
|
||||
|
||||
| Prop (SideNav) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `collapsed` | `boolean` | `false` | Collapsed to icon-only mode (w-20) |
|
||||
|
||||
| Prop (SideNavItem) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `icon` | `ReactNode` | — | Leading icon |
|
||||
| `active` | `boolean` | `false` | Active/current state |
|
||||
| `badge` | `number` | — | Count badge |
|
||||
| `alert` | `boolean \| 'info' \| 'success' \| 'warning' \| 'error'` | — | Alert dot indicator |
|
||||
| `href` | `string` | — | Renders as `<a>` instead of `<button>` |
|
||||
|
||||
| Prop (SideNavGroup) | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `icon` | `ReactNode` | — | **Required.** Group icon |
|
||||
| `label` | `string` | — | **Required.** Group label |
|
||||
| `defaultOpen` | `boolean` | `false` | Initially expanded |
|
||||
| `badge` | `number` | — | Count badge |
|
||||
| `alert` | `boolean \| 'info' \| 'success' \| 'warning' \| 'error'` | — | Alert dot indicator |
|
||||
| `active` | `boolean` | `false` | Highlight the group trigger |
|
||||
|
||||
```tsx
|
||||
import { SideNav, SideNavItem, SideNavGroup, SideNavDivider } from '@/components/organisms/SideNav'
|
||||
import { Home, FileText, Settings, Users } from 'lucide-react'
|
||||
|
||||
<SideNav collapsed={isCollapsed}>
|
||||
<SideNavItem icon={<Home />} active>My status</SideNavItem>
|
||||
<SideNavItem icon={<FileText />}>My details</SideNavItem>
|
||||
<SideNavDivider />
|
||||
<SideNavGroup icon={<Users />} label="PDP" defaultOpen>
|
||||
<SideNavItem active>My PDP</SideNavItem>
|
||||
<SideNavItem>PDP guide</SideNavItem>
|
||||
<SideNavItem>Management</SideNavItem>
|
||||
</SideNavGroup>
|
||||
<SideNavItem icon={<Settings />}>Settings</SideNavItem>
|
||||
</SideNav>
|
||||
```
|
||||
|
||||
#### PageHeader
|
||||
|
||||
Page title section with themed background, decorative arcs, and optional icon.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `title` | `string` | — | **Required.** Page heading |
|
||||
| `subtitle` | `string` | — | Supporting text below title |
|
||||
| `icon` | `ReactNode` | — | Leading icon or illustration |
|
||||
| `iconSize` | `string` | `'50px'` | Icon width/height |
|
||||
| `theme` | `'light' \| 'dark'` | `'light'` | Background theme (light: blue-04 bg, dark: navy bg) |
|
||||
| `centered` | `boolean` | `false` | Center-aligned layout |
|
||||
| `noBackground` | `boolean` | `false` | No background or decorative arcs |
|
||||
| `children` | `ReactNode` | — | Additional content below title |
|
||||
|
||||
```tsx
|
||||
import { PageHeader } from '@/components/organisms/PageHeader'
|
||||
|
||||
<PageHeader title="My Workspace" subtitle="Accreditation Level: Maintaining Proficient Teacher">
|
||||
<div className="flex gap-4 mt-2">
|
||||
<Badge variant="info">Maintaining</Badge>
|
||||
<Badge variant="navy">5 Years</Badge>
|
||||
</div>
|
||||
</PageHeader>
|
||||
<PageHeader title="Welcome" theme="dark" centered />
|
||||
<PageHeader title="Settings" noBackground />
|
||||
```
|
||||
|
||||
### Templates
|
||||
|
||||
Templates are page-level layout components that define where content goes via typed slot props. They do not own content. Use them inside `AppShell` for full page layouts, or standalone for the content area only.
|
||||
|
||||
#### AppShell
|
||||
|
||||
Application shell that composes TopBar + SideNav + scrollable content area. All pages render inside this.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `topBar` | `ReactNode` | — | **Required.** TopBar component |
|
||||
| `sideNav` | `ReactNode` | — | **Required.** SideNav component |
|
||||
| `sideNavCollapsed` | `boolean` | `false` | Whether SideNav is in icon-only mode |
|
||||
| `children` | `ReactNode` | — | Scrollable content area |
|
||||
|
||||
```tsx
|
||||
import { AppShell } from '@/components/templates/AppShell'
|
||||
|
||||
<AppShell
|
||||
topBar={<TopBar title="My App" />}
|
||||
sideNav={<SideNav>{/* nav items */}</SideNav>}
|
||||
>
|
||||
{/* Page content */}
|
||||
</AppShell>
|
||||
```
|
||||
|
||||
#### DashboardPage
|
||||
|
||||
Dashboard layout with stat summary row and responsive 2-column content grid.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `header` | `ReactNode` | — | PageHeader or custom header |
|
||||
| `stats` | `ReactNode` | — | Stat cards row (flex wrapped) |
|
||||
| `children` | `ReactNode` | — | **Required.** Content grid items (2-col at lg) |
|
||||
|
||||
```tsx
|
||||
import { DashboardPage } from '@/components/templates/DashboardPage'
|
||||
|
||||
<DashboardPage
|
||||
header={<PageHeader title="Dashboard" />}
|
||||
stats={<><StatCard /><StatCard /><StatCard /></>}
|
||||
>
|
||||
<Card>Left column</Card>
|
||||
<Card>Right column</Card>
|
||||
</DashboardPage>
|
||||
```
|
||||
|
||||
#### ListPage
|
||||
|
||||
List layout with stat summary, list header with actions, and scrollable item list.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `header` | `ReactNode` | — | PageHeader or custom header |
|
||||
| `stats` | `ReactNode` | — | Stat cards row |
|
||||
| `listHeader` | `ReactNode` | — | Title + action button above the list |
|
||||
| `children` | `ReactNode` | — | **Required.** List items (rendered inside divide-y container) |
|
||||
|
||||
```tsx
|
||||
import { ListPage } from '@/components/templates/ListPage'
|
||||
|
||||
<ListPage
|
||||
header={<PageHeader title="Activity Log" />}
|
||||
stats={<><StatCard /><StatCard /></>}
|
||||
listHeader={<div className="flex justify-between"><h2>Items</h2><Button>Add</Button></div>}
|
||||
>
|
||||
<div className="px-6 py-4">Item 1</div>
|
||||
<div className="px-6 py-4">Item 2</div>
|
||||
</ListPage>
|
||||
```
|
||||
|
||||
#### FormPage
|
||||
|
||||
Form layout with optional vertical stepper and constrained-width content.
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `header` | `ReactNode` | — | PageHeader or custom header |
|
||||
| `actions` | `ReactNode` | — | Action bar above form (dropdowns, buttons) |
|
||||
| `steps` | `FormPageStep[]` | — | Vertical stepper steps (`{ label, status }`) |
|
||||
| `children` | `ReactNode` | — | **Required.** Form content (max-w-3xl centered) |
|
||||
|
||||
**FormPageStep:**
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `label` | `string` | Step label text |
|
||||
| `status` | `'complete' \| 'current' \| 'upcoming'` | Step state |
|
||||
|
||||
```tsx
|
||||
import { FormPage } from '@/components/templates/FormPage'
|
||||
|
||||
<FormPage
|
||||
header={<PageHeader title="Setup" />}
|
||||
steps={[
|
||||
{ label: 'Your details', status: 'current' },
|
||||
{ label: 'Review', status: 'upcoming' },
|
||||
]}
|
||||
>
|
||||
<Card><CardContent><Input label="Name" /></CardContent></Card>
|
||||
</FormPage>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Do's and Don'ts
|
||||
|
||||
**Do:**
|
||||
@@ -577,6 +1080,8 @@ import { Popover, PopoverTrigger, PopoverContent } from '@/components/molecules/
|
||||
- Use semantic HTML (`<button>`, `<input>`, `<dialog>`) — not `<div onClick>`
|
||||
- Include `aria-label` on icon-only buttons
|
||||
- Use `lucide-react` for icons (already a dev dependency)
|
||||
- Compose pages using AppShell (TopBar + SideNav + content) as the outer layout
|
||||
- Use the spacing conventions (p-6 content padding, gap-6 between sections)
|
||||
|
||||
**Don't:**
|
||||
- Hardcode colour hex values in component code
|
||||
@@ -584,3 +1089,4 @@ import { Popover, PopoverTrigger, PopoverContent } from '@/components/molecules/
|
||||
- Use CSS modules or styled-components
|
||||
- Skip the `label` prop on form controls — all inputs must have visible labels
|
||||
- Nest interactive elements (button inside button, link inside button)
|
||||
- Reference palette tokens (`text-blue-01`, `border-grey-03`) in component code — add a semantic token if one doesn't exist
|
||||
|
||||
Reference in New Issue
Block a user