The Problem

AI generates hardcoded UI

When AI generates UI without design constraints, it usually produces raw values.

color: #3b82f6;
padding: 12px;
border-radius: 6px;
font-size: 14px;

These values may look correct in isolation, but they bypass the design system.

At scale this leads to:

• duplicated values across components
• inconsistent spacing and typography
• UI that slowly diverges from the brand

Automation accelerates development. Without governance, it also accelerates design drift.

Token governance for AI-generated UI

Underlith turns design tokens into enforceable infrastructure.

Instead of generating arbitrary values, AI generates UI through tokens.

color: var(--ul-color-brand-primary);
padding: var(--ul-space-3);
border-radius: var(--ul-radius-sm);
font-size: var(--ul-font-size-sm);

This ensures that both human-written and machine-generated code follow the same visual system.

Tokens act as hard constraints, not suggestions.

Governance model for automation

Underlith separates responsibilities across three levels. AI and automation operate at Level 3 — as product consumers, not decision-makers.

Level 1 — Underlith core (primitives, slow, stable)
      ↓
Level 2 — @your-org/tokens (brand contract, your cadence)
      ↓
Level 3 — Every product: web app, mobile, admin, AI agent
      ↓
CI enforcement (drift check, contrast, visual regression)
      ↓
Validated UI output

• Governance defines the rules
• CI enforces them
• AI operates within them

Automation executes the system. It does not redefine it.

Automated safeguards

Underlith integrates with CI pipelines to ensure automation cannot bypass design governance.

Token validation

lint:tokens

Ensures tokens follow schema rules, naming conventions, and semantic structure. CI fails when tokens violate the contract.

Drift detection

lint:tokens-check

Detects hardcoded design values in the codebase — hex, rgb, hsl, oklch literals and var(-- references not resolving to --ul-* or --ul-color-*.

Example — drift detected:

padding: 12px;

Expected:

padding: var(--ul-space-3);

Contract protection

breaking-change detection

Detects token changes that break downstream consumers.

Examples of breaking changes:

• token removal
• token rename
• semantic value change without version bump

CI blocks these changes until they are properly versioned.

AI-assisted workflows

Underlith is designed to work safely with AI-driven development. Tokens provide the machine-readable structure that allows AI to generate deterministic UI.

underlith init --shadcn

Reads an existing globals.css, maps CSS variables to semantic tokens, and rewrites the file.

No component changes required.

underlith brand init

Separates base tokens from brand tokens and scaffolds a publishable @your-org/tokens package — your Level 2 brand contract.

AI extracts structure from the token layer without inventing values.

underlith migrate (roadmap)

Scans a codebase for hardcoded design values and replaces them with the correct tokens.

This enables safe large-scale migrations.

Token-aware AI prompts

AI systems can operate directly within token constraints.

Example prompt:

Generate a Card component using only the following tokens:

Colors
--ul-color-neutral-0
--ul-color-neutral-200
--ul-color-neutral-900
--ul-color-brand-primary

Spacing
--ul-space-3
--ul-space-4

Radius
--ul-radius-sm
--ul-radius-md

Typography
--ul-font-size-sm
--ul-font-weight-medium

Motion
--ul-duration-fast
--ul-ease-inout

AI output remains aligned with the design system by design.

Result

Automation can safely generate and modify UI.

AI becomes a constrained executor within the design system, not a source of arbitrary visual decisions.

Design governance remains intact even as development becomes increasingly automated.

AI is a constrained executor, not a decision-maker.

Underlith ensures that automated workflows respect the same design contracts that define your brand.

What's available today

• Design tokens: spacing, typography, radius, colors (neutral/brand), opacity, elevation, status
• Motion tokens: durations, easings, composite animations and reduced-motion policy
• Semantic aliases for consumption via var(--ul-color-*) — single consumption path
• CSS-first consumption via src/underlith.css
• CLI flows: underlith init --shadcn and underlith brand init
• Governance and CI guidance with token-aware checks

CI inputs & outputs

CI operates on canonical inputs and produces deterministic artifacts.

Core CI jobs

• build:tokens — generate artifacts from the canonical source
• lint:tokens — validate schema, naming and aliases
• lint:tokens-check — block hardcoded design values in components
• breaking-change detection — protect the token contract
• test:contrast — validate WCAG AA contrast minimums for status and brand tokens
• visual-regression (recommended) — ensure visual equivalence
• audit-log — record generations and refactors

CI quickstart

name: Tokens CI
on:
  pull_request:
    paths:
      - 'src/tokens/**'
      - 'styles/**'
jobs:
  build-tokens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build:tokens
      - run: npm run lint:tokens

  drift-check:
    runs-on: ubuntu-latest
    needs: build-tokens
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint:tokens-check

Reduced motion

Motion tokens automatically respect accessibility preferences. When prefers-reduced-motion: reduce is set, durations collapse to near-zero.

@media (prefers-reduced-motion: reduce) {
  :root {
    --ul-duration-nano:     0ms;
    --ul-duration-micro:    0ms;
    --ul-duration-fast:     0ms;
    --ul-duration-base:     0ms;
    --ul-duration-moderate: 0ms;
    --ul-duration-slow:     0ms;
    --ul-duration-glacial:  0ms;
    --ul-duration-epic:     0ms;
  }
  *, *::before, *::after {
    animation-duration:        0.01ms !important;
    animation-iteration-count: 1      !important;
    transition-duration:       0.01ms !important;
  }
}

What's next

A slice of the Roadmap focused on Automation & AI.

Q3 2026 — Automation

• Token-aware linter: detect hardcoded values that should be tokens
• Pre-commit hooks: block commits with hardcoded design values
• CI templates: breaking-change detection and token audits
• underlith audit: report token adoption coverage across projects

Q4 2026 — Automation & AI

• TypeScript types for token names: autocomplete and build-time validation
• Visual regression harness for reference components
• underlith migrate: AI-assisted migration from legacy values to tokens
• MCP (Integration): expose tokens via Model Context Protocol to editors and AI agents