Overview of the flow

Design tools (Intent)
↓
Pipeline (Transformation)
↓
Underlith (Token Source of Truth)
↓
Application (Consumption)

This flow explicitly separates design decisions, token processing, and runtime usage, as recommended by the W3C.

1. Design tools define intent

W3C: Design Token Definition Layer

The W3C defines a design token as:

In this architecture, design tools are used only as the token definition layer.
They define intent and semantics, not implementation.

Applied principles

• Tokens represent design decisions, not technical details
• Semantic naming, independent of platform or framework
• Tokens may contain:

• Primitive values (`#0055FF`, `16px`)
• References and aliases (`{color.brand.primary}`)

Conceptual example

{
  "color": {
    "brand": {
      "primary": {
      "value": "#0055FF",
      "type": "color"
      }
    }
  }
}

This directly corresponds to the W3C concept of Design Token Definitions: neutral, declarative, and decoupled from runtime concerns.

2. Pipeline transforms

W3C: Token Processing & Transformation

The W3C recommends that tokens remain independent from how they are consumed.
For this reason, transformation is an explicit intermediate step.

Pipeline responsibilities

• Resolve aliases and references
• Normalize naming and hierarchies
• Convert tokens to multiple formats
• Prepare outputs for different platforms

Applied principles

• Tokens are treated as data
• Transformations preserve semantic intent
• Multiple outputs are expected and supported

Example outputs

• Normalized JSON
• CSS Variables
• Framework mappings (Tailwind, Sass, etc.)

This step corresponds to Token Processing in the W3C model.

3. Underlith centralizes tokens

W3C: Token Source of Truth

Underlith acts as the Single Source of Truth, a core concept in the W3C architecture.

A token source must be independent from any specific platform or runtime.

Underlith responsibilities

• Centralize `tokens.json` and `tokens.css`
• Preserve original token semantics
• Avoid framework or runtime assumptions
• Enable versioning, auditing, and traceability

Applied principles

• Semantic, platform-agnostic base
• Tokens are stable
• Applications are replaceable
• Clear separation between:

• design decisions
• token data
• runtime styling

Typical structure

Underlith/
├── tokens.json
├── tokens.css
└── metadata.json

This layer directly maps to the W3C Token Source concept.

4. Applications consume

W3C: Token Consumption Layer

At this stage, tokens are consumed, not redefined.

The W3C states that tokens should be applied according to platform needs, without altering their meaning.

Examples of consumption

• Tailwind (`theme.extend` via CSS Variables)
• Sass (maps, `@use`)
• CSS-in-JS (styled-components, vanilla-extract)

Example

.card {
  padding: var(--ul-space-4);
  background: var(--ul-color-surface);
}

Applied principles

• Applications depend on tokens
• Tokens remain platform-agnostic
• Design changes do not require structural refactors
• The semantic contract remains intact

Conclusion

Underlith follows the reference architecture defined by the W3C Design Tokens Community Group:

This model:

• Scales sustainably
• Avoids technological coupling
• Supports multiple platforms
• Preserves semantic integrity over time

This document describes a reference architecture, not a framework-specific solution.

Underlith is a semantic foundation aligned with the W3C and designed for long-term evolution.