Design Philosophy

Every existing UI library is optimized for human DX. Axiom UI is optimized, from first principles, for generation, comprehension, and modification by LLMs. Humans are the secondary beneficiaries.

The Inversion

The primary reader of code is no longer only human. Abstractions built for human cognitive load — deep inheritance, polymorphism, endless config options — become debt for LLMs: they fuel hallucination and waste context and tokens. Axiom carries none of that debt. Every design decision must pass one question:

"Does this decision raise or lower the probability that an LLM generates this component correctly in one shot?"

If it doesn't raise it, we don't build it.

The five-step algorithm

Applied in order, irreversibly.

1. Question every requirement

Every prop, component, and option must justify its existence. A requirement nobody can justify is a dumb requirement, even if a smart person wrote it.

2. Delete

The best prop is no prop. One way to do each thing — variants are hallucination fuel. The best component is no component: if a native HTML/ARIA primitive suffices, don't wrap it.

3. Simplify

Polish only what survived deletion. Never optimize before deleting. What remains gets thick types and examples.

4. Accelerate

Tokens and bytes per component are measured and gated in CI. Fat components don't merge. This is what lets an LLM read a whole file cheaply and fast.

5. Automate — last

MCP server, CLI, and doc generation come only after deletion and unification. Never automate what shouldn't exist.

Architectural consequences

1 component = 1 file

Implementation, types, docs, examples, and manifest co-located. Fitting in a single context window is a design constraint, not luck.

Type as the contract

strict: true, discriminated unions, no any. Types are the primary documentation — an LLM can emit correct code by reading types alone.

Copy & own

No npm runtime dependency. A CLI injects code into your repo. You own it — no black boxes, and LLMs can freely modify it.

MCP-first distribution

An MCP server ships alongside the library, so agents fetch version-accurate specs without wasting tokens. The 'paste the docs URL' step is deleted.

Machine-readable manifest

Each component carries { intent, props, states, a11y, examples } as structured data, so agents can select and render components — the foundation for generative UI.

Zero-config defaults

Works correctly with no props. Escape hatches exist but are never required.

Non-goals

Infinite theme customization (one good default instead)
Multi-framework support (in v0)
Anything claiming to "cover every use case"
A second API for the same purpose
Config options for features nobody asked for

Success metrics

Measured, not felt:

token/component — the average component fits in a single context window.
bundle/component — bytes per component are tracked and never regress.
one-shot generation rate — the primary KPI — how often an LLM generates correct code with zero fixes.
deletion ratio — lines deleted vs. lines added, recorded per release.

The best part is no part. The best process is no process. — This library is an attempt to apply that to UI.