Files
ims/design-system/design.md
T
adminandClaude Haiku 4.5 f117605775 docs(design): add design.md for the IMS Admin refresh and track its mockup references
Derived from IMS Admin Spec.dc.html and IMS Admin.dc.html. Defines tokens,
components (StatusTag, TableCard, shells, drawer), screen index, build order
and the changes from the live Modernist build. CLAUDE.md already cites it as
the source of truth.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-10-01 08:37:36 +08:00

211 lines
13 KiB
Markdown

# IMS Design System: Admin refresh
Source of truth for IMS UI. Derived from `IMS Admin Spec.dc.html` (patterns, tokens, states) and `IMS Admin.dc.html` (25 artboards: 7 desktop screens plus variants, 9 mobile screens). When this file and the mockups disagree, fix this file and say so in the PR. The earlier Modernist system (`design-system/_ds/`) is retired.
Rules in `CLAUDE.md` ("Design system") summarise this file. Tokens in `app/globals.css` mirror §2.
## 1. Principles
- Neutral commerce-admin look: grey ground, white cards, dark primary action, one teal accent used sparingly.
- Every list is a `TableCard` (§4.9). Do not hand-build tables.
- Status is always a dark text step on a light tint, with a text label (§4.2). Never white text on a saturated fill, never colour alone.
- Rules are 1px. Corners come from the radius scale in §2.3. Text and headings are flush left.
- Minimum hit target 44px on mobile.
## 2. Tokens
### 2.1 Colour
| Token | Hex | Use |
| --- | --- | --- |
| `ink` | `#1f1f1f` | Primary text, active sidebar text |
| `ink-2` | `#303030` | Primary button, chip text |
| `ink-3` | `#4a4a4a` | Secondary text, icons |
| `muted` | `#616161` | Labels, helper text |
| `faint` | `#8a8a8a` | Placeholders, input ring |
| `rule` | `#ebebeb` | Row rules, sidebar background |
| `rule-2` | `#e3e3e3` | Header rule, segmented background |
| `ring` | `#d4d4d4` | Secondary button and chip ring |
| `surface` | `#ffffff` | Cards, rows, inputs |
| `surface-2` | `#f7f7f7` | Table header, footer, row hover |
| `ground` | `#f1f1f1` | Page background |
| `accent` | `#0f766e` | Checks, links, focus ring, active tab icon |
| `accent-tint` | `#f2f7f6` | Selected row, selected card |
| `accent-tint-2` | `#e6f4f1` | Set filter chip (ring `#9fd3c7`, text `#0b4f47`) |
| `danger` | `#b3261e` | Overdue text, required marks, input error |
| `topbar` | `#1a1a1a` | App header (its controls use `#303030`, ring `#3d3d3d`, text `#a3a3a3`) |
Tailwind names: `bg-ground`, `bg-surface`, `bg-surface-2`, `text-ink`, `text-ink-2`, `text-ink-3`, `text-muted`, `text-faint`, `border-rule`, `border-rule-2`, `border-ring`, `bg-accent`, `text-accent`, `bg-accent-tint`, `bg-accent-tint-2`, `text-danger`, `bg-topbar`.
### 2.2 Type
Geist for UI, Geist Mono for references and keyboard hints. Exposed as `--font-geist` and `--font-geist-mono`.
| Spec | Use |
| --- | --- |
| 32 / 600 / -0.02em | Cover title |
| 22 / 650 / -0.02em | Mobile page title |
| 20 / 650 / -0.01em | Page title |
| 16 / 650 / -0.01em | Card title (detail) |
| 14 / 600 | Section heading |
| 13 / 400-550 | Body, table cells, buttons |
| 12 / 550 | Table header, pill, helper |
| 12.5 mono / 500 | References such as `IMS-2026-0247` |
### 2.3 Radius, shadow, spacing, icons
- **Radius:** 12 cards and phones; 10 mobile drawer and mobile inputs; 8 buttons, chips, inputs, pills, sidebar items; 6 avatars (24px); 5 checkbox; 999 badges. Tailwind: `rounded-md` = 8, `rounded-xl` = 12, `rounded-[5px]` checkbox.
- **Card shadow** (`shadow-card`): `0 0 0 1px rgba(0,0,0,.08), 0 1px 2px rgba(0,0,0,.06)`.
- **Floating shadow** (`shadow-float`, bulk bar): `0 0 0 1px rgba(0,0,0,.1), 0 12px 32px rgba(0,0,0,.18)`. Drawer: `0 0 0 1px rgba(0,0,0,.1), 0 24px 60px rgba(0,0,0,.24)`.
- **Focus:** `outline: 2px solid accent; outline-offset: 2px` on every interactive element.
- **Spacing:** 4, 6, 8, 10, 12, 16, 20, 24, 32. Card padding 16-20, table cell 12, toolbar 10/12.
- **Icons:** Lucide. 16px stroke 2 in UI; 12px stroke 2.5 inside chips and checks; 22px stroke 1.8 in the mobile tab bar.
- **Motion:** transitions 120ms on background and shadow only.
## 3. Layout shell
**Desktop (`AppShell`)**
- Top bar 56px `topbar`: brand 224px (28px teal tile radius 8, "IMS", muted "Setia HSE"), search max 520px (34px, radius 10, shows a Cmd-K hint), bell and user chip on the right.
- Sidebar 240px `rule` background, 1px right border `#e0e0e0`, padding 12, items 32px radius 8, 13px. Active item: white, 1px ring, teal icon. Badges 999 `#dcdcdc`, 11px/600. Footer block has a 1px `#dcdcdc` top rule.
- Main: padding 24/32, column gap 16. Page title 20px/650 with actions on the right. Detail pages use `1fr` plus a 320-340px side rail.
- Page background `ground`; cards `surface`, radius 12, `shadow-card`.
**Mobile (`MobileShell`, reporter and CAPA owner)**
- 390px reference. Page title 22px/650, horizontal padding 16, card gap 12.
- Tab bar: white, 1px top rule, 3 items, 22px icons, 10.5px labels, active `accent`.
- Controls 48px tall, radius 12; primary button full width 48px. Footers sit on `ground` with a 1px top rule and 30px bottom safe area.
## 4. Components
Hover and active values below are per component. Every interactive element also gets the global focus ring (§2.3). Disabled controls drop to 45% opacity.
### 4.1 Button
- **Primary** 32px, radius 8, `#303030`, white 13px/600, inset highlight `inset 0 -1px 0 #000, inset 0 1px 0 rgba(255,255,255,.18), 0 1px 2px rgba(0,0,0,.2)`. Hover `#1f1f1f`, active `#000`.
- **Secondary** white, 13px/550, ring `inset 0 0 0 1px #d4d4d4, 0 1px 0 rgba(0,0,0,.05)`. Hover `#f7f7f7`, active `#ebebeb`.
- **Icon** 28px ghost, radius 8, `ink-3`. Hover `#ebebeb`.
- Mobile primary: full width, 48px, radius 12.
### 4.2 StatusTag and PriorityTag
Pill: `inline-flex`, padding 2px 8px, radius 8, 12px/550, no wrap. Dark text on a light tint. Incident status and CAPA status share one palette.
| Label | Background | Text |
| --- | --- | --- |
| Reported | `#fff1c2` | `#6b4a00` |
| Triaged | `#e0efff` | `#00527c` |
| Investigating | `#ede7ff` | `#4b2e99` |
| CAPA pending | `#ffe6cf` | `#7a3a00` |
| Verification | `#e3e8ff` | `#2c3e8f` |
| Closed | `#d7f4e3` | `#0c5132` |
| Open | `#ebebeb` | `#4a4a4a` |
| In progress | `#e0efff` | `#00527c` |
| Overdue / Critical | `#fee3e0` | `#8e1f0b` |
| High | `#ffe6cf` | `#7a3a00` |
| Medium | `#fff1c2` | `#6b4a00` |
| Low | `#ebebeb` | `#4a4a4a` |
| Active | `#d7f4e3` | `#0c5132` |
| Verified | `#d7f4e3` | `#0c5132` |
| Reopened | `#fee3e0` | `#8e1f0b` |
Mapping from the data model: incident `reported/triaged/investigating/capa_pending/verification/closed` use the matching rows; CAPA `open/in_progress/overdue/pending_verification/verified/reopened/closed` map to Open, In progress, Overdue, Verification, Verified, Reopened, Closed; priority `high/med/low` map to High, Medium, Low. Severity 5 and Critical use the Overdue / Critical row. Tailwind: `st-<name>-bg` / `st-<name>-fg` pairs. No icon required; the text label is always present.
### 4.3 FilterChip
28px, radius 8, 12.5px, padding 0 10px. Unset: white, ring `#d4d4d4`, text `#303030`, trailing 12px chevron. Set: `accent-tint-2`, ring `#9fd3c7`, text `#0b4f47`, shows "Label: value" and a clear x.
### 4.4 Segmented
Container padding 2px, background `#e3e3e3`, radius 10. Option 13px, padding 5px 10px, radius 8. Active: white, 13px/600, `0 1px 2px rgba(0,0,0,.1)`. Used for List / Board.
### 4.5 Checkbox
16px, radius 5. Off: white with `inset 0 0 0 1.5px #8a8a8a`. On and indeterminate (header): `accent` fill, white 12px tick or minus at stroke 3.
### 4.6 Field and Input
Input 36px desktop, 48px mobile, padding 0 12px, radius 8 (12 on mobile), 13px, white. Rest ring `inset 0 0 0 1px #8a8a8a`; focus ring 2px `accent`; error ring `danger`. Placeholder `faint`. Label 12px `muted`, 5px above. Textarea and Select share the ring.
### 4.7 Avatar
24px, radius 6, background `#c5e8e0`, text `#0b4f47`, 11px/650, initials. Top bar variant sits in a `#303030` chip.
### 4.8 Card
White, radius 12, `shadow-card`, padding 16-20. Selected card uses `accent-tint`. Detail card title 16px/650.
### 4.9 TableCard
One component wraps every list. Parts top to bottom, all optional except the table and the card:
- **A. Saved views:** padding 8, bottom rule `#ebebeb`. View chip 28px radius 8, 13px; active `#e3e3e3` 13px/600 with a faint count (12px `#8a8a8a`); trailing + button opens "Save current filters as view". Saved views are server-side filters; counts update live.
- **B. Toolbar:** padding 10/12, bottom rule. Search 32px, radius 8, ring `#8a8a8a`, min-width 260. Filter chips (§4.3). Right-aligned actions.
- **C. Header:** `surface-2`, 12px/550 `muted`, padding 9/12, bottom rule `#e3e3e3`. Single-column sort: sorted column shows a filled arrow in `ink`, others a faint `#c4c4c4` double chevron.
- **D. Row rest:** white, 13px, cell padding 12, 1px `#ebebeb` rule. References in Geist Mono 12.5px in `accent`.
- **E. Row hover:** `surface-2`; quick actions (eye, more) appear on the right as 28px icon buttons.
- **F. Row selected:** `accent-tint` and a filled checkbox.
- **G. Footer:** `surface-2`, padding 10/16, "Showing 1-3 of 248" left, pager right (32px segmented chevrons, radius 8 on outer ends, ring `#d4d4d4`).
- **H. Bulk bar:** floats centred above the footer on first selection. White, radius 12, `shadow-float`, padding 6 6 6 12; checkbox, "N selected", divider, ghost actions (Assign, Export).
- **Empty state:** replaces thead and tbody: 64px icon tile, one line of copy, the primary action.
Behaviour: the whole row opens the record; the checkbox cell, links and quick actions stop propagation.
**Mobile:** below 768px the table becomes a stacked list in the same card: reference + status on line one, type and zone on line two, date on line three, chevron right. Saved views become horizontally scrolling 999px chips; filters collapse to one "Filter" button opening a sheet; the bulk bar becomes a bottom sheet.
### 4.10 Drawer
Notifications drawer: absolute, top/right/bottom 8px, width 420px, white, radius 14, shadow `0 0 0 1px rgba(0,0,0,.1), 0 24px 60px rgba(0,0,0,.24)`; scrim `rgba(0,0,0,.28)`. Header 16px/650 title with "Mark all read" (12.5px/550 `accent`), settings and close icon buttons. Tab row of 28px view chips with counts. Group labels 11.5px/600 uppercase `faint`. Items: 32px radius-9 icon tile, padding 12/16, rule `#f0f0f0`, unread items tinted.
## 5. Screen index
| Id | Screen | Route |
| --- | --- | --- |
| 01 | Incidents list | `/hse/incidents` |
| 01b | Notifications drawer | global |
| 02 | Incident detail | `/hse/incidents/[id]` |
| 02b | Triage form | `/hse/incidents/[id]` triage |
| 02c | Investigation form | `/hse/incidents/[id]` investigation |
| 02d | DOSH reporting (JKKP 6) | `/hse/incidents/[id]` new |
| 03 | Dashboard | `/hse/dashboard` |
| 04 | CAPA list | `/hse/capa` |
| 04b | CAPA board | `/hse/capa` board |
| 04c | CAPA detail, verification | `/hse/capa` new |
| 05 | Admin, users | `/admin` |
| 05b | Admin, sites and zones | `/admin` tab |
| 05c | Admin, trucks | `/admin` tab |
| 05d | Admin, audit log | `/admin` new tab |
| 06 | Settings, API keys | `/hse/settings` |
| 07 | Reporter, my reports | `/reporter` |
| 08 | Empty state | pattern |
| 09 | Mobile, reporter home | `/reporter` |
| 10 | Mobile, incidents | `/hse/incidents` |
| 11 | Mobile, incident detail | `/hse/incidents/[id]` |
| 12-15 | Mobile, new incident 1/3 to saved offline | `/report` |
| 16 | Mobile, CAPA owner action | `/capa-owner` |
New routes in the mockup that do not exist yet: audit log (05d), DOSH reporting entry (02d), and any "new tab" marked above. Treat them as separate features; do not build them as part of the restyle.
## 6. Accessibility
- Text on tints passes contrast because pills use dark steps. Body text is `ink` or `ink-3` on white or `ground`; `faint` is for placeholders only.
- Focus ring on every interactive element; nothing relies on colour alone.
- Hit targets 44px minimum on mobile.
## 7. Scope
This file covers look and component structure. Routes, queries, permissions and audit logging do not change as part of a restyle.
## 8. Build order
1. **Tokens:** replace the Modernist tokens in `app/globals.css` with §2 (`@theme static`), Geist via `next/font`, `shadow-card`, `shadow-float`, `st-*` pairs. Keep the `gray-*`/`blue-*`/`red-*` remaps pointing at the new neutral and teal values so unmigrated pages stay readable.
2. **UI primitives:** `Button`, `StatusTag`, `PriorityTag`, `Checkbox`, `Field`/`Input`/`Select`/`Textarea`, `FilterChip`, `Segmented`, `Avatar`, `Card`, `Drawer` in `components/ui/`.
3. **TableCard** (§4.9) with the desktop and mobile variants.
4. **Shells:** `AppShell` (top bar, sidebar, notifications drawer) and `MobileShell`.
5. **Migrate the Incidents list** (screen 01 and 10) as the first full screen.
6. **Remaining screens**, in §5 order, one plan per group.
Gate first: before step 1, update `scripts/check-design-gates.mjs` to allow `rounded-*`, flag `border-b-2` and `border-2`, and flag Archivo and `#ec3013`. `npm run check:design` must pass at the end of each step.
## 9. What changes from the live Modernist build
| Area | Now (Modernist) | After |
| --- | --- | --- |
| Font | Archivo | Geist and Geist Mono |
| Accent | `#ec3013` red | `#0f766e` teal (used sparingly) |
| Primary button | red, flush left | `#303030`, 32px, radius 8 |
| Radius | 0 everywhere | 8 / 10 / 12 scale |
| Rules | 2px section rules | 1px |
| Status | mono tags (accent, outline, neutral) | coloured pills (§4.2) |
| Sidebar | flat, 2px rule | dark top bar plus `#ebebeb` sidebar |
| Lists | per-page tables | `TableCard` |
| Gate | no rounded, 2px rules | rounded allowed, 2px flagged |