--- name: Baseline Design Governance type: governance status: anchor depends_on: [aleris-tokens.css, aleris-progressive-enhancement.md, aleris-privacy-jtbd-analysis.md, aleris-anti-patterns.md, aleris-baseline-animation.md, aleris-grids-tables-dataviz.md, foundation/constant-contextual, foundation/emotional-modes, foundation/colour, foundation/typography, foundation/voice] propagates_to: [aleris-tokens.css, aleris-design-system-open-questions.md, index.html] open_questions: [OQ-02, OQ-04, OQ-06, OQ-11, OQ-12] last_verified: 2026-03-21 --- # Baseline — Aleris Design Governance The reasoning behind the design system. What we've decided, why, and how certain we are. --- ## How to read this document Each section has two reading paths. **Beginner (the decision):** Marked with ✦. Read these if you want to know what to do. They're plain statements — no justification, no history. **Expert (the reasoning):** The paragraphs around each decision. Read these if you want to understand the tensions, the evidence, and what's still uncertain. **Certainty levels:** - **Fixed** — Decided. Tested or grounded in constraints that won't change (accessibility law, font file inventory, brand architecture). Don't revisit unless the constraint changes. - **Anchor** — Strong conviction based on evidence and reasoning. Treat as decided for practical purposes. Open to revision if new evidence contradicts. - **Hypothesis** — Best current thinking. Structured enough to build on, but not validated through user research or production use. Flag if your implementation surfaces problems. --- ## 1. Foundations ### Progressive enhancement (Fixed) ✦ Build from the simplest functional layer upward. The base layer is complete, not minimal. Complexity is earned, not assumed. Capability differences are normal, not exceptional. Progressive enhancement is borrowed from web development (Steve Champeon, ~2003) but applies at every level of Aleris product design. It means starting with what always works and adding richness on top — not starting with the richest experience and handling what breaks. This is the foundational principle because Aleris operates across three countries with separate IT infrastructure, 43 organizational units with varying digital maturity, and users ranging from technically confident clinicians to elderly patients on slow connections. A principle that treats this variance as the default condition produces more resilient products. Four application levels: - **Technical capability.** The base layer works on the least capable device and connection. JavaScript, animation, and real-time features are enhancements, never prerequisites. - **Surface temperature.** Instrumental surfaces are a complete base layer. Communicative surfaces add expressive layers (generous spacing, richer typography, illustration) on the same structural foundation. Remove the expressive layers and you have a functioning instrumental surface, not a broken communicative one. - **Patient contexts.** A patient on a slow connection or using assistive technology meets a complete service. - **Token architecture.** Primitives always work. Semantic tokens add meaning. Component tokens add specificity. A product implementing only primitives still gets a coherent Aleris palette. See: `aleris-progressive-enhancement.md` for the full principle. `aleris-token-governance-frameworks.md` for the CSS-first architecture that implements it. ### Privacy-first (Anchor) ✦ Privacy is a component-level behavior pattern, not a token dimension. Design for two domains: self-data (patient managing their own information) and work-data (clinician managing information about others). Collect only what serves the user. Confirmation is proportional to consequence. Privacy at Aleris goes beyond GDPR compliance into interaction design. The privacy JTBD analysis identifies 10 jobs across two domains — the patient who wants to manage healthcare "without having to think about whether my information could end up in the wrong place" and the clinician who needs "to access the right patient's information quickly and confidently without worrying about clicking the wrong record." These domains sometimes conflict directly. A patient wants data hidden after confirmation; a clinician needs it visible for verification. The design system resolves this through role-based component behavior — the same data field renders differently depending on who's viewing it and why. Key component patterns (all at Hypothesis certainty — desk research, not user-validated): - Masked input: cleartext during editing, masked on blur/confirmation, toggleable - Patient identification: name + one secondary identifier, consistently placed, full ID expandable - Tiered export: anonymous aggregate = no friction, individual data = confirmation + logging, bulk = formal confirmation + purpose - Notification templates: never include clinical content in preview text Proportional confirmation maps to the escalation framework: business-as-usual actions need no confirmation, important actions need acknowledgment, urgent/irreversible actions need explicit confirmation with purpose. See: `aleris-privacy-jtbd-analysis.md` for the full JTBD analysis. ### Jobs to Be Done as product lens (Anchor) ✦ Every product decision starts with "what job is the user hiring this for?" Distinguish functional, emotional, and social dimensions. The emotional job often matters more than the functional one. JTBD is demonstrated through the privacy analysis (where the patient's emotional job — "not having to be vigilant" — shapes the design more than the functional job of entering data) and through the surface temperature model (where the situation's job determines the interface mode, not the user's role). The design system doesn't prescribe a specific JTBD methodology. It establishes that every design decision should be traceable to a user job, and that emotional and social dimensions are first-class considerations — not nice-to-haves after the functional requirements are met. --- ## 2. Non-negotiables (Fixed) These are constraints, not choices. They apply regardless of surface temperature, user role, product type, or implementation timeline. ### Accessibility baseline ✦ WCAG 2.1 AA. 14px minimum font size. `focus-visible` with petrol ring for keyboard navigation. `aria-invalid` + `aria-describedby` for form validation errors. Color never carries meaning alone — always pair with icon, shape, or text. `prefers-reduced-motion: reduce` disables all animation. The 14px floor comes from the token system: `--font-size-xs: 0.78rem` (14px at 18px base) is the smallest value available. There is nothing smaller in the system. This is enforced at the primitive layer — you cannot reach a sub-14px size through the token scale. Focus ring specification: 2px offset, petrol-500 color, applied via `focus-visible` (not `focus` — avoids showing the ring on mouse click). Confirmed by the patient guide project implementation. The `aria-invalid` → red ring pattern for validation errors is also confirmed. Minimum touch/click target: 44px (Fixed). Table compact row height (36px) is row height, not tap target — interactive elements within rows still need 44px hit areas. ### Clinical data separation ✦ Patient-identifying information and clinical data are never combined in notifications, preview text, exports, or any context where the audience is not authenticated and authorized. This is a regulatory and ethical constraint, not a design preference. Notification templates never include clinical content in preview text. Export follows the tiered dialog pattern. Patient tables in non-clinical contexts use pseudonymised references. ### Multi-language architecture ✦ English for all code, variables, tokens, and technical documentation. Market-specific voice layers (SE/NO/DK) for patient-facing text. The design system references voice guidance without embedding it. Aleris operates in Sweden, Norway, and Denmark. The token system and governance documents are English. Patient-facing copy follows market-specific voice guides. The Swedish voice layer ("den nära experten") is complete; Norwegian and Danish adaptations are needed but not yet created. ### AI guardrails ✦ Aleris digital products — including AI chats — inform, navigate, and refer. They do not diagnose, recommend treatment, or interpret individual clinical results. When the right answer is "contact a person," that's the answer, with a specific referral (who + how). The medical boundary is absolute: the product can explain processes, timelines, and logistics; it cannot answer symptom questions, assess conditions, or give individual medical recommendations. AI chats acknowledge uncertainty directly and refer onward with specifics — never with generic "contact your healthcare provider." Medical disclaimers are shown once as a UI element, not repeated in every response. See: `4-den-nara-experten-digital-behavior-v1.md` for the full behavioral specification. --- ## 3. Surface temperature and emotional design ### Two surface modes (Anchor) ✦ Surface temperature is situation-based, not role-based. Communicative = Aleris tells, guides, explains, welcomes. Instrumental = the user works, navigates, configures, monitors. A patient can be in instrumental mode; a clinician can be in communicative mode. The situation determines the surface, 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. A flow owns its mode — temperature does not shift between steps within a single flow. An onboarding flow is communicative throughout. A booking flow is instrumental throughout. Mixing modes creates incoherent experience. Surface temperature affects all visual dimensions simultaneously: color (background warmth, contrast), spacing (density, padding), typography (size relationships, weight distribution), composition (grid strictness, whitespace rhythm), and content density (information per viewport area). A warm layout with cool colors reads as inconsistent. All dimensions move together. **Communicative surfaces:** generous spacing, softer hierarchy, sand tones, typography has room to breathe, images and illustration belong here, content typically spans 6–8 of 12 grid columns with generous margins, max-width capped at 1200px for reading comfort. **Instrumental surfaces:** tighter spacing, higher contrast for scannability, reduced decoration, typography optimized for efficiency, content can span all 12 columns, max-width fluid or 1440px. ### Scanning vs. attending (Anchor) ✦ Density is determined by the task's attention demand, not by the surface type. Scanning tasks (patient lists, schedules) use tables with strong hierarchy. Attending tasks (patient detail review, health declaration assessment) use generous spacing. Both can be instrumental. This reframes the density question. The Patientöversikt prototype is scannable not because it's dense, but because the information hierarchy is strong — columns, status badges, progress bars, sort/filter. The Hälsodeklarationer detail view is spacious because the task demands careful attention — screen real estate as "a luxury commodity" that helps the clinician think. Instrumental density comes from layout utilization and information hierarchy, not from spacing compression. The grid max-width (1440px / fluid) and column count do more work than tighter padding. Table density (compact/default/comfortable) is user-selectable as a power-user override, not the default strategy. ### Three escalation levels (Anchor) ✦ Business as usual (default, 90%+ of time) → Important (consequence-carrying actions) → Urgent (immediate attention). Escalation is a property of the view, not individual elements. Warmth is the default state; escalation is a departure from warmth. The trigger for Important is consequence-based: "Does interrupting this have consequences beyond the current moment?" Reading a patient guide has no consequences — you can close it and return. Signing a consent form does. This distinguishes BaU from Important without subjective judgment about difficulty. Important: consent forms, health declarations, payment steps, lab results requiring action, treatment plan confirmations, configuration changes with downstream effects. The interface reduces the decorative, increases precision and clarity. Urgent: system warnings, clinical alerts, missed steps that block a flow, time-critical actions. Minimal visual noise, maximum contrast. The interface clears everything except what matters. De-escalation should be deliberate. After completing an important action, the transition back to BaU should feel like resolution — a return to calm, not an abrupt context switch. See: `aleris-surface-temperature-tokens.md` for the full framework and DDR. --- ## 4. Design patterns ### Layout grid (Fixed) ✦ 12 columns. Gutters: `spacing-md` (24px). Margins: `spacing-sm` (16px) mobile, `spacing-md` (24px) desktop. Max-width: 1200px communicative, 1440px or fluid instrumental. Use CSS Grid with `fr` units and container queries. 12 columns because it divides cleanly into halves, thirds, quarters, and sixths. The grid is the same structure in both surface modes — the difference is how much of it is used. Communicative surfaces use the grid loosely (6–8 columns with generous margins). Instrumental surfaces use it fully (all 12 columns, sidebars at 2–3 columns). Container queries preferred over viewport queries — the grid adapts to its container, not just the viewport. This matters when the same component appears in different contexts. Breakpoints: 640px / 768px / 1024px / 1280px. Practical values, not derived from the modular scale. Responsive behavior follows the adaptive pattern: component swap at breakpoints, not just scaling. Tables become card stacks on mobile. Popovers become sheet drawers. Sidebars hide and become toggle panels. The same data is shown with different interaction models depending on context. ### Typography and hierarchy (Fixed) ✦ Museo Sans. Two working weights: 500 (regular) and 700 (bold). Perfect fifth (1.5) ratio. 18px base. 14px accessibility floor. 300 and 900 are exceptional use only. The type system is deliberately constrained. Two weights create clear hierarchy without ambiguity — regular for content, bold for structure. The perfect fifth ratio (1.5) is shared with the spacing scale for cross-dimensional harmony: body 18px × 1.5 = 27px (h3) × 1.5 = 40px (h2) × 1.5 = 60px (h1). Line heights resonate with the spacing scale: body 18px × 1.5 = 27px (= h3 font size), h3 27px × 1.33 = 36px (= spacing-lg), h2 40px × 1.2 = 48px (= spacing-xl). Weight 300 (light): only for large display text on communicative surfaces, xl (40px) or above. Weight 900 (black): almost never appropriate — try 700 at a larger size first. Weight 400 does not exist in Museo Sans; using it causes browser synthesis. Headers are quieter than data in tables — smaller type, uppercase, wider letter-spacing. The data in cells is what the user came for; headers serve the data. ### Radius and shape (Anchor) ✦ Three tiers. `radius-s` (4px) for containers: cards, panels, modals, tables. `radius-m` (8px) for interactive elements: buttons, inputs, dropdowns. `radius-full` (100px) for compact indicators: badges, tags, status dots. Evidence from production prototypes: patient portal cards use subtle 4px rounding. Buttons use moderate 8px rounding — not full pills. Filter chips and status badges use full rounding. The functional role determines the radius, not the visual weight. `radius-l` (12px) exists in the primitive layer but is not assigned to any component. It's available as a special-case value but not part of the standard system. ### Color system: button roles (Anchor) ✦ Four button colors, each with a clear job. Orange (brand-accent): "do this" — primary CTAs, booking, submission. Petrol (brand-primary): "go here" — navigation, exploration, filtering. Outline/ghost: "also available" — tertiary, less prominent alternatives. Green (#27ae60): "I'm done" — completion, sign-off, confirmation of finished work. The green confirm button is scoped tightly: "Klarmarkera", "Godkänn", "Signera", "Markera som klar." Not for generic "yes/ok" in dialogs — use primary for those. Evidence: Hälsodeklarationer prototype "Klarmarkera" button. Currently at Hypothesis certainty; validate across more products. Green (#27ae60) is distinct from goal-achieved (#2e8540), which is a dashboard indicator — not an interactive button color. ### Cards (Anchor) ✦ White on sand. `radius-s` (4px). Border + shadow together. Border provides definition; shadow provides subtle lift. Cards on sand-100 backgrounds use a 1px `border-default` (gray-100) plus `shadow-e1` (petrol-tinted). The border creates the "subtle line that helps with contrast making them pop subtly" — evidence from the Hälsodeklarationer prototype. Shadow alone is too soft on sand; border alone is too flat. Together they create the right amount of separation. Card padding uses `spacing-md` (24px). Cards do not stretch to fill available width — they take the width their content needs within the grid. ### Tables (Anchor) ✦ Two types: read tables (display data) and work tables (interactive workspaces). Don't design one pattern and stretch it to cover both. Three density levels (36/48/64px), user-selectable in instrumental surfaces. Identifier in column one, always. Numbers right-aligned, text left-aligned. Table design principles from the grids/tables/dataviz document: - Headers are quieter than data (smaller type, uppercase, wider letter-spacing) - Density is a user choice, not a design choice — compact for scanning long lists, comfortable for reviewing individual records - Actions near the identifier, not at the far right - Visual summary above the table, not instead of it - Avoid full-width tables — let the table take the width it needs - Zebra striping optional (sand-100), off by default Table privacy: patient tables in clinical contexts need patient identification from the privacy JTBD analysis (Job 2.1). Non-clinical tables use pseudonymised references. Export follows tiered dialog pattern. See: `aleris-grids-tables-dataviz.md` for the full table specification and dataviz principles. ### Data visualization (Anchor) ✦ Five principles: show the data then stop, let comparison happen naturally, use color with intention, annotate the important not the obvious, respect the reader's time. No pie charts. No dual Y-axes. No 3D effects. Small multiples over complex single charts. Direct labelling over legends. The chart palette provides 12 colors in cool/warm series. Most effective charts use 2–4 colors. More than 6 in a single chart is a signal to restructure. Color never carries meaning alone — supplement with pattern, label, or position. Title as insight, not description: "Stockholm clinic exceeds waiting time target in Q3" is better than "Waiting times by clinic." ### Forms and inputs (Fixed / Anchor) ✦ Labels above fields (Fixed). Mark optional fields "(valfritt)", not required (Anchor). Error: "what happened + what to do" below the field, replacing helper text (Anchor). `aria-invalid` + `aria-describedby` for accessible error linking (Fixed). Label position is Fixed — above-field labels work at every viewport width, are clearer for people with cognitive load, and create natural scan patterns. No exception for inline or side labels. Optional marking is Anchor — in clinical forms where 80%+ of fields are required, marking all required fields creates visual noise. Mark the exceptions instead. Error pattern follows "den nära experten" digital voice: tell the user what happened and what to do. Error text in `color-error-500`, `font-size-xs`, appearing below the field. Input gets red border ring (`input-border-error`). Focus ring: `focus-visible` with petrol-500 ring, 2px offset. Never `focus` — avoids showing the ring on mouse click. ### Disabled vs. read-only (Anchor) ✦ Patient-facing: prefer explain-on-click over disabled state — show what's possible, explain prerequisites. Instrumental: disabled acceptable when workflow context is self-evident. Read-only looks like content, not a greyed-out input. Disabled elements are problematic because they offer no explanation for *why* something is unavailable. "You need to complete the health declaration before you can book" is more useful than a greyed-out booking button. The explain-on-click pattern keeps the element interactive — clicking reveals the prerequisites. The exception for instrumental surfaces exists because clinical staff understand workflow prerequisites from professional context. A clinician knows they must complete the note before signing; the UI doesn't need to spell it out. Read-only presents data as content — sand background, transparent border, full text color. It blends with the page rather than looking broken. For data that can be unlocked to editable (role-based or state-based), present in an input-shaped container with a lock icon so the user can see it's editable under different conditions. ### Phase awareness (Anchor) ✦ Products that follow a patient journey know where the patient is in the process. Before = preparation and explanation. During = real-time support if needed, no unsolicited contact. After = recovery, follow-up, and contact guidance. Phase awareness prevents the system from giving preparation instructions to a patient who has already had surgery, or presenting post-care instructions before the patient knows what the procedure involves. Progression locks protect against mistakes — they're acts of care, not restrictions. The patient cannot skip phases or tasks that must be completed in order. Status messages driven by staff (assessment approved, surgery scheduled) appear as status banners — not tasks the patient can check off. The patient sees what happened but doesn't confirm things only staff can verify. ### Feedback without interruption (Anchor) ✦ Confirmations and error messages are shown inline, not in modals. Modals interrupt flow and create anxiety. Inline feedback provides the same information without taking control away from the user. The only exceptions to this are destructive or irreversible actions (mapped to Important/Urgent escalation levels), where a confirmation dialog is appropriate because the consequence warrants the interruption. Regular feedback — "saved", "sent", "updated" — is always inline. ### Animation and motion (Anchor) ✦ Animation has one job: confirm that the system is listening. Every movement responds to a user action or communicates a system state. Decorative animation does not belong. Four duration levels: instant (100ms) for focus rings and state indicators, fast (200ms) for buttons and hover, moderate (350ms) for modals and panels, slow (500ms) for major layout shifts — used sparingly. Two easing curves: ease-out (`cubic-bezier(0.0, 0.0, 0.2, 1)`) for elements arriving, ease-in-out (`cubic-bezier(0.4, 0.0, 0.2, 1)`) for elements moving. Never use ease-in alone. Only animate `transform` and `opacity` (GPU-composited, no layout reflow). Skeleton shimmer screens preferred over spinners for loading states. `prefers-reduced-motion: reduce` disables everything (Fixed, a11y). See `aleris-baseline-animation.md` for full guidance including what does *not* get animated (scroll-triggered reveals, page load entrances, decorative loops, large layout reflows). Surface temperature selects from the same tokens: instrumental surfaces default to instant/fast, communicative surfaces can use moderate/slow. The constraint is the same — motion serves comprehension (showing what changed), not decoration. --- ## 5. Voice The voice system is referenced, not embedded. It is market-specific (Swedish first, Norwegian and Danish to follow) and maintained separately from the design token system. ✦ For Swedish patient-facing products, follow "den nära experten" — the four-part voice guide covering core principles, per-genre voice, digital micro-copy, and product behavior. Micro-copy patterns from the digital voice document are partially embedded as component specifications in the token system. These are language-independent behavioral patterns: button labels use verb phrases, error messages follow "what happened + what to do", confirmations contain no thank-you phrases, empty states explain + offer next action, chat voice acknowledges boundaries and refers with specifics. The "no Scandinavian AI-smicker" anti-pattern: never use phrases like "Vad kul att du frågar!", "Jag förstår helt och hållet!", or "Absolut, det ska jag hjälpa dig med!" in AI-generated responses. The chat should be helpful, not performatively enthusiastic. Internal tools need a related but distinct register — more direct, task-driving, handling clearance and gateways. This register ("den nära chefen") is not yet defined (OQ-06). See: `voice/` folder for the full Swedish voice guide (4 documents). --- ## 6. Anti-patterns Ten behavioral anti-patterns are documented separately as machine-readable guardrails. ✦ For each pattern: Never (the behavior to avoid) / Because (the harm) / Instead (the alternative). Include in AI coding context alongside the token file. The existing anti-pattern document covers ethical/behavioral patterns: consent asymmetry, cost burial, urgency fabrication, obstacle withdrawal, informational hiding, data maximalism, default escalation, emotional exploitation, exit penalty, notification coercion. Still needed: visual/framework anti-patterns — side-by-side comparisons of framework defaults vs. Aleris for buttons, cards, forms, navigation, colors, shadows, backgrounds. "This is what a booking flow looks like with shadcn defaults" vs. "this is Aleris." This is Phase 3 work. The smell test (from the anti-patterns document): if a design decision makes you wonder "would we be comfortable if the patient could see how this was built?", the design needs revision. Pattern 5 (Informational Hiding) creates a progressive disclosure exception: the design system's progressive disclosure principle applies to complexity management, not to risk communication. Risks, costs, and limitations are never progressively disclosed — they are visible at the point of decision. This boundary is codified here as governance (OQ-08 resolution): progressive disclosure is for UI complexity; risk communication is always inline and immediate. See: `aleris-anti-patterns.md` for the full 10-pattern reference. --- ## 7. What's still open This governance document represents decisions at Fixed, Anchor, and Hypothesis certainty as of March 2026. The living open questions document tracks 17 questions and 11 resolutions across all phases. Key open questions relevant to this governance layer: - **OQ-04:** Operational real-time status palette (emerald/violet/amber/rose). Three status palettes in the system — are they the right architecture? - **OQ-06:** Internal voice register ("den nära chefen") for instrumental tool micro-copy - **OQ-11:** Animation timing tokens — codify 150ms/300ms split and easing function - **OQ-12:** Component architecture patterns — how to describe compound/CVA/slot in framework-agnostic terms - **OQ-13:** Role-based UI filtering as a standard pattern See: `planning/aleris-design-system-open-questions.md` for the full tracker. --- *Baseline — Aleris Design Governance. March 2026.* *Maintainer: Torfinn Almers, Head of Design, Aleris Group.*