--- title: Setup for AI coding tools type: how-to/recipe layer: how-to last_verified: 2026-05-22 --- # 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://brand.dev.aleris.ai`. 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://brand.dev.aleris.ai/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' ``` **Keep your own values in a second file that loads after this one — never append them to it.** A project will need values Baseline does not carry, and the instinct is to add them to the bottom of the vendored file. Do not: the vendored copy has to stay byte-comparable to the source, because that comparison is the only thing that can tell you the tokens have moved. Put local additions in `src/styles/-tokens.css`, import it *after* the Aleris file, and let the cascade do the overriding. Then re-vendoring is a file replacement instead of a merge. **Do not strip the comments out of the file by hand.** Roughly two thirds of it is prose, and every `@usage` and `@constraint` annotation is a rule rather than a note — deleting them to save bytes deletes the documentation a developer opens the file for. The saving is real and the place to take it is the build: `BASELINE.md` § *Serving this file* has the rule, the reasoning, the two failure modes and a pointer to a working implementation in another repo. Strip at build time, keep the source whole. **Step 1b — Link the hosted font stylesheet** Do not copy or bundle the woff2 files — not because the licence forbids it, but because a copied font file is a copy that drifts and a version nobody tracks. Instead, add these two tags to the `` of your root layout or HTML template: *(Corrected 2026-08-19 against the Fontspring Webfont EULA, read from the primary text rather than paraphrased. This step previously said the EULA "licenses @font-face linking on Aleris-controlled domains only", which is wrong on both halves: §2d limits use to websites the licensee **owns or controls**, with no domain count — Fontspring's Worry-Free terms state unlimited domains explicitly. The Aleris-domain restriction is our own CORS configuration on `brand.dev.aleris.ai`, not a licence limit, and describing our infrastructure choice as a legal one made a compliant build look non-compliant. Claude-drafted correction; the clause numbers are checkable.)* ```html ``` In a React/Next.js layout this looks like: ```tsx // app/layout.tsx (or equivalent) export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` The stylesheet uses `font-display: swap` so text is visible immediately in the fallback font while the woff2 loads. Set `font-synthesis-weight: none` on `body` to prevent the browser from synthesising fake bold when a weight is slow to arrive. Optional but recommended — also fetch the JSON form for token lookup, autocomplete, and constraint metadata: ```bash curl -fsSL https://brand.dev.aleris.ai/baseline/raw/tokens/baseline-tokens.json \ -o src/styles/aleris-tokens.json ``` **Step 1c — Tailwind projects only: fetch the theme bridge** Optional. It changes what is convenient to type and nothing about what the design system says — skip it and every token still works through `var(--token-name)`. ```bash curl -fsSL https://brand.dev.aleris.ai/baseline/raw/tokens/aleris-tailwind.css \ -o src/styles/aleris-tailwind.css ``` Import it **after** the token file and **before** Tailwind: ```css @import "./aleris-tokens.css"; @import "./aleris-tailwind.css"; @import "tailwindcss"; ``` You then get `bg-aleris-petrol-500`, `text-aleris-text-secondary`, `p-aleris-md`, `rounded-aleris-m`, `shadow-aleris-e1`, `leading-aleris-body` and the `aleris-md:` breakpoint variant, each compiling straight to the token. **Tailwind's own utilities are untouched** — the bridge adds a namespace, it does not replace one. That is also how you read a diff: `bg-aleris-*` is a token, `bg-[#004851]` is not. The bridge is generated from the token file and holds no value of its own, so it cannot drift from it. Do not hand-edit it, and do not hand-write your own — `schemas/design-token.md` § "Tailwind CSS v4" carries the reason, which is that the hand-written example this replaced had seven dead token references nobody had noticed. --- ## 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://brand.dev.aleris.ai/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://brand.dev.aleris.ai/baseline/raw/BASELINE.md — read it before writing UI. ## Surface mode This project is **[communicative | instrumental]**. ## 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, 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, booking flows. - 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://brand.dev.aleris.ai/baseline/raw/BASELINE.md). --- ## Step 4 — Read these before writing UI Fetch and read in this order: 1. https://brand.dev.aleris.ai/baseline/raw/BASELINE.md — hard rules, components, motion, accessibility. 2. https://brand.dev.aleris.ai/foundation/raw/voice.md — how Aleris sounds. 3. https://brand.dev.aleris.ai/foundation/raw/colour.md — palette and rules. 4. https://brand.dev.aleris.ai/foundation/raw/typography.md — type system. 5. https://brand.dev.aleris.ai/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://brand.dev.aleris.ai/baseline/raw/patterns/error-message.md - Confirmations → https://brand.dev.aleris.ai/baseline/raw/patterns/confirmation.md - Empty states → https://brand.dev.aleris.ai/baseline/raw/patterns/empty-state.md - Button labels → https://brand.dev.aleris.ai/baseline/raw/patterns/button-label.md - Chat responses → https://brand.dev.aleris.ai/baseline/raw/patterns/chat-response-simple.md The full machine-readable index is at https://brand.dev.aleris.ai/llms.txt. --- ## Known gaps (as of 2026-06-12) 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") - 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.