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:

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

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) is the primary action. If there are two orange buttons visible, one is wrong.
Status colors for state only. Error red, warning amber, confirm green, goal colors — never decorative.
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.
No all caps in content. Sentence case everywhere. No exceptions.
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

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.

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

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.