AI Design System

Opening screen. The title reads: A design system an agent can build from. Underneath it: I tested a design system by handing it to an agent and asking for a screen nobody had designed. I counted every rule the output broke, wrote up where and why, and rebuilt the system so those rules reach the build itself. The credits line: UX Designer, logistics operations, 7 days, controlled build test, 3 runs, built with Figma and Claude.

Video introduction. The heading reads: The whole case study, in 2:34. Underneath it: Same agent, same prompt, same screen. Only the system changed, and the violations dropped from 31 to 8. A note in Turkish says to click CC in the player for Turkish subtitles.

Fig. 01, the experiment, drawn as two rows. In the top row, system v1, written for people, is read by an agent that builds a shipment detail screen: 31 violations, run A. In the bottom row, system v2, written for both, goes through the same agent to the same screen: 8 violations, run C. One prompt sits between them, unchanged in both runs. The agent, the prompt and the target screen are held constant, so any change in the count belongs to the system. Below the diagram, the headline figures: 31 on system v1, 8 on system v2, a change of minus 23.

Section 01, Context. The heading reads: the rules were in a place the build never reached. I build with an agent every day and it does not read documentation the way a person does. It reads the files I hand it, and where those files are silent it invents something plausible. A rule that lives in a usage page or a Figma description is a rule it cannot follow. The claim I set out to test: rules an agent can read from a file should be followed more often than rules a person retypes into every request.

Section 03, System v1. Six colour cards, each with a use and a boundary written beside it. status.critical #A32219 for a cancelled or stopped shipment, never for a delay. status.delayed #9A5308 for later than planned, never for a cancellation. status.review #5A3FA0 once someone has taken the exception. status.cleared #0E6B52 once it is resolved. status.unknown #6B7280 when no tracking data came in. action.primary #14507F for the one action per view, never for a status.

The token chain in version one, drawn as three open layers: primitive, semantic, component. All three are reachable, so a component can bind to the raw colour and still look right. Beside it the six neutrals, from surface.default through to text.muted, and the naming convention: category.step for primitives, purpose.meaning for semantic tokens, component.variant.property for component tokens.

Foundations F.01 and F.02. Spacing runs in seven steps with nothing between them: 4, 8, 12, 16, 24, 32, 48. Type is one family at four sizes, each role named for the job it does rather than the size it is. heading.section 20/600, one per view. body.default 16/400, the reason a row exists. body.small 14/400, never load bearing. label.meta 12/400 for identifiers and routes.

Foundations F.03 and F.04. Radius has three values tied to the size of the surface: 6 for the smallest, 10 for anything a dispatcher clicks or scans down a list, 14 for containers that hold other components. Elevation has three levels. Flat sits in the page with a hairline border. Raised opens over the list while the list stays usable behind it. Overlay blocks the screen and is kept for a decision that cannot be undone. If a value is not on one of these scales it does not exist in the system.

Components C.01 and C.02. The status badge has five variants, one per status colour, and every one carries a word as well as a colour, because a coloured dot on its own is not a status. The table row has three states and three columns: identifier, route, status. Status sits last so a full list can be scanned down one edge, and the loading row keeps the same three columns so nothing shifts when the data lands.

Components C.03 and C.04. The filter chip has three states and carries selection through fill and weight together, never colour alone. The button has three levels and four states. One primary per view, and a disabled state that stays legible. That limit is written into the system rather than left to taste.

Components C.05 and C.06. The empty state says why the view is empty and what to do next, because an illustration on its own is not an empty state. The panel header has four slots: title, meta, a status slot and one action slot. Status shows here as well as in the list so it survives the jump between the two. Empty, loading and disabled are all defined in version one.

Fig. 02, the exceptions list, built from system v1. A dispatcher view with a dark navigation rail, a search bar, four filter chips and a table of five stalled shipments. Each row shows the shipment number, the route and the reason, an ETA and a status badge: critical, in review, delayed, unknown, cleared. Every piece of state on this screen comes from the six specified components. The shell around them sits outside the audited set.

The usage page from version one. A status badge rule in full sentences, sitting beside the component it governs, with a Do column and an Avoid column. Pair the colour with the status word. Use Critical only for a cancelled or stopped shipment. Move to In review as soon as someone takes the exception. The rule is complete and correct, and it is in the one place the agent was never handed. Below it, where version one fails: the rules sit beside the components instead of inside them, and all three token layers stay open.

Section 04, Method. Three runs and one variable between them, laid out in a table. Run A: version one, a three line prompt with no rules in it. Run B: version one, a long prompt written to make up for the system. Run C: version two, run A's prompt character for character. All three ask the same model in a clean session for the same shipment detail screen. Version two is built from what run A breaks, not from what run B needed.

The run C box and the prompt used in runs A and C. If the prompt moved too, any improvement could be credited to better prompting and the system would have proved nothing. The prompt in full: here is our design system, build the shipment detail screen for the exceptions tool, desktop 1440 wide, return it as HTML and CSS.

The run B prompt in full: a role, a task, the six status tokens with their meanings, a never list covering literal values, two primary buttons in one view, colour with no word and reinvented components, a required list covering empty loading and disabled states, contrast at or above 4.5:1 and spacing from the 4 to 48 scale, and a self check at the end. This is the best prompt I can write. It holds for one screen, and every rule has to be typed again for the next one.

The scoring instrument, six rules written before the first run. DS.01 Token: a literal value where a token exists, or a component bound to a raw primitive instead of the semantic name above it. DS.02 Component: a new element invented where a library component already covers the case. DS.03 Meaning: a status colour used for the wrong meaning. DS.04 Scale: spacing, type or radius set outside the defined scale. DS.05 State: an empty, loading or disabled state left out where the system defines one. DS.06 Accessibility: contrast or target size below the stated threshold.

How a violation is counted, four rules. One per instance, not per kind, so a literal hex in three places is three violations. One element can break two rules and is counted under both. Only what the system defines is counted, so the application shell is not scored. Everything is counted on the raw output before any correction, twice, by a script and by hand, and the two are reconciled before a number reaches the page. Below it, what would disprove the whole thing: if run C does not count lower than run A the change did nothing, and if run B counts as low as run C a good prompt is enough on its own.

Section 05, Findings. Two of the six rules broken. Version one produced a screen that looked correct: right layout, right hierarchy, the right status on the right shipment, every state present. Four rules held. Nothing on the screen looks wrong, which is why the violations took a file to find.

Fig. 03, the run A output, marked and uncorrected. The shipment detail screen the agent built from version one, with dashed outlines on four places the count found violations: the primary action, the event filter chips, the timeline and the secondary buttons. I gave the agent the shell, and everything inside the content area came back from run A. Four places are marked here and thirty one violations were counted in the file.

Four excerpts from the CSS run A actually returned. The primary action, with two colours invented on the spot for hover and active. The chip, reaching past text.muted to the primitive and setting 13px type the scale does not publish. The timeline, off the spacing scale at 3px and 2px and off the type scale at 13px. The secondary buttons, with three more bindings to the primitive. Every one of these renders correctly and a designer reviewing the screenshot would sign it off. The breakage is only in the file.

The two findings. DS.01, twenty two violations, colour taken from the wrong name: seventeen bindings reached past a semantic token to the raw primitive underneath, and five were literal colour values written straight into the stylesheet, four of them for hover and active states the system never specified and one inside a loading shimmer. DS.04, nine violations, values off the published scales: seven declarations set type at 13px where the scale publishes 12, 14, 16 and 20, and two set spacing at 3px and 2px where the scale starts at 4. Four rules held. No component was reinvented, no status colour carried the wrong meaning, every defined state was present, and nothing fell below 4.5:1.

Section 06, Changes. Two rules failed and four things changed. Run A broke DS.01 and DS.04, and changes 01 and 02 answer those. Change 03 covers the rules that held so they keep holding, and change 04 is how any of it reaches the agent. No rule was rewritten and nothing was tidied up in passing.

The four changes from version one to version two. 01, closed the raw palette, answering DS.01: the primitives are sealed, so the only name a component can reach is the one the rule is attached to. 02, turned advice into limits, answering DS.01 and DS.04: version one wrote its limits under a heading that said Avoid, version two states them as absolutes attached to the thing they constrain. 03, made every rule checkable, which guards DS.02, DS.05 and DS.06: each component now carries a short list of conditions that decide whether it was used correctly. 04, published it twice: the component library stays where designers work, and the same rules also ship as tokens.json and DESIGN.md for the agent to read.

The tokens.json excerpt, three blocks. Version one chains its own tokens correctly, but nothing marks the primitive off limits, so run A could legally bind a badge background straight to the raw hex. Version two seals the primitive with com.ship4all.private and the rule travels with the name: a description reading shipment cancelled or stopped, a never list reading delay, warning, overdue, and a pairsWith rule reading a visible label, never colour alone. Written in the W3C design tokens format, where anything the spec has no field for goes under extensions with a namespace.

The DESIGN.md excerpt and Fig. 04. The acceptance list for the status badge: every variant resolves through status.*, never colour.*; the badge shows its status word, not a dot alone; delayed and critical do not resolve to the same value; one shipment shows one variant in the list and in the detail header; the label on fill measures 4.5:1 or better. Six components each carry a list like this, and not one rule in it is new. Fig. 04 shows the same set of rules published in two forms: a component library with variants, states and usage pages that people read, and tokens.json plus DESIGN.md carrying value, use, never and accept when, which is what the agent reads.

Section 07, Result. Version two cut the count from 31 to 8. Every output counted against the six rules, twice, on the raw screen. Lower is better, and zero was never the target, because some of what a screen gets wrong is not something a system can state in advance.

Fig. 05, the run C output. The same shipment detail screen from the same three line request, built on version two. Every colour on it resolves through a name that carries its own rule. Set against Fig. 03: the request did not change, the file the agent read did.

The count, violations per run by rule. DS.01 Token: 22, 0, 0, a change of minus 22. DS.02 Component, DS.03 Meaning, DS.05 State and DS.06 Accessibility: zero across all three runs. DS.04 Scale: 9, 0, 8, a change of minus 1. Total: 31 for run A, 0 for run B, 8 for run C, a change of minus 23. Run B reads zero because its prompt restates every rule in the system and asks the agent to audit itself against them. What the column does not show is the cost. Run B also built less: 232 style declarations against run A's 338 and run C's 310, which works out at 9.2 violations per hundred declarations for run A, 2.6 for run C and 0 for run B.

How to read the table. A against C, 31 to 8: the system did the work. Same prompt, same agent, same screen, and twenty three violations went because the file changed, all twenty two colour violations among them. B against C, 0 to 8: the long prompt still won, which is the result I did not want. The system closed most of the gap and not all of it. Still broken: every violation left in run C is DS.04, the scale. The rules that moved were the ones written inside the token, beside the value the agent reads. The scale is still a list in the documentation, attached to nothing.

Section 08, working with the agent, and Fig. 06. An agent produced most of what this project shipped. The loop runs in four steps: I specify meaning and boundary, the agent builds the screen in one pass, I count six rules twice, I decide to keep, overrule or change. One step of four belongs to the agent. The return path is the rule this project tested: a failure is answered by changing the file the agent reads, not the sentence I type.

The division of work, three columns. I directed six things: the scope and the six components, what each status colour means and where its boundary sits, the six violation rules written before the first run, how a violation is counted, the prompt held identical between runs A and C, and the reconciliation of the two counts. The agent produced five: the component library from my specification, three screens one per run, a first draft of tokens.json and DESIGN.md, candidate token names, and an independent audit of each output. I overruled three: its first diagnosis, which blamed the token names rather than the open layers; a status badge that took its colour from the action token, which the system forbids; and its own audit, which counted spacing that was already on the scale as a token violation and read the keyword transparent as a colour.

Section 09, Judgment. Three decisions no specification makes. Where critical ends and delayed begins: a customs hold stops a shipment, a driver rest window does not, and nothing in the data draws that line. Whether an absence is a state: a shipment with no signal is not a shipment with a known problem, so Unknown got a token of its own. What counts as a violation: the agent audited its own output and disagreed with me twice, and settling it meant deciding what the rule covers, which is not something the count does.

Closing and verdict. What is worth keeping is which rules survived, more than the twenty three violations that went. Every rule attached to a token was followed. Every rule left as a sentence was ignored in both versions, by an agent that had just read it. What I would change next: the scale is still published as a list and enforced by nothing, so the next version would seal the numbers behind named tokens, the same move that worked for colour. The verdict: an agent produces faster than a team can review, and it built the first of these screens wrong in ways nothing on the surface showed. What it cannot do is decide. Direction has to live somewhere, and a prompt is the wrong place, because a prompt is written once per screen while a system is read on every build.

OPEN TO WORK

Looking for a UX or Product Designer?

Let's talk.

Open to full time UX and Product Design roles, and ready to relocate.

Request my CV

sezgunumutcan@gmail.com

LinkedIn

©2026 Umutcan Sezgun. All Rights Reserved.

Google Sites

Report abuse