The problem
- -Design produces mockups; engineering translates them into code; drift appears in production; humans negotiate the gap.
- -AI agents industrialize the guessing: they fill ambiguity confidently and ship those guesses at inference speed.
- -Drift accumulates faster than human review can catch it. Traditional answers — style guides, code review, design QA — assume a human-paced loop and don’t compose with agent-paced output.
The contract
- -Components — typed primitives with declared props and APIs; the consuming app invokes them through a structured interface.
- -Preview environment — every component in every supported state, rendered visually. The agreement layer between humans and the canonical reference for “what good looks like.”
- -Component index — a machine-readable manifest auto-generated from component sources. The agent reads this to know what’s available without reading every file.
- -Agent skill file — implementation rules shipped into the consuming repo. Tells the agent what conventions to follow, what raw markup is forbidden, and what verification command to run.
- -Component-usage audit — a static analyzer that walks the consuming app’s templates and verifies every invocation against the index. The agent runs it as the success condition of any UI work.
The architecture
- -The design system ships as a versioned package containing all five artifacts.
- -Engineering installs the package; their AI agent reads the contract and writes UI code that is structurally guaranteed to match the design system.
- -The agent’s loop: read the index → satisfy the skill’s rules → run the audit → fix what it flags → ship. Every step is mechanical. Where there was ambiguity, there is now a binary check.
- -No clarifying questions, no Slack threads, no late-stage drift. The handoff is a file, not a conversation.
