# Courts Service Portal Design System

This folder holds the browsable design system: the reference pages in
`app/pages/design-system/`, plus a snapshot of the CSS they were built against.

**Inside this repo, the source of truth for the CSS is `assets/css/design-system/`,
not `shared/css/` here.** Read "Which CSS to use" below before editing or linking
anything.

The AI instruction files are helpers for Codex and Claude; they are not the design
system itself.

## Which CSS to use

| | `assets/css/design-system/` | `legacy-design-system/shared/css/` |
| --- | --- | --- |
| Status | Live. Source of truth. | Frozen snapshot, last touched 2026-07-24. |
| Edit it? | Yes. | No. |
| Used by | Every portal page, and every reference page here. | Nothing. |

Every reference page now links the live CSS
(`../../../../assets/css/design-system/…`), so the snapshot's four layers are
unreferenced and only `design-system-nav.css` beside them is still in use. The
snapshot is retained as a record of what the system looked like on 2026-07-24;
it can be deleted once nobody wants that reference.

For the record of how far it drifted: `components.css` differs from the live file
by roughly 1,500 lines and lacks `.portal-pagination` and its page buttons,
`find-address.css`, and `info-input.css`. `utilities.css` and `app.css` are
identical; `tokens.css` is close but not identical.

## Included

- `shared/css/*` (frozen snapshot — see "Which CSS to use")
- `shared/css/design-system-nav.css` (still in use: the reference-page left rail)
- `app/pages/design-system/*.html`
- `assets/icons/Courts-Service-logo.svg`
- `claude/CLAUDE.md`

The agent skill moved to `.claude/skills/portal-design-system/` so it actually
loads. The component registry — the allowlist of every class in the system — is
`reference/docs/design-system/COMPONENTS.md`.

## Core Files

The sections below describe the shared CSS layers, all under
`assets/css/design-system/`.

### Tokens

`tokens.css` defines:

- color tokens and semantic aliases
- text and border role tokens
- radius, spacing, max-width, and shadow tokens
- typography family, weights, sizes, and line heights
- semantic surface tokens

### Shared component layer

`components.css` is the main shared UI layer for layout and reusable components.

`components/*.css` contains more focused component files for:

- breadcrumb
- cards
- chips
- forms
- header
- review
- stepper
- upload
- address block
- find address
- info input

### Utilities and app shell

`utilities.css` contains utility classes.

`app.css` contains app-shell and page-level shared styles used by the portal pages.

## Example Reference Pages

The example pages are in `app/pages/design-system/`. These are actively maintained —
add a new page here and register it in `shared/js/design-system-nav.js` so it appears
in the left nav.

Useful starting pages:

- `typography.html`
- `colors.html`
- `buttons.html`
- `inputs.html`
- `cards.html`
- `chips.html`
- `messages.html`
- `navigation.html`
- `headers.html`
- `utilities.html`
- `tables.html`

## Load Order

For most portal pages, the expected shared CSS load order is:

1. `tokens.css`
2. `components.css`
3. `utilities.css`
4. `app.css`
5. feature or page CSS last

Load these from `assets/css/design-system/`. Portal pages reference them as
`/assets/css/design-system/…`; reference pages in this folder need the relative
`../../../../assets/css/design-system/…`.

Some design-system example pages intentionally insert Bootstrap before `components.css` to demonstrate coexistence with the portal styles. For new work, treat the shared portal CSS files as the source of truth and avoid relying on Bootstrap defaults.

## Implementation Notes

- Typography uses `Lato` with fallbacks.
- The color system is token-led and semantic roles should be preferred over raw hex values.
- Header navigation selection is a hard design-system rule: selected header buttons and header menu items use `--header-nav-item-selected-bg` with `--header-nav-item-selected-fg`, not white text.
- Spacing uses a 4px/8px token scale with a few half-step compatibility tokens such as `--space-2h`, `--space-3h`, and `--space-4h`.
- Changes to the shared CSS layers are system-level changes — make them in
  `assets/css/design-system/`, never in the `shared/css/` snapshot.
- Prefer feature-local CSS outside the shared layer when building one-off screens.

## How To Review The System

Open any of the files in `app/pages/design-system/` in a browser using the package's existing folder structure.

The pages reach up into `assets/css/design-system/`, so they need the repo served
from its root — `npx serve .` at the top level, not inside this folder. This folder
is therefore no longer portable on its own; copying it elsewhere means taking
`assets/css/design-system/` with it and fixing the relative paths.

## Using This In Another Project

Copy from `assets/css/design-system/` rather than the `shared/css/` snapshot, which
is out of date. Minimum adoption path:

1. Copy `tokens.css`.
2. Copy the relevant shared CSS layers.
3. Use the example pages as implementation references.
4. Keep semantic token names intact where possible.

If this design system is being adapted rather than copied verbatim, keep `tokens.css` stable and remap only the consuming components first.