Component scaffolding

Not built

Described, not implemented. This page is the specification worth reviewing first.

What it would do

Take a component contract — props, states, accessible behaviour, tokens consumed — and emit the mechanical parts:

• the component skeleton, consuming the named tokens and nothing else;
• one story per contracted state, which is the part most worth automating because it is the part most often skipped;
• interaction test stubs asserting the declared keyboard model and announcements;
• the accessibility scan wiring;
• the documentation page, generated from the same source as the code.

Why the contract has to come first

Scaffolding from a description produces a plausible component. Scaffolding from a contract produces one whose gaps are visible: nine states in the contract means nine stories, and a state that was never designed shows up as a story nobody can fill.

That inversion is the entire value. Without it, the generator is a faster way to produce components with only their happy state — which is the problem the library exists to solve, now at higher throughput.

What it must not decide

What the contract says. Which states exist comes from example mapping; what they look like comes from the design system; which props exist is an API design conversation between the library and its consumers.

A generator that infers a contract from a screenshot has skipped every one of those, and produced something with the shape of an agreement and none of the agreement.

Whether a new component is needed at all. The most valuable answer to “scaffold me a card with an image” is often the library already has one. A generator that cannot say that makes the drift problem worse at speed.

How its output would be reviewed

Against the contract, not against taste:

• Does it consume tokens, with no raw values?
• Is there a story for every contracted state, and does each one render?
• Does it implement the declared role, name and keyboard model?
• Do the generated interaction tests actually fail when the behaviour is removed?

That last check is the one to insist on. A generated test that passes against a gutted implementation is worse than no test, and it is the characteristic failure of generated test suites.