AdesignsystemthatAIagentsfollow

In the design system for a legal product I built with AI, a team of 13 agents applied the system, one agent per screen. Zero new classes were created. The 53 blockers they reported all converged on a single shared components file. What made it work wasn’t the component. It was the rule being written in the place the agent reads before touching the interface.

The lesson comes from earlier. Eduzz isn’t one product, it’s an ecosystem: checkout, members area, creator dashboard, marketing tools, apps. Each one was born at a different time, with a different team, and carried its own choices for buttons, color, and spacing. For users, every part looked like it came from a different company. For the people building it, it meant the same component being designed and implemented over and over.

I worked as the product designer on a project I delivered for Eduzz: Houston, the design system created to fix that. The first decision wasn’t about components. Before designing anything, the project aligned with Eduzz’s team on why the system existed, and wrote down six goals: reduce time to launch, make global maintenance easier, standardize consistency, support product, engineering, and design decisions, value learning, and provide an ecosystem of components. Those goals became the first page of the documentation and the criterion for what got in. Every component had to serve at least one of them.

The lesson I took away wasn’t the prettiest component. It was that a design system is an internal product, and its user is the team. After Houston, I applied this to much smaller systems, in products I built with AI agents. The scale changed, and so did the user: the system’s consumer became, in large part, an agent writing screens. An agent doesn’t ask around in the hallway. It reads what’s written and follows it. If the rule isn’t there, it makes one up. Houston’s rules still held, with one more requirement: be where the AI reads.

Goals as a filter

A system without a goal grows by accumulation. Every request becomes a component, and soon there are three card variants and nobody knows which one to use.

In Houston, the goals worked as a filter: a request that didn’t serve any of the six didn’t get in, and there was a written reason to say so. In Glint, the same role was played by a design contract, a rules file every agent read before touching the interface. One of the rules was about meaning, not aesthetics: the primary color means action and navigation; the secondary one, identity and data. Applied in the shared components, that rule held on every screen without anyone having to remember it.

Layers: where each decision lives

Houston was organized in four layers. It’s the org chart that matters most in a design system, because it tells you where a change happens.

• Houston
  • Global tokenscolor, typography, spacing, radius, shadow
  • Brand tokensone palette per product, same structure
  • Componentsbuttons, forms, feedback, navigation
  • Contentwriting and voice guidelines

Tokens are what make the layering actionable. When color and spacing are named variables, a change happens in one place and propagates. I saw this work almost brutally well in my own products:

• In Glint, the dark-by-default design system has about 17 components and was applied to roughly 50 screens. The rule was never to hard-code a color, only tokens, and the light and dark themes come from the same variables.
• In Kitnets, the visual design went through two redesigns. The second swapped a generic indigo for a warm editorial tone, with serif headings and the primary action in black. Because everything was a variable, the change reached every screen at once, and tweaking the shade of orange became a one-line change.

Governance: who decides

Nathan Curtis, of EightShapes, described team models that became a reference, among them centralized and federated. Many teams end up with a hybrid.

	Centralized	Federated	Hybrid
Who maintains it	A dedicated team	People from product teams, part-time	A small core team, with contributors from the products
Strength	Consistency and fast decisions	Close to real needs	Core curation combined with product knowledge
Weakness	Becomes a bottleneck and drifts away from the products	Product priorities always win	Requires a clear contribution process

What my projects show is the simplest model: one maintainer and teams that consume. In Houston, the maintainer was Eduzz’s design system team; the consumers, the product teams across the ecosystem. In my own products, the maintainer was me, and the consumers were the agents implementing the screens, one per screen, with file boundaries that never crossed.

• System maintainerdecides what gets in, based on the goals
  • What they maintain
    • Tokens and components
    • Docs with the same tabs
    • Written rules contract
  • Who consumes
    • Product teamsin Houston
    • Agents building screensin my own products
  • Contribution pathrecommended: problem, triage, design, code, docs

With agents as consumers, one thing becomes obvious: the system only gets followed if the rule is written where the consumer reads. That’s what happened in the legal product, with the 13 agents. The file boundary didn’t just prevent collisions: it produced a report of where the system fell short, because every blocker pointed to the same place.

Rules written where the AI reads

A team of people tolerates incomplete documentation. Someone asks, someone remembers, someone looks at the screen next door. An agent does none of that. Whatever isn’t written along its path doesn’t exist.

In my products, that turned into three habits:

• A contract before the screen. In Glint, a rules file every agent read before touching the interface. It stated the meaning of the colors, not just their values: the primary is action and navigation; the secondary, identity and data.
• A change rule that’s short and absolute. In Kitnets, nothing gets renamed, only values and additions. It fits in one line, and an agent can obey it without interpreting.
• The traps next to the component. In the legal product, every dangerous class was discovered through a broken screen. Today I write the “don’t use it like this” right beside the “use it like this.”

The same goes for anyone automating an operation with AI. The AI only follows the business rule that’s written where it reads. The rest it fills in its own way.

Contribution: start with the problem

If anyone can add components, the system becomes a junk drawer. If nobody can, it becomes a bottleneck. The contribution process is the middle ground.

1. 01Proposal

   The problem and the screens where it shows up, not a finished component.

2. 02Triage

   Does something already exist? Which goal does it serve? Does it show up in more than one product?

3. 03Design

   Variants, states, anatomy, and accessibility.

4. 04Code

   Implementation, tests, and API review.

5. 05Documentation

   Usage, when not to use it, examples. Without this, it does not ship.

The “more than one product” criterion is the one I use most: a pattern only one screen uses can stay local. When a second screen needs it, it’s time to promote it.

Change without breaking things

Teams only trust the system if updates are predictable. The common pattern is semantic versioning: fixes, backward-compatible additions, and breaking changes, with a changelog written for humans, deprecation before removal, and a migration guide.

In a small system, the version number matters less than the discipline. In Kitnets, the design system rule was nothing gets renamed, only values and additions. In one of the redesigns, the page header started rendering the new highlight component internally, without changing its interface. All 22 pages got the new header from a change to one file, and none of them broke.

Docs with the same tabs

In Houston, each component page has the tabs Design, Usage, Code, Accessibility, and How to test. Whether you come from design or engineering, you find the same source of truth. When the two read different pages, each one builds their own version of the component.

The documentation is also where the traps live, and they need to be written down. In the legal product’s design system, I paid for every one of them:

• A class called .pagina (page) was invisible by default, because it worked as a router in the system’s catalog. Using it on a real screen left the screen blank, with no error at all.
• The table class forced all-caps headers. Applied to agent-generated text, it distorted the content; it needed its own variant.
• One class had three references in the code and had never been defined.

Generic names like these invite misuse. A class name is documentation, and one that looks like it’s for everything will get used for everything.

Adoption metrics

If it’s a product, it needs metrics, and they should measure use, not output:

• Coverage: how many screens use the system.
• Deviations: loose values instead of tokens. In Kitnets, a sweep with scanning agents found 42 deviations after the redesign, from stray headings to hard-coded colors.
• Leftovers from the old pattern: after the Kitnets redesign, the definition of done included the old color not appearing anywhere in the shipped code.
• Recurring questions and contribution time: if it takes too long, teams build around the system.

“Number of components” is left out on purpose. Lots of components with little adoption is a catalog, not a system.

What I’d do differently

• Write the traps into the system itself. In the legal product, each one was discovered through a broken screen. A “don’t use it like this” list in the docs would have saved all of them.
• Decide where the system’s boundary is. In Kitnets, the public website was left out of the second redesign because it didn’t consume the styles from the component package. A system that doesn’t cover every surface of the product leaves one of them looking like a different company, which is exactly the problem Houston existed to solve.
• Validate the direction before the rollout. In Kitnets, I myself rejected the first new header, the one with an icon, after seeing it applied. Since it was a single component, rolling back was cheap; in a system without that layer, it would have meant rework on every screen.

Design-system-as-product checklist

• Are the system’s users, people or agents, identified?
• Are there written goals, used as the criterion for what gets in?
• Are the layers (global tokens, brand tokens, components, content) separated?
• Is there a clear maintainer and a contribution path that starts with the problem?
• Do changes follow a rule that doesn’t break existing consumers?
• Do design and code document each component on the same page, with the same tabs?
• Are the traps and dangerous names written down?
• Do the metrics measure adoption and deviation, not component count?

A design system nobody consults doesn’t standardize anything. The work starts when a component ships, because that’s when someone, person or agent, tries to use it.