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

6 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.

Today I’m releasing Taste 1.0, a new model specifically designed for design system work.

Key capabilities:

• Generates components that match your system’s conventions

• Knows when to use ghost vs secondary vs tertiary

• Understands your spacing scale, your naming patterns, your anti-patterns

• Ships accessibility by default

• Never invents a new variant when an existing one works

Availability: today.

The model is a folder of markdown files. 🙃

I knoooow. You were hoping for something with 400 billion parameters and a clever name. But here is the thing:

You ask AI to generate a component. It ships something that looks fine. Then you paste it into your product, and it sticks out. Wrong spacing. Wrong naming. Wrong defaults. Wrong “feel”.

And you think: “I need a better model.”

You probably do not.

You need a “taste layer,” or in other words, an opinionated, structured set of guidelines. The best model in the world does not know what “good or good looking” means at your company. It does not know that you rejected outline buttons in 2025. It does not know that your spacing scale is 4px-based, not 8px. It does not know that color.text.muted it is for helper text, not placeholders.

No model knows this. No model will ever know this.

Unless you tell it.

That is what your set of markdown files can be. Your judgment, decisions, and taste, saved as context.

Two signals that this is where we are heading

First, Gartner predicts that by 2027, organizations will use small, task-specific AI models 3x more than general-purpose LLMs (Gartner press release).

However, we already moved from “pick a smart model” to “build a smart system”. And please don’t get me wrong, which model you choose still affects what you get in the end.

Model system vs model taste

Here is the simplest way I can explain it:

• Model system: the base model’s general capability. It can write, code, reason, and remix patterns. (Claude, GPT, Gemini, Llama, etc.)

• Model taste: your organization’s judgment layer. It defines what “good” means here. (Your markdown files: ds-core.md, ds-components.md, etc.)

Your taste lives in the files you maintain:

• ds-core.md says “use semantic tokens, never raw hex”

• ds-components.md says “max 4 variants per component.”

• ds-tokens.md says “we rejected 8px spacing in favor of 4px for density”

These files shape what gets produced and what gets rejected. They act like a conditioning layer on top of the base model.

I know what you are thinking

“Okay, but is this just documentation with a new name?”

Not really. These are opinionated, specific, structured guidelines for building user interfaces.

But here is what changes when you treat it like a system component:

• You version it.

• You review it.

• You prune it.

• You enforce it.

You write constraints so people and agents can ship consistently.

Routing is the shift

You do not ask every model to solve everything.

You first figure out what kind of problem this is. Then you route it to the right specialist.

Agent workflows need three things:

1. Routing: decide which specialist should answer.

2. Memory: keep decisions and context over time.

3. Specialization: use narrow experts instead of one generalist.

It is all about system design. Ask yourself, “How do we design an intelligent system made of many parts?”

The research backs this up. A 2025 study on instruction-following capacity (IFScale benchmark) found that even the best frontier models only achieve 68% accuracy when given 500 instructions. Most models show one of three degradation patterns:

• Threshold decay: near-perfect until ~150 instructions, then sharp decline

• Linear decay: steady, predictable drop across the spectrum

• Exponential decay: rapid early degradation, then floors at 7-15% accuracy

The takeaway: do not stuff everything into one prompt. Route to specialists with focused context.

Knowledge graph as the glue

When you split work across multiple specialists, you need something that keeps them aligned. That is the knowledge graph.

A knowledge graph is a structured representation of concepts and their relationships.

Think of it like this: instead of a flat list of definitions, you have a map. The map shows what things are, how they connect, and what rules govern their relationships.

In technical terms: nodes (things) plus edges (relationships) plus properties (attributes).

In practical terms: a shared vocabulary that everyone and everything can reference.

What does this mean for design systems?

For design systems, the knowledge graph answers questions like:

• What is a “Button”? What variants exist? What tokens does it use?

• What is color.text.muted? When do you use it? What is it not for?

• What is a “Card”? How does it relate to “Surface”? Can they nest?

• What counts as a “pattern” vs a “component” vs a “primitive”?

Without this, you get drift. One agent generates a GhostButton. Another generates a Button with variant="ghost". A third generates a TextButton. All three think they did the right thing.

With a shared knowledge graph, every specialist checks the same source before generating. They use the same names, the same relationships, the same constraints.

How is this different from regular documentation?

Regular documentation describes things. A knowledge graph connects things.

For example:

“Use muted text for secondary content” → color.text.muted → applies to → helper text, timestamps, captions

The key difference: a knowledge graph makes relationships explicit. An agent can traverse it. “What tokens does Button use?” “What components can go inside Card?” “What is the difference between muted and secondary?”

What should you put in your design system knowledge graph?

Design systems are evolving into intelligent context-aware systems.

Start with the foundation layers, then build toward the future.

Foundation layers (what you need today)

1. Primitives

The lowest-level building blocks.

• Colors (and their semantic mappings)

• Spacing scale (and when to use each step)

• Typography scale (and what each level is for)

• Radius, shadow, motion tokens

Example:

- Always use Tailwind CSS defaults
- Never use primitive design tokens on components

2. Components

The UI building blocks.

• Name, variants, states

• Which tokens each component uses

• Composition rules (what can go inside, what cannot)

• Accessibility requirements

- Check existing components before creating new ones
- Never hardcode colors
- Always check Storybook (link/token)
- Always check Figma UI kit (link) via Figma MCP
- Always check Gitlab (link)
- and so on ... 

3. Patterns

Combinations of components that solve recurring problems.

• Form layouts

• Navigation patterns

• Data display patterns

• Empty states, loading states, error states

- Always include one call to action
- Follow these rules for combining components (XY)

4. Decisions

The “why” behind everything.

• Why we chose X over Y

• What we tried and rejected

• When to break the rules

5. Taxonomy

The classification system that makes routing work.

• design vs engineering

• tokens vs components vs patterns

• new work vs existing pattern

Future layers

These are the layers that turn a design system into an experience system.

6. Context engine

How the system adapts to who is using it and what they need.

• Intent detection rules: what signals indicate the user wants X vs Y?

• Personalization mappings: user type → defaults, density, complexity

• Platform adaptation: web vs mobile vs embedded vs voice

• Locale rules: what changes per region, language, or market?

• Brand adaptation: how does the same component express different brands?

Example entry:

Intent: user wants to delete something

- Signals: clicked delete icon, selected items + pressed backspace, said "remove"
- Response pattern: show confirmation dialog (AlertDialog, not Dialog)
- Modality options: visual confirmation, haptic feedback on mobile, voice confirmation
- Escalation: if bulk delete > 10 items, require explicit confirmation

7. Interaction blueprints

Agentic flows and adaptive behaviors.

• Flows that shift based on user behavior (not just screen size)

• Proactive assistance patterns: when does the system offer help?

• Fallback rules: what happens when intent is unclear?

• Handoff patterns: when does the system escalate to a human?

Example entry:

Flow: onboarding

- Adaptive rule: if user skips 2+ steps, offer "skip to dashboard" option
- Proactive assist: if user pauses > 10 seconds on a field, show tooltip
- Modality switch: if voice detected, offer voice-guided onboarding

8. Multimodality mappings

One intent, expressed in the best way for the context.

• Touch, visual, audio, voice, gesture

• Haptic, text, ambient, motion

• Which modality is primary vs fallback for each intent?

• How do modalities combine?

Example entry:

### Action: confirm destructive action

- Visual: red button + confirmation dialog
- Voice: "Are you sure you want to delete [item]?"
- Haptic: warning vibration pattern before confirm
- Fallback order: visual → voice → haptic

9. Governance rules

How the system stays aligned at scale.

• Which decisions require human approval?

• Which outputs get auto-validated vs flagged for review?

• What are the hard constraints that never bend?

• How do you handle conflicts between agents?

You do not need fancy tooling to start

Start with markdown that acts like one:

Design Specs:

Colors:
- Background: #3B82F6 (primary), #FFFFFF (secondary)
- Text: #FFFFFF (primary buttons), #1F2937 (secondary buttons)
- Border: #E5E7EB (1px)
- Focus ring: #3B82F6 with 2px offset

Typography:
- Font family: Inter
- Font size: 14px (small), 16px (medium), 18px (large)
- Font weight: 500 (medium), 600 (semibold for primary)
- Line height: 1.5

Spacing:
- Padding: 8px 16px (small), 12px 24px (medium), 16px 32px (large)
- Gap between icon and text: 8px
- Minimum height: 32px (small), 40px (medium), 48px (large)

Visual effects:
- Border radius: 6px
- Box shadow: 0 1px 2px rgba(0,0,0,0.05)
- Hover: darken by 10%, lift shadow to 0 2px 4px rgba(0,0,0,0.1)
- Transition: all 150ms ease

This is not as powerful as a real graph database. But it gives you 80% of the benefit: shared definitions, explicit relationships, and a single source that agents can reference.

Why this matters for multi-agent systems

When you have a single model doing everything, you can embed context into a single prompt.

When you have many specialists, that breaks down. Each specialist sees a slice. If they do not share definitions, their outputs conflict.

The knowledge graph is the glue:

• All specialists reference the same definitions

• Outputs stay semantically aligned

• The system scales without drift

Without it, small models drift. Outputs contradict each other. Your system falls apart.

With it, models stay modular and coherent.

Binary tree routing: a mental model that makes this click

Think of routing like a decision tree. Each step narrows the problem.

Every decision reduces complexity until you hit the right specialist.

This is why small models work. They do not need to understand everything. They only need to understand their slice.

So, what I mean by “markdown is an additional model”

I mean, it behaves like a conditioning layer:

• It constrains behavior. It tells the system what “good” looks like.

• It compresses decisions. It prevents re-litigating the same debates.

• It generalizes across tasks. UI, copy, naming, motion, tokens, component APIs.

• It stays cheap to update. You edit a file. You do not retrain a model.

The taste kit: a folder of markdown files

Here is the key insight: if you are heading toward multiple specialists doing small things, your context files should mirror that.

Do not put everything in one giant CLAUDE.md.

Create multiple markdown files, each specialized for a specific design system task. When you route a task to a specialist, you give it only the context it needs.

The folder structure

.cursor/
├── ds-core.md           # Shared foundations (tokens, principles, stack)
├── ds-components.md     # Component creation and modification
├── ds-tokens.md         # Token decisions and naming
├── ds-prototyping.md    # Rapid prototyping rules
├── ds-ux-review.md      # UX review checklist and criteria
├── ds-documentation.md  # Writing component docs
├── ds-migration.md      # Migrating legacy patterns
└── ds-accessibility.md  # A11y requirements and testing

Each file is specific. Each file gets loaded only when relevant.

File 1: ds-core.md (shared foundations)

This is the only file every specialist sees. Keep it short.

# Design system core

## Stack
- React + TypeScript
- Tailwind CSS with design tokens
- Radix primitives for accessible components

## Principles (in priority order)

## Token rules

## Naming

File 2: ds-components.md (creating and modifying components)

Load this when the task is “create a component” or “add a variant”.

# Component creation rules

## Before creating a new component

## Component structure

## Variant rules

## Composition

## Anti-patterns

File 3: ds-tokens.md (token decisions)

Load this when the task involves tokens, theming, or color decisions.

# Token rules

## Naming convention

Examples:

## When to create a new token

## When NOT to create a token

## Token relationships

## Decisions log

File 4: ds-prototyping.md (rapid prototyping)

Load this when speed matters more than polish.

# Prototyping rules

## Goal

## What to skip

## What to keep

## Prototype checklist

## Output format

File 5: ds-ux-review.md

You can specify how to create automated screenshots, review work, review colors, etc.

# UX review criteria

## Consistency check
- [ ] Uses existing components (not custom implementations)
- [ ] Uses semantic tokens (not hardcoded values)
- [ ] Follows established patterns (not inventing new ones)
- [ ] Matches existing density and spacing rhythm

## Interaction check
- [ ] Interactive elements have visible focus states
- [ ] Destructive actions use confirmation dialogs
- [ ] Loading states use skeleton patterns
- [ ] Error messages appear near the action

## Accessibility check
- [ ] Color contrast meets WCAG AA (4.5:1 for text)
- [ ] Interactive elements are keyboard accessible
- [ ] Icon-only buttons have aria-label
- [ ] Form inputs have visible labels

## Content check


## Red flags (block the PR)

File 6: ds-documentation.md (writing component docs)

Load this when documenting components.

# Documentation rules

## Every component needs

## Writing style

## Props table format

## Do not include

The workflow: propose, route, generate, validate

If you want this to work in real teams, you need a repeatable workflow.

Step 1: Propose the intent

Write a short intent plus constraints in the PR description. One paragraph max.

Step 2: Route it

Decide which specialist should answer.

Start with a simple taxonomy:

• design / engineering

• tokens / components / content

• new pattern / existing pattern

Step 3: Generate with constraints

Give the specialist the minimum context it needs:

• ds-core.md (always)

• the task-specific file (ds-components.md, ds-ux-review.md, etc.)

• one canonical example if relevant

Step 4: Validate

Check the output against your rules:

• Does it use the right tokens for the right reason?

• Did it introduce a new variant?

• Does it follow your naming and composition patterns?

• Does it ship accessibility by default?

Step 5: Capture the decision

If you accept a new pattern, write down why.

If you reject it, write down the rejection rule.

This is how taste compounds instead of resetting every quarter.

Where to start

Start with two files and one task.

• Understand what a consistent, accessible, coherent UI looks like

• Know when to say NO to a new variant

• Capture decisions so taste compounds

• Evaluating output against real standards, not just “does it work?”

Here is a 60-minute plan:

1. Create ds-core.md with your stack, principles, and token rules. Keep it under 30 lines.

2. Pick your most common task. Component creation? UX review? Prototyping?

3. Create the matching task file. Start with ds-components.md or ds-ux-review.md.

4. Run one generation using only those two files as context.

5. Review the output. What did it get right? What rule was missing?

Then iterate. Add one file per week as new tasks come up.

Pro tip: If you use Claude Code, start with Plan Mode. It reads your codebase and markdown files before generating anything. This is exactly the “route first, then execute” pattern. Let it analyze your context files, propose an approach, then generate. You will catch misunderstandings before they become wasted code.

In short

You do not win in 2026 by picking the smartest model. You win by designing the system around it: routing, memory, specialization, and a shared source of truth.

Markdown is one of the fastest ways to build a taste layer that scales.

You got this.

Enjoy, Romina 🙌

Related read

🔗 Gartner predicts by 2027, organizations will use small task-specific AI models three times more than general-purpose large language models - Gartner press release on the shift toward smaller, task-specific models.

🔗 How to Write Good AI Agent Specs by Addy Osmani - Practical guide on structuring specs for AI agents, with emphasis on modular context and clear boundaries.

🔗 How Many Instructions Can LLMs Follow at Once? - Research showing instruction-following degrades significantly as instruction count increases.

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

💎 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

You’re watching another “build a design system in 4 hours” video and asking yourself: “Hoooooow?!” and thinking you’ll finally solve your component chaos.

I get it.

But here’s what the video doesn’t show:

• Three different button implementations across your codebase (plus more in Angular, Vue, and legacy jQuery)

• Developers asking “which token do I use?” (spacing, color, shadow... pick your confusion)

• The design system team of one, drowning in maintenance requests

• Leadership eventually seeing “why does our app look exactly like every other startup?”

This isn’t a design system. This is expensive copy-paste with extra steps.

I know what you’re thinking: “AI changes everything. We don’t need design system teams anymore.”

Let me show you why that’s only half true.

What changed in the last year(s)

Shadcn made component libraries free. Then came Radix, Ark UI, Park UI, and dozens more. AI made customization instant. Every startup can “build a design system in 4 hours.”

The narrative became: “You don’t need a design system team anymore.”

And they’re right until the codebase grows and customization takes up all your time.

Here’s what happens next:

Initial setup: Fast ✅
Customization: Much longer than expected
Answering “which variant?” questions: Ongoing forever
Fixing things when Shadcn breaks: Ongoing forever

Still cheaper than traditional design systems. But not free.

The trap you can fall into

This is where you can make expensive mistakes.

Startup reality:

• 10 developers

• One codebase

• Modern stack

• Can break things and move fast

Enterprise reality:

• 500 developers

• 12 codebases (React, Angular, new Next.js projects)

• Compliance requirements

• Cannot break things

Shadcn solves React. What about the other 60%?

Migration costs often exceed custom build costs by 3-5x when you have legacy systems. You’re not just migrating code. You’re retraining teams, updating tooling, managing parallel systems during transition, and dealing with breaking changes across multiple products.

From tools to taste

When you can buy a UI kit for $300 (or less) or copy Shadcn for free, leadership asks: “Why do we need a design system team?”

The answer most teams give is wrong. They say: “To build components faster.” But AI builds components faster than any team.

When software becomes cheap to create, the value shifts to problems that require deep context, taste, and ongoing stewardship. You just can’t buy judgment about what deserves to exist. That’s irreplaceable.

Old model:

• Design system team = Component factory

• Value = Shipping new components

• Success = Coverage+adoption (Do we have all the patterns?)

• Investment = Large team building everything from scratch

New model:

• Design system team = Curators + Strategists

• Value = Context

• Success = Coherence (Is everything consistent?)

• Investment = Smaller team + AI tooling

The role didn’t disappear. It evolved. And that’s actually good news if you’re willing to adapt.

AI amplifies what you already know. If you understand what makes a good pattern, AI helps you implement it 10x faster. If you don’t have that foundation, AI just helps you create garbage faster.

The data advantage

When everyone can generate a button in 30 seconds, the button has “no value”. The context for WHY you need this specific button is priceless.

Most design systems track adoption. That’s table stakes. The real advantage comes from capturing the context that’s invisible by default and compounds over time.

1. Usage data tells you what’s actually happening.

• Which components get used? Which gets ignored?

• How are they connected together? (The patterns that work best often emerge from real usage, not planning.)

• Where do people struggle? What gets copy/pasted instead of imported?

2. Decision history tells you why things exist.

• Why did we choose this pattern over alternatives?

• What did we try that failed?

• When should we sunset this?

Without this, every new team member asks the same questions. Every redesign starts from scratch. You lose years of learning.

3. Taste and curation tells you what deserves to stay.

• What’s been validated enough to standardize?

• What’s redundant and needs to be removed?

• What’s good enough to keep vs. what’s just legacy?

These three layers build on each other. Usage data informs decisions. Decisions shape curation. Curation improves usage. It’s a flywheel, but only if you’re capturing it.

Companies with this infrastructure will make better decisions 10x faster. The teams treating design systems like static libraries will drown in technical debt they can’t even see.

Making your system AI-readable

You’ve probably blamed the model when AI generates garbage. But the model isn’t the problem. Your context is.

Context is everything the AI sees when you ask it something. Your prompt, yes. But also the system instructions, previous messages, files it can access, and metadata. All of it.

And here’s the catch: AI tools have limited memory. Claude Code technically supports 200k tokens, but by the time you account for system prompts and tool definitions, you’re working with maybe 120k. Fill that up with noise, and the output quality tanks.

So the question becomes: what deserves to be in that limited space?

For design and design systems, I’ve found four things matter:

1. A project context file. Call it CLAUDE.md or whatever. Put it at the root. Tell the AI how your system works: naming conventions, component patterns, token structure, key decisions. This is the single highest-impact thing you can do.

2. Decisions in plain text. Not buried in Confluence. Not hidden in Figma comments. In markdown that AI can actually read. “We chose X over Y because Z.” Simple.

3. Lean documentation. Not 50 pages of Storybook stories. A clear reference that fits in context and answers the questions developers actually ask.

4. Tokens with intent. Not just color-primary: #0066FF. Explain why that color exists and when to use it. The AI needs the “why” to make good choices.

The goal? Anthropic calls it “the smallest possible set of high-signal tokens.”

Soooo, if your components keep coming out wrong, don’t switch models. Fix your context first.

The governance problem

AI makes creating components trivial. AI also makes creating BAD components trivial at scale.

Technical governance (solvable by AI):

• Linting rules ✅

• Type checking ✅

• Automated tests ✅

Human governance (still unsolved):

• Who decides when to add a new variant?

• How do we prevent “button-primary-new-final-v3”?

• What’s the process for breaking changes?

• Who has taste?

When creation is free, curation becomes priceless. The bottleneck isn’t “can we build this?” anymore. It’s “should this exist?” That question requires taste, context, and the courage to kill things. AI doesn’t have opinions. You do.

Cost of bad governance:

• Small company: Technical debt, slower velocity

• Enterprise: Massive duplicate work across teams

You can generate components quickly. You need years to build the taste, context, and governance.

Things are moving so fast that there are no books about new UX patterns. AI interactions, voice interfaces, spatial computing. We’re inventing the rules as we go. There’s no “Design Patterns” book for conversational U or best practices for AI-assisted workflows.

This means creating new ways of interacting requires more iterations than ever to build something genuinely useful. You can’t copy what worked before because “before” doesn’t exist for these patterns. You have to experiment, fail, learn, and iterate. Repeatedly. Until you discover what actually works.

The learning curve illusion

“Shadcn has a lower learning curve than traditional design systems.”

This is technically true, but strategically? Not so much.

❌ Before: Clear learning curve, high initial cost
✅ After: Fast start, expensive long-term maintenance

Lower initial learning curve ≠ Lower total learning cost.

You’re just deferring the learning to a more expensive phase.

What design system teams should actually do in 2026

Old job:

• Build React components

• Write Storybook documentation

• Fix component bugs

• Ship 2-3 components per quarter

New job (2026): Design System Lead

One person (or small team) with three responsibilities:

Curation:

Kill more patterns than you create. Use AI to generate, humans to judge. Ask “should this exist?” constantly.

Context:

Capture tribal knowledge before people leave. Translate the system into AI-readable formats. Maintain the “why” behind every decision.

Quality:

Track analytics on every component. Define “good enough” with data. Sunset bad patterns aggressively.

This isn’t a solo effort. Design systems require constant collaboration:

• Product teams need to understand business goals

• Designers and developers need to be in sync

• Stakeholders need to trust the system

• Leadership needs to see the value

You’re not just building software. You’re building organizational muscle memory about what good looks like.

My actual recommendations

Startup (<100 people)

Setup: Days, not months

✅ Use Shadcn/Radix + Tailwind
✅ Use AI for customization
✅ Assign someone to own consistency (part-time is fine)
✅ Track usage data from day one
✅ Document decisions in markdown (AI-readable)
✅ Accept you’ll rebuild every few years

❌ Build from scratch
❌ Hire a dedicated design system team
❌ Create perfect UI kit in Figma before product-market fit

The goal: Stay lightweight. Don’t over-engineer. Test what works.

Mid-size (100-500 people)

Setup: A few months

✅ Start with Shadcn for new projects
✅ Connect old and new with Web Components (see below)
✅ Dedicate someone to stewardship (not creation)
✅ Invest in analytics
✅ Use AI for generation, humans for curation

❌ Try to migrate everything at once
❌ Rewrite legacy code from scratch
❌ Build a massive team
❌ Copy enterprise approaches

Mapping old + new components

You have two paths for legacy components:

Option A:

Wrap it. Use Web Components to wrap legacy code. They work across React, Angular, Vue, and jQuery. Teams keep their existing APIs. The system modernizes underneath. Lower risk, slower progress.

Option B:

Regenerate it. Use AI to analyze legacy components and generate new components that match your target system. Feed AI the component code plus usage examples from your codebase. Validate the output. Replace the imports. Faster progress requires thorough testing.

Most mid-size companies do both: wrap the complex/risky stuff, regenerate the simple/well-tested stuff.

The goal: Bridge old and new without burning everything down.

Enterprise (500+ people)

Setup: Depends on your legacy!

✅ Custom design system is still worth it
✅ Small team focused on curation (not building)
✅ Invest more in governance than components
✅ Use AI for generation, not strategy
✅ Build data infrastructure around your system
✅ Measure outcomes, not adoption
✅ Use Web Components as the universal layer across all frameworks

❌ Try to move everyone to Shadcn
❌ Build components without usage data
❌ Measure adoption as success

Why Web Components make even more sense at scale:

Enterprise has the hardest legacy problem: React 2019, Angular 2017, Vue, jQuery, and whatever new framework the next acquisition brings. Web Components work everywhere. Build once, deploy across all frameworks. No more maintaining 4 versions of the same button.

The bridge strategy from mid-size applies here too, just on a larger scale. Wrap the legacy systems that are too risky to touch. Regenerate the simpler components with AI. Gradually consolidate.

ROI: Track how much time developers spend duplicating UI work. Even a conservative estimate shows the cost of inconsistency far exceeds the investment in a design system team.

Start with the right question

✨ “What problem are you actually solving?” ✨

“We need a starting point for components.”
→ Pick any library (Shadcn, Radix, whatever). But assign someone to own consistency from day one.

“We have 500 developers building duplicate UIs.”
→ Build a system. Hire a Design System Lead.

“We don’t know which patterns actually work.”
→ Invest in analytics.

“AI generates garbage code that doesn’t match our system.”
→ Make your system AI-readable. Then use AI.

“We can’t ship fast enough.”
→ Your problem isn’t just the design system. 🫢

What to do this week

You don’t need to build a design system right now. Start by building the infrastructure to know if you need one. Here’s a practical path:

Step 1: Set up analytics (Day 1-2)

• Track component usage

• Measure user outcomes

• Identify duplicate patterns

Step 2: Document decisions (Day 3-4)

• Create CLAUDE.md with context

• Make decisions AI-readable

• Capture the “why” behind every choice

Step 3: Test with AI (Day 5)

• Generate one component with AI

• See if it matches your standards.

• Identify gaps in your system’s clarity

Step 4: Make one decision (End of week)

Should you:

• Build a system?

• Use Shadcn?

• Invest in curation?

• Invest in agentic XY?

Base it on your data, not industry trends. Trust what you’re learning from your own context.

In short

Design systems in 2026 aren’t about components. They’re about CONTEXT.

Software is cheap to build.
Context is expensive to maintain.

Components are free.
Taste is priceless.

AI can generate anything.
Only humans know what deserves to exist (so start building taste).

The teams that understand this will build better products faster. The teams that don’t will spend hundreds on infrastructure that nobody uses.

And if you’re reading this, asking these questions, thinking critically about the path forward? You’re exactly the kind of person who will figure it out. 🙌

Enjoy the process 😊, 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

The Rise of the Model Designer

Interview with Barron Webster (Figma)

🔗 Link

This year, I stopped getting ready to get ready.

I went deep on AI and treated it like a mirror for my work: every workflow I had… I questioned. Some stayed. Many didn’t. Only Google spits out instant results → everything worth building takes reps.

If you read, replied, challenged me, shared your story, or trusted me with your work this year, THANK YOU. You made this year. 💛

If you want to go on a deep dive during the quiet days, here’s a curated list of what I built and published (or prepared) this year.

Start here

• YouTube (Design System Guide)

• The Design System Guide

• AI Design Guide

Guides

Creators 💛

(if you don’t follow them, start now 😊)

Alexander Fandén

Design Systems @Stripe

🔗 Linkedin

Check his 🔗 portfolio (inspiring for any design system designer) and listen to his 🔗 interview.

Vitaly Friedman

Vitaly is THE real UX king, sharing invaluable resources about all things design and UX.

🔗 Smashing Magazine

🔗 Linkedin

🔗 Smashing Events

🔗 UX Metrics Course

Sil Bormüller

Founder of

🔗 Website

🔗 Linkedin

🔗 Design System Jobs Portal

🔗 YouTube

/ Samantha Gordashko

🔗 Substack

🔗 Linkedin

🔗 Design Tokens aren’t enough. Architecture Decisions need a place in your Design System.

Ileania Notarangelo

Partner & Creative Director @ ILLO

My god, these animations are out of this world. Just check their work at illo.tv

🔗 Linkedin

Andressa Lombardo

Design System Lead @ Miro | Teacher @ Memorisely | Host @ IDS

🔗 Linkedin

Justine Montgomery

Design systems @Stripe

🔗 Linkedin

Listen to her talk about building a design system portfolio. Loooots of useful tips!

Growth Advisor, ex-Miro | Founder at Growthmates | Speaker · Creator

🔗 Linkedin

🔗 High-quality principles to support your Product-Led-Growth

Robin di Capua