Harness
Draft. The prose on this page is under review.
Components for AI products, with rules a machine can check. Install one and your agent gets the reasoning along with the code.
Super AI Components is a registry of 118 interface components for AI products, installed one at a time with shadcn add. Around the components sits a harness: the instructions, rules, contracts and tests that let an agent build here unattended and fail visibly when it gets something wrong.
The short version: components tell an agent what it may use. The harness tells it, in a failing test, when it used them wrong. This page is about the harness.
1What you get beyond the component
Each item installs two files: the component and a usage contract beside it. The contract records when to reach for the component, which variant fits which case, what to avoid and why, and what to use instead.
An agent working in your app reads that contract before it places the component. The contract is locked to the installed version, so it cannot describe a different component from the one in your tree.
1The installed contract
With a component installed
Read this first. It is locked to the version of the code beside it, so it outranks anything on the web.
components/super-ai/<name>.meta.json2The component's page
Before installing
When to reach for it, which variant fits which case, and what to use instead.
llms.txt, then the page it links3The full corpus
When choosing between components
Every component page in one file.
llms-full.txt
All of it derives from one guidance module per component. The 118 contracts, the routing table at apps/docs/index/components.toon and the corpus at apps/docs/public/llms.txt are written by one command and compared with their source by a test, so none of them can describe an older component quietly.
2The four parts
A harness is the scaffolding around a model that makes its work dependable. Here it has four parts, and each one holds content specific to this system.
1Instructions
Standing orders every session reads before anything else.
CLAUDE.mdis a map. It points at the contracts and restates none of them.- It sits under a byte ceiling with a test behind it, because context is the scarce resource.
- The build briefs under
docs/design-systemare the contracts themselves.
2Tools
What an agent runs to constrain, check and fix its own work.
- 20 rule records behind
pnpm check:tokens, each with a fixture that must fail and one that must pass. - 4 skills: build a component, integrate a batch, run every gate, audit for a generated look.
- A scaffolder that writes a component's files together, so none ships without its story.
- 20 rule records behind
3Memory
What the system knows about itself, derived so it cannot go stale quietly.
- 118 usage contracts, one installed beside each component.
- A routing table with one line per component, read before any full contract.
- The
llms.txtcorpus, for agents working in other repositories.
4Loops
The cycle every change runs through, ending at a person.
- Build: scaffold, write the judgment down, pass 12 gate steps, open a pull request.
- A rejection is finished when its lesson has become a rule or a gate.
- Audit: not built yet. Nothing re-checks
mainon a schedule.
The instructions file is short on purpose. CLAUDE.md is a map under a byte ceiling, and a test fails when it grows past it, because every line there competes with the task for the agent's attention.
3The part that has to be built here
A coding agent arrives with its own tools and its own loop. None of them can tell it whether a component is right for this system. That answer has to live in the repository, and here it lives in 12 gate steps that every change passes before it merges.
An ordinary test asks whether the component still works. These ask whether it still obeys the system: a colour came through a token, a contract matches its component, a catalog entry has the stories its states promise.
The limits are part of the design. Of 20 rules, 17 block a merge, and they are checked in three ways.
| How a rule is checked | Rules |
|---|---|
| By reading source | 18 |
| In a rendered page | 1 |
| By a person | 1 |
The contrast rule reads one element at a time, so muted text inside a muted surface painted by an ancestor passes it. The accessibility step in Storybook catches that shape.
There is no audit loop yet. Gates run on every push and pull request. Nothing re-checks the main branch on a schedule, and production is deployed by hand, so it can fall behind.
4How to explain it
The longer version, for someone deciding whether it matters:
Most component libraries stop at the code. This one ships the reasoning with it and tests the reasoning like code. Every component has a contract that says when to use it and what to avoid. Every rule the system cares about is a test that fails. An agent can build with it unattended, and when it gets something wrong the build says so before a person has to.
One question comes back reliably: is that a component library with tests? Close. The difference is what the tests check. They check design decisions, and they check the documentation against the code, so the written guidance cannot drift from what ships.