Files
ims/design-system/design.md
T

14 KiB

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

Mockup features with no backend yet (do not fake them in the UI): CAPA export, bulk actions on a selection (send reminder, reassign, escalate), group-by, department and due-date range filters, the activity and comments feed, cost, evidence files on a CAPA, the verification note, "ask owner a question", and edit. Add them in a slice that also adds the backend.

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) and slice 2 (CAPA list, board, detail, verification, create form) are 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