---
name: Token Governance & Framework Dependencies
type: reference
status: anchor
depends_on: [aleris-tokens.css, foundation/constant-contextual]
propagates_to: [aleris-design-governance.md]
open_questions: []
last_verified: 2026-03-21
---

# Token Governance & Framework Dependencies — Aleris Design Tokens

## Status
Architectural position paper. Establishes the relationship between design tokens, CSS, and frameworks like Tailwind. Ready for implementation validation.

---

## The Core Question

Design tokens need to reach code. The question is whether that path should run through a framework (Tailwind, Bootstrap) or through native CSS (custom properties). The answer affects who can use the tokens, what dependencies the system creates, and how resilient the architecture is over time.

For Aleris specifically, the question is sharpened by two realities: multiple IT environments across three countries with different tech stacks, and increasing use of AI-assisted code generation where the token system needs to function as machine-readable context.

---

## Position: CSS Custom Properties as Foundation, Frameworks as Enhancement

Tokens are defined as CSS custom properties. This is the base layer — platform-native, zero dependencies, works in any browser, any stack, any build system. Framework integrations (Tailwind, etc.) consume these properties and are optional layers on top.

This follows the same progressive enhancement principle that governs the rest of the design system: the base must be complete and functional on its own. Every added layer enriches the experience but is never a requirement.

---

## Why CSS Custom Properties as the Base

**Zero dependencies.** CSS custom properties are a browser-native feature. No build pipeline, no npm packages, no version conflicts, no framework lock-in. A plain HTML file with a `<link>` to the token stylesheet has full access to the design system.

**Universal compatibility.** Aleris operates across three countries with separate IT tenants and varying technical environments. A token system that requires a specific build tool or framework version creates adoption friction. CSS custom properties work in Next.js, in WordPress, in a static HTML page, in an email template — anywhere CSS works.

**Transparent to humans.** `var(--color-surface-warm)` is readable. You can inspect it in any browser's dev tools, see the resolved value, trace where it's defined. No abstraction layer between the design decision and its expression in code.

**Durable.** CSS custom properties are a W3C standard. They won't be deprecated, acquired, or abandoned. Framework popularity cycles; platform features persist.

### What it looks like

```css
/* aleris-tokens.css — the single source of truth */

:root {
  /* Primitive tokens */
  --color-petrol-500: #004851;
  --color-sand-100: #F2ECE4;
  --color-orange-500: #f58c61;

  /* Type scale (perfect fifth, base 18) — see aleris-tokens.css for canonical names */
  --font-size-xs: 14px;   /* accessibility floor — nothing below this */
  --font-size-sm: 16px;   /* half-step: √(14×18) */
  --font-size-base: 18px;
  --font-size-md: 22px;   /* half-step: √(18×27), h4 */
  --font-size-lg: 27px;   /* h3: base × 1.5 */
  --font-size-xl: 40px;   /* h2: base × 1.5² */
  --font-size-2xl: 60px;  /* h1: base × 1.5³ */
  
  /* Spacing scale (1.5 ratio, 4px aligned) — see aleris-tokens.css for canonical names */
  --spacing-3xs: 4px;
  --spacing-2xs: 8px;
  --spacing-xs: 12px;
  --spacing-sm: 16px;
  --spacing-md: 24px;
  --spacing-lg: 36px;
  --spacing-xl: 48px;
  --spacing-2xl: 72px;
  --spacing-3xl: 96px;
  
  /* Semantic tokens */
  --surface-subtle-warm: var(--color-sand-100);
  --text-primary: var(--color-petrol-500);
  --brand-accent: var(--color-orange-500);
}
```

Any HTML file that includes this stylesheet immediately has access to the full token system:

```css
.card {
  background: var(--surface-subtle-warm);
  color: var(--text-primary);
  padding: var(--spacing-md);
  border-radius: var(--radius-l);
}
```

---

## Why Tailwind as an Optional Layer

Tailwind provides value for specific use cases — but as a consumer of tokens, not as their source.

**Reduced decision space for developers.** Tailwind utility classes constrain styling choices to predefined values. `p-md` maps to exactly one spacing value. This is particularly useful when multiple developers of varying experience build against the system — the framework makes it harder to go off-piste.

**Fast prototyping and vibecoding.** AI code generation tools (v0, Bolt.new, Claude Code, Cursor) are heavily trained on Tailwind and produce fluent Tailwind output. For rapid prototyping and AI-assisted development, Tailwind classes accelerate production.

**Compact inline styling.** Tailwind co-locates styling with markup, which some teams prefer for readability and which simplifies component-level development.

### What it looks like

Tailwind v4 consumes CSS custom properties natively via @theme:

```css
/* tailwind config consuming the same tokens */
@import "tailwindcss";
@import "./aleris-tokens.css";

@theme {
  --color-surface-warm: var(--surface-subtle-warm);
  --color-text-primary: var(--text-primary);
  --spacing-sm: var(--spacing-sm);
  --spacing-md: var(--spacing-md);
  --spacing-lg: var(--spacing-lg);
}
```

Developers using Tailwind write `bg-surface-warm p-md text-primary`. Developers not using Tailwind write `var(--surface-subtle-warm)`. Both resolve to the same values from the same source.

---

## How This Serves Different Contexts

### Team with full stack (Next.js, Tailwind, Figma)
Uses Tailwind classes in components. Tokens flow from CSS custom properties → Tailwind config → utility classes. The framework provides guardrails and speed.

### Team with simpler stack (WordPress, static HTML)
Includes aleris-tokens.css directly. Uses var() references in their CSS. No build pipeline needed. Full access to the same design decisions.

### AI-assisted development (Claude Code, Cursor, v0)
Gets the token file as context. Produces output in whichever format is requested — Tailwind classes, vanilla CSS, or both. The token definitions are the design decisions; the output format is an implementation detail.

### Vibecoding (rapid prototyping, no developer)
Uses tools like v0 or Bolt.new that output Tailwind by default. The Aleris Tailwind config ensures generated code uses correct token values rather than framework defaults.

### Future unknown stack
Because the base is CSS custom properties, any future framework or tool that reads CSS can consume the tokens. No migration needed when tooling changes.

---

## Governance Rules

**Tokens are defined once, in CSS custom properties.** This is the single source of truth. All other formats (Tailwind config, Figma variables, JSON for native apps) are derived from this source, never the reverse.

**Framework-specific values never override token values.** If Tailwind's default spacing doesn't match the token scale, the Tailwind config adapts to the tokens — not the other way around. The design system governs the framework, not vice versa.

**New tokens require justification, not just addition.** Every token carries maintenance cost. Adding `--space-between-xs-and-sm: 14px` because someone needed it once creates system debt. The scale is the constraint; if the scale doesn't serve a legitimate need, the conversation is about adjusting the scale — not adding exceptions.

**Arbitrary values are a signal, not a sin.** When a developer uses a value outside the token system (a hardcoded pixel value, an off-palette colour), that's information. Either the token system is missing something needed, or the developer didn't know the right token existed. Both are worth investigating. Neither is resolved by adding linting rules alone.

**Token changes propagate through documentation, not just code.** Changing a token value updates CSS, Tailwind, and Figma — but also needs to update the design rationale. Why was this value chosen? What changed? This is where Architecture Decision Records earn their keep.

---

## What This Architecture Prevents

**Framework lock-in.** If Tailwind is superseded (as Bootstrap was, as every CSS framework eventually is), the token system survives. Migration means reconfiguring the framework layer, not rebuilding the design foundation.

**Inconsistency across tech environments.** Whether a product is built in Next.js in Sweden, WordPress in Norway, or a custom stack in Denmark, the same token file produces the same visual result.

**AI drift.** When AI code generators receive the token file as context, they produce output that respects design decisions regardless of which framework they generate for. The tokens are the constraint; the framework is the vehicle.

**The "two sources of truth" problem.** Figma variables, Tailwind config, and CSS custom properties all derive from one canonical definition. Updates happen at the source and propagate outward.

---

## Design Decision Record

**Decision:** CSS custom properties are the canonical token format. All other formats derive from them.
**Why:** Platform-native, zero-dependency, universally compatible. Aleris operates across multiple countries and tech stacks — the token system cannot require a specific build tool or framework. CSS custom properties are a W3C standard that will outlast any framework.

**Decision:** Tailwind is supported as an optional consumption layer, not a required dependency.
**Why:** Tailwind provides genuine value for developer speed and constraint enforcement, but mandating it would exclude simpler tech environments and create framework lock-in. Progressive enhancement applies to infrastructure too: the base works without the framework; the framework enriches the base.

**Decision:** AI code generators receive the token file directly, not framework-specific config.
**Why:** Token definitions express design intent. Framework config expresses implementation mechanics. AI models that understand design intent produce more correct output across any framework target.

---

## Open Questions

- What is the build/sync pipeline from the canonical CSS file to Figma variables? (Tokens Studio? Manual sync? CI/CD automation?)
- Should the token CSS file be published as an npm package for teams that prefer that distribution model, in addition to a plain CSS import?
- How do native mobile apps (if/when relevant) consume tokens defined as CSS custom properties? (Likely: a JSON export from the same source, using Style Dictionary or similar transform.)
- At what point does the system need linting to catch off-system values, vs relying on documentation and culture?