# Courts Service Portal Design System

Use this file when generating or editing UI that should follow the Courts Service Portal design system.

## Source of truth

The live CSS is under `assets/css/design-system/` at the repo root. Read these
before making design-system decisions:

- `../DESIGN-SYSTEM.md`
- `../../assets/css/design-system/tokens.css`
- `../../assets/css/design-system/components.css`
- `../../assets/css/design-system/utilities.css`
- `../../assets/css/design-system/app.css`
- `../../assets/css/design-system/components/*.css`
- `../app/pages/design-system/*.html` (browsable reference pages)

**Do not read or edit `../shared/css/`.** It is a frozen snapshot, last touched
2026-07-24, kept only so the older reference pages still render. `components.css`
there has drifted from the live file by roughly 1,500 lines and is missing later
components — you will reach wrong conclusions about what the system contains.

## Rules

- Prefer existing tokens over new raw CSS values.
- Prefer semantic tokens over palette tokens where both exist.
- Reuse existing shared component classes and patterns before creating new ones.
- Preserve the existing typography scale, Lato font family, spacing rhythm, radius tokens, and shadow tokens.
- Keep shared-system edits separate from feature-local edits. Shared edits go in
  `assets/css/design-system/`, never in `legacy-design-system/shared/css/`.
- Avoid introducing Bootstrap or framework defaults as if they were part of the portal system.

## Expected style

- Formal public-service product tone
- Accessible, legible layouts
- Strong semantic states for success, error, attention, and info
- Clear primary-action blue family
- Conservative but modern rounded UI treatment

## Implementation workflow

1. Inspect `tokens.css` for the values and semantic roles you need.
2. Inspect `components.css` and `assets/css/design-system/components/` for an existing pattern.
3. Check the nearest matching example in `legacy-design-system/app/pages/design-system/`
   (despite the folder name, these pages are current and actively added to).
4. Reuse or extend the existing pattern with minimal divergence.
5. Only add new shared tokens or classes when the existing system cannot express the requirement.

## Output preference

When proposing UI code, explain which existing tokens and shared patterns are being reused.