Baseline — Token Architecture

Architectural principle

Baseline is framework-agnostic. Design tokens are defined as plain CSS custom properties. They do not depend on Tailwind, React, or any other framework to function. A product that imports aleris-tokens.css into a static HTML page gets the full Aleris design system. A product that imports it into a Next.js app with Tailwind gets the same tokens, plus the option to use utility classes through a bridge layer.

This follows Aleris's progressive enhancement principle: the base layer is complete on its own. Additional layers make development faster or more expressive, but removing them does not break the system.

Three layers

Layer 1 — Tokens (the source of truth)

tokens/aleris-tokens.css defines every design value as a CSS custom property in :root. No framework references, no build tools required. This file works in any context that understands CSS: web, PDF generation, email templates, embedded webviews, future products on frameworks that don't exist yet.

The token file has its own internal hierarchy:

Primitives — raw values. Colors, spacing steps, type sizes, radii, durations. Platform-independent.

Semantic — primitives mapped to usage. --text-primary, --surface-page, --border-default. Product code references these.

Component — semantic tokens composed into clusters. --button-bg, --card-padding, --input-border-focus. Scoped to specific component patterns.

A product that only implements primitives still gets a coherent palette. A product that implements all three layers gets full contextual expression. Each layer references the one below it.

Governance rule: Values come from this file. No hex colors, no pixel values, no magic numbers in component code. If a value isn't in the token file, it's either an open question (flag it with /* OPEN: */) or a candidate for a new token.

Layer 2 — Framework bridges (optional enhancement)

A bridge is a thin mapping file that translates Layer 1 tokens into whatever utility system a project uses. Today, the primary bridge is for Tailwind CSS v4. Tomorrow it might be for something else. Bridges are disposable infrastructure — they make development faster but are not part of design governance.

The Tailwind bridge maps Baseline tokens into @theme so that Tailwind generates utility classes with Aleris values:

/* aleris-tailwind-bridge.css */
@theme {
  --color-petrol: var(--color-petrol-500);
  --color-sand: var(--surface-page);
  --color-orange: var(--brand-accent);

  --spacing-1: var(--spacing-3xs);   /* 4px */
  --spacing-2: var(--spacing-2xs);   /* 8px */
  --spacing-3: var(--spacing-xs);    /* 12px */
  --spacing-4: var(--spacing-sm);    /* 16px */
  --spacing-6: var(--spacing-md);    /* 24px */
  --spacing-9: var(--spacing-lg);    /* 36px */
  --spacing-12: var(--spacing-xl);   /* 48px */
  --spacing-18: var(--spacing-2xl);  /* 72px */
  --spacing-24: var(--spacing-3xl);  /* 96px */

  --font-size-sm: var(--font-size-xs);    /* 14px */
  --font-size-base: var(--font-size-sm);  /* 16px */
  --font-size-lg: var(--font-size-base);  /* 18px */
  --font-size-xl: var(--font-size-h4);    /* 20–22px */
  --font-size-2xl: var(--font-size-h3);   /* 24–27px */
  --font-size-3xl: var(--font-size-h2);   /* 36–40px */
  --font-size-4xl: var(--font-size-h1);   /* 60px */

  --radius-DEFAULT: var(--radius-s);  /* 4px */
  --radius-lg: var(--radius-m);       /* 8px */
  --radius-xl: var(--radius-l);       /* 12px */
  --radius-full: 9999px;

  /* Shadows use Baseline's petrol-tinted values */
  --shadow-sm: var(--elevation-1);
  --shadow-md: var(--elevation-2);
  --shadow-lg: var(--elevation-3);
}

The dependency is one-way: the bridge reads from tokens. Tokens never reference the bridge. Projects that don't use Tailwind ignore this file entirely.

What the bridge does not do: It does not eliminate all differences between Tailwind's documentation and the values a developer gets. The typography mapping is approximate — Baseline's modular scale (perfect fifth, 1.5 ratio) and Tailwind's default scale use different progressions. The bridge maps them as close as practical. This is an accepted trade-off: the token file is the authority, and any rendering context gets values that are correct for Aleris, even if Tailwind's own documentation describes different defaults.

Layer 3 — Component code (the consumer)

Components consume tokens directly via var() or through bridge utilities. The choice depends on the context:

Use token variables directly when:

The value is semantically significant (colors, status indicators, surface backgrounds)
The component needs to work outside a Tailwind project
Typographic precision matters (communicative surfaces, patient-facing content)

.card {
  background: var(--surface-card);
  border-radius: var(--radius-s);
  padding: var(--spacing-md);
}

.page-heading {
  font-size: var(--font-size-h2);
  font-weight: var(--font-weight-bold);
  color: var(--text-primary);
  line-height: var(--line-height-h2);
}

Use Tailwind utilities (in projects with the bridge) when:

Doing layout work (flex, grid, responsive breakpoints)
Applying spacing for one-off positioning
Rapid prototyping where speed matters more than cross-context portability

<div class="flex items-center gap-4 p-6 md:flex-row">

Never hard-code values. No hex colors, no pixel values for spacing or type, no raw Tailwind color classes (bg-blue-500). Everything resolves to a Baseline token, whether consumed directly or through a bridge.

Typography: the modular scale and framework alignment

Baseline's type scale is built on a perfect fifth ratio (1.5×) with an 18px base. The progression: 14 → 16 → 18 → 22 → 27 → 40 → 60px. This creates hierarchy through proportion — each step is perceptibly different from its neighbors, and the ratio resonates with the spacing scale.

Tailwind's default type scale uses a tighter progression: 12 → 14 → 16 → 18 → 20 → 24 → 30 → 36 → 48 → 60px. The two scales share values at the low end (14, 16, 18) and top (60), but diverge at the heading levels.

The Tailwind bridge maps Baseline headings to the nearest Tailwind utility. This means rendered output in a Tailwind project may not be pixel-identical to the canonical token values. This is acceptable. The token file remains the source of truth. If a rendering context needs exact values — patient guides, PDF generation, communicative surfaces where typographic precision serves the content — use var() references directly.

The modular scale's value is in providing a rationale for the system, a consistent mathematical relationship that holds across type and spacing, and a foundation that can generate new values when the system expands. The value is not in whether a heading renders at exactly 27px or approximately 30px in a given framework context.

Design decision record

Decision: The type scale follows a perfect fifth (1.5×) ratio with 18px base.

Why: Golden ratio is too aggressive for healthcare UI. Perfect fifth gives clear hierarchy with calm proportions. 18px body text meets accessibility requirements for sustained reading.

Decision: Framework bridges may approximate heading sizes to the nearest value the framework supports.

Why: Pixel-level precision in rendered UI is less important than system resilience, portability, and developer productivity. The token file holds the canonical values. Bridges optimize for the framework's conventions. Both serve the same design intent through different paths.

Spacing: natural alignment

Baseline's spacing scale aligns with Tailwind's numeric scale at every step. No approximation needed.

Baseline token	Value	Tailwind utility	Match
`--spacing-3xs`	4px	`p-1`, `gap-1`	Exact
`--spacing-2xs`	8px	`p-2`, `gap-2`	Exact
`--spacing-xs`	12px	`p-3`, `gap-3`	Exact
`--spacing-sm`	16px	`p-4`, `gap-4`	Exact
`--spacing-md`	24px	`p-6`, `gap-6`	Exact
`--spacing-lg`	36px	`p-9`, `gap-9`	Exact
`--spacing-xl`	48px	`p-12`, `gap-12`	Exact
`--spacing-2xl`	72px	`p-18`, `gap-18`	Exact
`--spacing-3xl`	96px	`p-24`, `gap-24`	Exact

Tailwind's intermediate steps (5/20px, 7/28px, 8/32px, 10/40px) exist in the framework but are not part of Baseline's scale. They are available in Tailwind projects without breaking governance — use them for micro-adjustments where the spacing scale doesn't provide the right value. If a project uses an intermediate step frequently, that's a signal to evaluate whether it belongs in the token file.

Colors, radius, shadows: direct mapping

Colors are Aleris-specific — there is no overlap with Tailwind's default palette, and the bridge replaces Tailwind's color namespace entirely. This is the simplest mapping: no ambiguity, no documentation confusion.

Radius maps with one functional difference: Baseline defines --radius-full at 100px, Tailwind uses 9999px. Both produce the same visual result (full pill/circle). The token file uses 9999px for compatibility.

Shadows use petrol-tinted values specific to Aleris. The bridge maps them to shadow-sm/md/lg. Tailwind's default shadows are fully replaced.

Adding a new bridge

When a new framework or rendering context needs to consume Baseline tokens, the pattern is:

Create a mapping file that reads from aleris-tokens.css and translates to the framework's conventions.
The mapping is one-way: bridge reads from tokens, tokens never reference the bridge.
Document where the mapping is exact and where it approximates.
The bridge is project-level infrastructure, not part of the design system itself.

Examples of future bridges: a Figma variables sync, a PDF generation stylesheet, an email-safe CSS subset, a native mobile token export.

What this means for new projects

Starting a new Aleris product:

Import tokens/aleris-tokens.css. This gives you the full design system as CSS custom properties.
If your project uses Tailwind, also import aleris-tailwind-bridge.css. This gives you utility classes that resolve to Aleris values.
Write component styles using var() references for semantically important values (colors, typography, surfaces).
Use Tailwind utilities for layout mechanics (flex, grid, responsive, spacing) where the bridge is active.
Never hard-code values. If a value doesn't exist in the token file, flag it as an open question.

Starting a project without Tailwind:

Import tokens/aleris-tokens.css. You have everything you need.
Write CSS that references tokens via var().
Use modern CSS features (nesting, cascade layers, container queries) for layout.
The design system works identically — no bridge needed, no framework dependency.

File structure

baseline/
├── tokens/
│   ├── aleris-tokens.css          ← Source of truth (Layer 1)
│   └── baseline-tokens.json       ← Generated machine-readable lookup
├── bridges/
│   └── aleris-tailwind-bridge.css ← Tailwind v4 mapping (Layer 2)
├── governance/
│   ├── aleris-anti-patterns.md
│   ├── aleris-design-governance.md
│   └── aleris-privacy-jtbd-analysis.md
├── reference/
│   ├── aleris-design-tokens.md    ← Human-readable token reference
│   ├── aleris-progressive-enhancement.md
│   ├── aleris-grids-tables-dataviz.md
│   ├── aleris-baseline-animation.md
│   └── aleris-baseline-images.md
├── voice/
│   └── ...                        ← "Den nära experten" voice guides
└── BASELINE.md                    ← AI instructions (this system's entry point)

Design decision record

Decision: Baseline tokens are framework-agnostic CSS custom properties. Framework integration happens through optional bridge files.

Why: Aleris operates across three countries with separate IT infrastructure, different digital maturity levels, and products built on different technology stacks. Coupling the design system to a specific framework creates a dependency that limits adoption and introduces maintenance risk when frameworks change. CSS custom properties are a W3C standard with universal browser support and no versioning risk.

Decision: The Tailwind bridge is disposable infrastructure, not design governance.

Why: Tailwind is the current utility framework used in Aleris product development. It provides genuine productivity benefits for layout and responsive design. But framework popularity shifts over time. The bridge pattern means Aleris can adopt or drop frameworks without touching the design system itself. The bridge is a convenience layer that earns its place through developer productivity, not through architectural necessity.

Decision: Typography bridges accept approximate mapping to framework-native values.

Why: The primary function of the type scale is to provide clear visual hierarchy across Aleris products. The modular scale (perfect fifth, 1.5 ratio) provides the mathematical foundation that generates coherent values and a rationale for why each size exists. In rendered output, the difference between a heading at 27px and one at 30px does not affect the hierarchy's clarity. Requiring pixel-level precision across every rendering context would force either framework divergence (confusing for developers) or scale compromise (weakening the mathematical foundation). Accepting approximate bridge mappings preserves both.

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