Horizontal · Design systems
Guardrails, real cases and checklists for building design-system components in Figma with an AI agent. Taken from two enterprise design-system builds and written to apply to any project.
The short version
The agent reads, counts, measures and repeats. A designer decides what a component is and what goes to the client. Every rule below exists because skipping it cost real time once.
01 · How to use this
What carries over and what doesn't
The method, the rules and the list of mistakes work on any project. Component details, token names and brand values don't. Only the shape of those carries over.
01 · How to use this · cont.
| Term | Means |
|---|---|
| Token | A named value (colour, spacing, radius, type size) that components point at instead of a raw number |
| Variant | One version of a component, such as Desktop / Hover / Arabic. A set holds all of them. |
| Property | A setting a designer or author changes on a component: a toggle, text, a swap or a variant choice |
| Atom | A small shared part reused inside components: button, input, icon button |
| Instance | A copy of a component placed somewhere. It follows the main component unless overridden. |
| Census | A count of where something is used, in the design file or on live pages |
| Live | The production site or product as the browser renders it today |
| Agent | The AI working in the terminal with access to Figma, the browser and the project notes |
02 · Guardrails
02 · Guardrails · cont.
03 · Case files
A full set, its parts, 24 tokens and the docs were built for the wrong component. The reference image showed the component next to it. The doubt was noted on day one, then built past.
Identity is a gate. If it's unclear, stop and ask.
15 of 25 banner variants carried a 30% black wash copied from a design reference. Live has no overlay. It went unnoticed for about 10 weeks, until QA raised a ticket.
Check every overlay, shadow and effect against live CSS.
Live had no truncation. The migration sandbox did. Two people were right about two different builds.
Say which build every defect refers to: live, sandbox or design.
A spec table listed where a component may be authored. It was read as where it is used, and scope decisions were made from it.
Count real pages on live before deciding variants.
03 · Case files · cont.
A shared menu was dropped into a filter panel at its own default size: 264 wide against 335 on live, with wrong padding and row height. 5 of 16 ticketed defects came from this.
Reusing an atom is right. Reusing its default size isn't a decision. Measure live.
An accessibility note matched the build. The agent rewrote it from a remembered standard and got both values wrong. The client's reviewer quoted the original.
Measure first, then write the note.
A set shipped with 24 variants, but only 6 looked different. The rest were copies that did nothing.
Before shipping a variant axis, compare renders. If two variants look the same, merge them.
A Show overlay toggle was declared and documented, but 7 overlay layers weren't linked to it. Authors couldn't turn them off.
For every toggle, check every layer it should control is linked to it.
03 · Case files · cont.
A fix compared a gradient stop (0.6) with live's painted peak (0.64) and missed the layer's 80% opacity. The developer built the design exactly, so the bug shipped.
Compare what is painted: stop alpha × layer opacity.
Browser dev tools showed 21 against Figma's 20. The CSS border sits outside the padding; Figma's stroke sits inside. The values were the same.
Compare the CSS classes, not the dev-tools box readout.
A count of where a shared part was used found 11 instances. There were 17. Instances nested inside other components weren't counted.
Count nested instances separately before editing anything shared.
A hover underline was fine at tablet and mobile but clipped at desktop, where the target was shorter.
Check every state at every breakpoint, not just the default size.
03 · Case files · cont.
Brand fonts were installed on the Mac, but the agent's Figma connection reads the server's font list. Every text edit failed. Only the browser editor could see local fonts.
On day one, test loading a font before any text work.
The agent typed a plugin name into Figma. The keystrokes ran as shortcuts and dropped a rectangle into a documentation table.
Drive Figma with clicks and the API only. Never send keystrokes to the canvas.
The original component sets were moved and edited during a template change. Instances on other pages changed with them, and the old positions hadn't been recorded.
Copy, then change the copy. Record the original first.
The project notes file grew past the agent's read limit, so the end of it silently stopped loading. The rules were there, but nobody was reading them.
Keep a short index plus one file per topic. Keep the index lines short.
04 · Checklists
04 · Checklists · cont.
04 · Checklists · cont.
05 · Who decides
| Agent | Person |
|---|---|
| Reads every variant, token and binding in the file | Decides what a component is when sources disagree |
| Measures the live site at each breakpoint and state | Decides whether to match live or improve on it |
| Counts usage across live pages | Signs off the variant model and count |
| Makes repeated edits across hundreds of nodes | Approves every deliberate difference from live |
| Calculates contrast ratios, grid maths and token checks | Checks the agent's numbers against the screen |
| Carries decisions between sessions in notes | Sends anything that goes to the client |
Take this seriously
The agent is just as confident when it's wrong. Its mistakes look plausible: a believable number measured from slightly the wrong place. The fix is to look at the screen and check where it measured.
06 · Setup & skills
| What | Why |
|---|---|
| Agent in the terminal | Notes, rules and skills are files on disk. They're versioned and handed over as a folder. |
| Figma connection with an edit seat | Reads and writes the design file |
| A real browser for live checks | CSS tells you what's set. Only a render shows how it looks. |
| Brand fonts reachable by the agent | Without them, nothing that touches text can be written (case 13) |
| Own token per person, stored outside the repo | Comments post as the token's owner, so tokens are never shared |
| Shared context repo with a secret scan on commit | The project's learning doesn't stay on one laptop |
Skills are just files
Each step is a skill saved in the repo. When something goes wrong, the fix goes into the skill, so the same mistake can't happen twice for anyone using the folder.
06 · Setup & skills · cont.
The method as three Claude skills. Each one is a folder with a SKILL.md. Claude picks it up when the task matches, or you call it by name.
| Skill | What it does | Download |
|---|---|---|
| ds-build-component | Builds one component through the gates and stops for sign-off. Includes the Figma API gotchas, live-capture playbook, build protocol and case files. | .zip |
| ds-learn | Captures what a session learned and files each lesson in one place: build rules into the build skill, tool gotchas into the pitfalls log, component facts into memory | .zip |
| ds-wrap-session | Closes a session: writes only what memory is missing, checks the index, prints a handoff the next session resumes from | .zip |
# Claude Code: unzip into your skills folder
unzip hztl-ds-skills.zip -d ~/.claude/skills/In the Claude app, upload each skill's own .zip under Settings › Capabilities › Skills.
The memory starts empty
The skills hold the method and anonymised cases only. No project's notes are included. The first ds-learn creates your project's memory/ folder.
07 · Starting a project
07 · Starting a project · cont.
Each of these answers removed a whole category of rework when we had it early, and caused one when we didn't.
| Question | What it settles |
|---|---|
| Which sites or products use each component? | The variant count, before anything is built |
| What can authors set in the CMS for each one? | Which options are real and which are invented |
| Is the goal to match live, or to refresh it? | Whether live or the new design wins in a conflict |
| How many brands, themes, languages and breakpoints? | The token structure and the size of every set |
| Who signs off, and on what? | Where a person has to decide, and how quickly |
| Where does feedback arrive, and in what form? | Screenshots in comments the agent can't read are handled up front |