Files
ims/design-system/design.md

213 lines
14 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: one pair per hue, `bg-st-<hue>-bg` / `text-st-<hue>-fg`, hue in `amber blue violet orange indigo green grey red`; `StatusTag` maps each status to a hue (reported amber, triaged blue, investigating violet, capa_pending orange, verification and pending_verification indigo, closed and verified green, open and low grey, in_progress blue, overdue and reopened red, high orange, med amber). Banners follow the same pairs: error red, warning or offline amber, success green; AI suggestions and hints use `bg-accent-tint`. 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.
Slice 1 (gate, tokens, primitives, TableCard, shells, Incidents list) is implemented; the remaining screens follow in later plans.
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 |