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: Draft, awaiting user review
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
Wrap evidence thumbnails and any content photographs in a grayscale class (filter: grayscale(1) contrast(1.08)). Exception: photos that document an incident where color carries evidence. Open question below.
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.
Open questions
- Is the status mapping in section 6 acceptable, or should green be kept as a second semantic color for "closed/verified"?
- Should incident evidence photos be forced to grayscale, or exempted because color can carry evidence?