One URL instead of eleven files

The last time I wrote about Amaca, it was at v1.2.0 and it lived inside Claude Design. The tool built tokens, variants and first drafts; I kept the brand and the judgement. Next to the site sat a first DESIGN.md, version 0.1: a description of the system written for machines. An agent given only that file built a pricing page that was about 70% right, and each miss became a new Don't.

That loop never stopped. In the six months since, Amaca shipped 31 releases, five of them majors. The components specified in the contract went from 7 to 46, the file became the system's contract, and the site became its demo.

This is the story of how it got there, and of the last step: how every AI tool now gets it.

In May, v2.0.0 made DESIGN.md the canonical context for AI. From then on the system had two halves: the site, still built and deployed from Claude Design, and the contract, written with an agent that worked on files. Each release crossed both, and each half kept its own record of what had changed.

Two records drift. On 5 August, v3.4.0 was the first release done end to end in one place, the contract, the site and the stylesheets together. The same release introduced the closed component registry, where anything the registry does not name is off-system: stop and ask. It also introduced the harness, a script that checks the whole system before anything ships. It ran about twenty checks then; on 6.0.0 it runs 130.

By the end of August I had written it down for myself.

A system checked only against itself can be consistent and still wrong. So I put Amaca next to two dozen public design systems, among them Polaris, Primer, Carbon, Spectrum, Atlassian, Cloudscape and Salesforce Lightning. Each was rebuilt into the same set of pages as Amaca, component by component, and compared side by side, again after every change. When a component looked right everywhere except in Amaca, or looked right in Amaca for the wrong reason, the fix went into Amaca.

The study also showed how other systems state their rules. Amaca's were a list: seven principles and a table of anti-patterns. v5.0.0 rewrote them in three layers. Five principles, ranked, so that when two pull in opposite directions the higher one wins. Ten conventions for how the system is written. And nine laws, each with an id, a severity, the principle it serves and the check that holds it.

The contract draws the line in one sentence: A principle guides a judgement; a law is measured and enforced. Every row of the old anti-patterns table went to one place or the other.

Constraints got the same treatment. Each component's Usage now says when to use it and, for every other case, which component to use instead. Renames are measured, not assumed: --magenta-* became --primary-* in v5.0.0 with no paint change across 10,165 elements, and in 6.0.0 the "mono" register, which promised a monospaced face the system never had, became the label register with none across 23,399. And from v5.3.0, every finding of the check carries the id of the law it breaks.

A contract this strict was ready for readers that are not people. What was missing was a good way to reach them.

Every AI tool reads instructions its own way. Claude takes a skill, Cursor and Copilot take rule files, Figma takes its own skill, a chat app takes a pasted document, Tailwind takes a theme. So the system shipped a projection of the contract for each of them: eleven downloads by the time of 6.0.0.

My bet was that a single MCP server could stand in for most of those files. An agent connected to it asks for what the task needs, one component, one token family, one section of the spec, and gets the published version every time.

v5.1.0 put it online on 19 October 2026: Streamable HTTP, stateless, read-only, no key, because everything it returns is already public. It answers from the files of the deploy that serves it, so it can't drift from the release. Claude takes it as a custom connector, Claude Code with one command, Cursor and VS Code by URL; the Claude Code plugin declares it, so installing the plugin brings the skill and the server together.

The server also carries instructions, which a client hands to the model when it connects. On 6.0.0 they open like this:

Reading the contract is half the job. The other half is knowing whether the code that came out follows it, and a model is a poor judge of its own output. So check_compliance takes the code an agent wrote, HTML and CSS or React with Tailwind, and returns each violation with the token or class that fixes it, the section it comes from and the law it breaks. The server's instructions ask the model to run it before handing anything over.

<style>
.pricing-card{background:#1B1F24;padding:14px 20px;border-radius:10px;transition:background 250ms ease-in-out}
.pricing-card:hover{background:var(--obsidian-800);transform:scale(1.02)}
.pricing-card .card-body{color:var(--obsidian-100)}
</style>
<div class="pricing-card"><div class="card-body">Pro</div><button class="btn btn-primary">Buy</button><button class="btn btn-primary">Trial</button></div>

error · line 2 · colour-literal · L4
found  #1B1F24
fix    no token has this value: pick one from get_tokens (primary, obsidian, secondary, tertiary, the semantic four)

error · line 2 · raw-px · L4
found  padding: 14px
fix    var(--s-3) (12px; it snaps from 14px, a visible change: check it)

error · line 2 · raw-px · L4
found  padding: 20px
fix    var(--s-5)

error · line 2 · raw-px · L4
found  border-radius: 10px
fix    var(--r-md) (8px; it snaps from 10px, a visible change: check it)

error · line 2 · raw-duration · L8
found  transition: 250ms
fix    var(--d-quick) (200ms; it snaps from 250ms, a visible change: check it)

error · line 2 · raw-easing · L8
found  ease-in-out
fix    var(--ease-standard)

warning · line 2 · reduced-motion · L7
found  transition or animation with no prefers-reduced-motion override
fix    components.css carries the global kill-switch (durations to 0.01ms); a component with a transform, a fade-in or an orchestrated animation also sets its own transitions to none inside @media (prefers-reduced-motion: reduce), or motion-reduce: in Tailwind

warning · line 6 · class-off-registry · C2
found  card-body
fix    not an Amaca class: compose the canonical ones (get_component card); if it is your project's own class, ignore this

warning · line 6 · one-primary · L3
found  .btn-primary × 2
fix    one .btn-primary per screen; the rest recede (secondary, ghost, outline)

The scan does not replace a review, and it says so whenever it finds nothing: A clean scan is not a review: it cannot see layout, hierarchy or the choice of component.

A bet needs a test. On 25 and 26 October I ran a benchmark: seven tasks, three runs per cell, four models working as subagents, and seven ways of giving them Amaca. No file at all, each of the short files, the skill, the whole DESIGN.md, and the server alone. Each output was scored against the contract; 599 runs were scored in the end.

• Quality, server only
  93.8
  skill 89.3 · DESIGN.md 89.2 · short files 76 to 79
• Tokens per run, server only
  42.3k
  skill 118.5k · DESIGN.md 85.3k
• Refusing to invent, server only
  0.79
  the file routes 0.96 to 1.00

The conditions, the seven tasks, the failures by route and every caveat are in the full benchmark report.

The two weak spots went straight into 6.0.0.

Each step of this path moved the system's truth into fewer places. First out of a tool and into one contract. Then out of prose and into laws a script can hold. Then out of eleven files and behind one URL. The server did what I expected of it: the published release, the parts and the rules on demand, at a fraction of the context. It did not make the downloads useless. Figma, Tailwind and a token pipeline still want files, and an agent with no network wants something on disk. What changed is their role: every file is generated from the contract and checked against it.

The other lesson is about where corrections come from. The comparison with other systems and the benchmark found things no review of Amaca on its own would have found, and both ended up in the same release. A design system for agents is not finished when it is written down; it is finished when something outside it has tried to use it.

What comes next is the obvious step: run the same benchmark on 6.0.0, and see whether naming off-system components and putting the parts in the short files close the gaps they were written for. Two parts of the original protocol, real chat clients and Figma, are still to be run.

Method The figures come from the benchmark of 25 and 26 October 2026 on Amaca 5.2.0: seven tasks, three runs per cell, four models as subagents, 599 runs scored, averages across models. Model names are left out on purpose; the full report has the setup and the caveats. A blind comparison of one task's outputs is not reported here. The scan in Fig. 09 was run on 13 November 2026 on the 6.0.0 release. The comparison with other systems ran from September to November 2026 on public packages.

• amaca.design, the system and its documentation.
• The MCP server, at https://www.amaca.design/mcp.
• github.com/angelomacaione/amaca-design, the repository, the server included.

• DESIGN.md, § Changelog, v1.2.0 to v6.0.0, and the release tags of the repository.
• The benchmark report of 26 October 2026, MCP server against files: full report.
• The release plan of v6.0.0 and its review.
• The comparison reports against other public design systems, September to November 2026.
• The previous case study, for the Claude Design period.
• The Amaca MCP server, 6.0.0 from the release branch, queried on 13 November 2026.