---
title: Setup for AI coding tools
type: scaffolder
last_verified: 2026-05-05
---

# 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):

```bash
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:

```ts
// 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:

```bash
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.

````markdown
# 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](https://aleris-brand-os.vercel.app/baseline/raw/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:

- Error messages → https://aleris-brand-os.vercel.app/baseline/raw/patterns/error-message.md
- Confirmations → https://aleris-brand-os.vercel.app/baseline/raw/patterns/confirmation.md
- Empty states → https://aleris-brand-os.vercel.app/baseline/raw/patterns/empty-state.md
- Button labels → https://aleris-brand-os.vercel.app/baseline/raw/patterns/button-label.md
- Chat responses → https://aleris-brand-os.vercel.app/baseline/raw/patterns/chat-response-simple.md

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.