# Baseline — AI Instructions

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

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

A visible question is better than an invisible assumption.

---

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

These are constraints, not suggestions. 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`) is the primary action. If there are two orange buttons visible, one is wrong.
4. **Status colors for state only.** Error red, warning amber, confirm green, goal colors — never decorative.
5. **Confirm green ≠ goal green.** `--color-confirm-500` (#27ae60) 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. No exceptions.
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

The situation determines the surface, not the user role.

**Communicative** — Aleris tells, guides, explains, welcomes. Patient-facing content, marketing, booking, 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.
- 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)

A flow owns its mode — temperature does not shift between steps within a single flow.

---

## Component shapes

Radius is assigned by functional role, not visual preference:

- **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

- **Font:** Museo Sans → Arial fallback. `--font-family-primary`
- **Body:** 18px / 1.5 line-height (`--type-body-*`)
- **Lead text:** 27px, regular weight, secondary color (`--type-lead-*`). Use once per section, after the heading.
- **Two weights in the system:** 500 (regular) and 700 (bold). These are the workhorse pair.
- **300** (light): exceptional use only — display text at 40px+ on communicative surfaces.
- **900** (black): almost never. Try 700 at a larger size first.
- **Headings:** h1 (60px), h2 (40px), h3 (27px), h4 (22px). Perfect fifth ratio.

---

## 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.

---

## Forms

- Labels above fields. Always.
- 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). Don't design one and stretch it.

- 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, wider letter-spacing)
- 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. No more.

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

These are hard constraints, not design opinions. Surface conflicts — do not resolve them by ignoring the anti-pattern.

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

| 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 behavioral guardrails |
| `governance/aleris-design-governance.md` | All 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 |
| `reference/aleris-baseline-images.md` | Image format strategy, aspect ratios |
| `voice/` | "Den nära experten" voice guides (Swedish) |

---

*Baseline v0.1 — March 2026. Maintained by Torfinn Almers, Head of Design, Aleris Group.*