Setup for AI coding tools

You are an AI coding assistant (Claude Code, Cursor, or similar) starting work on a new Aleris project. This page walks you through the four steps needed to bootstrap the design system into the project.

The base URL throughout this document is https://aleris-brand-os.vercel.app. Substitute your own host if you are reading a fork or proxied deployment.

Step 1 — Pull tokens into the project

The token CSS file is the only load-bearing build dependency. Everything else is reference.

Fetch it and write it into the project as src/styles/aleris-tokens.css (or wherever the project keeps global stylesheets):

curl -fsSL https://aleris-brand-os.vercel.app/baseline/raw/tokens/aleris-tokens.css \
  -o src/styles/aleris-tokens.css

Import it from the app entry point so every component can read the custom properties:

// app/layout.tsx, src/main.tsx, _app.tsx — wherever the global stylesheet lives
import '@/styles/aleris-tokens.css'

Optional but recommended — also fetch the JSON form for token lookup, autocomplete, and constraint metadata:

curl -fsSL https://aleris-brand-os.vercel.app/baseline/raw/tokens/baseline-tokens.json \
  -o src/styles/aleris-tokens.json

Step 2 — Drop a CLAUDE.md into the project root

Create CLAUDE.md at the project root with the contents below. Future sessions will read this and stay aligned without refetching this scaffolder every time.

# Aleris design system

This project uses the Aleris brand and design system. Tokens live in
`src/styles/aleris-tokens.css` (already imported). Reference material is at
https://aleris-brand-os.vercel.app/llms.txt — fetch that for the AI-readable
index of every guideline page.

## Non-negotiables

- Only use tokens from `aleris-tokens.css`. No raw hex, no pixel values, no
  raw Tailwind colour classes.
- Page background is sand, not white. `--surface-page` (communicative) or
  `--surface-page-instrumental`. Never white.
- One primary CTA per screen — orange `--brand-accent`.
- No font-weight 400. Museo Sans has no 400 weight. Use 500 or 700 only.
- 14px font floor — `--font-size-xs`. Nothing smaller.
- No all caps in content. Sentence case everywhere.
- Animate only `transform` and `opacity`. Respect `prefers-reduced-motion`.

The full list of ten hard rules and their reasoning lives at
https://aleris-brand-os.vercel.app/baseline/raw/BASELINE.md — read it before
writing UI.

## Surface mode

This project is **[communicative | instrumental]**.
<!-- Pick one. Communicative = patient-facing, marketing, booking, onboarding.
     Instrumental = tools, admin, dashboards, internal apps. -->

## When uncertain

Don't guess. Leave a comment in the code:

```css
/* OPEN: [the decision needed] */
```

Then continue with a reasonable placeholder. Surface OPEN comments at review.

## Out of scope for AI

- Don't write external-facing brand copy. Voice work is a human decision.
- Don't redesign tokens or invent new ones. Raise as an OPEN comment instead.
- Don't override hard rules to make a layout work — the layout is wrong.

## Owner

Torfinn Almers, Head of Design, Aleris Group.

Replace [communicative | instrumental] with one of the two values. The choice does not change between steps within a single flow.

Step 3 — Pick the surface mode

Every Aleris surface is either communicative or instrumental. The two modes use different page backgrounds, spacing, grid widths, and tone.

Communicative — Aleris guides, explains, welcomes. Patient-facing flows, marketing pages, booking, onboarding.

  • Page background: sand-100 (--surface-page)
  • Generous spacing, full type scale
  • Cards mandatory for content structure
  • Max width 1200px

Instrumental — The user works. Tools, admin, dashboards, internal documentation.

  • Page background: sand-50 (--surface-page-instrumental)
  • Tighter spacing, compressed type range
  • Cards optional — content can live directly on the surface
  • Max width 1440px or fluid

If unsure, ask the project owner. If the project mixes audiences (e.g. a clinician dashboard with a patient-facing report view), pick the dominant surface and treat the secondary view as a known divergence with a note.

Full reasoning is in the surface temperature section of BASELINE.md.

Step 4 — Read these before writing UI

Fetch and read in this order:

  1. https://aleris-brand-os.vercel.app/baseline/raw/BASELINE.md — hard rules, components, motion, accessibility.
  2. https://aleris-brand-os.vercel.app/foundation/raw/voice.md — how Aleris sounds.
  3. https://aleris-brand-os.vercel.app/foundation/raw/colour.md — palette and rules.
  4. https://aleris-brand-os.vercel.app/foundation/raw/typography.md — type system.
  5. https://aleris-brand-os.vercel.app/baseline/raw/governance/aleris-anti-patterns.md — ten healthcare anti-patterns. Hard constraints.

When you start building specific UI, fetch the matching pattern:

The full machine-readable index is at https://aleris-brand-os.vercel.app/llms.txt.

Known gaps (as of 2026-05-05)

These are not yet in the system. If the project needs them, ask the project owner before inventing:

  • F3 Logo placement, clearspace, sizing
  • F5 Writing conventions (microcopy, terminology, capitalisation rules beyond "no all caps")
  • Photography direction
  • Communication genres (email, SMS, push, letter formats)

Out of scope for this scaffolder

  • Picking a framework or build tool. Aleris doesn't mandate React vs Svelte vs anything else — but tokens must be importable as CSS custom properties, so ESM or postcss-friendly stacks are easiest.
  • Component library installation. There is no Aleris npm package today. Tokens are the contract; components are built per project.
  • Authentication, data layer, deployment. Out of brand scope.