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:

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

Page background: sand, not white. Communicative = --surface-page (sand-100, #f2ece4). Instrumental = --surface-page-instrumental (sand-50, #faf8f6). Never white.
Cards and surfaces: white, not sand. --surface-card is white. Sand on cards inverts the hierarchy.
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.
Status colors for state only. Error red, warning amber, confirm green, goal colors — never decorative.
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.
No all caps in content. Sentence case everywhere. The only exception is abbreviations (AB, MRI) — see foundation/typography.md.
Only animate transform and opacity. No layout-triggering animations. Respect prefers-reduced-motion: reduce — it disables everything.
No animation in email. All Aleris email layouts are static.
14px is the floor. --font-size-xs (14px) is the smallest text in the system. Nothing goes below it.
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.

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