# Baseline — AI Instructions

The Aleris brand is documented in two layers. **Foundation** defines identity and reasoning: colour, typography, voice, imagery, and the two reasoning tools (constant/contextual, emotional modes). **Baseline** is the implementation layer: the token architecture, component rules, and pattern library that apply Foundation across digital products. Read Foundation first; read Baseline for how to execute it.

When Foundation and Baseline conflict, Foundation takes precedence.

Before writing or modifying any UI code in an Aleris product, use only tokens from `aleris-tokens.css`. When uncertain about a decision, flag it as an open question in the code rather than guessing:

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

---

## Token system

All values come from `tokens/aleris-tokens.css` — a three-layer architecture:

- **Primitives** — raw values (colors, spacing, type sizes). Platform-independent.
- **Semantic** — primitives mapped to usage (text colors, surface colors, states). Reference these in product code.
- **Component** — semantic tokens composed into component-level clusters (button, input, card, table, tab-nav).

Machine-readable token data with `usage` and `constraint` fields is in `tokens/baseline-tokens.json`. Consult it for lookup — the CSS remains the source of truth.

**Never use raw values.** No hex colors, no pixel values for spacing, no raw Tailwind color classes. Everything goes through tokens.

---

## Hard rules

They apply to every surface, every product.

1. **Page background: sand, not white.** Communicative = `--surface-page` (sand-100, #f2ece4). Instrumental = `--surface-page-instrumental` (sand-50, #faf8f6). Never white.
2. **Cards and surfaces: white, not sand.** `--surface-card` is white. Sand on cards inverts the hierarchy.
3. **One primary CTA per screen.** Orange (`--brand-accent`) marks the primary action on a screen. Do not place two orange buttons in the same view.
4. **Status colors for state only.** Error red, warning amber, confirm green, goal colors — never decorative.
5. **Confirm green ≠ goal green.** `--color-confirm-500` (#4f866e) is interactive ("I'm done"). `--color-goal-achieved` (#2e8540) is indicator ("target met"). Don't mix them.
6. **No all caps in content.** Sentence case everywhere. The only exception is abbreviations (AB, MRI) — see `foundation/typography.md`.
7. **Only animate transform and opacity.** No layout-triggering animations. Respect `prefers-reduced-motion: reduce` — it disables everything.
8. **No animation in email.** All Aleris email layouts are static.
9. **14px is the floor.** `--font-size-xs` (14px) is the smallest text in the system. Nothing goes below it.
10. **No font-weight 400.** Museo Sans has no 400 weight. Using it causes browser synthesis. Use `--font-weight-regular` (500) or `--font-weight-bold` (700).

---

## Surface temperature

Baseline applies F6 (`foundation/constant-contextual.md`) to surfaces through two modes: **communicative** and **instrumental**. Mode is determined by the situation, never the user's role — a patient managing their treatment plan in MyAleris is in instrumental mode; a staff member reading an internal newsletter is in communicative mode.

**Communicative** — Aleris tells, guides, explains, welcomes. Patient-facing content, marketing, onboarding.
- Page background: `--surface-page` (sand-100)
- Cards mandatory for content structure
- Generous spacing (`--spacing-lg` to `--spacing-3xl`)
- Full type scale, typography has room to breathe
- Content spans 6–8 of 12 grid columns
- Max-width: `--grid-max-width-communicative` (1200px)

**Instrumental** — The user works, navigates, configures, monitors. Tools, admin, dashboards, documentation, booking flows (decided 2026-06-12 — a booking flow is instrumental throughout).
- Page background: `--surface-page-instrumental` (sand-50)
- Cards optional — content can live directly on the surface
- Tighter spacing, compressed type range
- Content can span all 12 columns
- Max-width: `--grid-max-width-instrumental` (1440px or fluid)

Mode does not shift between steps within a single flow.

---

## Component shapes

Radius by functional role:

- **Containers** (cards, panels, modals, tables): `--radius-s` (4px)
- **Interactive elements** (buttons, inputs, dropdowns): `--radius-m` (8px)
- **Indicators** (badges, tags, avatars): `--radius-full` (100px)
- No full-pill buttons exist in Aleris interfaces.
- `--radius-l` (12px) is reserved — do not use without governance approval.

---

## Typography

See `foundation/typography.md` (F2) for the typography system and principles. Baseline implementation:

- Reference typography tokens from `aleris-tokens.css` (`--type-body-*`, `--type-lead-*`, `--type-h1-*`, etc.) rather than specifying pixel sizes.
- Font weights available: `--font-weight-regular` (500) and `--font-weight-bold` (700). Do not use font-weight 400 — Museo Sans has no 400 weight and browser synthesis distorts the letterforms.
- `--type-lead-*` is used once per section, after the heading.

---

## Spacing

Modular scale, 1.5 ratio, 4px grid. Use tokens — never fabricate values.

| Token | Value | Typical use |
|-------|-------|-------------|
| `--spacing-3xs` | 4px | Minimum gap, label-to-field |
| `--spacing-2xs` | 8px | Tight inline gaps |
| `--spacing-xs` | 12px | Related elements, input padding-y |
| `--spacing-sm` | 16px | Component padding |
| `--spacing-md` | 24px | Section spacing, card padding |
| `--spacing-lg` | 36px | Between components |
| `--spacing-xl` | 48px | Between sections |
| `--spacing-2xl` | 72px | Major section breaks |
| `--spacing-3xl` | 96px | Page-level (communicative only) |

---

## Buttons

Six variants, each with a job:

- **Primary** (orange): "Do this" — main action, booking, submission
- **Secondary** (petrol): "Go here" — navigation, exploration
- **Outline**: Less prominent alternative
- **Ghost**: Tertiary, minimal visual weight
- **Confirm** (green): "I'm done" — completion, sign-off. Only for: Klarmarkera, Godkänn, Signera, Markera som klar. Not for generic "OK" in dialogs.
- **Small**: Compact variant for tight spaces

All buttons use `--radius-m` (8px). No full-pill buttons.

**Hover lightens, never darkens.** Every hover state moves one step lighter — a choice lights up rather than dims. Primary hovers to orange-400, secondary to petrol-300, outline/ghost to petrol-100, confirm to its lighter step. Do not introduce darker hover values.

---

## Forms

- Labels above fields.
- Mark optional fields "(valfritt)", not required fields.
- Error text: "what happened + what to do" below the field, replacing helper text.
- `aria-invalid="true"` + `aria-describedby` for error linking.
- Focus: `focus-visible` with petrol ring, 2px offset. Never `focus`.
- Disabled: use sparingly. Patient-facing: prefer explain-on-click. Instrumental: acceptable when workflow context is self-evident.
- Read-only: looks like content, not a greyed-out input.

---

## Tables

Two types: **read tables** (display data) and **work tables** (interactive).

- Three density levels: compact (36px), default (48px), comfortable (64px)
- Density is user-selectable in instrumental surfaces — persists as preference
- Headers quieter than data (smaller, sentence case)
- Identifier in column one, always
- Numbers right-aligned, text left-aligned
- Actions near the identifier, not at the far right

---

## Motion

Four durations, two curves.

| Token | Value | Use |
|-------|-------|-----|
| `--duration-instant` | 100ms | Focus rings, checkbox toggles |
| `--duration-fast` | 200ms | Buttons, hover, tooltips |
| `--duration-moderate` | 350ms | Modals, accordions, sidebars |
| `--duration-slow` | 500ms | Page transitions (sparingly) |

- `--ease-out`: elements arriving
- `--ease-in-out`: elements moving
- Never use `ease-in` alone — slow start reads as unresponsive.

Loading: skeleton shimmer, not spinners. < 2s: shimmer only. > 2s: shimmer + progress. > 10s: navigate away + notify.

---

## Anti-patterns (healthcare-specific)

If you experience a conflict between design requirements and anti-patterns, please note it and leave a comment.

1. **Consent asymmetry** — consent and decline must be visually equal. Same size, same prominence, same steps.
2. **Cost burial** — surface pricing before any data entry or emotional investment.
3. **Urgency fabrication** — no countdown timers or scarcity messaging unless clinically real and verifiable.
4. **Obstacle withdrawal** — anything booked online can be cancelled online with equal ease.
5. **Informational hiding** — risks and qualifying information inline at point of decision. Never progressively disclosed.
6. **Data maximalism** — collect only what the current service requires. Optional = labeled "(valfritt)".
7. **Default escalation** — no pre-selection on choices with financial, clinical, or privacy consequences.
8. **Emotional exploitation** — no shame, guilt, or fear to drive action. Motivate through clarity.
9. **Exit penalty** — no degraded experience for choosing a less profitable path.
10. **Notification coercion** — notifications for clinical relevance only. Marketing is separate with distinct opt-in.

**Smell test:** Is it easier to accept than to decline? Does the flow hide information that would change the decision? Does it require something not necessary for care?

---

## Accessibility

- WCAG 2.1 AA minimum
- 14px font floor (enforced by token scale)
- Color never carries meaning alone — always pair with icon, shape, or text
- 44px minimum touch/click target
- `focus-visible` with petrol ring for keyboard navigation
- `prefers-reduced-motion: reduce` disables all animation
- `aria-invalid` + `aria-describedby` for form errors

---

## File reference

**Foundation (read first)**

| File | Purpose |
|------|---------|
| `foundation/index.md` | Brand in Brief — entry point to all Foundation pages |
| `foundation/colour.md` | F1 Colour |
| `foundation/typography.md` | F2 Typography |
| `foundation/voice.md` | F4 Voice — "den nära experten" |
| `foundation/constant-contextual.md` | F6 reasoning tool |
| `foundation/emotional-modes.md` | F7 reasoning tool |
| `foundation/imagery.md` | F10 Imagery |

**Baseline (implementation)**

| File | Purpose |
|------|---------|
| `tokens/aleris-tokens.css` | Source of truth — all token values |
| `tokens/baseline-tokens.json` | Generated — token lookup with usage/constraint |
| `governance/aleris-anti-patterns.md` | 10 healthcare-specific behavioural guardrails |
| `governance/aleris-design-governance.md` | Design decisions with certainty levels |
| `governance/aleris-privacy-jtbd-analysis.md` | Privacy as interaction design |
| `reference/aleris-design-tokens.md` | Human-readable token reference |
| `reference/aleris-progressive-enhancement.md` | Foundational design principle |
| `reference/aleris-grids-tables-dataviz.md` | Grid, table, and dataviz specs |
| `reference/aleris-baseline-animation.md` | Motion system (implements F6/F7) |
| `reference/aleris-baseline-images.md` | Image formats, aspect ratios (implements F10) |
| `voice/` | Digital voice patterns, behaviour notes (implements F4) |

---

*Baseline — last updated 2026-06-12. Maintained by Torfinn Almers, Head of Design, Aleris Group. Change history: `planning/changelog.md`.*