Design tokens — why each value is what it is
Status: accepted · Owner: Head of Design · Scope: Aleris Group · Version: v0.1 · Updated: 2026-08-10
Author: Torfinn · Audience: designers, product teams, and the assistant — anyone deciding something the token file doesn't already cover
Supersedes: — · Related: [[schemas/design-token]]
Moved 2026-08-10 from baseline/reference/aleris-design-tokens.md and baseline/reference/baseline-token-architecture.md (Phase B step 3, board cards 46/48), where these records sat mixed in among 158 rows of value restatement — the exact material that drifted for four months and took two partial corrections before the 2026-08-07/10 sweep closed it. The values themselves never belonged here; the reasoning does. Each entry below leads with the question it answers, per the convention this layer already documents in principles/_index.md — the question is what transfers to a situation this file never named; the declarative claim underneath keeps the position unambiguous.
1. Why petrol, orange and sand instead of clinical blue and white?
The palette is warm-shifted on purpose, because "institutional" is the thing it has to avoid.
Petrol reads as trustworthy and medical without being cold corporate blue. Orange is warm and approachable without being alarming red. Sand feels calm and natural — not clinical white. Even the grays carry warmth (#585044 rather than #555555). This is deliberate: Aleris's brand essence ("den nära experten") requires interfaces that feel human and present, not institutional.
Turquoise was in the palette historically and was removed — it competed with petrol and created visual noise.
2. Should a surface's tone follow the user's role, or the situation?
The situation. Surface temperature is a property of a whole flow, never a person or a single step.
A patient managing their treatment plan is in instrumental mode. A staff member reading a newsletter is in communicative mode. The same person moves between both depending on what they're doing, not who they are.
Communicative surfaces (guides, marketing, onboarding) use sand tones, generous spacing, softer hierarchy. Instrumental surfaces (dashboards, scheduling, admin) use lighter/neutral tones, tighter spacing, higher contrast. Temperature doesn't shift between steps within a single flow — a booking flow is instrumental throughout, even where it carries informational content, because mixing modes mid-flow reads as incoherent.
3. Is confirm a colour decision, or an interaction decision?
It turned out to be an interaction decision wearing a colour question's clothes.
--color-confirm-500 (#4f866e) marks completion — set by Foundation F1 (status colour Bekräftelse), decided 2026-06-12. That value stands and remains distinct from --color-goal-achieved (#2e8540): confirm marks "I'm done," goal-achieved marks "target met" on a dashboard.
What changed (2026-07-31): this record used to call confirm-500 "the interactive confirm colour" for actions like Klarmarkera, Godkänn, Signera. White text on it is 4.23:1 — it failed the AA floor at rest, as an interactive fill, and always had. Rather than search for a darker green that would pass, the confirm button variant was retired outright, and completion moved to the petrol button form plus a required check glyph. Both confirm-500 and goal-achieved are now indicators, distinguished by what they indicate rather than by interactive-versus-not. Rule of record: BASELINE.md hard rule 5. Info status stays undefined on purpose — informational messages use petrol, since info is neutral brand communication (principles/colour.md).
4. Should dashboard status colours match the brand palette?
No — traffic-light convention outranks brand consistency here, because the user's prior expectation is the whole point.
Goal-tracking colours (--goal-achieved, --goal-borderline, --goal-missed, --goal-no-data) are deliberately standard green/yellow/red rather than brand-derived. In a goal-tracking context, users expect exactly these associations; remapping them to petrol/orange/sand would trade a real, useful convention for brand purity, for no benefit.
The "no data" blue (#007bc7) is a distinct hue from both petrol and the chart blues on purpose — it has to signal "neutral information," not "disabled" (which gray would imply) or "error" (which red would imply). About 8% of men have red-green colour deficiency, so the icon/shape pairing on every goal state isn't optional decoration — it's this system's implementation of the one constitutional rule that meaning is never carried by colour alone (constitutional/accessibility-is-foundational.md, normative: true).
5. Should chart colours borrow the brand palette?
No — a chart category that looks like a brand-orange button invites the user to click it.
The data-visualization palette is deliberately distinct from the brand palette: chart teal (#0f9081) is greener and brighter than petrol (#004851); chart terracotta (#d77a61) is warmer and more muted than orange (#f58c61). On an instrumental surface holding both interactive UI and data charts, a user needs to instantly tell "I can click this" (brand orange) from "this is a data category" (chart terracotta) — sharing a palette would erase that distinction.
The palette provides six light/dark pairs, enough for most healthcare data-visualization needs, and a canonical numbered order (01–12) so "category 1" always means teal across different dashboards and reports — consistency that builds pattern recognition over repeated use.
6. When does a new product get Museo Sans, and when does it get Arial?
Arial is the default; Museo Sans is the exception for contexts that already have it licensed.
The switch to Arial as the practical default eliminated licensing complexity across three countries. The visual difference is acceptable; the operational cost of managing font licenses for every digital product across Sweden, Norway and Denmark is not. New products use Arial unless Museo Sans is already licensed for the context.
7. How aggressive should the type scale's jumps feel?
Calm, not dramatic — which is why perfect fifth won over golden ratio.
Golden ratio (1.618) and its square root (1.272) were both evaluated. Golden ratio produces dramatic jumps, unsuitable for healthcare UI where hierarchy should read clear but calm. √φ gives more steps, but its 27.2% intervals land on sizes (23px, 29px, 37px, 47px) that don't resonate with spacing or line-height values elsewhere in the system.
Perfect fifth (1.5) produces visible hierarchy without drama — deliberate, not theatrical, matching Aleris's character of precision and warmth over impact. Using the same ratio for typography and spacing means line-heights at each type level land on values already in the spacing scale: body line-height (27px) equals h3's size; h3's line-height (36px) equals --spacing-lg; h2's line-height (48px) equals --spacing-xl. That internal resonance — sizes and gaps agreeing with each other across dimensions — is the practical payoff of sharing one modular scale, not an aesthetic flourish.
8. Why is Aleris's body text larger than the web default, and where's the floor?
18px because anxious readers on unfamiliar devices need calm, not haste; 14px because nothing goes lower.
Body text at 18px — larger than the web default of 16px — reads calm rather than rushed. Healthcare interfaces serve users who may be reading under stress, on devices they didn't choose. Larger body text is a structural empathy decision, not an aesthetic preference.
14px is an absolute floor: nothing in any Aleris interface renders below it. The Figma export once contained tokens at 12px and 13px; both were removed from the canonical scale entirely, not just flagged as discouraged.
9. Why do type and spacing share one ratio?
Because the alternative is a designer memorising two unrelated scales instead of reasoning from one.
Using the same 1.5 ratio for typography and spacing means a question like "how much space goes above this heading" already has an answer built into the system — space proportional to the heading's visual weight, derived from the same ratio that sized the heading. The system teaches correct usage through its own internal logic, rather than through a lookup table someone has to remember.
Communicative surfaces use the full spacing range (--spacing-sm through --spacing-3xl); instrumental surfaces use the tighter range (--spacing-3xs through --spacing-lg) — same tokens, different slice. Corrected 2026-09-05, card 122. This sentence read "exactly like the type scale's own communicative/instrumental split". There is no such split and there never was: the type scale is one scale on both surfaces, and surface temperature does not change type size. Spacing is sliced by mode; type is not.
10. Why round the modular scale to a grid instead of using its exact values?
Because sub-pixel rounding is a rendering bug waiting to happen, and 4px is already the industry's own half-step.
The spacing scale aligns to a 4px grid rather than a pure 1.5× progression. Sub-pixel values create visual inconsistency across devices and browsers; a 4px grid keeps rendering crisp and matches the industry-standard 8px grid with a 4px half-step. The scale's proportional relationships survive the rounding — the feel of the ratio is preserved even where an individual value is nudged onto the grid.
11. Why do shadows carry colour instead of staying neutral black?
Because a black shadow on a warm palette reads as a mistake, even to someone who can't say why.
Shadows use rgba(0, 72, 81, ...) — petrol — rather than rgba(0, 0, 0, ...) — black. Black shadows on a warm palette create visual discord: they read as "off" without most viewers being able to articulate the cause. Petrol-tinted shadows integrate with the warm sand backgrounds and hold the overall warm-shifted aesthetic. It's a subtle detail with disproportionate impact on whether an interface "feels like Aleris." (The Figma export still uses black-based shadows as of this writing — syncing it to the petrol-tinted canonical values is outstanding, tracked in schemas/design-token.md's Figma sync notes.)
12. Should the design system depend on a specific frontend framework?
No — CSS custom properties are the whole system; frameworks are optional bridges on top.
Aleris operates across three countries with separate IT infrastructure, different digital maturity levels, and products on different technology stacks. Coupling the design system to one framework creates a dependency that limits adoption and introduces maintenance risk whenever frameworks change. CSS custom properties are a W3C standard with universal browser support and no versioning risk — a design system built on them outlives any single framework choice.
13. Is the Tailwind mapping part of design governance?
No — it's disposable convenience infrastructure, kept intentionally separate from the tokens it reads.
Tailwind is the current utility framework in Aleris product development, and it earns real productivity benefits for layout and responsive design. But framework popularity shifts over time. Because the bridge pattern reads from tokens without tokens ever referencing the bridge, Aleris can adopt or drop frameworks without touching the design system itself. The bridge earns its place through developer productivity, not through architectural necessity — which is exactly why it's documented in schemas/design-token.md (mechanics) rather than governed here (reasoning that would make it feel load-bearing).
14. Should a framework bridge match Baseline's type scale pixel-for-pixel?
No — matching the framework's own nearest step matters more than matching Baseline's exact pixel.
The type scale's primary job is providing clear visual hierarchy across Aleris products. The modular scale gives the mathematical foundation — a rationale for why each size exists and a way to generate new ones coherently. In rendered output, the gap between a heading at 27px and one at 30px doesn't weaken that hierarchy. Requiring pixel-perfect precision in every framework context would force either framework divergence (confusing for developers) or scale compromise (weakening the mathematical foundation) — accepting an approximate bridge mapping avoids both, and the token file remains the authority for any context where exact values matter (patient guides, PDF generation, print).
15. Are Aleris buttons pills?
No, and they never were — the record claiming otherwise was never in force.
baseline/reference/aleris-design-tokens.md once carried a Design Decision Record arguing Aleris buttons are pills and cards are 12px, plus a "Beginner" summary instructing the same. Torfinn confirmed 2026-08-07 that this was never true in force — it's deleted rather than marked superseded, because there's no earlier accepted state to point back to. The hard rule (BASELINE.md): no full-pill buttons exist in Aleris interfaces; all buttons use --radius-m (8px). A 2026-07-30 partial correction had already fixed the one component-token row that stated radius-full (pill) for --button-primary-radius, contradicting both aleris-tokens.css and this hard rule — but left the prose record and its summary standing for another eight days. Card 45's 2026-08-10 production measurement confirmed it a second, independent way: nothing on any live Aleris site is a pill.
16. What decides a container's corner radius: its role, or its geometry?
Both, and the tension between them sat undetected for months because nothing ever brought the two into the same room.
Baseline assigned radius by functional role — containers 4px, interactive elements 8px, indicators pill — which is easy to teach but silently inverts the concentric-corner convention that a nested rounded rectangle's outer radius must be at least its inner radius plus the gap between them. At Baseline's 24px card padding nothing shares a corner region, so the inversion was invisible; it became visible the moment something sat flush against a card edge, and by 2026-08-07 the live case was named: an 8px image inside a 4px card.
Rather than patch that one pair, board card 45 (2026-08-10) reframed the question as one problem — what should a card's default corner state be — and answered it from what production had already settled empirically: computed styles measured live on aleris.se/.no/.dk showed every card shipping at 16px, not Baseline's 4px, already nesting correctly by the geometric convention (card 16 > inset image 8 > full-bleed hero 0). The decision: cards derive inward from a 16px base, floored at 0. --radius-l — retired 2026-08-07 at its old, never-assigned 12px value — is reinstated to carry it, at the new value, assigned to cards specifically. Scoped to cards only, deliberately: panels, modals and tables were never measured live, so they keep --radius-s until they are — this is a card exception, not a change to the general role-based model.
17. Does a flush image need its own corner radius?
No, and the first answer that said yes was reverted the same day it shipped.
The initial implementation of principle 16 gave a flush top-of-card image its own paired tokens — a top radius matching the card's, a bottom radius fixed at zero — to hand-match the result geometry demanded. Torfinn asked the obvious question a few hours later: why not let the card simply clip its own contents, so a plain, radius-less image renders with the identical result for free?
It works, and it's strictly better: a card with overflow: hidden and its own border-radius clips any child to its shape automatically, including a flush image at the top — rounded where the corner is shared, square at the bottom because that edge sits nowhere near a corner at all. --card-media-overflow: hidden replaced the paired radius tokens everywhere they'd landed. The one real trade-off — clipping affects everything that overflows the card, not just the image, which would clip a badge or dropdown meant to overhang the edge — is scoped away by applying the token to cards that actually contain flush media, not to every card, so a plain card stays free to host overhanging content later without reopening this decision.
Related
- [[schemas/design-token]] — the shape, the architecture, the framework integrations
- [[data-products/tokens/aleris-tokens.css]] — the canonical values these principles explain
BASELINE.md§ Component shapes, § Buttons — the rules of record these principles argue forworkspace/archive/2026-08-07-radius-contradiction-and-nesting.md,2026-08-10-radius-verify-prototype-and-package.md— the full radius-decision working notes behind principles 15–17