Files
ims/docs/superpowers/specs/2026-09-30-modernist-design-system-design.md
T

118 lines
8.3 KiB
Markdown

# 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.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
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, `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.
## Open questions
1. Is the status mapping in section 6 acceptable, or should green be kept as a second semantic color for "closed/verified"?
2. Should incident evidence photos be forced to grayscale, or exempted because color can carry evidence?