ARCANA UI
An experiment in making a design system legible to AI agents
The Gap
41% of all code is now AI-generated. GitHub Copilot, Cursor, v0, Bolt, Lovable — these tools write production code daily. But none of them have a design system. Existing UI libraries — Material UI, Chakra, shadcn/ui — were built for humans reading documentation. AI agents don’t browse docs. They parse context windows. And existing systems scatter their design decisions across SCSS variables, JS config objects, runtime APIs, and markdown files. The AI is guessing at patterns, not reading a spec.
The Solution
Arcana ships with manifest.ai.json — a single machine-readable file that gives AI agents complete context on every component, every prop, every design pattern. Semantic token naming that AI can reason about. Predictable component patterns it can learn from one example. One JSON file controls the entire visual identity.
The architecture follows a three-tier token system:
- Layer 1: Primitive tokens — raw values (colors, sizes, spacing).
- Layer 2: Semantic tokens — contextual meaning (
--color-bg-page,--color-action-primary). - Layer 3: Component tokens — specific to each component (
--button-bg,--card-radius).
Two Users
Arcana serves two audiences simultaneously:
For AI Agents
Machine-readable manifest. Parseable component context. Semantic naming that maps to intent. AI can generate correct, themed UI from a single example.
For Humans
Describe your brand in the playground — adjectives, colors, references. The AI generates a complete theme. Customize visually. Export production-ready code. Install via npm.
The Architecture
Three-layer product architecture:
Layer 1 — Core (Distribution)
MIT licensed, npm install @arcana-ui/core. React component library + design tokens. Zero dependencies. CSS custom properties for theming.
Layer 2 — Playground (Conversion)
AI-powered theme generation. Visual editor. Export to production code. This is how users discover Arcana and customize it.
Layer 3 — Platform (Revenue)
Pro license for advanced themes, team collaboration, and enterprise features. The business model that sustains the open-source core.
Where It Landed
Arcana was an experiment, not a product, and it is not what I spend my time on now. The large model labs are building this same idea with considerably more resources, and that is the right outcome: the question was worth asking and it is being answered.
The part that held up is the token architecture. This site still imports @arcana-ui/tokens and @arcana-ui/core/styles, and the theme you are looking at is a set of overrides on Arcana’s semantic layer. The React components here are a local fork rather than the published package, so I would not claim the site is built entirely on it. The three-tier cascade is the idea I still use everywhere.