nil-ds:↳ a design system agents can read

nil-ds is a design system I designed and built, with guidance written for AI agents as well as for people. I ran an eval to see whether that guidance helps Claude use the kit correctly, and wrote up what it can and can't show.

Back to Work
Role: Open Source / Solo Year: 2026 Stack: React · TypeScript · Vite · Vitest · Claude Code Timeline: Building in public

// 01

Overview

nil-ds is a small design system I designed and built. It has design tokens (named values, like a colour or a spacing, that code reads), React components that use only those tokens, and files written for AI agents: an AGENTS.md of rules, a DESIGN.md generated from the tokens, and a registry.json describing the components.

It has 24 components, each with its own tests and an axe check of semantics and ARIA. Contrast is checked at the token level: every mapped text and background pair meets WCAG AA, and the token check fails if one doesn't.

The nil-ds showroom gallery: Button variants, the Composer chat input, Dialog triggers and the start of the Menu.
The showroom's gallery: Button, Composer, Dialog and Menu, with a note on how each behaves.

// 02

Challenge

An AI coding tool reads a design system differently from a person. A kit can look tidy in its showroom while an agent building with it invents token names, types raw colours or rebuilds a button the kit already has.

I'd written files to stop that. I wanted to measure whether they change what Claude actually builds.

// 03

Try it

Open the showroom →

Every component and its states · light and dark

Read the eval →

Method, results and what it can't show

Source on GitHub →

Public · tokens, agent files and the eval

// 04

Outcome

The eval gives Claude five small UI tasks in two arms: the kit with its human docs, and the same kit with the agent files added. Ten rules score what it writes, all checked by code with no AI judge, and the checker was broken on purpose before any result was believed.

Once the guidance listed the token names, Claude searched the token file in 11 of 12 runs, against 3 of 12 without the agent files. The scores alone can't separate the guidance change from noise, and on the held-out task the gain looks like one copied sentence. The proof page says all of that plainly.

The nil-ds proof page: how the eval works, and the results table for both arms and both rounds.
The proof page's results, read from the eval's own result files when the page is built.

// 05

Reflection

It was important for me to start thinking about neurodivergence and how to bake that into product design, so the kit respects reduced motion from the token layer up.

The eval is a probe, not a benchmark: three runs a cell, one model, one kit. What it taught me is how easily a gain can come from one copied sentence, which is why the checks come first.