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

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.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).