# 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.md` and `styles.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 inline` in `app/globals.css`), 62 TSX files with `className`. - Utility usage: 522 `gray-*`, 120 `blue-*`, 219 `rounded*`, 57 `shadow*`. - Semantic colors in use: red (errors, overdue), green (done, verified), purple, yellow, orange (workflow statuses, priorities). - Font: Geist and Geist Mono via `next/font/google` in `app/layout.tsx`. - Icons: inline SVG, `lucide-react` is 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…900` map to `--color-neutral-100…900` (nearest step). Existing `gray-*` classes then render on the Modernist neutral ramp. - `--color-blue-50…900` map to `--color-accent-100…900`. Existing `blue-*` classes then render as the red accent (primary buttons, links, focus). - `--radius-*` (`sm`, `md`, `lg`, `xl`, `2xl`, `3xl`) are set to `0`. `rounded-full` is left alone, so circular avatars and radio dots stay round. - Shadows: remap `shadow-sm/md/lg` to `--shadow-sm/md/lg`. `shadow-xl` and `shadow-2xl` are replaced with `shadow-lg`. - `--font-sans` and `--font-heading` are 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, `grayscale` imagery, status via `StatusTag` and `PriorityTag`. - Save a memory file `ims-design-system.md` (type `reference`) pointing at `design-system/_ds/modernist-*/readme.md` and recording these rules and the status-color mapping, then add it to `MEMORY.md`. ## Testing and verification - `next build` passes 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, no `text-center` on 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 every `blue-*` 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 1. Status mapping in section 6 is approved as written. Green is not kept for "closed/verified". 2. Evidence photos are exempt from grayscale (section 5).