Headless Design Systems as AI Infrastructure

Why Headless?

A headless architecture separates the what (behaviour, accessibility, state) from the how (visual presentation). This separation is what makes a design system truly machine-readable.

Behaviour Separation

Headless primitives (Radix, React Aria) handle accessibility, keyboard navigation, focus management, and state. Zero opinions on styling. The stable foundation agents can rely on.

Token-Driven Theming

Your design system layer maps tokens to component variants. Swap token sets, swap brands. Same component tree, infinite visual identities. Styling becomes data, not code.

Machine-Readable

Structured props + typed variants + token contracts = components an AI agent can understand, generate, and compose without ambiguity. The design system becomes AI infrastructure.

The Architecture

From headless primitives to AI-authored interfaces. Each layer adds structure that agents can consume.

Headless Primitives

Radix, React Aria, Ark UI

↓

DS Component Layer

Props, variants, composition

↓

Brand Token Sets

JSON tokens, multi-brand

↕

Figma Code Connect

Bidirectional design-code sync

↕

MCP Server

Model Context Protocol endpoint

↓

AI Agent

Claude Code, Cursor, Copilot

Interactive Demo

Same headless structure, different brand tokens. Toggle themes to see how styling becomes data — the component tree never changes, only the tokens do.

Unstyled (Headless)

<Card>

Component Library

Tokens define every visual property. Structure stays constant.

Learn more

<Input>

Email address

We'll never share your email.

<Alert>

Note: Same semantic HTML. Zero styling opinions.

Themed (Tokens Applied)

<Card>

Component Library

Tokens define every visual property. Structure stays constant.

Learn more →

<Input>

Email address

We'll never share your email.

<Alert>

Note: Same semantic HTML. Tokens control every visual property.

Active Token Set --demo-primary: #2563eb --demo-accent: #06b6d4 --demo-radius: 0.5rem --demo-bg-subtle: #f8fafc --demo-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1)

The Code

Three layers that create the machine-readable contract. Headless behaviour, design system styling, and the token set that drives it all.

// Radix UI — behaviour only, zero styling
import * as Dialog from '@radix-ui/react-dialog';

export function ConfirmDialog({ children, onConfirm }) {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        {children}
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />    // No styles — just a11y + focus trap
        <Dialog.Content>
          <Dialog.Title>Confirm</Dialog.Title>
          <Dialog.Description>Are you sure?</Dialog.Description>
          <button onClick={onConfirm}>Yes</button>
          <Dialog.Close asChild>
            <button>Cancel</button>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

// DS Button — wraps headless, consumes tokens
import { forwardRef } from 'react';
import { tokens } from './tokens';
import { styled } from './styled';

type ButtonVariant = 'primary' | 'secondary' | 'ghost';
type ButtonSize = 'sm' | 'md' | 'lg';

interface ButtonProps {
  variant?: ButtonVariant;   // Agent knows: 3 options
  size?: ButtonSize;          // Agent knows: 3 options
  fullWidth?: boolean;        // Agent knows: boolean
}

export const Button = styled('button', {
  base: {
    borderRadius: tokens.radius.md,
    fontWeight: tokens.fontWeight.semibold,
    transition: `all ${tokens.transition.base}`,
  },
  variants: {
    variant: {
      primary: { bg: tokens.color.primary, color: 'white' },
      secondary: { bg: tokens.color.secondary, color: 'white' },
      ghost: { bg: 'transparent', color: tokens.color.primary },
    }
  }
});

// tokens/healthcare.json — the machine-readable contract
{
  "$schema": "https://design-tokens.org/schema.json",
  "brand": "Healthcare",

  "color": {
    "primary":   { "$value": "#059669", "$type": "color" },
    "secondary": { "$value": "#14b8a6", "$type": "color" },
    "accent":    { "$value": "#0d9488", "$type": "color" }
  },

  "radius": {
    "md": { "$value": "0.75rem", "$type": "dimension" }
  },

  "shadow": {
    "md": {
      "$value": "0 2px 8px -2px rgb(5 150 105 / 0.15)",
      "$type": "shadow"
    }
  }
}

// Agent reads this contract → knows exactly
// what values to use when composing UI

The Figma MCP Pipeline

The headless architecture plugs directly into Figma's MCP server, creating a bidirectional loop between design and code.

Figma Code Connect

React components are linked to their Figma counterparts. The agent knows that <Button variant="primary"> maps to the primary button in your Figma library.

MCP Server

The design system is exposed as a Model Context Protocol endpoint. AI agents can query available components, props, variants, and tokens as structured data.

AI Agent Authoring

Claude Code or any MCP-capable agent composes UIs using real DS components, respecting constraints and token contracts. No hallucinated markup.

I ←→ ×N ←→ C

The pipeline creates the bidirectional INC loop: Ideation flows to Code, code constraints inform design. The agentic design system is the ×N that amplifies both directions.

This page was built with the methodology it describes.

Every section, component, and line of code was generated via Claude Code prompts — proving that agentic design systems work.

View Design System Get in Touch