Presenting new partner of the newsletter, QT Group. They are launching a webinar series for Designers. 📅 First Webinar : Nov 5 | 3PM CET
First one is called: Why Is It a Field of Its Own and How Qt Is Tackling the Most Complex Design Challenge

4 years ago I compiled my list of useful 🔗 design system metrics. Well, a lot of them are not useful anymore. Not just total number of components and detachments, but many others as well.

Historically, adoption was the only metric that mattered, but today I would focus more on getting proper design system evals.

We have to think about a new user. Agents read our docs every single time and we need to set up rules to see if they are doing good job or not.

How do you know if your design system works or if it is getting improved every month? How do you share with stakeholders the numbers that give you budget? If you do this right, you will be able to see your progress.

Which metrics from the list I kept

Number of Snowflakes:
How many one-off components you have? Not just in Figma, in code as well.

New Linter Warnings:
Are there new violations coming up? Trend should go down.

Accessibility Pass Rate:
What’s accessibility audit score?

Support Questions and Time to Answer:
Since getting help from AI agents, are you faster? How much time do you need to answer design system questions?

Time to Adopt a New Release:
How long does it take for product to run the latest version?

System-wide Change Effort:
How much time does it take to re-brand, add new subrand or just change tokens?

Interviews with Designers and Developers:
This one is oldie, but goldie. So simple, but very effective. You hear directly from design system users what they about it. Repeat twice a year.

Stop spending time with these metrics

These numbers can only go up, but that’s all you find out.

Total component count
The right number of components is when there is enough of them to cover for everything you need for building your products. Some systems can have 50, some 80, but having more is not a sign of success.

Installs and downloads as adoption
Number of npm downloads is just a number. What are people doing afterwards is important. Are they changing the code, adding more components? Ha, you don’t know.

Number of MCP calls
More MCP call doesn’t mean your agents are doing more work, maybe they are just confused.

Agents reporting their own success.
You have to be careful with “too much“ success. A lot of times it might look like everything goes smooth and only when you push back, you get a real answer. Have in mind what was you end goal with task or eval, so you can compare the results.

Update the meaning of these metrics

These metrics are still useful, but I adjusted them a bit.

Detach Rate:
How often are components detached? Are teams exploring new components or because the solution is not good enough. Imagine you have a multi-brand design system. The main one works great, but the number of detachments in other brands is significantly higher. What does this tell you? Maybe you did not think enough about surfaces, different icons, more complex components or just more elements.

Docs page views
Which pages are the most read? What are keywords people use when searching for something? Think about improving content, adding help, improving components, etc.

Adoption by Product:
Which products use the system, and are they using components the way they were designed to be used? What is the problem with the design system that some teams are not using it? Do they have an old code and they would need a lot of time to update it? Treat it as a health check.

Design and Code Parity:
Do your Figma components and coded components match in props, states and variants?

Trust Pulse:
Get answers from design system user. Ask them if they would still use the design system it if it was optional? On the other hand, you also need to rate (and adjust) the trust levels for the agents.

Contributions from other teams, suggestions from the AI
How many contributions do you get? What kind of them? Do agents (AI tools) give you suggestions for improvements? Do you accept them?

Time to First Component:
How long does it need to ship the first screen with the system? (human vs agent)

Lead Time Against a Baseline:
How much faster do teams ship with the system? Compare with a baseline or a team without it, or the number means nothing.

Overrides and Hard-coded Values:
How many style overrides and raw values sit in each product? This is your design and tech debt in one number.

UI Bugs per Product:
How many UI and consistency bugs are reported for each product? Track the trend.

Now add these to your report

Conformance by surface
How much of your product really uses your components and tokens?

Agent adherence pass rate
How often an agent builds something that follows your rules?

Cost per shippable output
How much you really pay for something you can ship?

Accessibility pass rate
How much of your UI passes accessibility checks? Is it improving?

Component friction list
Which components don't do their job?

Setting up evals

Have in mind that having metrics look over design system health is totally different than measuring ROI or measuring the quality of the output.

The main thing today is to know if the system makes the output better and better? That’s for both users, people and agents. The output needs to be the same quality whether a person or agent prompt it.

Now we need our most needed layers again: intent + implementation. Intent tells us why and how components are use, and implementation is everything that changes over time anyway. The model, tools, skills, tokens.

To test how everything works together, we set up evaluations. In short, we call them evals. If these were users, we would call it user testing.

An eval is some kind of the bridge. It’s a real task, tested through our tools, models, components, scored against your intent. For task we give points. When something changes, we run it again. And again.

How do you choose your evals?

First, go through past issues and challenges. Make a list.
Then write down what would hurt your production the most if an agent (or human) broke the rules/guidelines?

Create a script that will automate these tasks. You can also write a list of prompts. Run each task or prompt at least 3 times.

When you get a report, read it, check the code, check the outcomes and of course the look and feel.

The trick is to try with cheaper models as well, because in the end, you want to save the money and keep the speed.

You can start with 10-15 tasks only.

When you see costs going down, and pass rates up, you won’t need much math to show your design system is doing well.

Enjoy the weekend. 🙌

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

✨ Community gems ✨

My friend Justine Montgomery (ex Stripe) is hosting a new course on Maven and it is all about showing your AI skills in your design portfolio. It’s a 4-hour, hands-on workshop.

Learn more about metrics

🔗 Tanya Donska, Design system adoption metrics lie

🔗 Greg Sargent, Design system adoption metrics

🔗 Kyle Yang, Dayforce Figma analytics

🔗 Luis Ouriach, Design System “Adoption” is a Red Herring

🔗 Figma, Design systems 104: making metrics matter

🔗 zeroheight, From basic adoption to meaningful measurement

🔗 Gusto Engineering, Eval-driven design systems, part 2

🔗 Storybook, agent-eval PR #36110

More useful articles from me

Do you already have components like “approval prompt” or “tool call row”. Don’t worry, maybe you don’t need them. But I have a longer list of new emerging components. I gathered them by using the apps, through my design system directory on aidesign.guide, and by spotting them on Mobbin.

The full catalog has way more, and you can find them on my website AI DESIGN GUIDE 🔗Agentic UX patterns (unfortunately, I can’t add so many images to Substack).

PS. I have a beginner-friendly LIVE AI course for designers in 2 weeks.

Let’s check the patterns now.

Entry points

1. Sparkle ✨ menu

Confluence

2. Hybrid ⌘K palette

With one modal, you can search or jump to a tool or assistant.

Figma

Read more

Let’s kick off this post with a quick exercise. Open any SaaS dashboard. The look and feel is mostly as it was 10 years ago. When there is no data, you see a bunch of empty cards; with data, maybe a few more charts appear.

I also opened Mobbin for dashboards and compared them. Calendly, Shopify, Framer, Semrush, Mintlify, AirOps, Sweatpals. Although they are completely different products in different industries with different price points, they all have almost the same layout. That makes sense: when people spend more time in products, they learn the layout faster.

Well, a familiar layout is a kindness: it means a person can walk into a new product the way you walk into a stranger’s kitchen and still find the spoons. What troubles me is that content and blocks themselves are still stupid.

I’ve been working with design systems for more than 10 years. In that time, we have learned to name our colors properly, switch themes with a single toggle, and scale our decisions to different products faster. But with today’s technology, we still lack intent-based dashboards. These blocks do not know what they are for.

In this post, I will explain how I envision smarter products through implementing intent-based design systems. I also believe this approach is the future of building products.

A brief history of getting “default taste”

To understand sameness and AI slop (where everything looks vibe-coded ugly), we need to go back in history. Defaults are coming from popular UI kits and Claude.

In 2008, it was orange. jQuery shipped the orange theme, and many people simply reused it without modifying it.

In 2020, it was indigo-500 from Tailwind UI. Adam Wathan chose it, and at the time it felt fresh. Then the models read the internet, and the internet was full of Tailwind-ish sites, so they followed the logic. And yep, this is where violet vibe-coded thingies are coming from.

In 2026, it is beige. This is coming from Claude. I’m sure you’ve seen warm, beige backgrounds, italic serif hero, 2-color text.

But why does everything look the same? Because the model just uses the average of all the screens it has seen. Even longer prompts don’t help, because models will, either way, move to the next logical design decision (or trend). There is a more detailed technical description how these things work from Paul Bakaus on the link.

How to fight this? The first obvious thing people do is to create a bunch of markdown files with rules. “No purple gradients.” “Don’t use Inter.” But the problem will repeat with new trends. To skip generic, you need to create your own foundations and knowledge graph. And then turn that into a shareable artifact. It can be a virtual server or a shared repository.

Dashboards can’t think

Back to those dashboards from the intro. Now let’s check concrete situations. Let’s look at the empty cards first.

Mintlify shows 80% vs. previous. The number is correct, but the red color shows panic. In reality, you had five visitors last week and one this week. Nobody sensible would lose sleep over it.

Similar story with Xero, Klaviyo, and Calendly. Cards show the math behind it, but users still need to connect the dots. Does it matter? Do they need to worry? What to do next?

Also, empty screens could be way more helpful. Zero is not the news here. Show users “how to get to your first visitor” or where to explore more options, connect data, etc. Be intentional and think about all intents and then improve the user experience.

Enter the assistant era

Then came the AI boom, and products with a lot of data had (and still have) a huge advantage in making their products better and smarter.

What most of them did was introduce AI assistants. By clicking on the “stars icon,” the AI process started showing more comments about the numbers.

Shopify added Sidekick conversations. Xero added a button for “Get AI insights”.

So the blocks stayed exactly as they were, and the thinking went into a chat window beside them. It can feel like the product got smarter, but I expected it to give me concrete next steps: what can I improve? But these answers took forever, and usually they were not really helpful. Why? Lack of context.

Adding more context phase

So naturally, we gave context. More files. More folders. Just EVERYTHING we have phase. Like a worried parent packs a suitcase for every weather. This is not really helpful.

If you don’t know what you are looking for, you will not get any answers.

I tested this with a simple task, where an AI tool had to create a developer handoff for a button. I have a design system built on Shoelace. It had to go through 7 checks: sizes, allowed and banned variants, tokens, one primary button per screen, a confirm dialog if there is something to confirm, and slots.

Each model got the same task with three kinds of context:

→ file dump (everything I have)

→ facts only (deterministic)

→ facts + rules

I tested the prices on October 3, and you can compare them below.

How did it go?

Facts only was the worst. Yes, it knew when to use a specific variant, but it didn't follow the rules.

The docs dump did better (because the info was there somewhere); but it was the most expensive.

Facts + rules passed on every model (even on the cheapest DeepSeek). For example, for Opus, swapping the docs dump for facts + rules costs two-thirds less. Those aren’t facts about the component. They’re intent.

Intent as the most underused layer

I keep returning to one word: intent. With intent-based content, the cards would change based on the user’s needs. This means dashboards become personalized. Practically speaking, a manager wants to see different content than a designer. Intent can live at four levels, like the floors of a house:

1. Token intent. What a value is for.

2. Component intent. How and when a component should be used.

3. Pattern intent. How components work together, and why.

4. Screen intent. What a whole screen is for.

rule: one-primary-action
applies_to: screen
check: count(Button[variant=primary]) <= 1
severity: block
why: Two primary actions means nobody decided what matters.

Intent-based dashboards

This is the part that makes me want to stand on a chair.

When blocks carry their intent, the system can combine components and create a personalized dashboard. These rules would easily fix empty cards on Mintlify, Xero, and Calendly.

Almost none of these rules are about pixels. That’s the point of intent. You write it once, and then you review it over time (based on conversion rate, product decisions, and so on).

Now let’s check another example.

Let’s give an agent a library of blocks like that and another piece of intent: what is this person trying to decide?

Comparing the dashboard for a finance lead vs. a support lead would open the same product, but the cards would show different content. But it is still the same design system.

The goal is to set the limits in our design system, then let agents work within them.

Sure, things can go wrong. When the finance lead and the support lead see different layouts, they might get confused (especially in the same meeting). Some users might want to see the whole picture (“admin view”) and not just a personalized view. And layouts should not just jump around with every refresh. But dashboards are just part of the story. The same intent can shape every flow in a product: onboarding that skips things you already did, empty states that are based on where you came from, an error message based on the user intent, … That’s why we need to start treating intent layer not as an option, but as a default.

You can only enforce what you own

Here is the catch. A rule only works if your agent can read it.

The prompt isn’t where your work is, and this post from Thariq sums it up perfectly. Prompt is one thing, but your environment changes EVERYTHING. The repositories, references, context, knowledge, decisions, examples, …

The less your team owns, the more your work will look like everybody else’s.

So a better question than “what is your prompt?” is “what can your agent read?”.
If part of your documentation is on Storybook, half on some other platform, some in Figma, and parts of it in Markdown files, then you know you have a challenge to solve.

“Renting” apps is still fine on some occasions. It does not mean you have to “vibe-code” every possible app. But if all your data lives in 3rd-party platforms and you rely only on their MCPs or APIs, you are losing time (and data, of course!) with manual work.

So what’s next for you?

Start by putting your rules in files. Pick one card/component from your dashboard. What would it say? Write down what it’s for, when a change is worth showing, and what it should say when there is no data. Then let your agent read it.

Enjoy exploring 🙌

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

PS. I wrote about these already, and it might help you as well 👇

Learn more and references

🔗 Mobbin dashboard screens

🔗 Paul Bakaus, “The Dark Arts of Skill Engineering“, AI Engineer

🔗 Filament Group, Introducing ThemeRoller (2008)

🔗 Adam Wathan’s post, August 2025:

🔗 Alan West, Why every AI-built website looks the same

🔗 Claude Design launch

As soon as you start with AI, it feels like crushing a piñata on the first punch. Especially if you skipped the early versions of ChatGPT and got disappointed when something didn’t work. Any of your non-coder coworkers can literally get from Figma to working prototypes in minutes. So why do you feel a little sarcasm in my writing?

Because you focus too much on having a “machine-readable” design system and skip everything that should happen in between. That’s why I am foundations maxxing.

Let me explain how and WHY.

What do I even mean by foundations maxxing?!

Instead of spending a crazy amount of tokens (credits), let’s focus more on what our foundations are. Running wild and spending tons of tokens doesn’t mean you will create a scalable product. Without a strong foundation, you can't scale. Even if you find your perfect workflow, does it lead to a scalable product if the ground stays shaky?

#1 Your design system is infrastructure

I want to set one thing straight. A design system is infrastructure. I see it as the API that allows AI to build your products safely. The same way your CI/CD pipeline is infrastructure. The same way your database is infrastructure.

When anyone can generate a screen or app, the only thing that sets you apart from your competitors is the system behind it. Yes, the whole combination of brand, consistency, uniqueness, and so on.

Plus, let’s not forget that a design system directly supports business outcomes. Just developing a single page or screen becomes at least 50% faster with a design system than coding from scratch. Rules and guidelines for building with AI will speed everything up even more. So, to sell it to leadership, it is much easier to frame it as infrastructure.

#2 How I audit a design system in 2026

Before you even think about making your design system machine-readable, you need to do an audit. I know, it is boring; it takes time, but it will give you insights you've never thought of.

My process:

→ Go through libraries.
Check design tokens (Figma variables). Dig in for hidden layers, applied tokens, raw hex colors. Check whether scopes are applied correctly and whether any unwanted layers, variables, or themes show up in Figma.

→ Review components and check if you can have fewer variants, what you can optimize, etc.

→ Check the code and compare hard-coded stuff. Use linters.

→ Read the docs and decisions.

→ Read .md files, use them, compare results. Are there any useful machine-readable docs? What is there? You can use them as a starting point for your knowledge graph.

→ How are things shared across the teams? How are others designing and using AI? What’s their process and tech stack? This step is especially important if you work in large companies where each team tends to have its own processes.

→ What’s up with accessibility? Dig in and make a report.

→ Review the design <> development workflows and governance.

You can also start by pointing an agent to your Figma file, docs, or code and let it compare, count the drift, find detached components, ... and then, after you get a report, you can decide and prioritize what to fix first.

→ Send out the survey to get the pulse from different teams. Include developers, product design, and the design system team. You need to hear different perspectives.

Useful tools

I use a variety of tools, but these are my most used:

Playwright: screenshots your product in every state; it’s free;

Figma MCP: connect Figma with your AI tool and share everything about variables, components, descriptions

Tidy Core (my plugin): finds detached instances, ghost variables, naming, Figma-to-code parity;

Claude Code, Cursor or any other AI tool for building

GitHub MCP: reads code

Storybook: your library of all the components

Style Dictionary: reads the pipeline

PostHog MCP: reads usage

Checklist before you connect an MCP

The audit report should fit on one page. Add straight-to-the-point observations that serve as a checklist for next steps. Nobody will read loooong report, everyone just wants to know "what's next!".

#3 Time to fix or prepare the foundations

1. Set up design token naming structure. A useful tool here is 🔗 Name Design Tokens Builder. You can also use AI tools like Cursor or Claude and create a set of tokens based on your preferred naming structure. If you need inspiration on how others do it, 🔗 check my database of design systems and explore them.

2. Add descriptions to your components
You can do it manually or kick-start this process with AI. Just prompt it: “add descriptions to my Figma files”.

3. Create .md files
Describe the components, variants, usage, and relationships between them. Include everything agents need to know, and anything helpful for building screens. I already wrote about this, so you can read a detailed article.

4. Semantic binding rule

Components need semantic or component tokens (depending on your design token logic). If you use color.action.primary for all primary actions, agents will know this token is used across themes for every primary action.
But be careful. Also define scopes. Sometimes I find border design tokens applied to background, text on icons, and so on.

5. Decision log

The decision log is a document with all your tiny decisions about what you chose instead of X. Keep it short, straight to the point, and share it with your agents in your folder (ideally knowledge graph). Write what happened that day, why, who was involved, and date it. So next time someone wants to change a dialog design, you have a decision and a reason why it’s not a good idea (for example).

This also creates timestamps for understanding analytics better.

6. Pipeline to code

You need to connect your Figma to your code. If you have an Enterprise plan, it is much easier, since the API exposes Figma Variables directly. If not, you still have plenty of options to make it work. I use my own Tidy MCP (you can get Tidy Core here). There is also an unofficial Figma Console from . The next step is setting up a pipeline that turns variables into CSS variables (Style Dictionary or your own script).

7. MCP
I already wrote about the knowledge graph, so I will only share the basics here.

If you haven’t yet, first connect either Figma MCP, Tidy Core, or Figma Console to the repo. Then start by adding other MCPs. I use Granola, GitHub, PostHog, … Add whatever is SAFE. Do not share info that is not allowed inside the org.
Do not forget to connect your .md files. You also need to feed CLAUDE.md with your rules. We call that your agent’s harness.

#4 Respect devs, because they know their sh**

Just last month, a product manager opened 114 PRs. Wow, let’s give him a high 5. NOOO! Not just that. Development teams got around 60% more PRs than in a record month last year. And who reviews those [N] PRs? And when?

I know we all love self-initiative people and ideas. But they were not trained as UX designers; they don’t have years of experience, not in design, nor in testing. They don't know how design systems work and usually skip existing components because they feel restricted. You do not want this. Ever.

What happens next is that you put all the pressure on developers, who then become cleaners and have to review all the PRs. 🫠

Instead of focusing on quality code, they review lines of gibberish. And again, instead of talking about improvements, we start talking about what should be there in the first place, what the initial problem was, and how components should be used.

That is step one, c’mon.

#4 Collaborate, talk, discuss

Not long ago, kick-off meetings, longer (UX) sessions, and weekly reviews were totally normal. Today we are only talking about speed. “Okay, so this can be done by tomorrow?”, “Just ask AI!” Okay, the benefit is that we finally realized longer meetings serve no one, but that doesn't mean we should skip them entirely.

I see skipping meetings as a shortcut to using only AI.

Product is people. By skipping discussions, the collaborative part of building the product, you are also skipping the needs of people. AI is capable, but it does not know or can’t predict things that you and YOUR USERS experience along the way.

#5 UX first, UI second

Imagine people who have never worked with user experience and have no prior knowledge can now create apps, screens, decide, and prioritize content. Feels insane. Instead of making UX better and better, you end up arguing who is “more” right. So all the time gained with AI is suddenly lost in explaining UX 101 and design principles. Who is measuring this??

Change is the only constant, but not in UI.

I know there is a tendency to say, “it can be reverted fast,” but users aren't ready to play with your UI experiments every day. Consistency exists for a reason.

I don’t want to pretend AI isn't useful for user experience. IT IS! You can use AI to get feedback from multiple streams in seconds. Connecting analytics tools, support tools, and just using MCP or API to get metrics in real time feels like a superpower. It’s way easier and faster to prioritize user problems and improve them. And yes, this is how I imagine integrating AI for the UX.

Time to do it yourself

Every story I shared today has one thing in common. People who are SKIPPING the steps. So the next time your super enthusiastic “no-code builder” creates a PR introducing shitty new styles, just send him this article. Engage with your team and strive for constructive discussions. Soon, you should see the gaps.

You know how the famous saying goes: “Trust me, I’m a designer. “😅

Enjoy exploring 🙌

PS. Would love to hear your stories about emerging PR’s :)

I spent the last six months running an AI agent inside a 30,000-node Figma file. I can now tell you which jobs it earns.

Tidy is the Figma plugin and MCP server I built for design system work. It exposes 105 tools to Claude Code: audits, variable CRUD, dependency graphs, screenshots, and a raw execute tool that runs arbitrary Plugin API code in the live file. On paper that sounds like a toybox. In practice, a client engagement decides fast which tools matter, because a real migration punishes everything that wastes your time.

I tried to visualize how I see my superpowers agent Tidy 😅

Ok, let’s move to ten workflows, and for each one, how to run it on your own file.

Delete a token family and prove nothing broke

Deleting tokens is where maintainers freeze, because Figma gives you no “who uses this” answer at deletion time, and a careless delete leaves broken aliases you find weeks later.

I retired a legacy background family of about two dozen tokens behind the gate below, zero tombstones left behind (a tombstone is an alias or binding that still points at a variable that no longer exists). An earlier, pre-agent deletion in the same engagement left dozens of them, and cleaning that up cost a session.

This is the workflow I would not run on a plain script, and the reason the open source tidy-core (basic version of the Tidy) exists, so it goes first. Figma’s own MCP server reads variables and cannot delete one. The Plugin API deletes a variable that is still in use without a check: the layers keep painting the last value, the aliases that pointed at it become tombstones, nothing on the canvas looks wrong, and the token export breaks weeks later. A script the agent writes will count consumers first if you asked it to, differently each time, and one day you will not ask. tidy-core cannot issue a hash for a delete while a consumer remains. The safety is in the tool, not in the prompt.

Plugging it in takes about twenty minutes and no build step. In Claude Code it is one line in the terminal:

claude mcp add tidy-core -s user -- npx -y tidy-core

In Cursor, Windsurf or Claude Desktop, add the same server to the app’s MCP settings file, which for Cursor is ~/.cursor/mcp.json, then fully quit and reopen the app:

{ "mcpServers": { "tidy-core": { "command": "npx", "args": ["-y", "tidy-core"] } } }

The server fetches itself the first time it starts. Figma needs one more piece, a small plugin that lets the server see inside your file. Download the repo as a ZIP, then in Figma Desktop go to Plugins, Development, Import plugin from manifest, and pick plugin/manifest.json from the unzipped folder. By the way, I suggest you put it in the folder where you usually store your “Coding” experiments.

Run it and it finds the server on its own. Ask your assistant “Check tidy status” and it should name the file it is connected to. The repo’s getting-started guide walks the same steps in more detail, for people who have never set up an MCP server.

Now open the library file and ask for the deletion straight out:

Plan deleting every token under legacy/bg. Intent: retire the legacy background family, replaced by color/background.

It comes back blocked. No hash, one line per token, and the counts are read from the live file:

{
  "status": "blocked",
  "planHash": null,
  "estimatedBudget": { "aliasReferences": 14, "nodeBindings": 212, "bindingsExact": true },
  "risks": [
    { "level": "blocking", "message": "\"legacy/bg/default\" is still used in 31 places (2 alias references, 29 layer bindings). Deleting it breaks them. Repoint them first with aliasVariable." }
  ],
  "nextStep": "This plan cannot be applied. Resolve the blocking risks above and build a new plan. No hash was issued."
}

That refusal is the whole product. The blocked list is also your migration to-do, token by token. Alias references you repoint with tidy-core itself, one plan per consumer, value-preserving so nothing shifts:

Point every token that aliases legacy/bg/default at color/background/default, in both modes.

Layer bindings are node-level, which is not one of the six operations, so those move with the count-and-rebind snippet in the next section, or with any bridge that runs Plugin API code. Then plan the delete again. The counts come back from the file as it is now, not as it was:

{ "status": "ready", "planHash": "3f9c2a1b04e7...", "estimatedBudget": { "aliasReferences": 0, "nodeBindings": 0, "bindingsExact": true }, "risks": [], "nextStep": "To execute: tidy_apply with planHash \"3f9c...\" and confirm: true." }

Save a named Figma version yourself, then apply with a reason:

Apply that plan. Legacy background family retired, replacement live since the July restructure.

The intent becomes the subject of a decision entry, that sentence becomes its rationale, and the tool writes the entry itself. If anyone touched one of those tokens between plan and apply, it stops and tells you what moved. A plan also expires after an hour, so a review from Tuesday cannot delete on Thursday. The plan that finally got a hash is the receipt: zero tombstones by construction, not by sweep.

One thing no single-file tool can see, and the case that bites. Your tokens live in a Foundation file and every component that uses them lives in a Components file. Open Foundation, plan the delete of legacy/bg, and the count comes back zero, because those 212 layer bindings are in Components, and a file cannot see the bindings inside another file. tidy-core issues the hash. The delete runs. Every one of those layers keeps painting its last value, and the export breaks a month later. That is the exact shape of the deletion that bit me: verified clean in the foundation file, dozens of tombstones in the components master.

So before you delete from a library, open the file where you have components in Figma. It needs to be a desktop app! Run the plugin there, and count bindings to the library token with the snippet in the next section.

tidy-core cannot do that count for you yet, because a plan only resolves the variables a file owns. It is the one place this gate still needs you.

What the gate enforces, in order, whichever tool you use:

1. Find everything that still uses the old tokens, in every file that consumes them.

2. Move each of those onto the replacement token, keeping the same values so nothing shifts visually.

3. Check that nothing points at the old family anymore: no components, no aliases, no stray bindings. Every count must read zero.

4. Only then delete.

5. Sweep once more for broken references, and keep that zero as your receipt.

#2 Repoint thousands of bindings in one session

The client’s component master file had accumulated years of legacy references (I call them ghost variables): tokens from a superseded collection, primitives bound where semantics belonged, renamed tokens that never propagated. Cleaning that by hand means clicking through instances one at a time. Nobody ever finishes that job. It just stops when the person assigned to it burns out.

With the MCP connected, the same job is a loop: scan every node, match each stale binding to its current target, rebind, verify. One session repointed about 2,400 bindings with zero errors. A separate sweep earlier that week moved over ten thousand paint bindings off stale cached records. The whole file, not a sample.

Two things made this safe rather than reckless.

I made the agent count bindings, not variables. An early estimate said “a couple dozen direct primitive bindings to fix.” The real number, once the agent counted actual node bindings instead of distinct variables, was over 3,500. If you scope a migration by variable count, you will underestimate the work by two orders of magnitude and blow the budget you promised the client.

I made it verify end state, never trust a zero-error return. Figma’s setBoundVariable silently does nothing on text-node typography fields. It returns no error. It changes nothing. The file had nearly a thousand letter-spacing bindings that a first pass “fixed” without touching, because text nodes need setRangeBoundVariable instead. Since then, every bulk write ends with a re-scan that counts what is actually bound now, and only that count gets reported to the client.

To run this on your file, pick one legacy family, not “everything,” and start with the count:

// count every binding to tokens from a legacy family (here: "legacy/")
const hits = [];
for (const node of figma.currentPage.findAll(() => true)) {
  for (const [prop, b] of Object.entries(node.boundVariables ?? {})) {
    for (const ref of Array.isArray(b) ? b : [b]) {
      if (!ref?.id) continue; // componentProperties nests its aliases one level deeper
      const v = await figma.variables.getVariableByIdAsync(ref.id);
      if (v?.name.startsWith("legacy/")) hits.push({ node: node.name, prop, token: v.name });
    }
  }
}
console.log(hits.length, hits.slice(0, 20));

That number is your real scope. Write the old-to-new mapping as a table, get it approved, checkpoint, let the agent run the rebind loop, then run this same count again. The migration is done when it prints zero, and not before.

#3 Extra themes in the picker mean a stale import record

This one is my favorite, because no amount of clicking would have solved it.

You switch a frame’s appearance and the picker offers more themes than your system has: Light, Dark, and then some extra themes. Nobody on the team ever created a theme called “Theme Neon”. The obvious guess, a duplicate collection, was wrong. The file referenced one collection through two import records (an import record is the file-local copy Figma keeps of a library collection once you have used it), and the second record survived on a handful of invisible anchors.

The agent swept bindings first. Zero stale bindings. Picker still broken. Then explicit mode pins. Fixed nearly a hundred of those. Picker still broken. The real anchors turned out to be things a human cannot see in the UI at all: a handful of ghost tokens flagged hidden-from-publishing but still bound in the file, and two dozen superseded variable records inside the current collection, same name, same collection, older internal id, still aliasing the dead record.

You detect those by re-importing every remote variable by key and comparing ids. If the fresh import comes back with a different id than the one bound in your file, you found a zombie. Collection-level audits report these as clean, because the collection id matches.

Once the last alias anchor died, the extra themes fell out of the picker on their own. The sweep went through node bindings, mode pins, styles, prototype reactions, and cached import records. Five layers, and the bug lived in the fifth. That is the kind of investigation an agent with file-wide read access finishes in an afternoon and a human never starts.

If your picker shows themes nobody created, hunt in this order, cheapest first: node bindings, explicit mode pins, styles, prototype reactions, and only then the cached import records. The first four are ordinary scans your agent can write from this description. The fifth needs the id comparison:

// collect every library variable bound on the page, re-import each by key,
// and flag the ones whose fresh import comes back with a different id
const bound = new Map();
for (const node of figma.currentPage.findAll(() => true)) {
  for (const b of Object.values(node.boundVariables ?? {})) {
    for (const ref of Array.isArray(b) ? b : [b]) {
      if (ref?.id && !bound.has(ref.id)) bound.set(ref.id, await figma.variables.getVariableByIdAsync(ref.id));
    }
  }
}
for (const v of bound.values()) {
  if (!v?.remote) continue;
  const fresh = await figma.variables.importVariableByKeyAsync(v.key);
  if (fresh.id !== v.id) console.log("zombie:", v.name, v.id, "→", fresh.id);
}

Rebind everything the zombie check flags onto the fresh imports, and the extra themes disappear on their own.

#4 Rename 2,000 tokens with a way back

Read more

I have to start this email with amazing news. Almost two weeks ago, I launched the Agentic Design Community + Guide. 🥳✨I rolled it out in batches to everyone on the waiting list. Thank you to everyone who has already sent feedback.

What is inside:
* 87 guides on token pipelines, Figma MCP, Claude Code, and component audits (growing weekly)
* 33 production prompts
* 9 suggested learning paths, including a beginner setup that takes you from zero to a working AI workflow
* 26 templates and checklists
* A directory of 158 real design systems, from Netflix to Porsche
* 40 honest tool comparisons, no affiliate links
* Free tools like the Style Explorer and Trust Levels Playground
* Live sessions
* Free, helpful tools
* and so on

It updates weekly. 🌀

Join for free here

And now to design tokens.

I thought design tokens would be the easiest design system data for AI agents to use.

They are already structured, they already live in JSON, and they already move between Figma and code. So I read the token files of 50 design systems to see how ready they really were.

I found two things I had not expected. They are far more different from each other than I assumed, and most of them tell an agent what a value is without telling it what the value means.

Okay, why this difference matters? A token file can be perfectly valid for a build pipeline and still be thin context for an AI agent. The pipeline needs to turn color.red.500 into a usable value. The agent needs to know whether that red is for danger text, destructive buttons, error borders, alert backgrounds, brand moments, charts, or something that should never be used directly. Those are different jobs.

Readable is not the same as usable

Design system teams have spent years making tokens machine-readable. That was the right step. Agent-ready data just asks for something on top of it. It asks:

• What does this token mean?

• When should it be used?

• When should it not be used?

• Is it deprecated?

• Which component or state depends on it?

• Which decision created it?

• Which platform does it map to?

Without that layer, the agent can still read the file. It just has to guess.

Say an agent needs a danger color. It finds red.500. Nothing in the file says that red means danger, so it might reach for the same red on a disabled button or a decorative chart. The file gave it a value, not a reason.

These files were built to compile, and they compile beautifully. Explaining themselves to an agent is a newer job, and most were designed before that job existed.

How I looked at this

I read the public token files of 50 design systems and then used AI to compare the real source an agent would load, not the polished documentation.

For every system I gathered the same four things:

• Where the tokens live, and in what format.

• How many tokens there are, by category: color, typography, spacing.

• How the tokens are named.

• What meaning the file carries.

The same data for all fifty, so the comparison is fair. I counted from the raw files: where a system ships every shade in code, I counted every shade, and where a system keeps spacing in a build script, I went and counted that too.

Where the tokens actually live

The first thing I learned is that there is no standard place, and no standard format. I found at least eight formats in active use:

• DTCG JSON (Primer, GitLab, Backpack, NL Design System)

• Style Dictionary JSON (Workday, PatternFly, Gestalt, Orbit, Pharos)

• Theo YAML (Salesforce, Twilio, Nord)

• Plain JSON (Suomi.fi)

• TypeScript objects (Carbon, Polaris, Fluent, Ant, Chakra, Base Web, Cloudscape, Mantine, Elastic, Braid, Grommet, Forma 36, Theme UI, Australian GOLD)

• CSS custom properties (Radix, Open Props, Vibe, Shoelace, Decathlon Vitamin)

• SCSS maps (Material, Liferay Clay, Bootstrap, Foundation, Bulma, Vanilla, GOV.UK, Semi, parts of USWDS)

• LESS or CSS variables compiled from it (Stack Overflow Stacks, TDesign, Arco)

Some live where you would not expect. Adobe moved Spectrum’s tokens to a repo called spectrum-design-data, Shopify keeps the Polaris tokens inside polaris-react, and GitLab ships its tokens inside the @gitlab/ui package.

Knowing where the tokens live is the kind of thing you would tell a new teammate on day one. An agent needs the same pointer. Here is the map.

How big is a design token system

There is no standard size either. But before the numbers, the lens that makes them mean something: every count in this section measures the same thing. How many decisions the system makes for you, versus how many it leaves to you. A small scale is an opinion. A large scale is a palette. Neither is wrong, but each one changes what a consumer of the system, human or agent, has to figure out alone.

Take spacing, the simplest scale.

The median is about 12 steps, and most systems land between 8 and 15. Mantine ships 5, Open Props ships 74.

Read those two extremes through the delegation lens. Mantine’s 5 steps mean a designer, a developer, or an agent picking spacing has five options and will be consistent almost by accident. Open Props’ 74 steps mean every gap on every screen is an open decision, and an agent facing 74 unlabeled options is a drift generator. Every step past what you can name and explain is a choice somebody will eventually get wrong. The field’s median of 12 is a usable benchmark: count your spacing tokens, see where you sit, and ask how many of them you could write a usage rule for.

Material Design is the strangest case. The M3 spec defines a full spacing scale, 18 tokens from md.sys.spacing.0 to md.sys.spacing.900, right there on the documentation site. But material-web, the shipped code an agent would actually load, carries none of them: its token folder has sys files for color, elevation, motion, shape, state, and typescale, and no spacing file. The scale exists on paper. In the file, it does not. Which is this post’s whole argument in one system.

Material is not the only one. A whole class of systems does the same, especially component libraries. Tailwind, MUI, Tamagui, Element Plus, Naive UI, and PrimeVue all treat spacing as a base unit times a multiplier, or tie it to component sizes, rather than a list of named steps. It is a common and reasonable pattern. It just is not something an agent can read off the file as tokens.

Now typography. The median system ships about 25 typography tokens, and the range is enormous.

Backpack ships 10, and none of them are font sizes. Its sizes live in compiled code rather than the token file.

Adobe Spectrum ships 312. It splits every type role into size, weight, line height, family, and script, with separate sets for CJK and serif.

The Guardian ships 100, a named preset for nearly every combination of family, weight, style, and size, built from only 12 underlying sizes. The NL Design System ships 113, most of them scoped to a single component.

This is the delegation lens again, sharpest in typography: presets are pre-made decisions, atoms are homework. The Guardian pre-decided every valid combination, so nobody, human or agent, can compose an invalid one; the count is high because the decisions are already made. Spectrum ships the atoms and trusts you to combine them well; the count is high because the decisions are still open. Same number, opposite meaning, which is why the count only makes sense once you ask what it delegates.

Neither approach is wrong. A 312-token system and an 11-token system are answering different questions.

So “a design token system” can mean 10 tokens or 312 for the same job.

Color is the least comparable number (for me), because some systems publish every shade and some publish only the few they use. Theme UI’s starter preset ships 5 and expects you to add your own. Fluent and Radix run past 600.

The number that matters is the semantic layer, the named roles an agent actually reasons over. There, the range is just as wide. Nord exposes 57. Polaris exposes 226. PatternFly exposes 342. Atlassian exposes 391. And it is the same lens one more time: the semantic count is roughly how many UI decisions the system has pre-made and named. That, not the size of the primitive ramp, is the number to compare.

Everyone names the same thing differently

Here is a semantic background color, named eight ways.

• Workday: surface.default

• Twilio: color-background-strong

• Polaris: color-bg-fill-critical-hover

• Fluent: colorNeutralForeground1

• GitLab: action.primary.background.default

• PatternFly: global.background.color.primary.default

• Cloudscape: colorBackgroundButtonPrimaryActive

• Spectrum: accent-background-color-default

Here is the primitive, the color blue

• Chakra: blue.500

• Mantine: blue[6]

• Radix: --blue-9

• Open Props: --blue-7

• Carbon: blue50

• Primer: base.color.blue.5

• Spectrum: blue-500

• Salesforce: SCIENCE_BLUE

To see how deep the differences go, put ten systems side by side. These are real tokens from the raw files, and no two share a grammar:

Read the right column top to bottom and the problem becomes obvious: even the order of information disagrees. Some put the property first, some the role, and Mantine puts the role before the category. Cloudscape packs five facts into one name; Carbon’s layer01 packs two. Workday’s surface.default and PatternFly’s global.background.color.primary.default describe nearly the same thing at a 5x length difference.

An agent that learned one of these conventions knows nothing about the next. There is no shared grammar across systems. The token name is the first thing an agent reads, and it means something different to everyone.

And here is the part that actually bites: your agent has already seen all ten of these grammars. They are in its training data, everyone. So it does not arrive at your codebase ignorant; it arrives with ten conflicting priors, and when it has to invent a token name, it blends them. That is why AI-suggested tokens come out looking plausible while matching nobody’s convention, including yours: a dotted path here, a kebab role there, a camelCase state glued on the end.

The fix costs one line. Declare your grammar where the agent will read it, in the token file or your conventions doc: “our tokens are category-role-state, kebab-case, semantic names only.” An agent can follow your grammar perfectly once you state it. What it cannot do is guess which of the ten you meant.

Meaning is the youngest layer

The files are stored differently, sized differently, and named differently. An agent can adapt to all of that. The one thing it cannot infer is the part most files leave out: what each token means.

I looked for three kinds of meaning across the fifty:

• A written description of the token: about 15 of 50.

• A deprecation field an agent can read: about 10 of 50.

• An explicit do-not-use rule: 1 of 50.

One.

That one is GitHub Primer. Its token file carries a field built for agents.

muted: {
  $value: '{base.color.neutral.9}',
  $type: 'color',
  $description: 'Muted text for secondary content and less important information',
  $extensions: {
    'org.primer.llm': {
      usage: ['muted-text', 'secondary-text', 'helper-text', 'placeholder'],
      rules: 'Use for secondary text like timestamps, metadata, and helper text. Do NOT use for primary content.',
    },
  },
},

That is more than a color value. It is a value, plus a job, plus a note on when to skip it.

A few systems are close behind. Workday records the old names each token used to carry, so an agent can migrate old code instead of guessing. Atlassian and GitLab attach a description and a deprecation flag to each token. Cloudscape keeps a parallel metadata file with usage notes and governance flags. The NL Design System, the Dutch government’s, ships clean DTCG with a description and a deprecation field on its tokens, the closest in spirit to Primer.

Most files look like this:

export const gray = {
  gray1:  "#fcfcfc",
  gray9:  "#8d8d8d",
  gray11: "#646464",
  gray12: "#202020",
};

The names hint at intent. The file itself stays quiet on role, usage, or what to avoid. An agent reading it gets a number and infers the rest.

This is not a gap in anyone’s work. For many systems the meaning does exist. It just lives in the documentation site, the build pipeline, or the naming convention, rather than the token file an agent loads first.

So meaning is the youngest layer. A few teams have started writing it into the file. Most have not yet, because the need is new.

The next phase of design tokens is not only transformation. It is labeling. That is what turns a readable token file into one an agent can reason with.

I tested the guess

Saying “the agent has to guess” is a claim, so I tested it.

I built a small fictional token file, ten colors, the kind of bare file most of the fifty look like. It contains one trap that real products have all the time: two reds. crimson500 is the brand accent. red600 is the system danger color. Nothing in the bare file says which is which.

Then I gave the file to an AI agent with one task: style a destructive “Delete account” button and an inline error alert, using only tokens from the file. I ran it three times on the bare file, and twice on the same file with one change: each token carried a DTCG $description saying what it is for, including “Do NOT use for system feedback or destructive actions” on the brand crimson.

The bare file, three runs:

• Run one put the brand crimson on the delete button.

• Run two picked the danger red for the button, but a different text color than the others.

• Run three put the brand crimson on the delete button again.

Two out of three runs painted the most destructive action in the product with the marketing color, and no two runs agreed on the full answer. The agent was not being careless. crimson500 is a perfectly reasonable guess for “destructive” if all you have is the name and the hex. The file gave it a value, not a reason.

The labeled file, two runs: identical answers, both correct, and both reasonings quoted the descriptions back to me. “red600 is explicitly designated for destructive actions.” No guessing, because there was nothing left to guess.

It is one small experiment with a planted trap, not a benchmark, so take it as an illustration rather than proof. But the trap is not artificial. If your brand color and your danger color live anywhere near each other, an agent reading your bare token file is flipping this same coin right now.

Is your token file agent-ready?

Open your actual token source, the file an agent would load, not your docs site, and answer these:

1. Does any token carry a written description in the file itself? Not in Figma, not on the docs site. In the file.

2. Is there a machine-readable deprecation field? If a token is on its way out, can a parser tell, or is that knowledge in someone’s head?

3. Does any token say when NOT to use it? The do-not rule is what stops the crimson-on-delete-button mistake.

4. Could an agent tell your brand color from your danger color using only the file? If both are named by hue and number, it cannot.

5. If a teammate asked “which token for an error border?”, does the answer exist anywhere a machine can read?

What you can try this week

If you want your tokens to work better with agents, you do not need to relabel everything. Start with ten high-use tokens, the ones an agent is most likely to misread:

• primary action color

• danger color

• disabled state

• focus ring

• form spacing

• card surface

• border radius

• elevation

• body text

• page background

For each one, add:

• role

• usage

• anti-usage

• state

• component relationship

• deprecated status

• decision link if one exists

Here is what that looks like on one ordinary token. Before, the way most of the fifty files look:

{
  "red600": { "$value": "#d62b1f", "$type": "color" }
}

After, using nothing but the DTCG fields that already exist plus one extensions block:

{
  "red600": {
    "$value": "#d62b1f",
    "$type": "color",
    "$description": "System danger. Destructive action backgrounds, error text, error borders.",
    "$deprecated": false,
    "$extensions": {
      "com.yourcompany.usage": {
        "role": "danger",
        "use": ["destructive-buttons", "error-text", "error-borders"],
        "doNotUse": "Decorative elements, charts, brand moments. Use crimson500 for brand.",
        "components": ["Button[variant=danger]", "Alert[type=error]", "Input[invalid]"],
        "decision": "ADR-014"
      }
    }
  }
}

Copy that block, rename the extension namespace to your org, and you have the template. Two things make this cheaper than it looks. $description and $deprecated are already part of the DTCG spec, so you are not inventing a format, and your build pipeline will ignore the extra fields without any changes. You are not migrating anything. You are annotating what is already there.

And while you are in the file, add the one line from the naming section: declare your grammar.

That is enough to start. The goal is to give the agent a little less to guess. In my labeling experiment above, the difference between guessing and knowing was exactly one $description field per token.

As you can see, your token file is not only a source of truth, but is a memory layer for your agents.

Enjoy exploring 🙌

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

Code prototypes are fast. Feedback on them is not by Pitre

🔗 Link

Pixel art tool where every pixel is code, not raster by

🔗 Link

I spent a week reading every public design system I could find that documents AI. Out of 156 systems in my dataset, 26 now address it in some form: an AI label, a chat pattern, an explainability framework, or a set of ethics rules. That is up from the handful you would have found a year ago, and it is climbing fast.

The interesting part is not the count. It is that the teams doing this well have never coordinated, and yet they keep arriving at the same four rules. IBM, AWS, GitLab, Red Hat, SAP, Workday, Apple. Different companies, different industries, different component libraries, and a similar rulebook. That convergence is the most useful signal in the dataset, because it tells you which AI guidelines are becoming conventions and which are still one company’s experiment.

What AI readiness actually means

For this piece, AI readiness means how well a public design system helps teams design, explain, govern, and scale AI-powered experiences. It measures the published system, not the company behind it. Apple shipped Apple Intelligence long before its guidelines documented generative AI.

The AI-readiness maturity model

Level 0: No visible AI layer

No public AI guidance at all. 130 of the 156 systems sit here, which leaves every product team to work AI out alone.

Level 1: AI as decoration

Shopify Polaris marks AI with a “Magic” color role and tokens like --p-color-bg-surface-magic. You get a recognizable signal and nothing about behavior. Mark only, and the ceiling is a purple badge.

Level 2: AI as a component

IBM Carbon ships an AI label that opens an explainability popover, reused across 13 components. Teams stop rebuilding the badge and the chat panel. A component library still cannot say when AI should act, when it should wait, or when a human takes over.

Level 3: AI as an interaction pattern

Atlassian publishes interaction guidelines for how AI should suggest, respond, and hand off inside a workflow. Designers and PMs get the behavioral decisions, not just the UI. The risk is patterns that float free of governance, metrics, or code.

Level 4: AI as governance layer

Microsoft Fluent 2 turns governance into enforcement: a Responsible AI rubric with letter grades and automatic fails, plus a page that governs the AI’s own tone and guardrails. The payoff is accountability. The catch is governance that never connects back to a reusable pattern.

Level 5: AI as system infrastructure

Microsoft Fluent is the only strong public signal here: a named “Copilot UI Kits” tier of AI components across Web, iOS, and Android, aligned to code. A kit that extends the core beats any principles page. Almost no one reaches this rung, because everything past that one table stays private.

Reading the ladder

The jump that matters is 2 to 3, the line between a system that styles AI and one that helps you design how it behaves. That is the model. Now the scores, because the ranking is not the one you would guess.

The scorecard

I scored the systems that document AI on five dimensions, twenty points each: how they mark AI, whether they ship reusable AI components, whether they document how AI behaves, whether they govern it, and whether they wire it into infrastructure.

It measures the depth of public documentation, not the quality of the company’s actual AI.

ServiceNow ships a full “Designing for AI” section, an “Identifying AI content” page, a ten-question value gate that opens with “Is AI really needed to solve the problem,” and a downloadable responsible-AI handbook. Red Hat PatternFly ships an actual npm ChatBot library with AI-labeled messages, citation tiles, feedback forms, streaming, and conversation-history error states. Quiet, enterprise, unglamorous, and ahead of everyone.

The household names sit low, for an honest reason. Apple has the best responsible-AI writing in the set and zero reusable components, because Apple ships frameworks, not a public component library, so it scores 43. Shopify has the cleanest AI marking tokens anywhere and almost no behavioral guidance, so it scores 31. High brand, low documented depth.

SAP did the work, then took it offline. It built a full AI and Joule design practice and published a lot of it openly, but those pages now return errors after a guidelines refresh. That is why it is not in the top 10: the thinking is not gone, the public just cannot read it anymore.

🚨 One honest limit before the rules.

This measures public documentation, and public is not the same as capable. A low score means a team has not exposed its AI thinking to the outside world, not that the thinking does not exist. Carbon’s deeper AI guidance sits behind “IBMers only” links. Atlassian gates its AI Figma libraries to Atlassians. Apple shipped Apple Intelligence across its platforms for a year before its public guidelines documented generative AI. The AI work inside these companies is almost certainly larger than what their design systems publish. What I am scoring is the generosity and discipline shown in the open, which is the only part another team can learn from.

Whatever level a system reaches, the ones worth copying share four rules. They are what good looks like from Level 2 up, and they are drawn from reading all 26 side by side.

Rule 1: Mark it, every time

The user must always know when content came from a model.

IBM’s Carbon for AI is the most developed example. IBM built an entire extension of Carbon whose core is the AI label, an interactive marker that sits inside any element containing AI-generated content. The label is also the doorway to an explanation, which I will come back to.

The rule Carbon writes is a restriction, and that is what makes it a real guideline:

“Don’t use the Carbon for AI styling as decoration. While these new styling elements are enticing, they are strictly intended to identify any instances of AI being used in an experience.”

AWS Cloudscape reaches the same place from a different angle. Its generative AI output label is a small “Generated by AI” tag with a sparkle icon, and the guidance reserves that icon with unusual strictness:

“Sparkle icon should not be used in any other labels other than generative AI output. Don’t use this label for outputs produced by other forms of AI that are not generative.”

Cloudscape even tells you not to over-mark: in a list where every item is AI-generated, label the group once, so users are informed without being overwhelmed.

GitLab Pajamas writes the same rule as ready-to-paste copy. Flag AI content with a “Generated by AI” or “Summarized by AI” disclaimer, and pair it with a verification nudge: “Content generated by AI should be seen as a starting point and verified before use,” or where space is tight, simply “Verify before use.”

Workday Canvas turns marking into infrastructure, shipping an AI badge, an AI button, and dedicated AI color tokens so the mark is consistent by default.

The shared rule: AI content is always labeled, the label is consistent, and the styling is reserved for AI alone.

Rule 2: Explain it, in layers

Marking tells the user that AI was involved. Explaining tells them why, and the leaders agree it should arrive in layers, not all at once.

The clearest live example is IBM Carbon. Its explainability popover attaches to the AI label: a quick summary first, with the option to dig into more detail only if the user asks. The principle underneath is What, Why, How. Show the decision on the surface, the reasoning one level down, and the data and process for the people who need to audit it, with depth scaled to the stakes. A low-risk suggestion shows the “what” and stops. A decision with regulatory weight exposes the “how” with a traceable trail.

Cloudscape applies the same idea to actions rather than content, showing each step the AI takes and a plain-language description of the impact before anything happens.

SAP Fiori once had the cleanest version of this, a well-regarded “Explainable AI” page built on those What, Why, How layers. Then SAP pulled it. As of this writing the page reads “This page has been deprecated and is no longer available,” part of an AI guidelines refresh. It is a sharp reminder that AI documentation is so young that even good work gets deprecated mid-flight, which is the strongest argument for treating these guidelines as living infrastructure rather than a one-time publish.

None of the live examples dumps model internals to the user. They reveal on demand, scaled to how much the decision matters.

Rule 3: Keep the human in control

This is the rule with the most agreement and the best detail, because it is where AI UX differs most from ordinary UX.

GitLab states the principle directly:

“Design AI to be collaborative, not autonomous. AI should suggest and assist while users remain in control. Respect human judgment by ensuring AI acknowledges uncertainty and defers to user expertise when appropriate.”

Carbon expresses the same idea as a component behavior. When an input holds AI-generated content and the user edits it, the field drops its AI styling and becomes ordinary. A “revert to AI” control lets the user bring the original suggestion back. The rule “the human can always override, and the override is reversible” is written into how the component works, so a team cannot forget to honor it.

AWS Cloudscape goes furthest, with a full pattern for actions an AI takes on your behalf. It defines authorization levels tied to risk, a human-in-the-loop sequence, and a rule about permanence.

“Don’t execute changes that have serious, irreversible, or cascading consequences without explicit user authorization.”

Cloudscape’s flow is worth copying outright: the AI states the action and its impact, lists the exact resources affected, asks for simple authorization on low-risk changes and additional confirmation on destructive ones, then confirms what changed and offers a way to reverse it.

Three companies, one rule. The human decides, the human can undo, and the riskier the action, the more explicit the consent.

Rule 4: Design for the moment it is wrong

The weakest section in most teams’ thinking is the strongest signal of a mature guideline. The good ones plan for failure on purpose.

PatternFly gives the rule its own heading, “Be prepared for something to go wrong,” and states it plainly:

“When AI fails, be explicit about errors and let users regain control as they want. Provide easy access to human support.”

GitLab formalizes this into a risk assessment. Before building, weigh the probability of an error against its impact, where impact compares cost and benefit. An agent explaining a feature is low risk. A flow that opens merge requests with security fixes is high risk, and high-risk actions require opt-in and a review step before execution. GitLab also writes the fallback rule: when confidence is low, “make sure there is a path forward that does not rely on AI.” Cloudscape designs the failed-action state in detail, showing which step broke, why, and the specific steps to recover.

Failure handling is where you can tell the difference between a real guideline and a press release. A press release talks about what the AI can do. A guideline tells you what happens when it does the wrong thing.

The differences

Every company invents its own visual language for AI (which makes sense, since it connected with the branding). Carbon uses light, glow, and gradients as a metaphor for illumination. Cloudscape uses a sparkle icon. GitLab uses a custom “tanuki AI” illustration. Workday uses an AI badge with its own tokens. Each is internally consistent and externally incompatible. A person who uses four products in a day gets four different signals for the same concept, “this came from AI.” The field agreed that AI must be marked. It has not agreed on what the mark looks like, and until that settles, the transparency only works one product at a time.

There is a quieter disagreement too, about whether to build the feature at all. PatternFly opens its guidelines with a value gate: do not add AI “simply because it is new, trendy, or fun.” GitLab says the same, telling designers to ask “How might we help users?” instead of “Can we use AI to?” Apple, in the Generative AI section it added to its Human Interface Guidelines in 2025, writes it most plainly: “Generative AI is a powerful tool, but it’s not the right solution for every situation.” When IBM, GitLab, Red Hat, and Apple independently tell you that the first AI guideline is permission to not use AI, that is worth listening to. The gate is the most underused guideline in the set, and the one I would adopt first.

What to learn from

I would not say copy, because what is public is only a slice of what each team knows, and a pattern lifted without its context tends to break. Learn the move and the reasoning behind it. Five worth studying.

• Carbon’s tokenized AI identity. AI color and style tokens live inside the existing themes, and the AI label component doubles as the trigger for a layered explainability popover. The lesson: make marking AI a variant toggle, not bespoke styling, so it stays consistent by default.

• Fluent’s responsible-AI scorecard. A pass or fail rubric with letter grades and automatic-fail conditions. The lesson: turn governance into a shippability gate, so an AI feature cannot go out without meeting transparency and user-control criteria.

• Atlassian’s workflow-level patterns. AI framed as behavior, with a standing “Uses AI. Verify results” footer carried by the component. The lesson: bake verification into the pattern rather than leaving it to each team to remember.

• Cloudscape’s user-authorized actions. Actions classified by risk, then gated. The lesson: a simple confirmation for reversible changes, explicit authorization for destructive ones, and a way back wherever possible.

• Shopify’s AI signaling reads as a floor and not a ceiling. The Magic tokens are the cleanest marking system in the set. The lesson is the reservation rule, mark only genuine AI, and the warning is not to mistake marking for the whole job.

What to avoid

• Treating AI as a color palette. A purple badge is marking, not design.

• Shipping sparkle icons with no behavioral rules behind them.

• Documenting chat but not its failure states.

• Documenting generation but not review.

• Documenting AI presence but not user control.

• Documenting principles but not reusable patterns.

• Keeping the AI guidelines in their own silo, cut off from the rest of the system.

What is missing from almost every design system

I could not find solid public guidance for:

• confidence and uncertainty

• source attribution

• hallucination recovery

• user correction loops

• escalation to a human reviewer

• AI memory and personalization controls

• proactive-behavior boundaries

• agent permissions

• multi-agent workflows

• validation of AI-generated UI

• product analytics for AI interactions

• design-system observability

Some of this almost certainly exists inside these companies, in internal guidelines and gated libraries, but it is not published, so no one outside can learn from it yet. The first team to document them well in the open will set the next standard, the way Carbon set it for the AI label.

What a good AI pattern actually documents

Most AI “patterns” are a single sentence. A real one answers fifteen questions: user intent, trigger, input, output, system behavior, user controls, feedback mechanism, error state, confidence and uncertainty handling, explainability, accessibility, data and privacy implications, examples, anti-patterns, and implementation notes.

The whole gap is visible in one comparison.

A weak pattern says:

Use this badge when AI is involved.

A strong pattern says:

Use this pattern when AI generates content the user must review before publishing. The user must be able to inspect, edit, accept, reject, regenerate, and report low-quality output. The system should show what was generated, what source or context was used, and what happens after acceptance.

That difference, between marking AI and designing it, is the whole article. The 26 systems that document AI mostly live in the first sentence. The few that live in the second, Carbon, Cloudscape, Atlassian, Fluent, are the ones worth studying.

Why this matters

The component is no longer the hard part. Anyone can ship an AI chat panel or a glowing suggestion field this week. The hard part is the same as it has always been in design systems: writing down when to use it, how to mark it, who stays in control, and what happens when it fails, so the next person who builds with your system does the right thing without asking.

That is the entire job of a usage guideline, and AI did not change it. AI only raised the cost of skipping it. An unlabeled component that quietly does the wrong thing is a bug. An unlabeled AI component that quietly does the wrong thing, with no explanation and no way back, is a breach of trust.

Enjoy exploring 🙌

🔗 IBM Carbon Design System, “Carbon for AI.” AI label, explainability popover, revert-to-AI, reserved styling.

🔗 AWS Cloudscape, “Generative AI output label” and “User authorized actions.” Reserved sparkle icon, human-in-the-loop authorization, action permanence.

🔗 GitLab Pajamas, “AI-human interaction.” Collaborative not autonomous, risk assessment, “Verify before use,” graceful failure.

🔗 Red Hat PatternFly, “AI guidelines.” Value gate, transparency, failure handling.

🔗 SAP Fiori, “Explainable AI” (the What / Why / How layers, now deprecated as of guideline v1.130 and showing a deprecation notice).

🔗 ServiceNow, “Designing for AI” and “Identifying AI content” (top scorer, governance + marking).

🔗 Red Hat PatternFly ChatBot, the @patternfly/chatbot React library.

🔗 Apple Human Interface Guidelines, “Generative AI” (added June 2025). Transparency, keep people in control, the value gate, hallucination handling.

🔗 Shopify Polaris, “Magic” color role and tokens (Level 1 example).

🔗 Atlassian Design System, “AI interaction guidelines” and “Rovo and AI” patterns (Level 3 example).

🔗 Microsoft Fluent 2, “Responsible AI” and “Content engineering” (Level 4 example).

🔗 Microsoft Fluent 2, “Copilot UI Kits” tier, “Start designing” (Level 5 example).

🔗 Workday Canvas, “AI Elements.” AI tokens, AI badge and button, AI color roles.

🔗 Emplifi Soul Design System, “AI guidelines.” Eight AI interaction patterns.

🔗 Microsoft HAX Toolkit. 18 evidence-based guidelines for human and AI interaction.

🔗 Google PAIR, “People + AI Guidebook.” A foundational reference several of the systems above cite.

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

Don’t build components for the sake of components by Marianne Røsvik

The frontend world loves new tools. New frameworks, new libraries, new ways to wrap what is essentially just HTML, CSS and a bit of JavaScript.

Right now, Web Components are getting a lot of attention for good reason. But we need to be careful not to fall into a classic trap: using a technology because we can, not because we should.

🔗 Link

When I connected 105 MCP tools to my design system, I thought it was AI-ready. It wasn’t.

The tools could read the surface: tokens, docs, components, Figma. But they did not know why a pattern had been rejected, because that memory lived across Slack, ADRs, and Figma comments. I had given the agent access. I had not given it memory.

This is why I think memory is the design system advantage.

The shift is simple: stop asking whether your agent needs more tools. Ask whether it can find the decisions your team has already made. The advantage is the memory your company has and whether your agent can use it, not the model, the number of tools, or the clever prompt.

Companies are already feeling the AI ROI problem. They have bought the tools. They have run the demos. They have a dozen teams asking agents to write code, summarize research, generate flows, review tickets, and clean up docs.

But the hard part is whether the agent has enough trusted context to do useful work without constant correction.

Some companies have too much data. Thousands of docs, tickets, meetings, comments, specs, research notes, and decision threads. The agent can technically read them, but it has no idea what matters.

Some companies have not enough usable data. The important decisions exist, but only as memory, buried Slack threads, or comments in files nobody will open again.

Both create the same failure.

You end up babysitting the agent. You correct the same wrong assumption three times. You explain the same component history again. You remind it that the team deprecated that pattern last quarter. You paste the context that should already be known.

If you do not want to babysit your agents, you have to be smart with your data.

Bad context is expensive

Every wrong answer has a cost. Every retry has a cost. Every agent loop that reads the wrong files, summarizes the wrong docs, or repeats a rejected pattern burns tokens before it burns trust.

The Verge reported that Microsoft is winding down most internal Claude Code usage in its Experiences + Devices group by the end of June and moving engineers toward GitHub Copilot CLI. The decision was framed as platform convergence, but The Verge also reported that financial pressure was part of the move.

Uber hit the same wall from a different direction. Its CTO Praveen Neppalli Naga told The Information:

I’m back to the drawing board, because the budget I thought I would need is blown away already.

Axios reported an even cleaner version of the problem from inside Nvidia. Bryan Catanzaro, Nvidia’s vice president of applied deep learning, said:

For my team, the cost of compute is far beyond the costs of the employees.

Gartner’s forecast makes the pattern more obvious. Token prices may fall by more than 90 percent by 2030, but agentic systems can require 5 to 30 times more tokens per task than a standard chatbot. Lower unit cost does not save you if the workflow burns through much more context.

METR’s time-horizon work explains why this gets more important as models improve. In its original March 2025 analysis, METR estimated that the length of tasks frontier agents can complete with 50 percent reliability had been roughly doubling every seven months.

https://metr.org/time-horizons/

This does not mean agents are faster than humans. METR defines the time horizon as the length of task measured by how long a human expert would take, not how long the AI spends running. The point for design systems is simpler: as agents take on longer tasks, they need more context, more tool calls, and more chances to retrieve the wrong memory.

So context quality matters.

If the agent has to rediscover the same decision in every session, you pay for that rediscovery every time. If it asks the wrong person, reads the wrong file, or misses the support ticket that explains the pattern, you pay again. If a designer, engineer, PM, researcher, accessibility specialist, or support lead holds part of the answer but their knowledge is not in the corpus, the agent works with a partial map.

Partial context creates expensive confidence. The goal is not to feed the agent everything. The goal is to make the right team memory retrievable before the agent starts acting.

The visible 10 percent and the invisible 90

Open your design system right now. The agent-readable surface is bigger than you think.

The right column is the moat. Anyone can fork your token JSON. Nobody can fork why you made the decisions inside it.

This is the part I was ignoring. I had built tooling against the left column and assumed that was enough.

The moat does not exist on day one

The important part is not just data. It is data that improves over time.

Design systems have two phases, and the data flywheel works differently in each.

0 to 1: founding phase

The job is to make it work and prove it matters. Scrappy. A handful of high-impact components. Naming conventions still fluid. Adoption inside one team. The job is to ship the system, not to feed an agent. The data you generate is mostly throwaway, things like “the team tried X, it broke, then tried Y.” That is fine.

1 to 100: scaling phase

Make it last and make it scale. Solidified architecture. Rules over examples. Multiple brands, platforms, markets. Now you have:

• Three years of token renames with reasons attached

• A dozen deprecated components and the threads explaining why

• Governance trade-offs and the conversations that produced them

• Drift reports across surfaces and brands

• Critique notes that surface the same blind spots over and over

• Performance reviews of the design system team itself

This is the data most 1 to 100 design system teams already have. Almost none of them feed it to their agents. Most 1 to 100 teams already have this memory. They just have not made it retrievable.

A pile of files is not enough

The naive fix is “dump everything into a folder, point Claude at it, hope.” I tried it. It does not work well enough.

The agent can read individual files. It cannot reason across them. Ask “what changed about Alert this year and why?” and you get a polite shrug, because the answer lives across a Figma comment, a Slack thread, a closed PR, and an ADR that nobody linked together.

QMD tests whether the pile has signal. The graph is what you build once you know it does.

QMD is a local search tool by Tobi Lutke that lets an agent search your own folders with keyword search, vector search, and reranking.

It is the lightweight version I used first. It does not turn your design system into a graph. It gives you a local hybrid index over your files, which is enough to start testing whether your corpus has signal.

The mature design system version is a graph. Tokens connect to components. Components connect to decisions. Decisions connect to outcomes. Outcomes connect back to tokens. The agent walks the graph instead of grepping the pile.

For a design system, the graph nodes are bigger than files. They are token, component, pattern, decision, owner, surface, brand. The edges are uses, supersedes, depends on, was decided by, drifted from.

This is what I rebuilt Tidy around. Every component knows its variants, its tokens, its owner, its decision history, its drift score. The agent queries the graph and knows, instead of crawling Figma and guessing.

How I tested QMD on my own files

I wanted to know if this actually works on my data, not just in theory.

So I installed QMD on a Tuesday and pointed it at six folders:

• Tidy decisions

• Client design system specs

• My Substack drafts

• Customer research

• IDS talk material

• Granola meeting transcripts

It embedded 1,511 of my documents locally in about 5 minutes.

That part matters. I did not want a huge knowledge management project. I wanted the smallest test that could tell me whether my own corpus was useful. It combines keyword search, vector search, and reranking, then returns the files most likely to help the agent answer the prompt. It works because it is a better first pass than asking the agent to crawl a random folder and hope.

The setup was simple:

1. Pick a folder with real signal.

2. Add it as a QMD collection.

3. Embed it locally.

4. Query it before the agent answers.

5. Inject the top results as context.

That pattern helps a design system because the system’s value lives across decisions, specs, critiques, and usage history.

It also helps a product.

A product team has the same problem in a different shape. The answer to “why does checkout work this way?” may live across research notes, support tickets, experiment docs, pricing decisions, analytics writeups, and a half-forgotten launch memo. If the agent only sees the current UI, it will confidently suggest the thing the team already tried.

The goal is not to make the agent read everything, but to make it retrieve the right context before it starts acting.

Then I ran three queries that map to real design system work.

Query 1: “why did I choose certain naming conventions for tokens”

Query 2: “what have I written about agentic design system governance”

The hybrid pipeline (BM25 + vector + LLM rerank) connected “agentic governance” to “shared practice with developing consciousness.” It pulled a file I had categorized in my head as “philosophy” back into the bucket of “things I have written about how agents should behave.”

This is where QMD earned its keep on this corpus. Pure keyword search would never have surfaced that file. Hybrid retrieval did.

Good data not only makes agents more accurate, it changes what you have to repeat.

The agent layer is the smallest part

This is the order most teams have backwards. They start with the agent. They should start with the data.

There are three layers, and they have to come in order.

1. Your data sits at the bottom. Tokens, decisions, drift, critiques, ADRs, and deprecation history. Everything in the invisible column from the table above.

2. Your structure sits on top of the data. A graph or hybrid index that lets an agent reason across it, not just search it.

3. Your agent sits on top of the structure. It is the smallest layer, mostly orchestration on top of the first two.

Skip layer one, and the agent generates plausible nonsense. Skip layer two and the agent finds a file but cannot connect it to anything. Nail one and two and the agent layer is almost trivial. You can swap models freely.

This is also why “the team will switch to a better model later” is the wrong worry. Models get cheaper and more capable on someone else’s roadmap. Your data does not show up on its own.

What to do this week

If you are in the 1 to 100 phase and want to start, this is the smallest useful version.

1. Pick one folder that already has a good signal. ADRs, design critique notes, component specs, research summaries, or support tickets.

2. Install and index it with QMD: npm install -g @tobilu/qmd, add the folder as a collection, then run qmd embed.

npm install -g @tobilu/qmd
qmd collection add ~/design-system/decisions --name decisions
qmd embed

3. Run five real questions against it, using questions your team actually asks instead of demo questions.

4. Look at the misses. A miss means one of two things: the document is missing, or the document exists but the language is too vague to retrieve.

5. Write the missing decisions down. Start with the ones you are tired of explaining.

6. Add retrieval to the agent. Call qmd query directly through your agent’s shell tool, or add a pre-prompt hook that injects the top results as context.

You will know it is working when the agent stops asking you obvious things and starts reminding you of decisions you forgot you made.

Start with the invisible column. Decisions, critiques, drift, rejections. Make one folder searchable and ask real questions.

QMD is only the first step. It tells you whether your corpus has signal.

Next week, I want to go one layer deeper: data labeling. Once you know which memories matter, the next question is how to label them so agents can use them reliably.

The design system is no longer the deliverable. It is the dataset.

What part of your invisible column would you wire in first? Let me know below 😊

Enjoy exploring 🙌

Romina

Explore on your own

🔗 QMD by Tobi Lütke (GitHub). Local hybrid search exposed as MCP.

🔗 Why Tobi Lütke built QMD (Gamgee). Background on the tool’s reasoning.

🔗 How to Build for AI Agents and a Claude Code Second Brain in 25 Min, Peter Yang. Useful context on using QMD with Claude Code.

🔗 Microsoft starts canceling Claude Code licenses, The Verge. Reporting on Microsoft moving engineers from Claude Code to Copilot CLI.

🔗 Uber CTO AI budget coverage, Techmeme / The Information. Summary of reporting on Uber’s AI coding budget overrun.

🔗 AI can cost more than human workers now, Axios. Source for Bryan Catanzaro’s compute-cost quote.

🔗 Gartner inference cost forecast. Forecast on token cost decline and higher agentic token demand.

🔗 Goldman Sachs token demand coverage, PYMNTS. Reporting on Goldman Sachs’ forecast for agentic AI token consumption.

🔗 Time Horizon 1.1, METR. Source for the updated task-completion time horizon data.

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

Figma Variables for Complex Multi-Brand Systems by Veronica Campana

Standard tutorials about variables often fall short when it comes to the technical intricacies of enterprise design systems. Drawing from my work building the Index Design System for Dow Jones, this article details the layered variable architecture we developed to manage high-level complexity without sacrificing the designer experience.

🔗 Link

Quick note before we dive in. My Agentic Design Course is almoooost ready. The “it has to be amazing” brain took over, and I kept adding before launch. A few testers are inside it now. It’s coming in the end of May. 😍

Most design system teams are preparing for the wrong AI future.

They are asking:

“How do we use AI to generate components faster?”

But the better question is:

“Can AI understand why this component exists, when to use it, and when not to?”

That is the real shift.

The next generation of design systems will not be judged by how many components they have. They will be judged by how well agents can read them, reason with them, and safely act on them.

In other words, your design system is no longer just for humans. It is becoming infrastructure for agents.

Gartner predicts that 40% of enterprise apps will embed task-specific AI agents by the end of 2026, up from less than 5% in 2025. Gartner also warns about “agentwashing,” where ordinary assistants are marketed as agents even when they cannot operate independently.

That distinction matters.

Microsoft is already redesigning Fluent around adaptive interfaces that respond to user intent and move from passive UI toward more dynamic systems.

Meanwhile, many design system teams are still treating AI like a chatbot. Ask a question → get an answer → move on. That is not the future.

The future is orchestration.

From chatbot to orchestration

A chatbot answers. An agent acts. A system of agents coordinates work across tools, files, workflows, and approval gates. That is the shift design system teams need to understand.

AI in design systems is not just:

• “Write documentation for this component.”

• “Generate a React card.”

• “Summarize our token structure.”

• “Create a Figma variant.”

The bigger change happens when agents can read your design system, understand its rules, propose changes, validate those changes, and escalate risky decisions to humans. That is where the design system stops being a passive library and starts becoming operational infrastructure: not a chatbot, an orchestration layer.

So, what is an agentic design system?

An agentic design system is a system where AI agents can read, interpret, and apply design decisions with human oversight. Not just generate code from prompts. Not just summarize documentation. Not just create random UI.

A real agentic design system gives agents enough structure to understand:

• what exists,

• why it exists,

• when to use it,

• when not to use it,

• what rules must be followed,

• what changes are safe,

• what changes require approval.

The difference looks like this:

The shift is not from “human design” to “AI design.” That framing is too shallow. The real shift is from “Here is a button” to “Here are the rules, intent, constraints, accessibility requirements, and usage conditions for this action pattern.” The button does not magically know what to do. The system does.

Components become contracts

This is the most important mental model.

In traditional design systems, a component is something you import.

In an agentic design system, a component becomes a contract between design, code, product intent, accessibility, and behavior.

A button is no longer just:

<Button variant="primary">Submit</Button>

It also carries rules:

• Use primary buttons for the main action in a flow.

• Do not use destructive styling without a confirmation pattern.

• Maintain a minimum contrast ratio.

• Preserve keyboard navigation.

• Use loading states for asynchronous actions.

• Use platform-appropriate interaction patterns.

• Escalate if the requested variant does not exist.

• Do not create one-off styling without checking token availability.

This is what agents need. The better the contract, the safer the agent.

What exists today

You do not have to imagine the entire future. The building blocks are already here.

They are not perfect. They are not fully autonomous. But they are enough to start preparing your design system for agents.

1. Figma MCP gives AI access to design context

Figma introduced its Model Context Protocol server in 2025. This is a major shift because it allows AI tools to access structured design context directly from Figma.

The Figma MCP Server Guide explains how teams can connect supported AI clients to Figma so that models can read design context, including components, variables, styles, layouts, and implementation details.

This matters because design systems have always struggled with translation. Design lives in Figma. Code lives in GitHub or GitLab. Documentation lives somewhere else. Usage data lives in analytics. Decisions live in people’s heads. MCP is one way to reduce the copy-paste layer between these worlds. It gives AI tools a bridge into the design source of truth.

That does not mean agents can safely redesign your system on their own. It means they can finally see more of the system.

This also explains why the dedicated design-to-code category, like Anima, Locofy, Builder.io, and v0, is being absorbed. Each of those tools tried to translate Figma frames into React using its own heuristics. With MCP, a general-purpose agent like Claude Code, Cursor, or Codex can do the same job and also read your codebase, your tokens, and your existing components in one pass. The bridge is no longer a separate tool. It is whatever agent is already in your workflow.

The interesting question is no longer “which design-to-code tool wins.” It is whether your design system gives any agent enough context to generate code that survives review. That depends on you, not the tool.

2. Quality automation is already part of the agentic foundation

Many teams already have pieces of agentic infrastructure without calling it that.

For example:

• automated accessibility checks with axe-core and Playwright,

• visual regression testing with Chromatic or Percy,

• token validation with stylelint rules,

• component usage checks in code,

• Storybook-based documentation and testing,

• CI pipelines that block broken changes.

These tools are not agents on their own, but they are the guardrails agents need. Without validation, AI just makes output faster. With validation, AI can start working inside a system. That is the difference.

3. Agents are already entering engineering workflows

Spotify is a useful example, even if it is not a design system case study. In Spotify’s background coding agent writeup, the team describes how internal agents help with engineering workflows, migrations, and large-scale maintenance work.

The lesson for design system teams is not “copy Spotify.”

The lesson is this:

Background agents make the most sense when the work is repetitive, rule-based, measurable, and reviewable.

That describes a lot of design system work: token migrations, component cleanup, documentation updates, accessibility checks, usage audits, deprecated prop detection, design-code drift. These are not glamorous tasks, but they are exactly the kind of tasks agents are good at.

What is emerging now

The next phase is not full autonomy, it is governed autonomy. Agents propose, humans approve, systems validate, changes are traceable. This is where design systems become much more interesting.

The point is not full delegation. It is delegating just enough that the system moves faster without losing oversight.

A designer agent watches Figma for drift

• components missing descriptions,

• variants that do not follow naming conventions,

• detached instances,

• local styles that should use variables,

• inconsistent spacing,

• missing accessibility annotations,

• components that have grown too many variants.

The agent should not automatically redesign everything. It should produce a report, suggest fixes, and escalate risky changes.

A developer agent catches token misuse in code

• hard-coded colors,

• incorrect token usage,

• custom components duplicating system components,

• deprecated props,

• inconsistent imports,

• missing tests,

• components that do not match Figma specifications.

Again, the value is not blind automation. The value is reducing the invisible drift between design and implementation.

A documentation agent stops your docs from rotting

• component usage guidelines,

• variant tables,

• accessibility notes,

• examples,

• changelogs,

• migration guides,

• design token references.

This is one of the easiest places to start because the risk is relatively low.

A QA agent runs the boring checks before merge

• accessibility tests,

• visual regression tests,

• keyboard interaction tests,

• responsive behavior checks,

• token compliance,

• browser compatibility,

• Storybook build validation.

This is where agentic systems become practical, because it can run boring checks consistently and tell the team where attention is needed.

Orchestration is what makes it agentic, not chatbot

The orchestrator is the most important part.

It coordinates the agents and decides:

• which changes are safe to automate,

• which changes need review,

• who should approve what,

• which tests must pass,

• when to create a pull request,

• when to roll back,

• when to escalate.

You give structured autonomy inside clear boundaries.

What may come next

By 2027 and 2028, design systems may operate very differently.

But this future will not arrive evenly.

Some teams will still be manually updating component docs.

Others will have agents monitoring usage, generating PRs, and surfacing design system drift before it becomes expensive.

The difference will not be prompts. It will be structure.

Tokens carry intent, not just values

Most tokens today are still treated as values.

{
  "color.primary": "#3B82F6",
  "spacing.md": "16px"
}

That is useful for consistency. But it is not enough for agents. Agents need to understand intent.

Shopify Polaris already shows the direction with semantic tokens that communicate purpose through naming and usage. The next step is richer metadata that agents can read directly.

For example:

{
  "color.action.primary": {
    "value": "#3B82F6",
    "intent": "primary action",
    "useFor": [
      "main action in a flow",
      "confirmation action",
      "high-priority CTA"
    ],
    "avoidFor": [
      "decorative backgrounds",
      "low-priority actions",
      "destructive actions without confirmation"
    ],
    "accessibility": {
      "minimumContrast": "4.5:1",
      "requiresTextContrastCheck": true
    }
  },
  "spacing.component.md": {
    "value": "16px",
    "intent": "standard internal component spacing",
    "useFor": [
      "default card padding",
      "form field grouping",
      "standard layout rhythm"
    ],
    "responsiveRules": {
      "compact": "spacing.component.sm",
      "comfortable": "spacing.component.lg"
    }
  }
}

This does not require science fiction. It requires better structure. Your tokens become more than reusable values; they become decision support.

Documentation becomes an executable context

Most documentation is written for humans. That will still matter. But agentic design systems also need documentation that machines can interpret.

That means documenting:

• intent,

• constraints,

• examples,

• anti-patterns,

• dependencies,

• accessibility requirements,

• edge cases,

• migration paths,

• ownership,

• approval rules.

This is where many design systems are weak. They explain how something looks, but they do not explain how decisions should be made. Agents need decision logic, and that logic has to live somewhere.

Runtime adaptation becomes possible, but risky

The most exciting future is also the easiest one to overhype. Components may adapt at runtime based on context.

For example:

<Button
  intent="primary-action"
  adaptsTo={["platform", "inputMode", "contrastPreference", "locale"]}
>
  Submit
</Button>

This kind of adaptation is reasonable.

A component can respond to:

• viewport,

• platform,

• input method,

• language,

• motion preference,

• contrast preference,

• density preference,

• accessibility settings.

That is helpful, but some forms of adaptation are much more sensitive. For example:

• adapting based on user hesitation, emotional state, conversion probability, inferred confidence, behavioral vulnerability.

That is where teams need governance.

The question is not only:

“Can the system adapt?”

The better question is:

“Should it adapt, who benefits, and how do we prevent harm?”

Agentic design systems will need more than tokens and components. They will need ethics, permissions, audit trails, and product principles. Otherwise, adaptive UI becomes manipulation with better tooling.

What can go wrong

• Agents can optimize locally while breaking the broader product experience.

• A developer agent might clean up code but break design intent.

• A documentation agent might confidently describe a component incorrectly.

• A designer agent might suggest consistency where the product actually needs difference.

• Without governance, agents can create drift faster than humans can notice it.

Design debt at machine speed

AI does not magically fix weak systems; it amplifies them. If your components are poorly named, your tokens are inconsistent, and your docs are outdated, agents will inherit that mess. Bad metadata creates bad output faster.

False confidence

AI-generated documentation often sounds correct even when it is wrong, and that is dangerous. Design system documentation is not just content, it is instruction. If agents and teams rely on incorrect guidance, the damage spreads quickly.

UX manipulation

Runtime adaptation can improve usability. It can also cross a line. If the system changes UI based on inferred hesitation, conversion likelihood, or emotional state, teams need clear product and ethics review. Not every adaptive pattern is user-centered. Some are just business pressure wearing a nice interface.

Governance gaps

Agentic systems need:

• approval rules,

• audit logs,

• rollback mechanisms,

• permission levels,

• test gates,

• ownership models,

• escalation paths.

Without these, “agentic” becomes another word for “uncontrolled.”

The goal is not to make agents autonomous everywhere. The goal is to decide where autonomy is safe, useful, and measurable.

Figma becomes a control surface

Figma is moving from a visual design tool toward a design system control surface.

That could include:

• managing component libraries,

• defining variables and modes,

• adding semantic metadata,

• previewing generated UI,

• reviewing agent-proposed changes,

• connecting design context to code tools,

• helping humans understand what agents are doing.

Figma is not the entire agentic system, but it can become one of the most important human interfaces into that system.

Visual judgment still matters

AI can generate layouts. That does not mean it understands taste, brand, timing, emotion, or product strategy. Designers still make the decisions that require judgment:

• what should feel premium,

• what should feel calm,

• what should feel urgent,

• where consistency helps,

• where consistency hurts,

• when to follow the system,

• when to evolve the system.

The more AI generates, the more valuable human judgment becomes, not less.

Designers move from making variations to defining intent

Designers will spend less time manually producing every variation. They will spend more time defining:

• intent,

• behavior,

• constraints,

• examples,

• quality bars,

• governance rules,

• evaluation criteria,

• approval models.

The designer becomes less of a component factory and more of a system architect.

Why structure beats prompts

The companies that win will be the ones that prepare their design systems for machine interpretation. That means they will:

1. Structure components for AI consumption

They will document not only what a component is, but how it should be used.

They will define: intent, variants, anatomy, accessibility, dependencies, anti-patterns, product examples, implementation rules.

2. Add intent to tokens

They will move beyond raw values and primitive naming.

{
  "color.action.primary": {
    "value": "#3B82F6",
    "intent": "primary action",
    "useFor": ["main CTA", "confirmation"],
    "avoidFor": ["decoration", "destructive actions"]
  }
}

Agents need meaning. Semantic structure gives them that meaning.

3. Build feedback loops

They will connect design system decisions to real product usage.

For example:

• Which components are used most?

• Which components are duplicated?

• Which tokens are overridden?

• Which variants are missing?

• Which patterns create accessibility issues?

• Which docs are most visited?

• Which components create the most support questions?

This is where design systems become measurable, not just maintained. Improved.

4. Use agents for boring, high-value work

The first useful agents will not be magical design partners. They will be boring, and that is good. They will: detect drift, update docs, open migration PRs, flag accessibility issues, find token misuse, summarize component usage, generate changelogs, and suggest cleanup tasks.

Boring is where trust starts.

What to do this week

1. Turn one component into a contract

Pick your most-used component. Write a one-page contract with five sections: intent, variants, rules, accessibility, anti-patterns. A markdown file is enough. Start with one component. Not fifty.

2. Add intent metadata to five tokens

Pick your five most-used semantic tokens. For each, add what it is for, what it is not for, and the accessibility requirement. JSON, README, or doc page. Whatever you already have.

Tools change. Structure compounds.

Agents are leverage. Leverage applied to a weak system breaks it faster. Leverage applied to a readable system builds compounding advantage.

The prompt is not the moat. The structure is.

Enjoy experimenting. 🙌

Romina

Mentioned links

Gartner: 40% of Enterprise Apps Will Feature AI Agents by 2026

Microsoft Design: Designs for the Frontier Future

Figma: Introducing Figma MCP Server

Figma Help: Guide to the Figma MCP Server

Figma: What is Model Context Protocol?

Shopify Polaris: Color Tokens

Spotify Engineering: Spotify’s Background Coding Agent

IBM Carbon: Color Tokens

IBM Carbon: stylelint-plugin-carbon-tokens

Anima

Locofy

Builder.io

v0 by Vercel

Chromatic Visual Testing

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

Design System Report 2026 🔗 Download the report

If you want a baseline for what "normal" looks like, read Zeroheight's State of Design Systems report. 147 companies surveyed. It is the only annual data I trust on how teams actually work, not how they say they work.

Wow, what a week of AI releases! First Claude Design and Opus 4.7, then Image 2 and GPT 5.5 model. I have been using and comparing all of them since launch.

Anthropic is building the AI-native version of the entire knowledge-worker stack. Claude Code for engineering. Claude Cowork for the rest of your job. Claude Design for anything visual. Opus 4.7 underneath all of it.

OpenAI shipped the response in the same week. GPT 5.5 for reasoning and long agentic work, easy to talk to, and detailed when the answer lands. ChatGPT Images 2.0 for generating images. I feel like everything is possible. I’m impressed.

Let’s start with Anthropic.

Opus 4.7: the model underneath

Whenever a new model comes out, I run the same tasks to see what has improved. With this model, I can say that at the start, the model felt faster than 4.6. But 2 days ago, Anthropic admitted that Opus 4.6 was made slower in March.

(jokes aside…)

After a few days of testing, Opus 4.7 is the first Claude release I cannot call a major upgrade. On design work specifically, it treats each screen as a fresh problem. Ask it to extend an existing pattern, and it forgets the pattern exists two steps later. It does not connect things.

The individual design suggestions are often better than what 4.6 gave me. But then again, not repeatable without additional instructions. I can run the same prompt twice on 4.7 and get two different directions, neither of which builds on the last. 4.6 was less ambitious per shot, but I could compound it. 4.7 needs more guidance, in every single prompt, to stay on track.

In practice it means you have to tell 4.7 exactly what you need, where it needs to connect in the existing system, and what the goal is. No shortcuts. No “you know what I mean.” Every prompt has to carry its own context.

Which is, conveniently, the argument I have been making for months in code is cheap, understanding is not and The Self-Healing Design System. AI agents get better the more structured context you feed them. 4.7 just turned that from a suggestion into a requirement. If your design system is not yet machine-readable, with tokens, component definitions, and written decisions the model can actually parse, 4.7 will feel punishing. If it is, 4.7 is the first model that actually rewards the investment.

• Coding wins across every Anthropic benchmark (CursorBench, Rakuten-SWE-Bench, their internal 93-task eval, Databricks OfficeQA Pro).

• A reasoning regression on NYT Connections: 94.7% down to 41.0%. A 53-point drop is not a rounding error.

• Stricter instruction-following. Per Anthropic’s migration guide: “4.7 takes the instructions literally and will not silently generalize.”

• Price stays flat at $5 per million input tokens and $25 per million output tokens.

• Effective cost is slightly up because the new tokenizer consumes 1.0 to 1.35 times more tokens per input.

Plus, two new features →

• Adaptive thinking replaces fixed thinking budgets. Set thinking: {type: 'adaptive'} and the model picks depth per sub-task.

• Extra high effort (xhigh) is a new tier between high and max. Many of the “Opus 4.7 is slow” complaints come from people reflexively maxing out effort. xhigh is usually the right answer.

My working rule. If you are on Pro and you are not doing engineering-grade work, default to Opus 4.6 for chat, Opus 4.7 only where reasoning depth pays for itself. For design-system work, Opus 4.7 is worth it, but only if you write precise prompts and use plan mode before execution. The best combo right now is Opus 4.7 for planning and then using GPT 5.5. (More about this below).

Claude Design: where your design system actually goes next

Claude Design, launched April 17, 2026, as a research preview. Anthropic’s own case studies claim that the final project is done with way fewer prompts.

Figma’s valuation dropped around $730M (4.26%) on the day Claude Design launched. Anthropic’s CPO resigned from Figma’s board three days before the announcement.

It is by far the easiest tool to pick up if you are new to AI. It is also a research preview with real gaps.

Here is what it actually does.

The interface.

Four starting templates: Prototype, Pitch Deck, From Template, and Design System.

Six inputs: images, text, codebase links, document uploads, web captures, saved design systems.

Four refinement tools: inline comments on elements, direct text editing, tweak sliders (colors, spacing, typography), and global design changes via chat. Export to PDF, PPTX, HTML, and Claude Code. (Export to Canva is listed on the page. It does not yet work.)

The workflow that matters to most.

Upload your design system, either as a Figma file, a GitHub repo, or a DESIGN.md file. Claude Design generates new work that respects your tokens. There is already a free repository at getdesign.md with DESIGN.md files for brands like Mastercard, Airbnb, and Ferrari. That tells you where this is heading.

I fed it our UI kit. It took around 10 minutes and burned a lot of tokens. The output was different from what I got piping Figma through MCP into Claude Code which surprised me. You see a preview of the interactive components immediately, and they are somewhat real. I would put them at around 70% Figma to code parity.

Compared to Figma Make, the gap is not subtle. Claude Design is faster, the range of outputs is wider, and the starting options are way more useful (also compared to Lovable, v0, ….).

Figma Make runs on Sonnet 4.5. Claude Design runs on Opus 4.7, with vision at 2,576 pixels and 3.75 megapixels, roughly three times the resolution of previous Claude models. The tool Figma is paying Anthropic to host is running on the slower, lower-vision model. The tool Anthropic ships directly is on the flagship.

Figma Make gives you a handful of layout variations inside the Figma canvas. Claude Design generates interactive pages, animated videos, pitch decks, mobile apps, and a first-draft design system in the same few minutes, and exports to HTML, PDF, or PPTX, or hands off directly to Claude Code.

If you are using Claude Code and have set up the skills, MCPs, then going to Claude Design feels like going back a few steps when you want to make prototypes.

Use cases, ranked by how much I trust them today:

1. Prototypes. If you are new to AI, it will be easy to start and get

2. Landing pages. Give it a reference URL and a tone. “Recreate this product page, but make it tongue-in-cheek” gets you 80% of the way there in four minutes.

3. Pitch decks. Use Claude (chat) to iterate the copy first. Paste the copy into Claude Design and ask for a deck or animated video.

4. Mobile app mockups. Claude Design takes screenshots of its own output and fixes overlapping text on its own.

My complaint list:

• Token cost is brutal. A mobile app with a full design system can burn a Pro plan’s daily quota in a single prompt.

• Output quality is inconsistent. Abstract illustrations are hit or miss. Expect to regenerate.

• No Figma-level granular control. You can tweak palettes, fonts and layout, but you cannot move a single element five pixels without prompting (which takes more time and tokens).

• Export to Canva is listed but broken.

Now let’s go to OpenAI releases.

ChatGPT Image 2.0

My observations:

• Visualizations are waaaay better than before;

• It understands styles and can replicate them in a better way

• Endless possibilities in doing styles (Anime, 90s video games, amateur photos… practically anything)

Some examples I did:

Create an illustrated, playful map of Sardinia with sport activities

Amateur photograph of a family portrait, on the beach in Italy, amateur composition, candid

Design a full-page modern website homepage for a crochet courses platform.

Style: cozy, warm, soft, playful, handmade aesthetic. Feminine but not childish. Inspired by Scandinavian + Japanese calm design mixed with craft culture. Clean but emotional.

Visual direction:

Soft pastel color palette (peach, cream, sage green, dusty blue, warm beige)
Subtle paper texture background
Hand-drawn floral illustrations, small birds, yarn icons, hearts
Rounded cards, soft shadows, organic shapes
Slightly imperfect, handmade feeling (not too polished)
Editorial composition with strong hierarchy

Tone:

Warm, inviting, supportive
Focus on creativity, calmness, and joy
Feels like a safe, cozy space

Avoid:

Corporate SaaS look
Sharp edges or harsh colors
Overly trendy AI/glossy aesthetics

GPT 5.5

OpenAI shipped GPT 5.5 a few days later, and it is the first model of theirs I would put next to Opus 4.7 without flinching.

5.5 is a steep change in coding, and it is easy to talk to. That combination is rare. It is slower than Opus in response time. When the response does land, it is more detailed and more structured. Architecture overviews are better. It can work longer without interrupting to ask what you meant.

It is also a better writer than previous OpenAI models. And it does not just execute the task I gave it. It starts suggesting what might be smart to add or change next. That shift, from “assistant that replies” to “agent that nudges,” is the real story with 5.5.

Where 5.5 pulled the most weight this week:

• Agentic knowledge work. This is the first OpenAI model that manages to be both a stellar senior engineer and a tool you can point at a spreadsheet, a research doc, or a rough brief. Crazy fast. Amazing inside the Codex desktop app.

• Long-running tasks. Opus 4.7 still needs hand-holding every few steps on big jobs. 5.5 runs further on its own. During the testing week, much of my team switched from Claude Code to Codex on GPT 5.5 for exactly this reason.

• Writing drafts that do not read like model output. The writing regression I keep hitting on 4.7 is not there on 5.5.

Where Opus 4.7 still wins:

• Plan quality. Opus 4.7’s plans have sharper insight and better attention to detail. If the quality of the plan decides the quality of the build, Opus is still my pick.

• Front-end and full-stack product work. 5.5 gets close. Opus is still a step ahead.

• Vibe coding without a plan. 5.5 is a great vibe coder with a plan. Without one, it is worse than Opus.

The working split. Opus 4.7 for the plan and for design-heavy front-end work. GPT 5.5 inside Codex for long agentic runs, research reading, and writing drafts. I switch between them inside the same task now, which is a strange feeling after two years of running almost exclusively on Claude.

For design-system work specifically, the pairing I am settling into is: plan in Claude with Opus 4.7, execute long audits and front-end build in Codex with 5.5, back to Claude for the doc generation.

Image 2 inside Codex.

The pairing I did not expect. Image 2 running inside Codex reads a whole database quickly, and connects to plugins without the usual setup tax. For anything that spans a DB and a handful of integrated tools, this is already the fastest setup I have used this week. I am still figuring out what it means for design-system work specifically, but it is the combination I keep reaching for.

Then I tried and used my Token Hunter game and applied Image 2 capabilities in Codex.

80/20 rule

The same phrase kept coming up in every video and every blog post I read this week. The 90/10 rule. AI generates 90% of the artifact in minutes. The last 10% is a human making colors, copy, and hierarchy choices.

I would say it is closer to 80/20. And the 20 that is still on me is not just polish. It is foundations, tokens., components, strategy, written design decisions, knowledge graph.

That is the real shift. Not “AI replaces designers.” Not “Figma is dead.” Just: your design system moved one layer up. It is your infrastructure.

Happy experimenting, and let me know how it goes. 🙌

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

OpenBridge design system (Lit-based web components) OPEN-SOURCED.

His Royal Highness Crown Prince Haakon and Prince Sverre Magnus of Norway officially launched a comprehensive, open-source code library for the maritime industry.

Kjetil Nordby : "By offering ready-to-use code, we are making it significantly cheaper and easier to adopt the standard for user-friendly, safety-critical design."

Kjetil Nordby and his team at the Oslo School of Architecture and Design spent eight years building it. 40+ industry, academic, and public partners.

Now you can easily create user-friendly OpenBridge 6.1 user interfaces for maritime and other industrial workplaces.

🔗 GitHub
🔗 Storybook
🔗 Figma file
🔗 Official site

I spent a few years collecting public design systems into my Airtable. I tracked what each system actually ships: tokens, GitHub repos. I have now used AI and gathered valuable insights.

The finding that surprised me most: almost no design system ships all the “layers”. They all make trade-offs. And the trade-offs follow a pattern.

The seven layers of a design system

A design system can serve its users in seven ways. I checked which of these layers each system makes publicly available:

What this tells you

This measures how many layers a system makes available, not how good any layer is. It also only measures what’s public. Some systems have excellent internal Figma libraries, Storybooks, and docs that score low here because the outside world can’t see them. I’m not scoring quality. I’m mapping coverage.

A note on the dataset

The 158 systems were collected from public sources: documentation sites, GitHub repositories, Figma community files, npm registries, and design system directories. Each entry was manually verified against its live URL. Some systems required deeper digging than others.

What the data shows

89% have code examples. That’s the first layer teams build. But after that, each subsequent layer drops off sharply. Only 37% add usage guidelines. Only 21% document accessibility. Only 13% include content guidelines.

Three systems scored a perfect 7: Polaris (Shopify), Paste (Twilio), and eBay Playbook.

The leaderboard

Look at the top. Shopify. Twilio. Workday. Microsoft. Salesforce. These are companies with dedicated design infrastructure teams and years of investment. The gap between them and the average is not small.

Accessibility is still a lower priority

Only 34 systems explicitly mention accessibility. That’s 21%.

4 systems have accessibility issues flagged. Meaning someone noted problems.

Some of these systems probably have accessible components under the hood. They just don’t document it or surface it as a priority. But if you don’t talk about it, your adopters won’t prioritize it either.

The tech landscape

React dominates. But the picture is more interesting than “React won.”

React is the default. More than half of all systems use it. No surprise.

Web Components are the quiet second wave. These are not startups experimenting. These are large organizations making a deliberate bet on framework-agnostic components.

Tailwind is the new entrant. 8 systems: shadcn/ui, daisyUI, Flowbite, Tremor, HeroUI, Nessie, Nuxt UI, Park UI. All relatively new. All growing fast. The utility-first, copy-paste model is rewriting the distribution rules.

15 systems support 3+ technologies. Carbon (IBM) leads with 6: React, Vanilla JS, Angular, Vue, Svelte, Web Components. That’s not a design system. That’s a platform.

The Tailwind gap

This one surprised me.

There are 8 Tailwind-based design systems in the dataset: shadcn/ui, daisyUI, Flowbite, Tremor, HeroUI, Nessie, Nuxt UI, Park UI. They are some of the fastest-growing projects in the ecosystem. shadcn/ui alone has 112K GitHub stars.

But across all 8 systems, not a single one documents accessibility. Not one includes content guidelines.

This isn’t a criticism of Tailwind. It’s a pattern about what happens when the distribution model is “copy this code.” The copy-paste philosophy solves the adoption problem brilliantly. But it skips the layers that make a design system more than a component starter kit. When you own the code, nobody is responsible for documenting when to use it, how to make it accessible, or how to write the words inside it.

The question is whether these systems will fill in those layers as they mature. Or whether the “you own it, you document it” model means those layers never get built centrally.

Tone of voice

Only 21 systems out of 158 include content guidelines. 13%.

But look at which 20. Sainsbury’s. Polaris (Shopify). Atlassian. Lightning (Salesforce). NHS Digital. Pharos (JSTOR). Bolt. Workday Canvas. Paste (Twilio).

These are retail, fintech, healthcare, government, and enterprise SaaS. Industries where getting the words wrong has consequences. An error message that says the wrong thing in a banking app isn’t just bad UX. It’s a compliance risk. A healthcare system that uses inconsistent terminology isn’t just confusing. It’s dangerous.

The systems that ship tone of voice aren’t doing it because they’re more thorough than everyone else. They’re doing it because their industry demands it. Content guidelines aren’t a “nice to have” when regulators read your interfaces.

But compliance isn’t the only reason. When 10 teams use your Button component and each writes different label text, different error messages, different confirmation dialogs, your product speaks in 10 different voices. Content guidelines aren’t a legal checkbox. They’re how you keep the experience consistent at scale. Without them, your design system controls how things look but not what they say. That’s half a system.

The documentation gap

89% of systems have code examples.

But only 37% tell you when to use a component. Only 21% tell you how to make it accessible. Only 13% tell you how to write the content inside it.

33 systems have code examples but no usage guidelines and no accessibility documentation. They show you how to implement a button. They don’t tell you which button to use, when, or why.

A design system without usage guidelines is a component library. A component library without accessibility documentation is a liability.

How many components do the top systems actually ship?

This one gets misunderstood constantly. People equate “big design system” with “lots of components.” The data says otherwise.

The range is massive.

More components is not better. More components is more to maintain, more to document, more to keep accessible. The systems that score highest aren’t the ones with the most components. They’re the ones that document the components they have.

How many design tokens power these systems?

I counted CSS custom properties and documented tokens across the top systems. Some counts are verified from the source code. Others are estimates from documentation.

The popularity contest nobody asked for

npm downloads measure one thing: who gets npm installed. Open community libraries naturally dominate here. Enterprise and internal systems are consumed behind firewalls, not through public registries.

Stars don’t mean what you think

I almost didn’t include this chart. But the myth of “more stars = better system” needs data thrown at it.

The architecture fingerprint

I divided each system’s token count by its component count. The ratio tells you something fundamental about design philosophy.

I’ve thrown a lot of numbers at you. Here’s what they change about how I’d build a design system today.

1. Write usage guidelines before building more components.

2. Add accessibility documentation now.

3. Add Storybook before another component.

4. Ship decision logic, not just components.

5. Content guidelines are required if you’re regulated.

6. Fund it like an infrastructure.

Why this matters more than it used to

I’ve spent the past year building agentic design systems. AI agents that audit tokens, compose patterns, generate documentation, and open pull requests. I wrote about the architecture in Parts 1, 2 and 3 of that series.

But here’s the thing I keep running into: agents can only work with what’s documented. An AI agent can’t use a component that has no usage guidelines. It can’t check accessibility if accessibility isn’t described. It can’t compose a pattern from a system that only ships code and a landing page.

Everyone is talking about AI agents for design systems. This data shows that many systems aren’t ready for a human to use properly, let alone a machine.

Fix the layers first. The agents will follow. 🙌

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

MemPalace / Free, local AI memory system that stores your entire chat history and makes it searchable across sessions. 96.6% recall, no cloud, works with Claude/Cursor/ChatGPT

🔗 Link

In Part 1 and 2, I made the case that design systems are the semantic layer that makes AI-assisted design possible. The understanding, not the code, is the asset.

Now let’s talk about the machinery AND the judgment calls. The architecture, the self-healing loop, what AI genuinely cannot do, and three phases you can start this week.

The architecture

This is the architecture I’ve built over the past year.

At the center: Claude Code as the orchestration layer. Connected via MCP to Figma (through my Tidy plugin), to GitHub, to Storybook, to PostHog (analytics) , to Granola (meeting notes), to Sentry for error monitoring, to the documentation layer, and to the Observatory dashboard.

👋 A note on tooling:

Claude Code is not the only option here. Because everything connects through MCP, the orchestration layer is swappable. I’ve tested Cursor, Codex, and other AI coding tools in this setup. I also run the same exercises across new models whenever they come out (Gemini, GPT 5.2 through 5.4, Llama, Mistral) to benchmark how they handle token naming, component composition, and system-level reasoning. Claude Code consistently delivered the best results for design system work, particularly in reasoning about component relationships and token semantics. But the architecture doesn’t lock you in. If a better tool shows up tomorrow, you swap the center, and everything else stays the same. That’s the point of building on a protocol, not a product.

The loop is:

1. Watch. Detect drift in tokens, components, and docs.

2. Analyze. Score severity, prioritize fixes.

3. Execute. Generate PRs, update docs, sync tokens.

4. Observe. Verify results and loop back.

But here’s the thing. This architecture only works because the foundation is solid. Without clean token naming, without component descriptions, without intent documentation, the agent has nothing meaningful to work with.

Read more

This year I gave a talk at the Into Design Systems conference called Agentic Design Systems. The response genuinely caught me off guard. Thank you to everyone who showed up, stayed engaged, and sent those messages. It means more than you know.

A year ago, I already presented at IDS and talked about context-aware design systems. A vision. Something we could see coming but couldn’t quite build yet.

This year, I came back with tools, numbers, and failures. Real ones.

This series covers everything from that talk. Not as a transcript, but as something you can actually use. If you’re building a design system today, or thinking about what AI means for your system, this is for you.

Let’s start with the shift that changes everything.

Your design system is infrastructure

Before anything else, I need to set one thing straight.

A design system is not a side project. It is not a nice-to-have. It is infrastructure. The same way your CI/CD pipeline is infrastructure. The same way your database is infrastructure.

And right now, in 2026, design systems are more important than they have ever been. Every product team is shipping faster than ever. AI is generating code at scale. And the only thing standing between your product and total inconsistency is the system that governs it.

Design systems reduce rework. They enforce brand. They catch accessibility issues before your users do. If you still need to justify your design system to leadership, frame it as infrastructure. Because that’s what it is.

The design system is the API that allows AI to build your product safely.

That’s not a metaphor. That’s literally what’s happening.

The numbers that should wake you up

Let me set the scene with what happened in the 12 months between IDS 2025 and IDS 2026:

• 28+ frontier models released by 6 major labs in under 10 months

• $226 billion invested in AI. Nearly 2x the year before.

• 84% of developers now use AI tools daily

• 41% of all new code written in 2025 was AI-generated

Claude Code hit a billion dollars in revenue in under 12 months. The MCP ecosystem went from 100K to 8 million downloads. Gartner says 40% of enterprise apps will embed AI agents by end of this year.

This is the environment your design system lives in. Code is being generated faster than anyone can review it.

And that changes everything about how we think about governance.

The economics have flipped

When code is cheap and understanding it is expensive, architecture must optimize for the impermanence of code.

We all know by now that developers using AI agents ship faster. Studies show a 39% productivity increase. But the interesting part is where the gain comes from. It's not that people write more code. The work shifts from syntactic to semantic. From "how do I write this" to "what should this do and why."

That’s exactly the shift design systems need to make.

A developer can generate a button component in 30 seconds with AI. But that button won’t know it should use your danger token inside an alert. It won’t know it should be secondary inside a card. It won’t respect your spacing scale.

The code is free. The understanding is the expensive part.

And that understanding? That’s what your design system encodes. Your tokens, your naming conventions, your component intent, your usage guidelines. That’s the real asset.

So when people ask me “will AI replace design systems?” I tell them: AI makes design systems more critical than ever. Because AI generates code. Design systems generate understanding.

How an agent actually works

Let me make this concrete. One story runs through the entire talk: a team needs a destructive confirmation dialog.

A developer says: “I need a confirmation dialog for deleting a workspace.”

Watch what happens when an agent handles this:

1. Reading context. It pulls in your component index, your token structure, your usage guidelines.

2. Thinking. It knows Dialog exists. It knows Button has a destructive variant. It knows Alert has a warning slot.

3. Planning. Dialog + Alert + two Buttons. Destructive primary, secondary cancel. color.bg.danger for the action, not color.bg.primary.

4. Acting. It assembles the pattern, applies the right tokens, and generates the code.

What makes it agentic is three things: autonomy, tool use, and feedback loops. It doesn’t just answer a question. It takes action, observes the result, and adjusts.

But here’s the key: none of this works unless the agent has something to read. The components need to be described. The tokens need intent. The patterns need reasoning.

That’s what the rest of this series is about.

Intent changes everything

The flow looks like this:

Intent (natural language) -> Context (extracted dimensions) -> System output (specific guidance)

“I need a confirmation dialog for deleting a workspace” is the intent.

The system extracts five dimensions from that: component type, action severity, user flow, token scope, platform. These are the lenses the agent looks through.

The output isn’t a vague suggestion. It’s specific: Dialog + Alert + 2 Buttons. color.bg.danger token mapping. “Always pair with cancel” rule. A link to the Dialog component in Figma. A suggested composition template.

The agent doesn’t guess. It reads your system’s rules through these context layers.

This only works if those rules exist.

MCP: USB for AI

For any of this to work, the agent needs to connect to your tools. That’s where MCP comes in.

Model Context Protocol is a standard way for AI agents to connect to external tools. Think of it as USB for AI. Instead of building custom integrations for every tool, you expose your tools as MCP servers and any AI agent can use them.

My most used MCPs: Figma, GitHub, Storybook, Chromatic, Granola, Notion, Jira, Stylelint, Linear, Mintlify. Each one gives the agent a different slice of context.

CLI vs MCP: you need both

A practical question I get a lot: do I need MCP for everything?

No. CLI and MCP serve different purposes.

CLI is for speed. Direct command execution. Simple setup. No servers, no schemas. Fast experimentation. Designers can start immediately with local tools. Less context overhead, fewer reasoning loops. Great for single-tool workflows, like tasks happening entirely inside Figma.

Here’s what CLI looks like in practice.

I built a token command that resolves Figma token values straight from the terminal:

$ token color.bg.danger
→ #DC2626 (alias: primitives/red-600)

Or composing a full UI pattern with one shell script:

$ ./patterns/run-pattern.sh destructive-confirmation
→ Creating frame in Figma...
→ Dialog + Alert + Button(destructive) + Button(secondary)
→ Tokens bound: color.bg.danger, color.text.on-danger
→ Done. Check your Figma canvas.

No MCP server running. No schema negotiation. Just a direct HTTP call to a Figma plugin that exposes a local API, and the pattern appears on your canvas (will share more in part 3). You can read token values, compose patterns, and run audits without any agent infrastructure. That’s the power of CLI: you go from zero to useful in minutes.

MCP is for scale. When the agent needs to orchestrate multiple tools. Connect Figma, GitHub, Storybook, docs, CI in one flow. The agent understands structured design data: components, tokens, variants. Changes propagate end-to-end from design to code to docs. It enables autonomous agents that detect, analyze, plan, and fix. Standardized protocol that runs in CI pipelines. Scales across teams.

Where MCP shines is when the agent needs to connect the dots across tools. “A token changed in Figma. Which components use it? Which pages are affected? What’s the traffic on those pages? Should I open a PR?” That’s four different data sources (Figma, GitHub, PostHog, the knowledge graph) orchestrated in one flow. CLI can’t do that. MCP can.

CLI for speed. MCP for scale. The best systems use both. We used both in our setup: Tidy’s HTTP API for CLI-speed pattern composition, with MCP’s structured component and token data for the orchestration layer.

The three layers that make components machine-readable

This is where most design systems fall short. I see teams with a component library and tokens, but the agent can’t do anything useful with them because they’re missing layers.

There are three layers an agent needs:

Layer 1: The Index

What exists, what uses what, what depends on what.

The agent knows Dialog exists. It knows Button has 4 variants. It knows Alert connects to both. This is the relationship map.

Without the index, the agent is blind.

Layer 2: Metadata

This is the how and why.

The component description for Button says: “use the destructive variant for irreversible actions, always paired with a cancel option.”

That single sentence is what told the agent to add a secondary cancel button. Without metadata, the agent knows components exist but not when to use them.

Layer 3: Reasoning

The selection logic.

For a confirmation dialog, compose Dialog + Alert + two Buttons. For a login form, compose Input + Input + Button.

This is the playbook. Without reasoning, the agent assembles random parts.

Most design systems today have some of layer one, very little of layer two, and almost none of layer three. That’s the gap we need to close.

And closing it is not a year-long project. Writing 554 component descriptions took me one session with AI.

Context makes the same component behave differently

Here’s what context-aware means in practice.

Same component: Button. Three different contexts:

• In an alert: use bg-danger. Intent: destructive action. Always pair with a cancel button.

• In a card: use bg-neutral. Intent: secondary action. Don’t compete with page-level CTAs.

• In the nav: use bg-brand. Intent: conversion action. One per nav bar maximum.

Same Accordion component. FAQ gets question-phrased headers (”How do I reset my password?”). Settings gets noun-phrased headers (”Notification settings”).

The agent writes different docs for each because it knows WHERE the component lives, not just what it is.

But here’s what nobody tells you: if the agent knows where a component lives, it can infer most of this automatically.

Take Accordion. The agent sees it in FAQ, in Settings, and in Checkout. Same component. Three different contexts. Now it can write three different sets of documentation without anyone asking.

It figured that out by looking at 34 instances across 6 products. It can generate do/don’t examples. It can prioritize: a component on homepage and checkout is more critical than one only in admin.

The agent doesn’t just know the component spec. It knows the business context. And you get this for free if you map which pages represent which products.

Plant seeds, not trees

I showed two videos in the talk.

First one: seeds. You plant them. You water them. You wait. Growth is slow but it’s real.

Second one: trees. You buy them fully grown and drop them into your garden. Looks impressive on day one.

Every team I talk to wants the tree. They want the fully autonomous agent that fixes everything. But that’s not how this works.

You have to plant seeds. You have to build the foundation first: the naming conventions, the token structure, the component descriptions, knowledge graph. Then the automation grows on top of it.

Without structure, AI amplifies noise at scale. With structure, it amplifies understanding.

What this means for you

If you take one thing from this part of the series, let it be this:

The asset is not just the code. The asset is the understanding.

Your design system’s value isn’t in the React components or the Figma library. It’s in the naming conventions, the token intent, the component metadata, the usage reasoning, your knowledge graph. That’s what AI reads. That’s what makes the difference between a generic button and a button that belongs in your product.

Start there.

The rest of the series shows you how.

Next up: Part 3: The Self-Healing Design System where I’ll show the architecture, the MCP connections, the knowledge graph, and the self-healing loop that catches problems before they ship.

Stay tuned,
Romina

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

Granola

If you want to make an extra step when setting up an agentic design system, connect meeting notes to Claude via MCP and start using Granola. 🔥
I use Granola and as additional data layer.

Granola is an AI notepad that transcribes your calls in the background.

NO MEETING BOTS.
No weird "AI assistant has joined the call."

You take notes as you normally would, and Granola automatically turns them into structured summaries, action items, and next steps. It works on both Mac and Windows.

But here's where it gets powerful.

Granola supports MCP (Model Context Protocol).
That means your meeting notes flow straight into Claude or ChatGPT as searchable, queryable context. 🤯

Instead of digging through old notes, I ask:

* "What did we decide about the component API last Tuesday?"
* "Pull all action items from client calls this month."
* "Summarize feedback from our last three design reviews."

5 seconds, boom, done. ✅

My workflow:

↪️ Meeting happens. I add quick notes. Granola transcribes in the background.
↪️ Meeting ends. Summary, action items, and next steps are ready instantly.
↪️ Recipes (pre-made prompts) help me write follow-ups or prep for the next call.
↪️ Zapier pushes action items to Linear, Jira, wherever work lives.
↪️ MCP connects it all to Claude. Every past conversation becomes a context I can query.

Try it and thank me later ☺️ I've got a link to a free month

Recommended read → UX + AI written by ✨

This is a space for curious minds who care about how we design, build, and think about digital products in a world shaped by AI. Really recommend you follow Ileana and learn something new every week.

UX + AI

Product in the Age of AI: When Product Manager and Designer Skills Start to Overlap

Over the last two years, the rise of AI has reshaped the design world…

Read more

9 months ago · 66 likes · 28 comments · Ileana, Karo (Product with Attitude), Elena | AI Product Leader, and Just J

🔗 Link

I am not affiliated with any of the suggested tools

I know what you’re thinking.

“Vector databases? That’s for AI engineers and data scientists. What does that have to do with my design system?”

Here’s the thing: Vector databases solve a problem that design systems desperately need to solve, too.

They organize information by meaning, not just by structure.

And that changes everything.

The Problem With How We Organize Design Systems Today

Right now, your design system is probably organized like a SQL database.

You have rigid hierarchies:

• Components → Buttons → Primary → Hover State

• Tokens → Color → Background → Primary

It’s clean. It’s logical. It works.

But here’s what it doesn’t do: It doesn’t help you find things based on what they mean or why you’d use them.

When a designer asks, “What should I use for a destructive action?” they have to translate that intent into your taxonomy. Is that a “danger button”? A “negative action”? A “warning state”?

You didn’t have to memorize the exact folder structure in your brain. You just had to know the right keywords.

But what if your design system could understand intent?

How Vector Databases Actually Work

Let me show you what I mean.

Vector databases don’t store data in rows and columns. They store meaning as high-dimensional numerical coordinates.

Here’s a simple example:

When you search for “king” in a vector database, it doesn’t just find exact matches. It finds concepts that are semantically similar:

• “queen” (same domain, different gender)

• “monarch” (same meaning, different word)

• “ruler” (related concept)

The database understands that these concepts cluster together in meaning-space.

Now imagine applying that to your design system.

What Changes for Humans

You Can Search by Intent, Not Just by Name

Instead of browsing through component categories, you could ask:

“Show me all patterns that convey urgency”

And your design system would return:

• Error messages

• Warning banners

• Destructive action buttons

• Toast notifications with alert icons

• Red status indicators

These components live in completely different parts of your taxonomy. But they share semantic meaning.

That’s the power of meaning-based organization.

You Can Finally Solve the “New Component vs. Variant” Debate

I’ve sat through countless design system meetings where teams debate:

“Do we need a new component, or is this just a variant of what we have?”

I’ve seen this firsthand. When you’re looking at a system with 50, 80, even close to 100 components, the overlaps become invisible. Manual audits catch some of them. But naming differences, context differences, and organic growth across teams create duplicates that no spreadsheet review will surface.

Vector logic could actually quantify similarity between components.

Compare two components based on:

• Visual embeddings (how they look in Figma)

• Code structure (how they’re built)

• Token usage (what design decisions they share)

• Usage context (where they appear in products)

If two components score high similarity across these dimensions, you probably don’t need both.

You might be wondering, “How accurate is this really?”

That’s fair. But here’s what I’ve learned: You don’t need perfect similarity scores. You need better visibility into what you already have.

Even a rough similarity map helps you spot duplicates that manual audits miss.

What Changes for Agents

AI Tools Actually Know What to Use

Here’s where it gets interesting for agentic design.

Right now, when an AI tool generates a UI, it relies on your component names and descriptions. It’s essentially doing keyword matching.

But with vector-based context retrieval, the AI could understand:

“I’m building a form validation error. What components, patterns, tokens, and accessibility guidelines are semantically related to this task?”

The system retrieves:

• Similar error patterns from your existing designs

• The correct tokens (not just “red” but “color.feedback.error”)

• Accessibility requirements for error announcements

• Validation timing patterns

• Microcopy guidelines for error messages

All pulled together by meaning, not by manual tagging.

Design Tokens Could Become Behavioral

Traditional tokens store values: color.blue.500 = #3B82F6

Vector-inspired tokens could store behavioral meaning:

• How assertive (0.8 on a scale)

• How calm (0.2)

• How noticeable (0.9)

Now imagine an adaptive interface that reads the user’s context and adjusts its tone.

Picture a checkout flow. The payment fails. Instead of the UI just swapping in a red banner, the entire interface shifts. Visual assertiveness dials down. Calmness increases. The system isn’t just showing an error state. It’s modulating the experience to match the emotional weight of the moment.

A celebration moment? It cranks up energy and noticeability.

The same components, but contextually tuned based on meaning vectors, not just static values.

Components Gain Semantic Elasticity

In agentic systems, context determines behavior.

Take a toast notification. It can:

• Confirm a successful action

• Warn about a risky operation

• Inform about system status

• Celebrate an achievement

Right now, you’d handle these with separate variants or different components entirely.

But with vectorized meaning, a single component could adapt based on detected intent.

The system reads the context (”this is a celebration”) and adjusts:

• Color intensity

• Animation style

• Icon selection

• Duration on screen

All semantically informed, not hardcoded.

Compare that to manually coding every possible variant upfront. The difference is massive.

The Reality Check

Let me be honest: Most design systems aren’t ready for this yet.

This isn’t because the technology doesn’t exist. Vector databases are mature. Embedding models are accessible.

The challenge is conceptual.

We’ve built design systems around structure: hierarchies, taxonomies, strict naming conventions.

Shifting to meaning-based organization requires rethinking:

• How we document components

• How we describe patterns

• How we train our teams

• How AI tools interact with our systems

It’s a fundamental shift from “what is this thing called?” to “what does this thing mean?”

What This Actually Looks Like

You don’t have to rebuild your entire design system around vectors tomorrow.

But you can start thinking differently today.

Here’s what that might look like:

Start with documentation:

• Add semantic descriptions to components: “This pattern expresses urgency and requires immediate attention.”

• Tag components with intent, not just categories: “confirmation,” “prevention,” “celebration.”

• Describe usage contexts: “Use when the user needs reassurance that their action succeeded.”

Experiment with embeddings:

• Generate vector embeddings for your component descriptions

• Build a simple similarity search

• See what clusters emerge naturally

Augment, don’t replace:

• Keep your existing taxonomy

• Layer semantic search on top

• Let both approaches coexist

The next generation of design systems will likely blend:

• Token databases (structured facts)

• Vector databases (semantic meaning)

• Context engines (runtime reasoning)

➡️ That’s how you get agentic design systems. Systems that understand why a component exists, not just what it’s called.

Try This

If you’re ready to experiment, here’s where to start:

1. Pick 10-20 components from your system

2. Add a semantic description for each: What’s its purpose? When would you use it? What feeling does it convey?

3. Use an embedding model (OpenAI’s text-embedding-3-small works well) to generate vectors

4. Run similarity comparisons between them

5. Look at what clusters together

You might discover patterns you didn’t know existed.

You might find duplicates hiding under different names.

You might see how your system could be organized by meaning instead of taxonomy.

And that’s when design systems start to get really interesting. 🙃

Next week, I will share more about Agentic Design Systems, my setup, and MCP. ✨

Stay tuned,
Romina

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

Building Effective AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned

AI agents suffer from the same problem as large design systems:

Context collapse. A new 55-page paper on terminal coding agents explains why.👇

AI agents in long sessions forget their instructions, bloat their context, and start making bad decisions.

🔗 Link

I am not affiliated with any of the suggested tools

Everyone wants to add AI agents to everything right now. Your design system is no exception.

Someone on your team has already suggested it. “What if we built an agent that validates token usage?”

Let me give you a framework to figure out when an agent actually makes sense, when a simple workflow does the job, and when you should just write a shell script and move on with your life.

First, what is an agent?

An agent is an LLM that can use tools and take actions. Not just answer questions. Act.

That’s the key difference from a regular AI chat. When you ask ChatGPT or Claude a question, it generates a response and stops. It lives entirely inside the conversation. It can’t open your files, check your codebase, run a command, or push a commit. It can only talk.

An agent can do all of those things. It has access to tools such as your file system, terminal, APIs, design token files, and Figma. When you give it a task, it doesn’t just tell you what to do. It reads your code, finds the problem, writes a fix, runs the tests, and tells you what happened. Then it decides what to do next based on the result. If the tests fail, it reads the error, adjusts, and tries again.

Here’s what that looks like in practice. You tell an agent: “Check if our Button component matches the Figma design.” The agent:

1. Connects to Figma’s API and pulls the design specs for the Button component.

2. Reads your component source code to understand the current implementation.

3. Launches a browser using Playwright, navigates to your Storybook, and takes a screenshot of the rendered Button.

4. Compares the screenshot against the Figma design and flags differences: wrong padding, missing hover state, border-radius off by 2px.

5. Writes a summary with specific suggestions and the exact lines of code to change.

No single tool does all of that. The agent stitched five tools together on its own and decided the order. That’s the difference. A chat would have told you how to do the comparison. The agent did it.

So, you tell it what you need, and it figures out the steps. Sometimes it asks for clarification. Sometimes it goes down the wrong path and corrects itself. Sometimes it nails it on the first try.

The other key difference is from a workflow: an agent chooses its own path. A workflow follows steps you defined in advance. When the task is predictable, a workflow wins. When the task requires adapting to what it finds along the way, that’s where agents earn their keep.

How do you actually make an agent?

You don’t need to write code to use an agent. Tools like Claude Code, Cursor, and GitHub Copilot are agents you can use right now. Open a terminal, point Claude Code at your codebase, and ask it to do something. That’s it. You’re using an agent.

But if you want to build your own, the format is simpler than you’d expect. At its core, an agent is just three things:

1. Instructions. A markdown file or system prompt that tells the agent who it is, what it knows, and how it should behave. Think of it as the job description for your intern.

2. Tools. What the agent can actually do. Read files, search code, call APIs, run commands, edit files. You decide what to give it access to.

3. A loop. The agent reads its instructions, picks a tool, uses it, looks at the result, and decides what to do next. It keeps going until the task is done or it gets stuck.

That’s the whole architecture. Instructions, tools, loop.

For design systems specifically, the most common entry points are:

• Claude Code with a CLAUDE.md file. You write a markdown file describing your design system’s conventions, token structure, component patterns, and coding standards. The agent reads it before every task. This is the lowest-effort way to get a design-system-aware agent.

• Custom MCP servers. The Model Context Protocol lets you expose your design tokens, component docs, or Figma data as tools an agent can query. Your agent can now look up your actual token values, not guess at them.

• SDKs for full control. Anthropic’s Agent SDK, OpenAI’s Assistants API, and frameworks like LangChain let you build agents programmatically. More power, more complexity. Only go here if the simpler options aren’t enough.

You don’t need to start with SDKs. Start simple with Claude Code and a well-written CLAUDE.md file. Start there.

Agents have opinions

And agents have opinions. A recent study of 2,430 Claude Code interactions found that in 12 out of 20 task categories, the agent chose to build a custom solution rather than recommend an existing tool. Asked to add feature flags? It builds a config system from scratch instead of reaching for LaunchDarkly. Asked about authentication? It implements JWT + bcrypt rather than suggesting Auth0.

This matters for design systems. Point an agent at your token validation problem and it will happily build you a custom solution. That might be exactly what you need. Or you might have been better off with an ESLint plugin that already exists. The agent won’t make that call for you. You have to.

The hype is real, but so is the waste

Peter Steinberger, creator of OpenClaw (the fastest-growing GitHub project ever), just joined OpenAI. His mission: “build an agent that even my mum can use.” Gartner published a report on February 13 about “context graphs” as essential infrastructure for agentic systems. Enterprise is all-in.

But Anthropic, the company behind Claude, says something much more grounded in their “Building Effective Agents” guide: find the simplest solution possible, and only increase complexity when needed.

That’s worth repeating. The company selling you AI agents is telling you not to build agents unless you have to.

Why? Because agents trade latency and cost for better task performance. They consume roughly 4x more tokens than simple chat interactions. Multi-agent systems? Try 15x. And when something goes wrong, you don’t get a nice red error message. You get a token bill that looks like someone put an API call inside an infinite loop.

For most design system work, a workflow or a well-written script will outperform an agent. Less cost, faster execution, more predictable results.

By the way, these are typical token drivers:

• System + tool schemas → High upfront cost

• Planning / reasoning loops → Medium–high

• Tool outputs re-ingested → High

• Memory retrieval → Medium

• Self-reflection / retries → High

✨ A simple chat = 1 request → 1 response
✨ An agent = plan → act → observe → reflect → retry

Agent Skills are modular capabilities that extend AI coding assistants. Each skill consists of a SKILL.md file with instructions, plus optional scripts and templates. In December 2025, Anthropic released the Agent Skills specification as an open standard, and OpenAI adopted the same format for Codex CLI and ChatGPT. Skills are model-invoked—the AI automatically decides when to use them based on context.

🔗 https://skillsmp.com/

A five-question checklist

1. Is the task complex enough?

If the task follows the same steps every time, you want a workflow. If it requires judgment, adaptation, and handling unexpected situations, you might want an agent.

Token linting is a workflow. You know the rules. Check if raw hex values are used instead of tokens. Flag primitive tokens used directly in components. Run it on every PR. Done. No agent needed.

But reviewing a new component design against your entire design system’s guidelines, considering context, brand, accessibility, and platform constraints? That requires judgment. That’s agent territory.

2. Is the task valuable enough?

If each task run saves less than $0.10 of human time, use a workflow. If it saves more than $1.00 per run, an agent starts making economic sense.

Checking a file for unused imports? Pennies. Not worth an agent.

Migrating 200 components from one token schema to another, where each component needs contextual decisions about which new token maps to the old one? That’s hours of human work per component. An agent pays for itself on the first run.

3. Are all parts of the task doable?

This one trips people up. If your agent needs to access Figma’s internal rendering engine, read a designer’s mind about intent, or make pixel-perfect visual comparisons without any ground truth, you don’t have an agent problem. You have a scope problem. Reduce it until every step is technically feasible.

4. What is the cost of error?

High cost of error means read-only access and human-in-the-loop. Low cost of error means you can let agents run autonomously.

An agent that suggests documentation updates? Low risk. A human reviews before publishing. Let it run.

An agent that automatically pushes token changes to production across 12 codebases? Extremely high risk. One wrong semantic mapping, and your entire product suite has the wrong error colors. Keep this read-only, with human approval gates at every step.

5. Can you trust the output?

There’s a design systems angle to agents that almost nobody is discussing yet. Design systems are trust infrastructure.

Teams adopt your tokens, components, and patterns because they produce consistent, predictable results every time. Agents introduce variability. Run the same prompt twice, and you might get two different outputs. That’s fine for a blog draft. It’s a problem when the agent is deciding which semantic token maps color.background.danger across your component library.

So before you deploy an agent into any design system workflow, ask yourself: is the output deterministic enough that teams can rely on it? Can you audit what the agent did and why? Can someone else reproduce the result? And when the agent makes a choice, can it explain its reasoning in terms your team actually understands? If the answer to any of those is no, you don’t have an agent problem. You have a governance gap. Close it before you ship.

Three core principles for agents from Anthropic:

1. Simplicity in design

2. Transparency → explicitly show planning steps

3. Careful ACI (agent-computer interface) → invest heavily in tool documentation and testing

Applying this to real design system work

Let me walk through five common scenarios.

Token validation → Workflow

The rules are static. You know exactly what correct looks like. Check if raw hex values are used instead of tokens, flag primitives used directly in components. AST parsing and token matching are solved problems. Each individual check is cheap, and false positives are just noise.

Write a linter. Run it in CI. Done.

Component documentation generation → Agent with human review

This one gets interesting. Reading code, extracting props, understanding usage patterns, writing clear descriptions. There’s real judgment involved. And documentation is the #1 complaint about every design system, so the payoff is high.

But bad docs are annoying, not destructive. So scope it to generating drafts. The agent handles the tedious extraction and first pass. You handle the voice and accuracy check. A human approves before merging.

Design review against guidelines → Scoped agent

Context matters enormously here. A red button is fine in a destructive action confirmation, wrong in a success state. Manual design reviews are a bottleneck for every team, so the value is obvious.

The problem is feasibility. Visual comparison is hard. Semantic analysis of intent is harder. And bad feedback wastes designer time and erodes trust.

So reduce scope to what’s actually doable. Token usage, spacing consistency, accessibility requirements. Leave subjective judgment (layout quality, visual harmony) to humans. Be honest about what the agent can and cannot evaluate.

Cross-codebase migration → Agent with strict guardrails

This is where agents genuinely shine. Every component has unique context, dependencies, and edge cases. Migrations eat months of team time. It’s the single most valuable automation you could build.

But it’s also the most dangerous. One wrong semantic mapping and your entire product suite has the wrong error colors.

Run agents with read-only access first. Generate migration PRs for human review. Never auto-merge. Test each migration against visual regression snapshots before approving.

Generating new components from Figma → Agent

Translating design intent to production code involves many judgment calls. Hours saved per component. Tools like Claude Code already do this well when given proper context (your existing components, tokens, and conventions).

The agent generates a first pass. A developer refines it. Bad code gets caught in review. This cuts component creation time from days to hours.

The “90% workflow” test

Anthropic’s framework includes a brutally practical insight. Track your agent runs for a month. If the agent does the same tasks in the same order for 90% or more of cases, you’ve discovered a workflow hiding inside an agent.

Convert it. You’ll get faster execution, lower costs, and more predictable results.

Most design system automation falls into this category. Token syncing, changelog generation, accessibility checks, component scaffolding. These are all repetitive, well-defined tasks. Build them as workflows. Save agents for the genuinely complex work.

Start here

If you’re considering agents for your design system, start with this:

1. Audit your manual tasks. List everything your team does repeatedly and time needed for each one.

2. Score each task against the four questions. Be honest about complexity and error cost.

3. Build workflows first. Linters, CI checks, and scripts handle 80% of design system automation needs.

4. Pilot one agent use case. Pick the highest-value, lowest-risk task from your audit. Documentation generation is usually the safest starting point.

5. Measure ruthlessly. Track time saved, error rates, and token costs. If the agent isn’t clearly outperforming a workflow, simplify.

The goal isn’t to have the most sophisticated AI setup. The goal is to free your team from repetitive work so they can focus on what actually matters: making decisions about your system’s direction, quality, and adoption.

Don’t build an agent because you can. Build one because nothing simpler will do the job.

The real way to learn this

Pick a small problem you actually have. A report you have to manually compile. A workflow that’s tedious. A prototype you wish existed.

Spend 30 minutes writing context before you prompt. Not the prompt itself. The context. What the problem is, who it’s for, what good looks like, what constraints exist.

Point an agent at it and watch what happens. Don’t expect perfection. Expect a starting point. React to it. Guide it. Iterate.

Do this ten times. With different problems. Different levels of complexity. You’ll develop intuition for what works, what context matters, how to evaluate output.

The hard part is still the same thing→ understanding the problem, user empathy, judgment, taste.

Those don’t get automated. They get more valuable. 🙌

Start building,
Romina

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

Component Odyssey (Course)

Learn to build and publish your own component library that works in any web framework.

Save yourself and your company weeks of development time. Build components your users will love. Become a future-proof web developer.

🔗 Link

Paper (just launched)

The connected canvas for teams shipping with agents.

🔗 Link

I am not affiliated with any of the suggested tools

You have more demand than capacity.

You are expected to ship components, keep tokens in sync, help product teams move faster, reduce inconsistency, and now also “use AI.”

Here are 20 ways design system teams can use AI this year. Real tools, workflows, and setups that reduce toil and make your system feel more like a product.

I have written about most of them in depth. I will link to those articles so you can go deeper into whatever interests you.

I grouped the 20 ideas into five areas:

• Components and implementation

• Documentation and enablement

• Strategy and prioritization

• Tokens and consistency

• Adoption, metrics, and ROI

Let’s go 👇

Components and implementation

1. Generate components from your Figma designs with AI

Most AI-generated components look fine in isolation but fall apart the moment you put them next to your real system. They use the wrong tokens, invent their own spacing, and ignore your composition patterns. Meanwhile, designers hand off Figma frames, and engineers still rebuild from scratch. The AI output is a curiosity, not a shortcut.

The fix is to connect AI directly to your system. Figma Make generates code from your design frames, but instead of producing generic markup, it references your existing component library. Pair it with MCP connectors (Notion, GitHub) so Figma Make can read your component docs and token files. Then add an .ai/ directory in your repo that contains your component generation rules: which tokens to use, which base components to compose,and accessibility requirements.

The setup:

1. Figma Make generates a first pass from your design frames. Not generic code, but code that references your existing components

2. MCP connectors (Notion, GitHub) give Figma Make access to your component docs and token files

3. An .ai/ directory in your repo contains your component generation rules: which tokens to use, which base components to compose, accessibility requirements

This same approach works outside Figma Make. Both Cursor and Claude Code can connect to the Figma MCP server, read your design frames directly, and generate components using your tokens and component library. The .ai/ directory works the same way regardless of which tool you use. Pick the one your team already runs.

The gap between “design done” and “component shipped” shrinks from days to hours. AI does the first draft; you do the review.

I covered the full workflow here:

2. Automate design system audits with Playwright

Accessibility audits, visual regression tests, and token usage checks are the work nobody has time for, but everybody notices when they are skipped. Most teams run these manually once before a major release, identify a backlog of issues, and then do not address them again for months.

Playwright’s MCP integration changes this. It gives you three AI agents that work together to keep your audits running continuously:

• Planner: explores your Storybook or documentation site and creates test scenarios

• Generator: writes the actual test code by interacting with your components

• Healer: fixes broken tests automatically when components change

Five audits you can automate today:

1. Token consistency audit (scan rendered components for hardcoded values)

2. Component behavior testing (keyboard nav, focus management)

3. Accessibility checks (ARIA roles, contrast, screen reader labels)

4. Documentation accuracy (do the docs match what the component actually does?)

5. Visual regression (screenshot comparison across themes and viewports)

Your team stops catching checkbox-level issues in reviews and focuses on the hard stuff (interaction patterns, naming, architecture) while Playwright handles the checklist.

3. Build a custom Figma plugin for your design system

Every design system has rules that Figma does not enforce. Designers use the wrong tokens, skip semantic layers, or apply status colors to the wrong contexts. You catch these in review. The same review comments, week after week.

A custom Figma plugin can automatically validate token usage. And with plugma, building one is no longer a side project that takes a sprint. Plugma gives you a modern dev toolchain for Figma plugins (hot reload, TypeScript, bundling) so you can use AI to write most of the plugin logic while plugma handles the build.

Example: a token intent validator

Your plugin can scan selected frames and flag:

• Raw hex colors used instead of tokens

• Primitive tokens (blue.500) used directly in components

• Status colors (danger/success) used in the wrong context

• Interactive tokens applied to static elements

Designers get inline warnings with suggested fixes. You stop repeating the same review comments.

The setup:

npx create-plugma@latest my-token-validator
cd my-token-validator
npm run dev  # hot reload in Figma

Use AI to generate your validation rules from your token naming convention (see “Generate a token naming convention” below).

4. Write a migration guide for breaking changes

You ship a breaking change. Three teams break. Nobody reads the changelog. Changelogs list what changed, not what to do about it. A migration guide is the artifact that actually gets used: who is affected, what to change, and where to watch out.

Feed AI the diff between the old and new API, plus a short explanation of why the change was made. It generates a structured guide in minutes that would otherwise take you an hour to write and another hour to format.

Prompt:

Write a migration guide for this breaking change.
Inputs:
- old API: [paste]
- new API: [paste]
- why we changed it: [paste]

Output:
1) who is affected
2) before/after examples
3) a step-by-step migration checklist
4) common mistakes

Save as migration-guides/[component]-[version].md. When teams ask “how do I update?”, send a link instead of typing a response.

Documentation and enablement

5. Automate your documentation pipeline

Documentation that lags weeks behind code is worse than no documentation. It actively misleads people. Screenshots go stale. Props tables list options that were removed two releases ago. Teams stop trusting the docs and start reading source code instead, which defeats the entire purpose of having a design system.

The fix is not “write docs faster.” The fix is a pipeline that keeps docs in sync with your components continuously. Connect Figma MCP + Claude Code + Mintlify (or your docs framework of choice). Figma MCP reads your component designs and extracts props, variants, and states. Claude Code generates documentation markdown from your component source code combined with the Figma data. Mintlify publishes automatically on merge.

The pipeline:

1. Figma MCP reads your component designs and extracts props, variants, and states

2. Claude Code generates documentation markdown from your component source code + Figma data

3. Mintlify (or Storybook, or your docs site) publishes automatically on merge

4. Cron job (optional) runs weekly to re-sync screenshots and catch drift

Add Claude Code Skills to your design system workflow

Everyone on your team prompts AI differently. One person writes a paragraph of context. Another pastes raw code and says, “Fix this.” The results are wildly inconsistent, and people end up writing the same instructions repeatedly, or worse, stop using AI because the output never matches the system.

Claude Code Skills solves this. Skills are reusable instruction sets that auto-load based on context. They are prompts that know when to activate and what files to read. You do not have to remember to use them. They just show up when relevant.

The best Skills for design system work:

✨ token-migration-assistant
Detects your token format and migrates between Style Dictionary, W3C DTCG, Figma Variables, CSS, and Tailwind.

✨ component-audit
Runs comprehensive audits: accessibility, theming, responsiveness, code quality.

✨ documentation-standards
Generates consistent component docs matching your format.

✨ brand-guidelines
Applies your brand’s colors, typography, spacing, and motion rules.

✨ figma-variables-generator
Generates Figma Variables JSON directly from your design tokens.

A prompt library is a document people forget exists. A Skill auto-loads when Claude Code detects it is relevant. That difference is everything.

I covered Skills in depth here 👇

7. Make your own custom Skill

The prebuilt Skills cover common workflows, but your design system has its own rules, naming conventions, and patterns that no generic skill can cover. The good news: a custom Skill is a Markdown file with YAML front matter. That is it.

Example: a token naming validator Skill

---
name: token-naming-validator
description: Validates design token names against our naming convention
autoload: when working with design tokens or token files
---

# Token Naming Validator

When reviewing or generating design tokens, enforce these rules:

## Naming structure
- Format: `{category}.{property}.{variant}.{state}`
- Categories: color, spacing, typography, elevation, motion
- Use dot notation, not camelCase or kebab-case

## Rules
- Semantic tokens MUST reference primitives, never raw values
- No color names in semantic tokens (use "primary" not "blue")
- State variants: default, hover, active, disabled, focus
- Every token must have a description field

## On violation
- Flag the token name
- Suggest the correct name
- Explain the rule that was broken

Save personal Skills to ~/.claude/skills/ or project Skills to .claude/skills/ (version controlled, shared with the team). Now your entire team gets consistent AI behavior (same naming rules, same validation, same output format) without anyone memorizing the rules.

8. Create a design system onboarding FAQ from real questions

Every new hire asks the same 20 questions. Where do I find the tokens? Which Button variant do I use for destructive actions? How do I submit a new component request? You answer these individually, every time, in Slack DMs that nobody else can see.

Take the last 50 questions that new team members actually asked. Answer them, feed them to AI and generate a structured FAQ. The next person who joins does not need you to onboard them. They have the FAQ.

Prompt:

Turn these questions into an onboarding FAQ for our design system.
Requirements:
- group by theme
- answer in plain language
- link to the right doc sections (use placeholders if unknown)
- include "common mistakes"

Save as onboarding-faq.md and link it from your main docs. Update it quarterly as new questions come in.

Strategy and prioritization

9. Turn requests into a single backlog

Design system requests come from everywhere: Slack threads, Jira tickets, meeting sidebars, and post-it notes from a workshop three weeks ago. You spend hours manually deduplicating, and you still miss things because half the requests were verbal.

Dump your last 30 days of requests into a single document. Feed it into the AI and ask it to deduplicate, group by theme, count frequencies, and identify the underlying job-to-be-done. You get a clean backlog in minutes, not a half-day of spreadsheet work.

Prompt:

You are helping a design system lead consolidate requests.

Input: a list of requests (Slack snippets, Jira tickets, meeting notes).
Output:
1) A cleaned list of requests grouped by theme (duplicates merged)
2) For each theme: frequency, impacted teams, and the underlying job-to-be-done
3) A short "what we are NOT doing" list (scope control)

Format: markdown

Save as design-system-backlog.md. Update it weekly. 2–3 hours saved per sprint, and you now have a source of truth that is not your memory.

10. Write a one-page strategy map

Leadership asks, “What’s the plan?” and you have 47 Notion docs, but no clear answer. The detail is there. The clarity is not. What you need is a single-page summary: everything you know about the current state, the vision, and the path forward, reduced to one page that anyone can read in two minutes.

Prompt:

Create a one-page design system strategy map with:
- Context: what is broken today (3-5 bullets)
- Vision: where we want to be in 12 months
- Strategy: our 3 biggest bets
- Metrics: what we will measure monthly
- Stakeholders: who needs updates and how often

Make it plain English. No corporate jargon.

If it does not fit on one page, you do not understand it well enough yet.

11. Run a component ROI sanity check before you build

Most component decisions follow the same pattern: someone with influence requests it, you build it, and six months later it is used in two places. Meanwhile, the component the three teams need is in the backlog because no one lobbied for it loudly enough.

Before you build, run a quick sanity check. Map the request to screens, teams, and reuse potential. It takes five minutes and saves you from building the wrong thing first.

Prompt:

Help me decide whether to build a new component.

Component request: [paste]
Context:
- Teams requesting it: [list]
- Known screens / flows: [list]
- Alternatives in system today: [list]

Output:
1) Reuse likelihood (high/medium/low) with reasoning
2) Risks (maintenance, variants, accessibility complexity)
3) MVP scope (minimum viable version)
4) What to validate before building

Save the output in your decisions folder. When someone asks, “Why didn’t we build X?” you have a written record of the reasoning.

12. Use Claude Code for design system research

Researching how other systems handle a problem (token structures, component APIs, theming approaches) usually eats an entire afternoon. You open ten tabs, compare three Storybook instances, skim four blog posts, and still end up with scattered notes.

Claude Code has built-in web search and file analysis. Point it at a competitor’s public repo, a Storybook instance, or a set of documentation pages, and it pulls everything together into one document.

Example:

# From your terminal, ask Claude Code to research
claude "Research how Shopify Polaris, Atlassian, and GitHub Primer
handle their color token structure. Compare naming conventions,
semantic layers, and how they handle dark mode. Output a comparison
table I can share with my team."

You get a research summary your team can act on in the same week you asked the question, not a collection of bookmarks you will never revisit.

Tokens and consistency

13. Generate a token naming convention from your real usage

Token naming inconsistencies are a burden on every engineer who touches your system. color-primary in one file, primaryColor in another, brand.primary in a third. Engineers guess. Designers copy what looks right. The inconsistency compounds silently until a rebrand or a multi-brand initiative forces you to deal with all of it at once.

Instead of designing a naming convention from scratch, give AI your current token set and ask it to propose a scheme that matches what you already do, then tighten the edges.

Prompt:

Analyze our token set and propose a consistent naming convention.
Goals:
- predictable
- scalable to multiple brands
- clear semantic vs primitive separation

Output:
1) naming rules
2) 10 "before -> after" renames
3) a short migration strategy

The goal is predictability. A developer should be able to guess the token name without checking the documentation.

14. Connect Figma variables to your codebase with MCP

Every time you paste token values into an AI prompt, they are already stale. Your Figma variables update. Your tokens JSON gets a new release. But the AI is working with whatever you copy-pasted last Tuesday.

A Model Context Protocol (MCP) server connects your design tokens directly to Claude. The Figma MCP server lets AI read your variables, modes, and collections in real-time.

The setup:

1. Install the Figma MCP server (or build your own with the MCP Design Tokens Server template)

2. Point it at your Figma file or your tokens JSON

3. Now every AI prompt you run has live access to your actual token values

15. Use Context7, so AI always has current documentation

AI models have a training cutoff. When you ask Claude or Cursor about Style Dictionary v4, Radix Themes, or Tailwind v4, you might get answers based on last year’s API, and not realize it until you have already built something around a deprecated method.

Your token pipeline probably depends on Style Dictionary. Your components might use Radix or shadcn. Your utility layer might be Tailwind. If AI gives you advice based on outdated docs, you waste time fixing problems that do not actually exist.

Context7 feeds AI the latest documentation for the libraries your design system depends on. Add it as a reference source in your AI workflow. When generating components or debugging token transforms, ask AI to check Context7 for the current API first.

16. Run a token drift audit with a Skill

Teams bypass tokens. You find out weeks later when the UI looks wrong. Manually checking every PR for hardcoded colors and spacing values does not scale. And asking people to “just use tokens” in Slack is not enforcement, it is hope.

A token audit Skill tells Claude Code exactly what to look for in your codebase (hardcoded hex values, raw pixel spacing, missing theme variants) and how to report it. Save it once, and anyone on your team can run it on demand or as part of their review process.

Example: a token audit Skill

---
name: token-drift-audit
description: Scan codebase for hardcoded values that should use design tokens
autoload: when reviewing PRs or checking token usage
---

# Token Drift Audit

Scan the codebase for values that bypass the design token system.

## What to flag
- Hardcoded hex, rgb, or hsl colors in component files
- Raw pixel spacing values (4px, 8px, 16px, etc.)
- Inline font sizes instead of typography tokens
- Colors that exist as tokens but are written as raw values
- Primitive tokens (e.g. blue.500) used directly in components

## What to check
- All themes (Light, Dark, High Contrast) have matching token sets
- No broken token references
- Color contrast ratios meet WCAG AA (4.5:1 text, 3:1 large text)
- Naming follows the convention: {category}.{property}.{variant}

## Output format
- Group findings by severity: critical, warning, info
- Show file path and line number for each finding
- Suggest the correct token for each hardcoded value
- End with a summary count

Save this as .claude/skills/token-drift-audit/SKILL.md in your repo. Now anyone on your team can run it:

claude "Run a token drift audit on the components/ folder"

You catch drift in PRs, not production. And because it is a Skill, the audit is consistent. Every team member gets the same checks, the same output format, the same severity levels.

Adoption, metrics, and ROI

17. Build an adoption dashboard

Leadership wants metrics. But runtime tracking (watching which developers use which components in real time) feels invasive, and the data is noisy anyway. Importing a component does not guarantee it is used correctly.

Start with build-time signals instead. Component imports, token drift counts, bypass signals (raw <button> elements, inline styles), and PR drift delta. These are facts extracted from code, not surveillance of people.

Prompt:

Design a design system adoption dashboard plan.
Start with build-time metrics only:
- component imports / usage counts
- token drift counts
- bypass signals (raw <button>, inline styles)
- PR drift delta

Output:
1) metrics definitions
2) data sources
3) weekly reporting format

Build-time metrics tell you what is happening in the codebase without anyone feeling watched. That is the foundation. Add complexity only when you have proven the basics are useful.

18. Find the bypass patterns that hurt consistency

When teams bypass your design system, the instinct is to blame them. “They should have used the component.” But if people are bypassing consistently, the system is failing them. The component does not exist. The token is missing. The docs are unclear. The API is too rigid.

Bypass patterns are user research. Feed AI your drift report and ask it to identify what is recurring, why teams do it, and what the smallest fix is that you can ship this sprint.

Prompt:

Given this drift report, identify the top bypass patterns.
For each bypass:
- why teams do it
- what the design system should change (component, token, docs)
- the smallest fix we can ship this sprint

Every bypass you fix makes the system easier to use, which makes the next bypass less likely. That is how adoption compounds.

19. Generate release notes that teams will actually read

Your changelog says “updated Button component.” Nobody knows what changed, who is affected, or whether they need to do anything. So nobody reads it, and then they complain they were not told about breaking changes.

Release notes for design systems need to be written for non-design-system people. What changed, why it matters for product work, and what teams need to do (if anything). AI can generate this from your changelog and merged PRs in minutes.

Prompt:

Write design system release notes for non-design-system people.
Inputs: changelog + list of merged PRs.

Output:
- what changed (3-7 bullets)
- why it matters (tie to product outcomes)
- what teams need to do (if anything)
- links to migration guides

If the release note does not say “what this means for you,” it will not get read.

20. Run your own AI design system assistant 24/7

OpenClaw (previously clawdbot) is an open-source AI assistant that runs 24/7 on your own hardware. A ~5/month Hetzner VPS is enough. Connect it to Telegram, Slack, Discord, or WhatsApp and your team has an always-on design system expert that can actually read your repo.

What it gives you:

• Always-on access via Telegram, Slack, Discord, or WhatsApp

• Full system access: it can run scripts, query your token files, check your repo

• Scheduled jobs: automate weekly reports, competitor checks, content generation

• Persistent memory: it remembers previous conversations and context

• Your choice of model: Claude, GPT, Gemini, DeepSeek, whatever fits your budget

Example setup for a design system team:

• Morning cron job runs a token drift scan and posts results to Slack

• Team members message the bot on Telegram: “What’s the current spacing scale?” It reads the actual tokens and responds

• Weekly automated competitor check: “What did Polaris, Carbon, and Primer ship this week?”

A word on security: Keep this on a separate server from your production infrastructure. Give it read-only access to a clone of your token files and documentation, not your live codebase. This is a tool for answering questions, running reports, and automating research. It is not a deployment pipeline. Treat it like a team assistant with a read-only badge, not an engineer with push access.

The toolkit

Here is every tool mentioned in this article and where to start:

Claude Code
AI coding assistant with file access, web search, and Skills

MCP (Model Context Protocol)
Connects AI to live data sources (Figma, tokens, docs).

• Figma MCP for reading variables, design frames, and component metadata

• GitHub MCP for reading repos, PRs, issues, and component source code

• Slack MCP for monitoring design system requests and support channels

• Notion MCP for reading and writing design system documentation and decision logs

• PostHog MCP for querying adoption metrics, feature flags, and usage data

• Zapier MCP for connecting your design system workflows to Jira, Linear, and hundreds of other tools

Figma Make
Generates code from Figma designs using your component library.

Playwright
Automated browser testing with AI agents (Planner, Generator, Healer).

Context7
Feeds current library documentation to AI tools.

plugma
Modern Figma plugin development toolchain. npx create-plugma@latest

OpenClaw
Self-hosted AI assistant on your own server.

PostHog
Product analytics platform with feature flags, session replays, and A/B testing. For design systems, it tracks component usage in production, measures adoption across teams, and gives you real data for ROI conversations with leadership. The PostHog MCP server lets AI query your analytics directly.

Enjoy exploring 🙌

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

Swap Wizard Figma plugin

1st place at the IDS hackaton

✨ Auto-matches components even when names don't align perfectly
✨ Lets you validate and adjust mappings with live previews
✨ Handles variant properties so you pick the exact component you need
✨ Re-attaches detached components

🔗 Link

Edgy Figma plugin

2nd place at the IDS Hackaton → The team explored whether a plugin could analyse flows, call out missed edge cases, and generate any missing screens directly on the canvas using an existing design system. And they did it.

🔗 Link

Design Token Naming Guide + Builder

🔗 Link

I am not affiliated with any of the suggested tools

You spend 2 hours setting up beautiful variants in Figma. Primary, secondary, ghost. Small, medium, large. Default, hover, disabled.

Then a developer asks: “What are the props for this component?”

You explain everything again. In a meeting, in a Notion doc, or in Slack messages. The developer writes the component with slightly different naming. Now “Primary” in Figma becomes type: 'main' in code.

The translation layer between design and code breaks down within weeks.

Here’s the thing: your Figma variants already ARE your props. They just need to speak the same language as your code. When you set this up correctly, your Figma button with variants “Primary, Secondary, Ghost” automatically becomes a React component with variant: 'primary' | 'secondary' | 'ghost', which automatically becomes interactive controls that anyone can toggle.

No manual documentation. No translation meetings. No drift.

What you will learn:

• Figma variant properties = Component props: When you name variants correctly, AI generates matching TypeScript types automatically

• The naming alignment is everything: “Primary” in Figma should become 'primary' in code, not 'main' or 'type1'

• Storybook controls generate from types: Clean union types mean clean dropdown controls, no configuration needed

• Prompts: Copy-paste prompts for every step of this workflow

What is Storybook (and why should you care)?

Storybook is a free, open-source tool that lets you browse and test your components in isolation, outside of your app. Think of it as an interactive catalog of every component in your design system.

Why is it so useful:

• You can click through every variant without spinning up the full product

• Controls panel lets you toggle props (size, variant, disabled) in real time

• Auto-generated documentation pulls from the code, so it never goes stale

• Shareable URL means you can send a link to anyone for review

When your Figma naming matches the code, Storybook generates all of this automatically from your TypeScript types.

The mental model: how props flow

Before you touch any tools, understand this flow:

FIGMA                      CODE                        STORYBOOK
───────────────────────────────────────────────────────────────────
Variant property     →     Component prop       →     Control panel
"Variant: Primary"         variant: 'primary'         [Dropdown: Primary ▼]
"Size: Medium"             size: 'md'                 [Dropdown: Medium ▼]
"Disabled: True"           isDisabled: boolean        [Checkbox: ☑]

You set up Figma → AI generates the code → Storybook creates the controls.

When this chain works, everything stays in sync. When it breaks (usually because Figma naming doesn’t match code conventions), you get drift.

Let’s go step by step.

Setting up Storybook

In your React/Next.js project, run:

npx storybook@latest init

This creates a .storybook folder with configuration. Start it with:

npm run storybook

You’ll see a local server at http://localhost:6006 with example stories.

Optional: Publish with Chromatic

Chromatic publishes your Storybook online, so your entire team can browse components in a browser. Free for open source, generous free tier for everyone else.

I use this option, so I can also share the work with others.

→ Sign up at chromatic.com (GitHub login works)

→ Create a new project and get your project token

→ Install and publish Chromatic:

npm install chromatic --save-dev
npx chromatic --project-token=YOUR_TOKEN

You’ll get a public URL to share. Chromatic also catches visual regressions when you push changes.

Setting up Figma so AI can read it

This is the most important step. AI tools read your Figma file directly: your variant properties, layer names, and design tokens. If these are messy, the generated code will be messy.

Your Figma variant property names become your prop names.

Name your Figma variants with code-friendly values (lowercase, no spaces, consistent format), and AI generates cleaner code.

Checklist before you generate

Open your component in Figma and verify:

• Consistent naming: All variants use the same format (sm/md/lg, not sm/Medium/LG)

• Code-friendly values: No spaces, lowercase preferred (primary, not “Primary Button Style”)

• Boolean properties for on/off states: isDisabled, isLoading, hasIcon (not “State: Disabled”)

• Meaningful layer names: “Leading Icon”, “Label”, “Trailing Icon” (not “Frame 47”, “Vector”, “Text”)

Add a component description

Select your component set in Figma and add a description. AI reads this and uses it for context:

Button component for user actions.

Props:
- variant: primary | secondary | ghost | danger (default: primary)
- size: sm | md | lg (default: md)
- isDisabled: boolean (default: false)
- isLoading: boolean (default: false)

Usage: Use primary for main actions, secondary for alternative actions,
ghost for tertiary actions, danger for destructive actions.

Pick your AI tool

You need an AI tool that can read your Figma and generate code. Here are your recommended options:

Claude Code reads Figma files directly through the Figma MCP server. One-time setup. Claude Code can be used as an extension in any IDE or in your terminal.

Or, you can use Cursor.

Cursor is an AI-powered code editor (IDE) with built-in chat. It also supports MCP servers, so you connect Figma the same way. You can switch between AI models (Claude Opus 4.6, GPT-5.2, Gemini, etc.) to compare outputs.

The two prompts that do everything

This is the core of the workflow. The first builds your component, the second pushes it to Storybook.

Prompt 1: Generate the component

Select your component in Figma, then paste this:

Get the design context for the selected Figma component.

Generate a React component with TypeScript that:
1. Has props matching the Figma variant properties exactly
   (use the same names and values, lowercased)
2. Uses TypeScript union types for all variants
   (e.g., 'primary' | 'secondary', never just string)
3. Uses boolean props for on/off states
   (e.g., isDisabled?: boolean)
4. Adds JSDoc comments for every prop explaining:
   - What it does
   - Available options
   - Default value
5. Follows the patterns in our existing components at src/components/

Show me the generated TypeScript interface first so I can verify
the prop names and values match my Figma setup before you write
the full component.

More detailed guide and tricks about generating components with AI here →

What you should get back:

export interface ButtonProps {
  /** The visual style of the button */
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
  /** The size of the button */
  size?: 'sm' | 'md' | 'lg';
  /** Whether the button is disabled */
  isDisabled?: boolean;
  /** Whether to show loading state */
  isLoading?: boolean;
  /** Button content */
  children: React.ReactNode;
}

Check that the prop names and values match your Figma exactly. If AI-generated type instead of variant, or small instead of sm, tell it:

The prop names don't match my Figma. Change "type" to "variant"
and "small/medium/large" to "sm/md/lg".

Prompt 2: Generate stories and run Storybook

Once your component looks good, paste this:

Look at the component you just created.

Generate Storybook stories that:
1. Use CSF 3.0 format with Meta and StoryObj types
2. Include the 'autodocs' tag for automatic documentation
3. Create one story for each variant
4. Create one story showing all sizes side by side
5. Create stories for every boolean state (disabled, loading, etc.)
6. Add an "AllVariants" story that renders every variant
   in a grid so I can compare them at a glance
7. Add edge case stories:
   - Long text label (50+ characters)
   - With leading and trailing icons
   - Inside a form context
8. Add a play function to the default story that:
   - Clicks the component
   - Verifies the click handler fires
   - Tests keyboard navigation (tab + enter)

Put the stories next to the component file.
Then run Storybook so I can see the result.

What happens next

Open http://localhost:6006 (or whatever local address you have) You’ll see:

• Live component preview you can interact with

• Controls panel with dropdowns for variant and size, checkboxes for isDisabled and isLoading

• Auto-generated docs with your JSDoc comments as prop descriptions

• AllVariants story showing every combination in a grid

You didn't configure any controls. Storybook figured it out from your types. That's the whole point of getting the naming right in Figma.

Check the example story here →

When things go wrong

Two issues come up most often:

Controls don’t match your Figma variants

This happens when AI uses different names than your Figma. Tell it exactly what to fix:

Update the component types to match my Figma naming exactly:
- variant: primary | secondary | ghost | danger
- size: sm | md | lg

Types are too loose

If AI typed a prop as string instead of specific values, tighten it:

The size prop is typed as `string` but it should only accept
specific values. Change it to a union type: 'sm' | 'md' | 'lg'

Why this matters

The props connection between Figma and Storybook creates a single source of truth.

When your Figma variants, code props, and Storybook controls all use the same language:

• Designers review components without asking “what did the developer call this?”

• Developers implement without asking “what does the designer mean by Type 2?”

• Documentation stays accurate because it generates from the code

• AI updates everything when you change the Figma source

The biggest design system problems aren’t technical. They’re communication problems. Naming alignment solves a surprising number of them.

Inspiration: Storybooks worth exploring

See how top companies document their components:

🔗 Shopify Polaris: Accessibility auditing, viewport testing, theme switching

🔗 GitHub Primer: Clean organization, great props documentation

🔗 IBM Carbon: Comprehensive component library with detailed usage guidelines

🔗 BBC iPlayer: Rebuilt their entire UI library in Storybook after a component audit

🔗 Monday.com Vibe: Beautiful welcome page, clear navigation

🔗 Audi UI React: Brand imagery meets component documentation

🔗 Grommet (HPE): Extensive theming examples

🔗 WordPress Gutenberg: Block editor components, accessibility focus

🔗 JetBrains Ring UI: Developer tools components, dark mode support

Browse more at the Storybook Showcase.

Enjoy exploring 🙌

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

Introducing: Design Token Naming GUIDE + BUILDER 2.0 🎉

Try it here

I built a free, interactive tool to help designers and developers improve their naming of design tokens. And maybe, build their own token systems along the way. 🙃

Whether you're just getting started with tokens or trying to get your team on the same page, this might help.

Here's what you'll find:

• 6 interactive lessons that walk you through what design tokens actually are, how they work, and how to name them well (about 15 mins total)

• Token BUILDER to configure your own naming structure with components, categories, states, and roles

• Primitive vs Semantic modes, so you can switch between simple scale-based tokens or full semantic naming

• Live preview that shows your token names as you build them

• Export-ready, so you can copy or download your tokens and start using it

• Figma Variables ready format

• Advanced filtering and sorting

• Add values manually or put placeholders in a second
  

The whole point is to let you quickly switch naming conventions and test what works for your project.

Feedback for improvements is always welcome. 🫶

💎 Community Gems

Winden Tokens
A Figma plugin for managing design tokens (variables) with a spreadsheet-style interface. Quickly create, edit, and organize your design system variables.

🔗 Link (GitHub) 🔗 Figma plugin

Design systems don’t sleep. Teams push code at midnight. Someone uses a raw hex value “just this once.” A deprecated token sneaks into production.

It’s hard to watch everything. But for €5/month, something can.

A personal AI assistant running 24/7 in the cloud. It monitors your repos, flags violations, and messages you on Telegram when something needs attention. It runs while you sleep. It’s yours to customize.

In short

• €5/month beats €600 hardware: A Hetzner cloud server gives you 24/7 uptime without buying a Mac Mini

• Telegram is your control center: Message your AI from anywhere, get responses even when your laptop is closed

• No DevOps needed: Copy-paste commands get you from zero to running in under 2 hours

• Bonus: Complete command cheat sheet: Every command you need on a single page

Why everyone’s talking about OpenClaw

If you’ve been on tech X lately, you’ve probably seen the Mac Mini buying frenzy.

People are setting up dedicated machines just to run an AI assistant 24/7. One user described it as “sort of amazing knowing that we are all having the same weekend... Mac Minis and OpenClaw.”

So what is OpenClaw, and why are people treating it like hiring their first employee?

OpenClaw (formerly Clawdbot, then Moltbot) is an open-source personal AI assistant created by Peter Steinberger (@steipete). The lobster has molted twice already. Unlike ChatGPT or Claude.ai, which live in browser tabs, OpenClaw:

• Runs on your hardware (Mac, Linux, Windows, Raspberry Pi, or cloud VPS)

• Connects through chat apps you already use (Telegram, WhatsApp, Discord, iMessage, Slack)

• Has full system access (can execute terminal commands, write scripts, install software)

• Works with any LLM (Claude, GPT, Gemini, DeepSeek, Perplexity)

• Remembers everything (persistent memory across sessions)

• Can improve itself (add new capabilities just by talking to it)

The project has exploded: 108k GitHub stars, 15k forks, and a Discord community building skills for everything from calendar management to home automation.

What makes it viral? It feels like “the future” because it actually does things, not just chats. One user set up OpenClaw to manage multiple AI coding agents, autonomously debate code reviews, and deploy features while walking the dog. Another had it decode emergency radio frequencies using RTL-SDR hardware, which they just plugged in.

Here’s the thing, though: you don’t need a $600 Mac Mini. The creator himself keeps telling people to stop buying hardware. A €5/month cloud server works just as well, and that’s what this guide covers.

Before you start: Security is not optional

This is not a toy. OpenClaw has full system access. It can execute terminal commands, write scripts, install software, and spin up sub-agents. If you’re not paranoid about security, you should be.

Treat it like hiring a stranger with the keys to your house.

Here’s what that means in practice:

Isolate the environment

• Run it on a dedicated server or user account, not your main machine

• If using a Mac, create a separate user just for OpenClaw

• A cloud VPS (like this guide covers) is actually safer than your personal laptop

Lock down messaging

• Use a messaging app you don’t use for anything else (Telegram works well)

• If your phone is stolen or a token is compromised, someone could impersonate you

• During testing, OpenClaw sent emails as one user rather than for them. Careful prompting required.

Use the “new employee” rule

• Don’t give it your primary email, passwords, or personal accounts

• Create separate accounts with limited access (e.g., read-only calendar access)

• Use a dedicated password vault with only the credentials OpenClaw needs

• When OAuth asks for permissions, manually restrict to only what’s necessary

Think about what you’re exposing

• Your calendar has your kids’ school schedules, doctor appointments, and home address

• Your repos have API keys, deployment configs, and business logic

• Ask yourself: would you hand this to a contractor you just met?

Have an exit plan

• Know how to revoke all tokens and API keys

• Know how to delete the Telegram bot

• Know how to wipe the server

If you haven’t done a security tabletop exercise for this, do one before you start. The power is real. So are the risks.

OpenClaw vs Claude Code: When to use which?

If you already use Claude Code, you might wonder why you’d bother with OpenClaw. Fair question.

When OpenClaw makes sense:

• You want something running while you sleep (”Research competitor APIs and summarize by morning”)

• You need an assistant available from your phone, anywhere

• You want to monitor repos, get alerts, or run scheduled tasks

• You’re building workflows that span hours or days

When Claude Code is better:

• Active coding where you need fast feedback loops

• Working on local files in your IDE

• You want tight integration with your development environment

• Latency matters (OpenClaw’s Telegram round-trip adds delay)

The honest answer: They complement each other. Claude Code for real-time coding. OpenClaw for “set it and forget it” tasks that run while you’re not at your desk.

The architecture

Here’s what you’re building:

┌─────────────────────────────────────┐
│         HETZNER SERVER              │
│         (runs 24/7 in the cloud)    │
│                                     │
│    • OpenClaw installed here        │
│    • Always online                  │
│    • €4-5/month                     │
└─────────────────────────────────────┘
              ↕
        ┌─────────────┐
        │  Telegram   │  ← You control it from here
        │  (phone or  │     (anywhere in the world)
        │   desktop)  │
        └─────────────┘

Your laptop is only needed for the initial setup. Once configured, OpenClaw runs independently.

Part 1: Create your Telegram bot

Before touching any servers, let’s set up the Telegram bot you’ll use to control everything. You can, of course, use any other messaging service, but again, be careful with which account (better to create a new one than share your real one).

Step 1: Talk to BotFather

Open Telegram and search for @BotFather. This is Telegram’s official bot for creating bots. Start a chat and send:

/start

BotFather will ask you two questions:

1. Name: This is the display name. Call it whatever you want (e.g., “Mochi”)

2. Username: Must end in bot. Something like puffy_assistant_bot

BotFather then gives you a token that looks like this:

123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Save this token somewhere safe. You’ll need it later.

Step 2: Get your Chat ID

Now you need your personal Chat ID so the bot knows who to talk to.

1. Find your new bot in Telegram (search for the username you just created)

2. Send it /start

3. Open this URL in your browser, replacing YOUR_TOKEN with the token from BotFather:

https://api.telegram.org/botYOUR_TOKEN/getUpdates

Look for "id" in the response. It’s a number like 123456789. That’s your Chat ID.

Common issue: If you see {"ok":true,"result":[]}, the message expired. Go back to Telegram, send /start again, then refresh the URL within a few seconds.

What you should have now

ItemExampleWhere you got itBot Token123456789:ABCdef...From BotFatherChat ID123456789From the getUpdates URL

Keep these somewhere safe. You’ll paste them during server setup.

Part 2: Set up your Hetzner server

Step 1: Create a Hetzner account

Go to hetzner.com/cloud and sign up. You’ll need to add a payment method (credit card works).

Step 2: Generate an SSH key

SSH keys let you log into your server without a password. On your Mac or PC, open Terminal and run:

ssh-keygen -t ed25519 -C "your@email.com"

When it asks questions:

• File location: Press Enter to accept the default

• Passphrase: Press Enter twice (no passphrase makes things easier)

Now copy your public key:

cat ~/.ssh/id_ed25519.pub

You’ll see something like:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... your@email.com

Copy that entire line. You’ll paste it into Hetzner.

Step 3: Create the server

1. Go to console.hetzner.cloud

2. Create a project (name it whatever you want)

3. Click + Create Server

Use these settings:

• Location: Falkenstein or Helsinki

• Image: Ubuntu 24.04

• Type: Shared Resources → Cost-Optimized → CX22

• SSH Keys: Click “Add SSH Key” and paste your public key

• Name: openclaw-agent

Click Create & Buy now. In about 30 seconds, you’ll have a server with an IP address like 112.111.2.221.

Step 4: Connect to your server

In Terminal, run:

ssh root@YOUR_SERVER_IP

Replace YOUR_SERVER_IP with the actual IP from Hetzner. When it asks “Are you sure you want to continue connecting?” type yes.

You should see:

Welcome to Ubuntu 24.04.3 LTS
root@ubuntu-4gb-hel1-1:~#

You’re now inside your cloud server. Everything you type runs there, not on your laptop. First win! 🥳

Part 3: Install OpenClaw

Now the fun part. You’re on your server via SSH. Let’s install the AI.

Step 1: Update the system

Run this first (takes 1-2 minutes):

apt update && apt upgrade -y

Step 2: Install Node.js and OpenClaw

OpenClaw requires Node.js 22 or newer. Install it first:

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs

Now install OpenClaw:

npm install -g openclaw@latest

Then run the onboarding wizard:

openclaw onboard --install-daemon

The wizard walks you through:

• Accepting the security warning

• Choosing your AI provider (Anthropic, OpenAI, etc.)

• Pasting your API key

• Configuring messaging channels

Step 3: Give your bot a personality

OpenClaw asks what it should be. Type something like:

Your name is Mochi. You're my AI assistant for design systems and coding projects. You help me monitor GitHub repos, analyze code, and automate tasks. Be helpful, proactive, and friendly.

Press Enter.

Step 4: Connect GitHub (optional but useful)

If OpenClaw asks for GitHub access:

1. Go to github.com/settings/tokens

2. Click Generate new token (classic)

3. Name it openclaw

4. Check the repo scope

5. Generate and copy the token (starts with ghp_...)

6. Paste it into OpenClaw

Part 4: Connect Telegram

Almost there. Let’s hook up your bot to Telegram.

During onboarding, OpenClaw asks which messaging channels you want to use. Select Telegram and enter:

• Bot Token: The token from BotFather

• Chat ID: Your personal Chat ID

If you skipped this during onboarding, you can re-run:

openclaw onboard

And select Telegram when prompted for channels.

Test it

1. Open Telegram on your phone

2. Go to your bot’s chat

3. Send: hello

You should get a response from your bot. If you do, it’s working.

Part 5: Keep it running forever

When you connect to your server, you’re opening a “session.” Any programs you start live inside that session. When you close your laptop, disconnect from WiFi, or just close the Terminal window, that session ends. And when the session ends, everything running inside it gets killed.

It’s like having a conversation on the phone. The moment you hang up, the conversation stops. What we need is a way to start OpenClaw and have it keep running even after we “hang up” our SSH connection.

That’s what process managers do. They run your program in the background, completely independent of your SSH session. Even better, they can restart your program automatically if it crashes or if the server reboots.

Option 1: PM2 (recommended)

PM2 is the most popular process manager for Node.js applications. Think of it as a babysitter for your programs - it watches them, restarts them if they crash, and keeps logs of what happened.

npm install -g pm2

This installs PM2 globally on your server. You only need to do this once.

pm2 start openclaw --name "openclaw"

This tells PM2 to start OpenClaw and give it the nickname “openclaw” (so you can refer to it later). PM2 immediately moves it to the background.

pm2 save

This saves your current setup. PM2 now remembers that it should be running OpenClaw.

pm2 startup

This is the magic command. It creates a system service that starts PM2 automatically when your server boots up. PM2 then starts all saved processes (including OpenClaw).

The result: You can now close your Terminal, shut down your laptop, go on vacation. OpenClaw keeps running. If the server restarts for any reason (updates, maintenance), OpenClaw comes back automatically.

Verify it’s running

After setting up PM2 (or daemon mode), disconnect from your server:

exit

Wait a few seconds, then send a message to your bot on Telegram. If it responds, congratulations - your AI assistant is now running independently of your computer.

Check status anytime

You can always SSH back in and check on things:

pm2 list
# or
systemctl status openclaw

Command Cheat Sheet

Copy this and keep it somewhere handy:

┌─────────────────────────────────────────────────────────────┐
│                   OPENCLAW CHEAT SHEET                      │
├─────────────────────────────────────────────────────────────┤
│ SERVER CONNECTION                                           │
│   ssh root@YOUR_IP          Connect to server               │
│   exit                      Disconnect from server          │
├─────────────────────────────────────────────────────────────┤
│ OPENCLAW COMMANDS                                           │
│   openclaw onboard          Run setup wizard                │
│   openclaw onboard --install-daemon  Setup + auto-start     │
│   openclaw gateway          Start the control plane         │
│   openclaw agent --message  Send a task to your agent       │
│   openclaw doctor           Diagnose issues                 │
│   openclaw update           Update to latest version        │
├─────────────────────────────────────────────────────────────┤
│ PM2 COMMANDS (PROCESS MANAGER)                              │
│   pm2 list                  Show running processes          │
│   pm2 logs openclaw          View live logs                  │
│   pm2 restart openclaw       Restart the bot                 │
│   pm2 stop openclaw          Stop the bot                    │
│   pm2 save                  Save current config             │
│   pm2 startup               Enable auto-start on boot       │
├─────────────────────────────────────────────────────────────┤
│ SKILLS (via ClawdHub)                                       │
│   clawdhub install <slug>   Install a skill                 │
│   clawdhub update --all     Update all skills               │
│   Skills dir: ~/clawd/skills/                               │
├─────────────────────────────────────────────────────────────┤
│ IN-CHAT COMMANDS                                            │
│   /status                   Show model and token usage      │
│   /new or /reset            Clear session history           │
│   /think <level>            Set reasoning depth             │
│   /verbose on|off           Toggle detailed output          │
└─────────────────────────────────────────────────────────────┘

Troubleshooting

“Connection refused” when SSHing
Double-check the IP address in Hetzner’s dashboard.

OpenClaw command not found
Run the install script again, then source ~/.bashrc.

Bot not responding on Telegram
Check the service status with systemctl status openclaw or pm2 list. Verify your Bot Token and Chat ID are correct by re-running openclaw onboard.

Got disconnected from SSH
Just reconnect with ssh root@YOUR_IP. OpenClaw keeps running if you set up PM2.

Cost breakdown

Infrastructure:

• Hetzner CX22: ~€4.35/month

AI Models (per 1M tokens in / out):

• Claude 3.5 Sonnet: $3 / $15 (~$0.01-0.03 per message)

• Claude 3.5 Haiku: $0.80 / $4 (~$0.005 per message)

• GPT-4o: $2.50 / $10 (~$0.01-0.02 per message)

• GPT-4o mini: $0.15 / $0.60 (~$0.001 per message)

• DeepSeek V3: $0.27 / $1.10 (~$0.002 per message)

Realistic monthly API costs:

• Light use (10 messages/day): $3-10/month

• Moderate use (50 messages/day): $15-50/month

• Heavy use (automated tasks running overnight): $50 →

Mac Mini vs. Server Cost Comparison

The Complete System

The guide above gets you a working AI assistant. But if you want OpenClaw to actually help with design system work, you need the right skills and configuration.

1. Design System Skills Pack

Skills teach OpenClaw how to use tools. Each skill is a SKILL.md file with instructions. Browse available skills at ClawdHub.

Install skills via ClawdHub CLI:

clawdhub install steipete/bird      # Twitter/X access
clawdhub install steipete/goplaces  # Google Places API
clawdhub update --all               # Update all installed skills

Some useful skills for design system work:

• bird: Monitor design system discussions on X, post updates

• Web browsing (bundled): Research design patterns, check documentation

• File system (bundled): Monitor token files, read component code

• Git (bundled): Track repo changes, review commits

Create your own skill:

Skills live in ~/clawd/skills/. Create a folder with a SKILL.md:

---
name: token-validator
description: Validates design token usage in code files
---

## Instructions

When asked to validate tokens:
1. Scan files for raw hex colors (#XXXXXX)
2. Check for primitive tokens used in components
3. Report violations with file paths and line numbers

OpenClaw learns from your SKILL.md and applies those instructions when relevant.

2. SOUL.md Template

This is the personality file that shapes how OpenClaw thinks and responds. Copy this into ~/clawd/SOUL.md:

# Identity

You are a Design System Assistant specialized in helping design and engineering teams maintain consistency, quality, and adoption of their design system.

## Core responsibilities

1. **Token management**: Monitor token files for changes, validate naming conventions, flag breaking changes
2. **Component health**: Track component usage, identify inconsistencies, suggest consolidation opportunities
3. **Documentation**: Keep docs current, generate changelogs, answer team questions
4. **Adoption support**: Help teams migrate to new components, explain design decisions, provide code examples

## How you communicate

- Be direct and specific. "Button uses wrong token" not "there might be an issue"
- Include file paths and line numbers when referencing code
- Provide copy-paste solutions when possible
- Flag severity: 🔴 breaking, 🟡 warning, 🟢 info

## What you monitor

- Changes to `/tokens/` directory
- PRs that modify component files
- Issues tagged with `design-system`
- Figma file updates (when connected)

## Scheduled tasks

- **Daily 9am**: Summarize overnight PRs affecting design system
- **Weekly Monday**: Generate component usage report
- **On PR merge**: Check for token violations in changed files

## Token naming conventions

Follow this hierarchy:
- Primitive: `color.blue.500`, `spacing.4`
- Semantic: `color.background.primary`, `color.text.danger`
- Component: `button.background.default`, `input.border.focus`

Flag violations when:
- Raw hex values used instead of tokens
- Primitive tokens used directly in components
- Semantic intent doesn't match usage (e.g., `danger` on non-destructive action)

## Response format for alerts

When alerting about issues, use this format:

**[SEVERITY] Issue Title**
- File: `path/to/file.ts:42`
- Problem: What's wrong
- Fix: How to resolve it
- Context: Why this matters

Customize the scheduled tasks and monitoring paths to match your repo structure.

3. GitHub Webhook Setup

Make OpenClaw respond to repository events in real time. This requires the Gateway service to be running.

Step 1: Generate a webhook secret

Ask it to create a webhook based on your configuration and it will help you.

Step 4: Add webhook to GitHub

1. Go to your repo → Settings → Webhooks → Add webhook

2. Payload URL: https://webhook.yourdomain.com/github

3. Content type: application/json

4. Secret: The hex string from Step 1

5. Events: Select “Let me select individual events”

   • Pull requests

   • Push

   • Issues

   • Issue comments

Step 5: Test it

Create a test PR. Within seconds, OpenClaw should message you on Telegram with a summary.

4. Automation Recipes

Five ready-to-use workflows. Tell OpenClaw to set these up, or configure manually.

✨ Recipe 1: Token Sync Alerts

Trigger: Any push to tokens/ directory

When files in /tokens/ change:
1. Parse the diff
2. Identify added/removed/modified tokens
3. Check for breaking changes (removed or renamed tokens)
4. Send Telegram alert with summary
5. If breaking: tag as 🔴, list affected components

✨ Recipe 2: PR Review Summaries

Trigger: New PR opened

When a new PR is opened:
1. Read the PR description and changed files
2. Identify design system impact:
   - New components?
   - Token changes?
   - Breaking changes?
3. Generate summary for Telegram:
   - PR title and author
   - Files changed (grouped by type)
   - Design system impact assessment
   - Suggested reviewers

✨ Recipe 3: Component Usage Reports

Trigger: Weekly (Monday 9am)

Every Monday at 9am:
1. Scan codebase for component imports
2. Count usage per component
3. Identify:
   - Most used components
   - Unused components (candidates for deprecation)
   - Components with declining usage
4. Generate markdown report
5. Post to Slack/Telegram and save to /reports/

✨ Recipe 4: Documentation Updates

Trigger: Component file changes merged to main

When component files change on main:
1. Parse the component's props/API
2. Compare with existing documentation
3. If mismatched:
   - Generate updated docs
   - Create PR with changes
   - Alert on Telegram

✨ Recipe 5: Weekly Health Check

Trigger: Sunday 8pm

Every Sunday at 8pm:
1. Run token validation across all files
2. Check for console warnings in component tests
3. Verify all components have documentation
4. Count open design system issues
5. Generate health score (0-100)
6. Send weekly digest:
   - Health score trend
   - Top 3 issues to address
   - Wins from this week

How to set up a recipe:

Tell OpenClaw in plain English:

Set up a scheduled task: Every Monday at 9am, scan the codebase
for component imports, count how often each is used, and send
me a summary on Telegram. Save the full report to /reports/weekly/

OpenClaw will create the automation and confirm the schedule.

Are you stuck?

1. Check the OpenClaw Discord for community help

2. Search GitHub Issues

3. Run openclaw doctor for automated diagnostics

What’s next

Once you have OpenClaw running:

1. Browse and install skills from ClawdHub:

clawdhub install steipete/bird
clawdhub install steipete/goplaces

1. Set up GitHub webhooks so your AI monitors your repos

2. Add more integrations like Discord or Slack

3. Customize the personality by editing SOUL.md in your workspace

You now have a personal AI assistant running 24/7 in the cloud. You control it from Telegram on your phone. And unlike ChatGPT or Claude.ai, it’s yours to customize however you want.

More to come …

Enjoy exploring and stay careful. 🙌

Explore more

🔗 Hetzner Cloud → Affordable European cloud hosting

🔗 OpenClaw Documentation → Official documentation

🔗 OpenClaw GitHub → Source code and issues

🔗 OpenClaw Website → Project homepage

🔗 Telegram BotFather → Create Telegram bots

🔗 Anthropic Console → Get your Claude API key

🔗 PM2 → Node.js process manager

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.

💎 Community Gems

Figma Console MCP Repo by TJ Pitre

Your design system as an API. Connect AI to Figma for extraction, creation, and debugging.

🔗 Link

If you’re anything like me, you’re tired of the same recycled advice about design system teams.

“Hire a design systems engineer.” “You need a dedicated team of 5.” “Document everything.” The playbooks written in 2022 still get passed around as gospel, even though the world shifted A LOT.

The “right” team size changed dramatically in the past two years. What required 3 people in 2023 can now often be done by 1 person with the right AI toolkit. And what required a much larger enterprise org can now often be done by a smaller, senior team. Well, if the whole delivery system evolves (review, testing, release), not just “writing code.”

But here’s the uncomfortable part: the landscape now changes almost weekly.

New AI capabilities drop constantly. Claude gets better. Cursor ships new features. MCP servers unlock new integrations. What was impossible 6 months ago becomes trivial this month.

This creates a paralyzing question I hear from every design system team: when does it make sense to invest in upskilling?

Most teams are stuck in this loop:

• “We should probably learn these AI tools properly.”

• “We should create our own LLM.”

• “But what if everything changes again next month?”

• “The time investment feels bigger than the payoff.”

• “Let’s wait until things stabilize.” 🫠

The problem? Things won’t stabilize.

The teams waiting for the “right time” are falling further behind those that have accepted that continuous learning is now part of the job.

The ROI calculation has flipped. The question isn’t “is it worth the investment?” It’s “can you afford NOT to, when your competitors are shipping 2-3x faster?”

This isn’t about replacing humans. It’s about understanding which roles become MORE important with AI, and which tasks you can delegate to AI tools.

I want to share 5 ideas on design system team structure that challenge the conventional wisdom and actually reflect reality in 2026.

Let’s begin.

The cheat sheet: company size → team structure

You aren’t struggling with headcount. You’re struggling with leverage.

Most design system leads I talk to have the same complaint: “We need more people.”

But when I dig into how they spend their time, I find the same pattern. Senior engineers writing documentation. Designers are manually auditing token usage. Leads are drowning in Slack support requests while their roadmap collects dust.

They don’t have a headcount problem. They have a leverage problem.

The reality is that design system work falls into two categories: work that requires human judgment and work that doesn’t.

Human judgment work:

• Deciding which components to build next

• Designing APIs that will scale

• Building relationships with product teams

• Navigating organizational politics

• Solving novel accessibility challenges

Non-judgment work:

• Writing the first draft of documentation

• Scaffolding component boilerplate

• Auditing tokens for consistency

• Generating changelogs from commits

• Triaging support tickets

In 2023, we had to do both categories ourselves. In 2026, AI handles the second category with minimal oversight.

If you want to scale your design system, you must have the systems that create scale before you add headcount.

Most teams add people first. Then wonder why the output doesn’t double. The new person gets absorbed into the same inefficient workflows. You pay for two people to do what one person with better leverage could accomplish.

I’ve seen 3-person teams outperform 10-person teams. Not because they worked harder. Because they understood which work to automate, which to delegate, and which to own.

The team of 10? They had more hands, but every hand was doing low-leverage work.

The traditional team models are obsolete. Here’s what replaced them.

The 1-person design system team (2026 edition)

You’re alone. You have to:

• Design components in Figma

• Build them in code

• Write documentation

• Evangelize adoption

• Handle support requests

• Maintain governance

• Plan the roadmap

In 2023, this was nearly impossible to do well. Something always suffered (usually documentation and adoption).

But even with AI, there’s a ceiling. One person cannot:

• Build deep relationships across 10+ product teams

• Ship major components AND do adoption evangelism simultaneously

• Handle a design system used by 100+ developers

AI extends your reach. It doesn’t give you infinite capacity.

Warning: The 1-person + AI model only works if...

This model is compelling, but it’s easy to dangerously over-generalize. It only works under specific conditions:

• Senior-level experience
  You’ve shipped design systems before. You know what good looks like. AI can’t replace the judgment you’ve built over years.

• Organizational trust
  Leadership gives you autonomy to make decisions without endless approval cycles. If every component needs a committee, AI won’t save you.

• Product maturity
  Your company’s product patterns are relatively stable. If requirements change weekly, you’ll spend all your time on context-switching, not leveraging AI.

• Technical foundation
  You can set up your own tooling. If you need someone else to configure CI/CD, MCP servers, or AI integrations, this model breaks down.

• Scope discipline
  You can say “no” to requests. One person + AI can maintain 20-40 components well. Trying to maintain 100 components solo is a path to burnout.

Red flags this model won’t work:

• Your org expects a “design system team” to also run the component library, documentation site, design ops, AND Figma governance

• You’re expected to support 5+ product teams with conflicting priorities, design changes, endless meetings, etc.

• There’s no executive sponsor who shields you from scope creep

• You’re junior/mid-level and still building core design system skills

If you don’t have these prerequisites, push for a 3-person team before accepting the solo + AI role.

The 3-person model

The 3-person model (2023):

• Design Systems Lead (Figma, design decisions, documentation)

• Design System Engineer (code, CI/CD, tooling)

• Product/Ops (roadmap, adoption, support)

This made sense when each domain required full-time effort. Documentation alone could consume 30% of someone’s week.

The 3-person model (2026):

• Design Systems Lead (strategy, governance, adoption – 60% strategic, 40% hands-on)

• Design Systems Engineer (components, CI/CD, AI tooling, MCP servers)

• Design Engineer (Figma library, design-to-code, prototyping, documentation)

Every team member needs these AI-era skills:

• Prompt engineering basics: Writing effective prompts for consistent output

• AI orchestration: Knowing which tool to use for which task

• Quality control mindset: AI output requires review; knowing what to check

• MCP/API literacy: Understanding how to connect AI to your systems

Traditional → now handled by:

Documentation writing → AI-assisted, owned by whoever builds the component

Support ticket responses → AI triage + templates, minimal human time

Changelog maintenance → Automated from commits

Usage analytics reports → Dashboards + MCP servers querying data

Contribution process → Templated workflows, AI-assisted code review

The real question isn’t “how many people?” anymore. It’s “how many people doing WHAT?”

What a 3-person team can realistically achieve with AI augmentation in 2026:

• 50-100 components maintained

• Support for a few product teams

• Bi-weekly release cadence

• Comprehensive documentation (AI-assisted)

• Basic design token automation

• Visual regression testing

• Accessibility compliance monitoring

The 10-person design system team (2026 edition)

At 10 people, you’re running what’s essentially an internal product. The challenge shifts from “can we build it?” to “can we coordinate it?”

Most 10-person design system teams fail not because they lack talent. They fail because they lack clarity.

• Nobody knows who decides what

• Design and engineering work in parallel silos

• Governance becomes bureaucratic gatekeeping

• AI tools are used inconsistently (or not at all)

• No change log (or decisions log)

Here’s what the optimal 10-person team looks like in 2026:

Strategic Layer (3 people):

• Director: Exec alignment, strategy, vision

• Product Manager: Roadmap, metrics, prioritization

• Adoption Lead: Evangelism, training, support relationships

Design Layer (2-3 people):

• Lead Designer: Architecture, governance

• Design Engineer: Figma + Code, prototyping

• Visual Designer (optional): Multi-brand systems

Engineering Layer (3-4 people):

• Engineering Manager: Architecture, code quality

• Platform Engineer: AI infra, CI/CD, MCP servers

• Frontend Engineers (x2): Components, features

Specialized (1-2 people):

• Accessibility Specialist: Compliance, auditing, training

• Developer Experience (optional): Docs, AI tooling, prompt libraries

The hiring signals that actually matter

Don’t hire based on company size. Hire based on these signals:

• You’re spending more than 50% of time on support and maintenance

• Adoption has stalled because you can’t do outreach

• You have a backlog of 6+ months of component requests

• Teams are building workarounds because they can’t wait for you

• You’re burning out

The skills that became MORE valuable

Own these:

• Strategic decisions: Which components to build next

• Design quality: Ensuring components solve real problems

• Relationship building: Getting teams to actually adopt the system

• Governance frameworks: Setting the rules (even if AI helps enforce them)

• Complex problem-solving: Edge cases, accessibility nuances, cross-platform considerations

Delegate to AI:

• First drafts of documentation

• Code scaffolding and boilerplate

• Token validation and linting

• Changelog and release notes

• Support ticket triage and initial responses

Delegate to product teams (with good tooling):

• Basic component usage

• Bug reports with clear templates

• Contribution of simple patterns

Roles that are becoming MORE important in 2026:

1. Adoption Lead

AI can generate components. It can write documentation. It can even respond to support tickets.

What AI cannot do is convince a skeptical product team to use your system instead of their custom solution. It cannot navigate the politics of a reorg. It cannot sit in a room and understand why adoption stalled.

The companies winning at design systems in 2026 have someone dedicated to this. Not as a side responsibility. As the main job.

2. Platform Engineer

Someone needs to set up and maintain the AI infrastructure. MCP servers. Automation pipelines. The tooling that lets AI access your design system data.

Most teams underinvest here. They use AI tools but don’t customize them for their context. They get generic outputs because they provide generic inputs.

3. Accessibility Specialist

AI catches basic accessibility issues. It can run automated scans and flag obvious violations.

But accessibility at scale requires human expertise for edge cases, cultural considerations, and training teams to think accessibly from the start. This role became more important, not less.

4. Developer Experience Engineer

With AI-assisted development, the quality of your AI tooling setup directly impacts productivity. The prompts. The context. The MCP configurations.

This role didn’t exist in 2023. In 2026, it’s a competitive advantage.

Roles that shrunk or merged:

1. Technical Writer (as a standalone role)

Documentation is now AI-assisted and owned by builders, not a separate function. The writer role evolved into “documentation architect” – someone who designs the structure and reviews AI output.

2. Junior Developers

AI handles much of what junior devs used to do. Copy-paste patterns. Boilerplate scaffolding. Basic component implementation.

Fewer junior roles, but those who remain need AI collaboration skills. The junior dev of 2026 is more like the mid-level dev of 2020.

3. Pure Visual Designers

Design engineers who can implement are more valuable than designers who only produce Figma files.

The 2026 Formula

Fewer people + Higher seniority + AI augmentation = Same or better output

A 1-person team with AI beats a 1-person team without.
A 3-person team with clear roles beats a 5-person team with unclear ownership.
A 10-person team with defined accountability beats a 15-person team playing politics.

Your design system team structure isn’t about hitting a magic number. It’s about:

1. Understanding what AI changed

2. Investing in the right roles

3. Matching structure to stage

4. Watching the signals

Start by auditing your current team against these models. What’s your biggest gap?

That’s where you either hire or leverage AI.

I’ve gathered more articles below, if you want to dig in to numbers or experiences from other companies.

Stay tuned and enjoy the process,

Romina

💎 Community Gems

Hackathon

February 6-8 2026 - Online

I am part of the jury and will also help you to hack faster ;) See you there. 😊

🔗 Link

• 84% of developers were using or planning to use AI tools in 2025

• GitHub Copilot now generates 46% of all code written by active users

• Design in 2025: Navigating the AI Revolution and Redefining Our Role

• 90% of Fortune 100 companies utilize GitHub Copilot

• Developers complete tasks 55% faster with GitHub Copilot

• Average time to open a pull request dropped from 9.6 days to 2.4 days

• The death of design expertise? How AI is reshaping creative industries forever

• Design Systems Report 2025 - An overview

• Top 5 Trends for 2025: How AI, Change, and Employee Experience Are Shaping Organizational Design

• Cursor study showed 39% increase in merged pull requests

• Gartner estimates 80% of engineers will need to reskill by 2027

• “Hiring someone who can see the big picture and work well with AI reduces the need for large, specialized teams”

— If you enjoyed this post, please tap the Like button below 💛 This helps me see what you want to read. Thank you.