Design System Overview

Pathogen is the shared visual language for healthcare, laboratory, and public-health tools. It lives in components, tokens, previews, and CSS. The system is strongest when those pieces feel like one considered product.

On a busy screen, Pathogen should feel quiet, precise, accessible, compact, and trustworthy. The interface should make the work easier to see: the specimen row, the run status, the form error, the save action. Everything else should stay out of the way.

The Five Qualities

Quality	What it asks of the UI
Quiet	Surfaces recede. Colour and weight appear only when they carry meaning.
Precise	Type, spacing, corners, and alignment feel intentional at every scale.
Accessible	Focus, contrast, names, state, and motion are part of the form.
Compact	Dense tools keep enough rhythm for reading, scanning, and correction.
Trustworthy	Clinical work feels credible because the interface is clear and consistent.

These qualities are not separate checkboxes. A compact grid is trustworthy only if it remains readable. A quiet button is accessible only if its state is still visible. Precision is what holds the whole system together.

From Smallest Part To Whole Product

Build from purpose, then move outward:

Purpose
  What job does this element do?
    ↓
Tokens
  Colour, type, radius, elevation, motion
    ↓
Building blocks
  Roles, scale, spacing, corners, state
    ↓
Controls
  Button, link, form field, tab
    ↓
Content
  Labels, body copy, code, copyable values, tooltips, badges
    ↓
Surfaces
  Panels, grids, fieldsets, dialogs, overlays
    ↓
Pages
  Regions, workflows, host apps, previews

Layer	Examples	Read more
Tokens	--pvc-color-surface, --type-control	Tokens
Building blocks	Colour roles, type scale, spacing, radius	Foundations
Controls	Button, Link, Form::*	Foundations
Content	Badge, Typography, tooltips	Foundations
Surfaces	DataGridComponent, fieldsets, dialogs	Foundations, Dark mode
Pages	Host apps, Lookbook previews	Preview guidelines

The Foundations page describes how the middle layers behave: colour, type, spacing, radius, elevation, motion, controls, and accessibility.

Surfaces, Not Cards

A surface is a bounded work area: a grid frame, form section, fieldset, dialog body, or preview frame. It has a job. It groups related work, separates one region from another, or contains a focused task.

Pathogen does not ship a generic Card component yet. Compose surfaces from tokens and layout. The :card preset on Pathogen::Typography::HeadingGroup is only a compact heading style, not a card component.

Reading Order

1. Foundations — colour, type, spacing, buttons, forms, state, and accessibility.
2. Tokens — the materials of the system and what is still migrating.
3. Dark mode — the same product language under lower light.
4. Preview guidelines — how examples should look like real product work.
5. Review checklist — a compact pass before merge.
6. Host and library boundary — what belongs in Pathogen vs any host app.

When Docs, Code, And Previews Disagree

1. These pages describe the intended direction. Known CSS gaps, if any, are on the token list.
2. pathogen.tailwind.css and shipped components are ground truth for behaviour and values not called out as future work.
3. Previews should prove the system in product-like contexts. Fix drift instead of creating a second visual language.

Button and CopyableValue are the clearest semantic-token examples today. New work should follow them instead of legacy neutral-600 shortcuts.

Host Applications

Pathogen owns shared roles, component behaviour, and accessibility expectations. Host apps own brand colour through --color-primary-* and compose pages with Pathogen::*. See Host and library boundary for what must stay out of the gem and how to retire host-local UI debt.