Underlith logo Underlith

W3C alignment

Underlith is aligned with the W3C Design Tokens Community Group model and terminology.

Its architecture follows the recommended separation between definition, transformation, source of truth, and consumption.

The W3C reference architecture

The W3C Design Tokens Community Group defines a four-layer reference architecture for design token systems. Underlith implements the third layer — and provides the tooling to complete the pipeline.

Underlith implements the Token Source of Truth layer. @your-org/tokens — generated by underlith brand init — is the published artifact that your org's products consume.

1. Design tools define intent

W3C: Design Token Definition Layer

The W3C defines a design token as a named entity that stores visual design attributes. Design tools are used only as the definition layer — they define intent and semantics, not implementation.

Applied principles

Conceptual example

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

Neutral, declarative, and decoupled from runtime concerns — as defined by the W3C.

2. Pipeline transforms

W3C: Token Processing & Transformation

The W3C recommends that tokens remain independent from how they are consumed. Transformation is an explicit intermediate step.

Pipeline responsibilities

Example outputs

3. Underlith implements the source layer

W3C: Token Source of Truth

Underlith provides the base token infrastructure — the stable, versioned, framework-agnostic foundation that any product can build on. The W3C requires this layer to be independent from any specific platform or runtime.

On top of Underlith, underlith brand init generates your org's brand package — @your-org/tokens — which is the published artifact your products actually consume.

Underlith responsibilities

Structure

@mikaelcarrara/underlith   ← base token infrastructure
└── src/tokens/
    ├── underlith.tokens.css
    ├── spacing.css
    ├── colors.css
    ├── motion.css
    └── semantic-aliases.css

@your-org/tokens           ← your brand layer (generated)
├── your-org.brand.css
└── your-org.base.css

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

.card {
  padding: var(--ul-space-4);
  background: var(--ul-color-bg-surface);
  border-radius: var(--ul-radius-md);
}
/* Tailwind v4 */
@theme {
  --color-brand: var(--ul-color-brand-primary);
  --radius-md: var(--ul-radius-md);
}

Applied principles

Summary

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

W3C layer Implementation
Token Definition Design tools (Figma, Tokens Studio)
Token Transformation Pipeline (underlith brand init)
Token Source of Truth Underlith + @your-org/tokens
Token Consumption Plain CSS, Tailwind, Sass, CSS-in-JS

Underlith is a semantic foundation aligned with the W3C and designed for long-term evolution. The implementation is yours. The infrastructure is shared.

W3C Spec Status

Design Tokens Format Module — W3C Design Tokens Community Group · 2025.10 View spec →