Why I built a docs playground for the Espalier component library
TL;DR
I set up the documentation website for our design system long before the design system was done. Most of its building blocks were written after the documentation site already existed.
Each building block's description and examples are written next to its code, and the documentation site is generated from them. The examples become working demos you can click on and adjust.
For months, trying a component on its own documentation page was how I tested it. If the page looked wrong or a demo broke, the component wasn't finished.
Because the documentation was the thing I actually used, the AI tools had to write it well. Thin or wrong descriptions showed up right away.
That documentation gave the AI tools something reliable to work from as we built out Taproot on top of the design system. The same idea now runs the command-line tool I use to publish this website.
Why I built the playground first
I wanted to practice documentation-first development: a component isn't done until someone can read how it works, see it running, and try it. The easiest way to hold myself to that was to make the documentation the place I tested from. So I built a documentation site that generates its pages, and a playground on each page, from the comments in Espalier (opens in a new tab)'s source. The comments became my manual test plan.
That also kept the AI tools honest. When Claude Code or Codex wrote a component, I didn't read the comment block and nod. I went straight to the generated page and used the thing. If the description was vague, the page was vague. If an example was broken, the demo was broken. Either the documentation was good and the component worked, or I found out quickly.
I had already built working versions of Espalier and Taproot before I started using AI tools. Once I did, they added rocket fuel to my ideas. They started writing the tests I never had time to write myself, and they helped me reengineer the playground. That's when things really started taking off.
The payoff came when the AI tools started working on Taproot (opens in a new tab), the web publishing platform I'm building. By then every Espalier component had a description, examples, and a machine-readable list of its attributes and events. The AI tools building Taproot's screens had all of that to work from instead of guessing.

I've written about why documentation-first development helped us build with AI before. This piece is about the timing: what it looked like to build the documentation playground while the library was still young, and what it caught.
How early was "before it was finished"?
Not before the first component. Espalier's history starts in February 2025, and it used Storybook at first. In September 2025 I removed Storybook and set up an Eleventy site, starting with the button's documentation. At that point the library had 32 custom elements. Today it has 75, and its first public release didn't ship until June 2026.
So more than half of Espalier's components were written after the documentation site existed. Over the next few weeks I moved component after component to documentation generated from comments: the button, the dialog, the box, and the input, whose commit message was simply "documented input entirely from comments." In February 2026 we deleted about 30 hand-written component pages and generated all of them from the source. That tooling later moved into its own package, WTFM (opens in a new tab).
Every example is a manual test
Here's part of the comment on Espalier's single-choice picker. Our early CLAUDE.md pointed AI tools at this component as the reference for how to write examples:
/**
* Selects one option from a list. For selecting multiple options, see
* [esp-pick-some](/components/pickers/pick-some/).
*
* ```html
* <esp-box>
* <esp-form-item label="Pick a fruit">
* <esp-pick-one>
* <esp-picker-item text="Apple" value="apple" icon="apple"></esp-picker-item>
* <esp-picker-item text="Cherry" value="cherry" icon="cherry"></esp-picker-item>
* <esp-picker-item text="Lemon" value="lemon" icon="lemon"></esp-picker-item>
* </esp-pick-one>
* </esp-form-item>
* </esp-box>
* ```
*
* ### Initial state
*
* Set the initially selected item using the `selected` attribute
* on the `esp-picker-item`:
* ...
*/Read that as a test plan and it works surprisingly well. Each heading is a scenario (initial state, variable-height items, and so on), and each fenced example is the setup. On the generated page, every fence turns into a live demo. Open the page, look at the "Initial state" demo, and Lemon should already be selected. If it isn't, something is broken, and the page tells you exactly which promise the component didn't keep.
The documentation guide we wrote in February 2026 put the process plainly: a component was tested by interacting with it on its own documentation page. From September 2025 until February 2026, Espalier had no automated tests at all. The generated site was the test surface. That changed when the AI tools arrived: the reengineered playground, with its generated controls, landed in February 2026, and the first automated tests followed the next day.
The playground writes its own controls
When a demo has exactly one instance of a component, WTFM adds an Attributes tab and an Event Log tab under it. Nobody writes those controls. WTFM reads the Custom Elements Manifest, the JSON description of the library's public interface that the analyzer builds from the same comments, and picks a control from each attribute's type:
private classifyAttrType(attr: CemAttribute): "boolean" | "enum" | "string" {
const t = (attr.type ?? "").trim();
if (t === "boolean") return "boolean";
if (t.includes("|") && (t.includes('"') || t.includes("'"))) return "enum";
return "string";
}A boolean gets a checkbox, a union of string literals gets a pick list, and everything else gets a text box. Every event the comment documents gets logged when it fires. The playground itself is built out of Espalier's tabs, checkboxes, pickers and inputs, so using the documentation site exercised the library twice.
There's a limit worth knowing about. Only attributes get live controls. Slots, CSS parts and CSS custom properties show up as reference tables, and you test those through the written examples.
What the documentation site caught
Because I was using the generated pages every day, problems showed up there first. A few from the record:
A demo on the details component called a helper the documentation runtime doesn't provide, which broke the demo on the published page. The fix added an architecture test that fails the build when a demo calls a helper that won't exist, instead of waiting for someone to open the page and notice.
On the forms guide, two context examples that were supposed to look different looked identical, and a focused field had unreadable contrast. Both were real styling bugs, found by looking at the page.
The toaster showed duplicate toasts on component pages, because each demo on a page creates its own page container. That's a real situation a product can hit, and the documentation site hit it first.
Claude picked a background color for the playground that didn't exist in the design system. The fix was small, but it led us to generate a token manifest, a machine-readable list of every design token with its description, plus a guide telling AI tools to use it.
That last one is the pattern I care about most. When an AI tool guessed wrong, the answer was more documentation it could read, generated from the code so it couldn't fall behind.
How it shaped what the AI tools wrote
Once the comments were the source of the documentation site, the instructions for AI tools could be short and specific. Espalier's first CLAUDE.md, in March 2026, opened with this:
This project uses documentation-driven design via WTFM. Demo pages in
public/components/are generated from JSDoc comments on component classes.
It went on to tell AI tools never to edit the generated pages, and to write examples in the component's comment block instead, pointing at the picker above as the model.
Today the canonical instructions live in AGENTS.md, which says examples belong in the class's JSDoc and names custom-elements.json as the source of truth for component APIs. Claude Code and Codex review each other's work there, and a reviewer can open the same generated page I do.
The current manifest describes 74 components with 690 attributes and 90 events, and about 180 runnable examples live in component comments. Every component has a description. I can't tell you how much faster any of that made us, because we never measured it.
Taproot uses the documentation as a test
Taproot's frontend is built from Espalier components, so the generated manifest does a second job there. One of Taproot's contract tests reads Espalier's custom-elements.json and its type declarations, then checks every Espalier attribute Taproot's code uses:
/**
* Architectural contract: every Espalier attribute Taproot uses exists
* on that component, and every literal value passed to an enum-typed
* attribute is a member of that attribute's declared union.
*
* The bug class this catches in one shot:
* <esp-status-indicator placement="above"> ← invalid; allowed set
* is { top, bottom, left, right }
*/An AI tool that invents an attribute value fails the build instead of shipping a broken screen. A similar test checks that every design token Taproot references exists in Espalier's token manifest. Neither test needs updating when Espalier adds a component, because both read whatever the latest release documents.
Taproot also generates documentation for its own page components the same way, with the same WTFM pipeline and a check that fails when a component is missing from the manifest.
The same idea runs the CLI I write this site with
I write this website through Taproot's command-line tool, taproot-site, and so do the AI tools that help me. Its offline help is the documentation they read before writing a page. It's generated from the same schema declarations the validator uses, so the help and the validator describe the same components. The task that created it says so directly: don't maintain a second hand-written vocabulary that can drift from validation.
Two more details keep it honest. Every help schema has to accept its own example through the real validator, and the API only accepts the latest CLI release, so the help on my machine always matches the server. The help reference has been revised 58 times in about three months. When I published a post about the tulips at RoozenGaarde this week, the tool reported which photos were missing descriptions before anything was staged, because that rule is now part of what it documents and checks.
What we got wrong
Some of the early claims went too far. Our first philosophy guide said that if a component works in the docs, it works in the product, and that we rejected isolated unit tests for visual components. That wasn't true for long. A working example covers only the situation it shows. Espalier now has about 158 Vitest test files and nearly a hundred browser fixtures, and in October 2026 we rewrote the guide to take out the inflated claims. (I also wrote about the opposite problem, tests that weren't earning their keep.)
The checks around the documentation are narrower than they sound, too. Continuous integration verifies that every component has its page metadata and that its events are documented. It doesn't verify that a component has a description or an example. We have those because the generated site made their absence obvious, not because a rule forces them.
And building a documentation tool is real work. WTFM has its own code, tests and releases, and it's one more package to keep current.
If you want to try it
You don't need WTFM to get most of this. If you build web components, run the Custom Elements Manifest analyzer over your JSDoc and put the examples in the comments. Generate a page per component, even a plain one, and make that page the first place you go when you test. Then tell your AI tools where the examples live and where the generated manifest is, and check their work on the page instead of in the diff.