Most systems ship components. This one ships the decisions.

A taxonomy book: one indigo, one token contract, and the rules that turn them into a UI library you own, not a bundle you import.

The whole system, in four numbers

213

Design tokens

Taxonomy tiers

Contrast floor

Action accent

Built for agents

Agent-native. MCP-first. AI-ready by design.

A live MCP server exposes this system as seven typed, verifiable tools — read a token, check contrast, lint CSS — so an agent builds against the contract instead of scraping HTML.

MCP serverAgent skillllms.txtregistry.json

Explore the agent layer

The taxonomy

Three tiers, one direction

Tier 1

Foundations

The token contract. Color, type, space, radius, shadow, motion. Start here.

references: primitives

Tier 2

Patterns

Recipes built from foundations: states, forms, accessibility, voice.

references: foundations

Tier 3

Components

SJ and W UI, built only from patterns and foundations. Coming next.

references: patterns, foundations

The one rule: a tier may reference the tier below, never above. That single constraint is what keeps the system coherent as it grows.

Naming

The name tells you where it lives

Shared, domain-free UI

SJButton, SJInput. Built only from tokens and patterns. No business logic.

App-specific widget

WEventCard, WCheckoutSummary. Composes SJ components; holds the domain logic.

--token

The value contract

var(--color-primary), var(--space-6). The only source of color, space, and type. Never a raw hex.

Single source of truth

Authored once, compiled everywhere

tokens.json
DTCG

Style
Dictionary

CSS vars
+ TypeScript

Change a token once, and every surface that references it updates in step. The DTCG JSON is the contract; nothing downstream is edited by hand.

TS / CSS

// app entry, once
import '@ramoslabs/tokens/css';

/* then build against the contract */
.sj-card {
    background: var(--color-surface);
    padding: var(--space-6);
    border-radius: var(--radius-lg);
    box-shadow: var(--shadow-sm);
}