Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015e81pY6swiKHQZDcN86CTD
8.3 KiB
Modernist Design System Restyle
Date: 2026-09-30
Status: Approved
Goal: Restyle the whole IMS app to the Modernist design system in design-system/_ds/modernist-*/, and record the guidelines so future development follows them.
Decisions
- Governing source: Modernist (
design-system/_ds/modernist-6062679c-a4aa-42a4-9043-28fea370dda9/readme.mdandstyles.css).design-system/IMS Admin.dc.html(Geist, teal, 12px radius) is superseded and is not implemented. Its screen structure is out of scope for this pass. - Scope: Whole app in one pass: tokens and base styles, shared shell, then every page (login, reporter, HSE, supervisor, management, capa-owner, admin).
- Approach: Remap Tailwind v4 tokens to Modernist so the existing utility classes restyle automatically, then add a thin set of shared components where token remapping leaves the markup structurally wrong.
Current state
- Tailwind v4 (
@import "tailwindcss"and@theme inlineinapp/globals.css), 62 TSX files withclassName. - Utility usage: 522
gray-*, 120blue-*, 219rounded*, 57shadow*. - Semantic colors in use: red (errors, overdue), green (done, verified), purple, yellow, orange (workflow statuses, priorities).
- Font: Geist and Geist Mono via
next/font/googleinapp/layout.tsx. - Icons: inline SVG,
lucide-reactis not installed. - Shared UI:
components/ui/modal.tsx(rounded-2xl, gray-900/50 backdrop),components/layout/sidebar.tsx.
Design
1. Tokens (app/globals.css)
Copy the Modernist :root variables verbatim from styles.css (colors, neutral and accent ramps, fonts, spacing, radius, shadows). Do not hard-code hex values elsewhere.
Expose them to Tailwind through @theme:
--color-gray-50…900map to--color-neutral-100…900(nearest step). Existinggray-*classes then render on the Modernist neutral ramp.--color-blue-50…900map to--color-accent-100…900. Existingblue-*classes then render as the red accent (primary buttons, links, focus).--radius-*(sm,md,lg,xl,2xl,3xl) are set to0.rounded-fullis left alone, so circular avatars and radio dots stay round.- Shadows: remap
shadow-sm/md/lgto--shadow-sm/md/lg.shadow-xlandshadow-2xlare replaced withshadow-lg. --font-sansand--font-headingare set to Archivo (400, 600, 800). Remove Geist, and Geist Mono stays only if monospace is used anywhere.
Base layer (from styles.css): body uses --color-bg and --color-text at 15px/1.55, headings use Archivo 800 with the Modernist scale, a uses the accent, :focus-visible is a 2px accent outline with 2px offset, ::selection is an accent tint, disabled controls drop to 45% opacity. Remove the prefers-color-scheme: dark block: Modernist defines only a light ground.
Fix app/globals.css input colors (#111827, #6b7280) to use --color-text and a 55% text mix.
2. Shared components (components/ui/)
Each takes Modernist tokens only and carries the markup rules Tailwind remapping cannot:
| Component | Rules |
|---|---|
Button (primary, secondary, ghost, icon, block) |
Archivo 800 14px, flush-left label even when wide, primary is solid accent with accent-600 hover and accent-700 pressed. Secondary is a 1px divider border. |
Tag (accent, neutral, outline) |
11px, 3px 10px padding, no radius. Used for statuses and priorities. |
Field and Input |
12px label above, 36px min height, surface fill, 1px divider border, accent border on focus. |
Card |
Surface fill, 12px padding, no border, no radius, optional kicker, title, meta. |
DataTable styles |
Uppercase 11px header with a 2px divider under it, 1px row rules, 4% text-tint row hover. |
Modal (existing) |
Restyle to .dialog: surface fill, 0 radius, --shadow-lg, neutral-900/50 backdrop, title uses Archivo 800 20px, Lucide X for close. |
Existing pages keep their own markup where the remapped utilities already render correctly. Migrate a page to these components only when its markup needs a structural change (for example centered button labels, rounded chips, hairline dividers).
3. Shell
- Sidebar: flat surface, 2px right rule in
--color-divider, brand in Archivo 800, nav items flush left with Lucide icons, active item in accent, version label kept at the bottom. - Mobile bottom nav: 2px top rule, same active treatment.
- Notification bell: square button with a 1px divider border (was a round white button).
- Section dividers: use
.hr(2px) between major sections, not whitespace or hairlines.
4. Icons
Install lucide-react and replace the inline SVGs in the sidebar, modal, nav, and buttons with Lucide equivalents. Default 16 to 20px, stroke 2.
5. Imagery
Add the grayscale class (filter: grayscale(1) contrast(1.08)) for decorative or brand photography only. Incident evidence photos and thumbnails stay in full color, because color can carry evidence (spill color, burns, signage). Decided 2026-09-30.
6. Status and priority colors (design decision)
Modernist is near-mono with one accent, so the current red, green, purple, yellow and orange status chips cannot all survive. Proposed mapping:
| Meaning | Treatment |
|---|---|
| Needs attention or overdue, open, reported, severity 4 to 5, errors | tag-accent (red tint), red text for inline errors |
| In progress (triaged, investigating, CAPA pending, verification) | tag-outline (accent outline) |
| Done (closed, verified, completed) | tag-neutral |
| Low priority or informational | tag-neutral |
Status is never conveyed by color alone: every tag keeps its text label, and the workflow states gain a Lucide icon. One central StatusTag and PriorityTag component replaces the scattered STATUS_COLORS and PRIORITY_COLORS maps (used in capa-board.tsx, incident-list.tsx, incident-header.tsx, incident-detail.tsx, and the reporter, supervisor and capa-owner pages).
7. Out of scope
- The IMS Admin mockup layouts (index tables with saved views, filter chips, bulk select).
- Dark mode.
- Data, API, auth or routing changes.
- Email templates and the generated PDFs (JKKP 6/7/8, incident report). They keep their own styling.
Documentation and memory
- Add a "Design system" section to
CLAUDE.md: Modernist is the source of truth, use tokens and never hard-code hex or px, 0 radius, flush-left labels, 2px rules, Lucide icons,grayscaleimagery, status viaStatusTagandPriorityTag. - Save a memory file
ims-design-system.md(typereference) pointing atdesign-system/_ds/modernist-*/readme.mdand recording these rules and the status-color mapping, then add it toMEMORY.md.
Testing and verification
next buildpasses with no type errors. The vitest suite still passes. Only tests asserting old class names need updating.- Run the app locally and check each role's pages in a browser: login, reporter report form and list, HSE inbox, incident detail, CAPA board, supervisor, management dashboard, admin users and settings. Check desktop and mobile widths.
- Grep gates after migration: no
rounded-(sm|md|lg|xl|2xl|3xl)left in app/ or components/ apart from deliberate exceptions, no hard-coded hex in TSX, notext-centeron button labels. - Keyboard: every interactive element shows the 2px accent focus ring.
- Contrast: body copy in accent uses
accent-700, not the accent itself (accent on ground is 3:1, so chrome only).
Deployment
A build-only deploy per the IMS deployment procedure (/srv/apps/ims/app, never build on the server, keep .next/BUILD_ID and .next/static in place). No database changes.
Risks
- Remapping
blue-*to red can make unrelated blue uses (links, info banners) read as errors. Review everyblue-*site (120 uses) and switch informational ones to neutral. - Status legibility: removing green and purple makes states less scannable. Icons plus labels mitigate this, and the mapping above needs your sign-off.
- Archivo 800 headings are wider than Geist and can overflow narrow table headers and mobile nav labels. Check at 360px.
- Visual diff is large (62 files of class changes), so review in a browser, not only via the diff.
Resolved decisions
- Status mapping in section 6 is approved as written. Green is not kept for "closed/verified".
- Evidence photos are exempt from grayscale (section 5).