Arcana UI

An experiment in making a design system legible to AI agents.

ROLE: Creator & Design Engineer
AT: Arcana
WHEN: 2025
WITH: React, TypeScript, Design tokens, MCP

3token tiers

> THE PROBLEM

AI tools write production UI every day, but design systems were built for humans reading docs. Agents read context windows, and most systems scatter their decisions across SCSS, JS config and markdown.

> WHAT I DID

Designed a three-tier token architecture: primitive, semantic, component.
Wrote manifest.ai.json, one machine-readable file describing every component and prop.
Built an MCP server so agents can query the system directly.
Published it all to npm as open source (MIT).

PRIMITIVE   --primitive-red-600: #dc2626
    |
SEMANTIC    --color-action-primary: var(--primitive-red-600)
    |
COMPONENT   --button-bg: var(--color-action-primary)

> WHAT CHANGED

It was an experiment, not a product. The big labs are building this idea with far more resources, which is the right outcome.
The token architecture held up. I still use the three-tier cascade everywhere, this site included.

[ arcana-ui.com ↗ ]