Why test
An agent that has read a page can still ignore it. It will often produce something that looks right and quietly uses a hex value, an unlabelled icon or an “Are you sure?” the page told it not to. You only find out by asking it to do real work with the page and checking the result against what the page says.
Every foundation, pattern, kit and component page ends with an AI readiness test: one task, the context to give, a constraint, and the list of things a reliable answer contains. It tests the page as much as the agent. If several agents fail the same test in the same way, the page is unclear, and the page is what gets fixed.
The shape of a test
- Task. Real work in Kwark’s world: “Restyle a settings panel so it works in the Paper room and in dark mode.”
- Give the agent. The page, and the few other files the task needs. Nothing else.
- Constraint. The limit that makes the test meaningful: “No new colours. Say which roles you used.”
- A reliable answer. Four to six things that must be true of the answer. Each one is checkable by reading the answer, without judgement calls.
How to run one
- Start a fresh conversation. No earlier messages, no project memory, no
CLAUDE.mdwith Kwark rules in it. You are testing what the page teaches, not what the agent already picked up. - Give it only the listed context. Paste the markdown twins (switch to Agent, then Copy markdown) or give the
.mdURLs. Do not add hints. - Paste the task and the constraint, as written. Use the readiness prompt if you want the agent to also list what it used.
- Let it answer once. Do not correct it mid-answer; a correction is a second test.
- Grade against the reliable-answer list.
Run each test in every tool your team uses. The same page can pass in one model and fail in another.
How to grade
Grade each item on the list as met or not met. There is no partial credit and no overall score to chase.
| Result | What it means | What to do |
|---|---|---|
| Every item met | The page is ready for this agent. | Keep the test; run it again when the page changes. |
| One item missed | The agent is close, or the page buries that rule. | Read the page as the agent did. If the rule is in a paragraph rather than a Must line, promote it. |
| Several items missed | The agent did not use the page, or the page is unclear. | Check the agent was given the page. Then rewrite the page, not the test. |
| An invented token, component or rule | The most serious failure. | The page must say plainly what to do when something is missing: stop and ask. |
Count what the answer did: “Used --k-surface and --k-text, no hex, contrast checked in dark, did not assume copper.” Four of four met.
“Looks good, about 8 out of 10.” A feeling is not a grade, and a score hides which rule failed.
What a reliable answer looks like
A reliable answer is specific in the same ways every time:
- It uses names from the page exactly:
--k-text-2, not “the secondary text colour”;Sheet, not “a bottom drawer”. - It says which tokens, components and rules it used.
- It says plainly where the system did not cover something, and asks, instead of inventing.
- It covers the states the page lists: empty, loading, error, offline, read-only.
- It keeps Kwark’s limits without being reminded: no judgement of the writing, nothing a machine writes without a revision mark, no glow.
An answer can be well written and still unreliable. Grade what it does, not how confident it sounds.
Writing a new test
- The task is something a real Kwark team would ask for, in Kwark’s world (Scene 12, the call sheet, Mira, Act 2).
- The constraint closes the easy way out (“No new colours”, “Phone first”, “Name the components”).
- Every item on the reliable list is checkable by reading. “Uses only --k-* roles” is checkable; “feels calm” is not.
- Four to six items. More, and nobody runs it.
Every page with a test
Each of these pages ends with its own test.
Getting started and agents
Foundations
Patterns
Creative app kits
Components
Every component has its test in the For agents tab of its page. The full list is in the component catalogue and in components.json; each entry’s docs URL leads to the page with the test.
AI readiness test
Task. Run the readiness test from the Colour page against two agents and report the result.
Give the agent. This page, the Colour page’s markdown twin.
Constraint. Fresh conversations, only the listed context, one answer each.
A reliable answer
- Starts each agent in a fresh conversation
- Gives only the Colour page and the files its test names
- Grades each reliable item as met or not met with no score
- Names which rule failed when an item is missed
- Proposes a page change rather than a test change when both agents miss the same item