Design Systems Architecture

Headless Design Systems

Behaviour without opinion. Token-driven theming. Machine-readable for AI agents. One system, infinite expressions.

View ArchitectureSee the Code
Why Headless

Separate behaviour from presentation

A headless design system defines what components do, not how they look. Styling becomes a token layer that can be swapped per brand, per product, per context.

Behaviour Separation

Radix UI primitives handle accessibility, keyboard navigation, and state management. Zero visual opinions baked in.

Token-Driven Theming

Swap a single CSS file to re-skin the entire system. Healthcare, fintech, e-commerce — same components, different tokens.

Machine-Readable

Tokens as CSS custom properties. CLAUDE.md as context. AI agents can consume, extend, and generate from the system.

Architecture

Six layers, one system

Each layer has a single responsibility. Replace any layer without breaking the others.

01
Headless Primitives
Radix UI — accessibility, keyboard, focus, state
@radix-ui/*
02
DS Component Layer
Props, variants, composition API
src/components/*
03
Design Tokens
CSS custom properties — colour, spacing, radius, shadow
src/tokens/*.css
04
Brand Themes
Token sets per brand — swap CSS to re-skin
healthcare.css
05
Figma via Code Connect
Visual layer synced to code source of truth
MCP bridge
06
AI Agent Layer
CLAUDE.md context + MCP tools — agents consume and extend
CLAUDE.md
Live Demo

Same component, different tokens

The form below uses identical markup and behaviour. Only the token layer changes.

default.css
user@example.com
Your data is encrypted end-to-end.
healthcare.css
patient@clinic.com
HIPAA-compliant data handling enabled.
Code

Tokens in, components out

default.cssToken Layer
:root {
  --color-primary: #2563eb;
  --color-primary-dark: #1e40af;
  --color-secondary: #8b5cf6;
  --color-accent: #06b6d4;

  --radius-md: 6px;
  --radius-lg: 8px;

  --shadow-sm: 0 1px 2px rgba(0,0,0,.05);
  --space-4: 1rem;
  --space-6: 1.5rem;
}
Button.tsxComponent Layer
export function Button({ variant, children }) {
  return (
    <button
      className={styles[variant]}
      // Radix handles: focus, keyboard,
      // aria-*, disabled state
    >
      {children}
    </button>
  );
}

// Tokens consumed via CSS Modules
// Zero hardcoded values
Pipeline

Code to canvas, canvas to code

The MCP bridge keeps Figma and code in sync. Tokens flow from CSS to Figma variables. Components flow through Code Connect.

01Parse Tokens

Read CSS custom properties from styles.css and map to Figma variable collections.

styles.css → Variables
02Build Components

Generate Figma components from React source with variants and auto-layout.

*.tsx → Components
03Code Connect

Map Figma nodes to codebase files so developers see real imports in Dev Mode.

Figma ↔ Codebase
04Agent Layer

CLAUDE.md provides context. MCP tools let agents read, create, and extend the system.

CLAUDE.md → Agent
The INC Framework

Ideate < Narrate > Create

IIdeate

NorthStar prototyping with AI. Explore when possibilities are widest.

<
NNarrate

The agentic design system layer. Domain knowledge as machine-readable context.

>
CCreate

Production code, content, shipping. The system amplifies execution.

Ready to build your agentic design system?

Let's talk about how headless architecture and AI agents can transform your design-to-code workflow.

This entire page was designed in Paper and coded via Claude Code prompts.

lincolnmitchell.io · linc@lincolnmitchell.io

/