Book a call

WritingAI-ready design systemsPart 11 of 20 in Making your design system AI-ready

Why does AI ignore my design system? 10 causes and how to fix each

Generic buttons, Tailwind blues, a pile of divs from a Figma link. When AI tools ignore your design system, the cause is almost never the model. A ten-minute diagnosis, ten causes with their symptoms and fixes, and a one-week rescue plan.

Diagram: an agent's request passes three checks (did it find the system, where did it learn, did anything say it was wrong) before reaching on-system UI.
On this page"It just doesn't use our components"
  1. "It just doesn't use our components"
  2. First, diagnose: three questions in ten minutes
  3. The ten causes at a glance
  4. Discovery problems
  5. Wrong-source problems
  6. Missing-guidance and feedback problems
  7. Context and tool problems
  8. A one-week rescue plan
  9. Common mistakes when troubleshooting
  10. The short version
  11. Frequently asked questions
  12. Further reading

The short answer

AI tools "ignore" a design system for one of ten reasons, and almost none of them are about the model. The agent never found the system (no rules file, no tools), found the wrong version first (legacy code outnumbers new code), couldn't tell options apart (undescribed tokens, overlapping components), had nothing to follow (no usage rules or patterns), got no feedback (no lint, loose types), or was drowned in context. Diagnose before fixing: read the agent's transcript, ask it where it learned each choice, and match the symptom to the cause in the table below. Each fix takes between an hour and a few weeks.

  • The fastest single fix is usually a short AGENTS.md with your package name and a "never use" list.
  • If the agent's checks all pass on off-system code, the problem is the checks, not the agent.
  • Part 11 of 20 in the series on AI-ready design systems. Parts 11–20 answer the questions teams ask most.

"It just doesn't use our components"

This is the complaint we hear more than any other. A designer prototypes in an AI tool and gets generic shadcn-style buttons. An engineer asks a coding agent for a settings page and gets bg-blue-600 everywhere. Someone pastes a Figma link and gets a pile of <div>s. The natural conclusion is that "AI doesn't work with design systems". The real story is more useful: an agent follows the path of least resistance through whatever information it can reach, and something on that path is pointing it away from your system.

Part 2 explained the agent loop: read instructions, search, open files, write, check. This article turns that into a troubleshooting guide. It follows Harbor, the made-up design system at a made-up payroll company, Kestrel, that we've used throughout the series.

First, diagnose: three questions in ten minutes

Don't start fixing until you know which of the ten causes you're dealing with. You can usually tell in ten minutes.

  1. What did it read?

    Open the agent's transcript or activity log. List every file it opened and every tool it called. Did any of them belong to the design system? If not, the problem is discovery (causes 1–3).

  2. Where did each choice come from?

    Ask in the same session: "For each component, token and helper you used, tell me where you learned about it." Answers like "I followed TeamCard.tsx" or "I used standard Tailwind colours" point to wrong sources (causes 4–6).

  3. Did anything tell it it was wrong?

    Run your lint and type check on its output. If they pass while the UI is clearly off-system, the problem is missing feedback (causes 7–8).

Agent ignored the systemStart here
→
Opened any system file?No → discovery: 1, 2, 3
→
Learned from the wrong place?Yes → sources: 4, 5, 6
→
Checks passed anyway?Yes → feedback: 7, 8
→
Still wrong?Context and tools: 9, 10
A diagnostic path. Work left to right; most teams find their main cause in the first two boxes.

The ten causes at a glance

#CauseTypical symptomFixEffort
1No instructions at the startOutput depends on who wrote the promptAGENTS.md section in every repo1 hour
2System not reachableAgent never opens anything from your packagePoint to manifests; add MCP tools1 day
3Tool doesn't support your stackPrototyping tool swaps in shadcn or generic componentsUse the tool's design system import, or a supported package1–5 days
4Legacy code outnumbers newCopies old components from nearby filesDeprecations, nested rules, lint, codemodsWeeks
5Options can't be told apartPicks the wrong blue or the wrong dialogToken descriptions; sharper component purposesDays
6Training data winsTailwind defaults, Material habits, invented propsSemantic-only theme; precise typesDays
7No usage rules or patternsRight parts, wrong combination or variantMetadata rules; pattern pagesWeeks
8No feedback"Done!" with off-system UILint with fix-it messages; one check command1–2 days
9Too much contextInconsistent results; ignores rules that existShorter rules; fewer tools; progressive disclosureDays
10Figma file doesn't identify the systemDesign-to-code makes divs and hex valuesVariables, attached instances, Code ConnectWeeks
Symptom → cause → fix. Effort is a rough guide for a mid-sized system.

Discovery problems

Cause 1: nothing tells the agent your system exists

Every agent session starts from zero. If nobody types "use Harbor" and no file says so, the agent has no reason to look. Fix: add a design system section to each product repo's AGENTS.md (or CLAUDE.md, or the tool's own rules file) naming the package, the "never use" list and the check command. The full template is in part 6. In AI prototyping tools, the equivalent is the tool's "guidelines" or "knowledge" feature (part 15).

Cause 2: the agent knows about the system but can't reach it

The rules file says "use Harbor", but the component list is a 4,000-line source folder, the docs are behind a login, and the tokens are in a SCSS file with no comments. The agent gives up and guesses. Fix: give it compact, reachable data: a component index and token manifest in the installed package (part 4, part 3), and ideally an MCP server that answers questions directly (part 7).

Cause 3: the tool can't use your stack

Some AI tools only work with certain frameworks or package formats. Figma Make's design system kits, for instance, currently support React packages; many app builders are built around React, Tailwind and shadcn/ui. If your system is Angular, Vue or web components, a tool may quietly substitute its defaults. Fix: check each tool's supported formats before blaming the output. Where your stack isn't supported, give the tool your tokens and written guidelines at minimum, so the look is right even if the components aren't.

Wrong-source problems

Cause 4: legacy code is easier to find than the system

This is the most common cause in established products. If 60% of files import the old button, an agent searching for examples will find the old button first and copy it, because that's what "following the codebase's conventions" means.

An illustration: the copied card

Symptom

Kestrel's agents keep producing LegacyCard even after AGENTS.md says to use Harbor.

Diagnosis

The transcript shows the agent searched for "Card", opened three feature files, and all three used LegacyCard. Code it read beat the rule it was told.

Fix

A nested AGENTS.md in src/legacy/ ("being removed; don't copy"), a lint error on new imports with the replacement named, and a codemod for the 40 most-copied files.

Fix: mark old code as old where the agent will see it (deprecation tags, nested rules files), make new imports of it fail lint, and migrate the most-copied files first. See part 10.

Cause 5: the agent can't tell your options apart

Six pale blues with no descriptions, or Modal, Dialog and Sheet with purposes that overlap. The agent picks one, often the wrong one. Fix: a $description on every semantic token ("Use for… Not for… Use instead…") and component purposes that don't overlap, each with "avoid when" pointing to the alternative. If you can't write purposes that don't overlap, merge the components.

Cause 6: training data wins

Models have seen millions of files using Tailwind's default palette and popular component libraries. When your system is unclear or absent, those habits fill the gap: rounded-lg shadow-md bg-white, <Button variant="destructive">, size="large". Fix: make the defaults impossible or loudly wrong. Remove Tailwind's default palette from your theme so only semantic classes exist; type every option prop as a union so invented values fail to compile. Details in parts 3 and 4.

Missing-guidance and feedback problems

Cause 7: the parts are there, the rules aren't

The agent uses Harbor's real components but builds a settings page with three primary buttons, a table where a list would do, and an empty state with an illustration for a search that found nothing. Each part is correct; the combination isn't. Fix: write usage rules into component metadata ("one primary per view") and write pattern pages for the screens you build often (forms, tables, empty states, settings). Agents retrieve them when the docs are structured for retrieval (part 5).

Cause 8: nothing says "wrong"

If lint and type checks pass on off-system code, the agent reports success, and so would a person. This is the cause that hides all the others. Fix: lint rules for deprecated imports, raw colours and Tailwind defaults, each with a message naming the replacement; one check command; and a line in AGENTS.md telling the agent to run it. Agents read error messages and fix their own work (part 9).

Tool call · runpnpm check
ResultSettingsPage.tsx 18:5 error Raw colour in style. Use a semantic token, e.g. var(--color-text-secondary). SettingsPage.tsx 3:10 error Modal is deprecated. Use Dialog, or ConfirmDialog to confirm an action.
AgentReplaced the hex value with var(--color-text-secondary) and Modal with ConfirmDialog. All checks pass.
Illustration Feedback turns "ignored the system" into "corrected itself" in the same session.

Context and tool problems

Cause 9: too much information

The opposite of cause 2. A 1,500-line rules file, twelve MCP servers, and a prompt with the whole docs site pasted in. The rules you care about are buried and the agent applies them inconsistently. Fix: a short rules file that links out, a handful of task-shaped tools, and details loaded only when needed. Part 12 covers this in depth.

Cause 10: the Figma file doesn't say which system it uses

Design-to-code tools convert what the file says. Detached instances, raw hex fills and frames named "Frame 4182" carry no link to your components or tokens. Fix: variables named like your tokens, attached library instances, auto layout, and Code Connect for your most-used components (part 8). If variables and tokens have drifted apart, start with part 14.

A one-week rescue plan

If agents are ignoring your system today and you need visible improvement quickly, this order gives the most improvement per hour:

DayDoFixes causes
1Run three real tasks with an agent; save transcripts; score the outputDiagnosis
1Add the AGENTS.md section to the busiest product repo1, 4 (partly)
2Add no-restricted-imports for legacy packages and a raw-colour rule, as errors on changed files4, 8
3Write descriptions for the 30 most-used semantic tokens; remove Tailwind's default palette5, 6
4Write purpose and "avoid when" for the 10 most-used components; fix overlapping ones5, 7
5Rerun the three tasks; compare scores; decide what's nextMeasure
Five days, no new infrastructure. MCP servers, metadata files and Figma work come next, once you know which causes remain.

Common mistakes when troubleshooting

MISTAKE

Switching models first

A newer model may follow instructions better, but it can't use information it never sees. Fix the system, then compare models on the same tasks.

MISTAKE

Longer and longer prompts

Each failure adds a sentence to everyone's prompt. Move the rule into a file or a lint rule so it applies automatically.

MISTAKE

Judging from one run

Agents vary between runs. Run each test task several times before deciding something worked.

MISTAKE

Fixing the code, not the cause

Correcting the agent's output by hand fixes one screen. Correcting the description, rule or lint message fixes every future screen.

The short version

  • AI "ignores" design systems because of discovery, wrong sources, missing rules, missing feedback, context overload or unprepared Figma files.
  • Diagnose with three questions: what did it read, where did each choice come from, did anything say it was wrong?
  • The quickest wins: an AGENTS.md section, lint with fix-it messages, token descriptions and a semantic-only theme.
  • Legacy code that outnumbers new code is the most common cause in older products.
  • Fix the source of each mistake, not just the output.

Next: How much design system context does an AI agent need?

Frequently asked questions

Why does AI ignore my design system?

Usually because it never found the system, found legacy code first, couldn't tell similar tokens or components apart, had no usage rules to follow, or received no error when it went off-system. The model is rarely the cause.

Why does Cursor or Claude Code not use my components?

Check the transcript. If it never opened your package, add a rules file (AGENTS.md or CLAUDE.md) naming the package and how to look components up. If it copied old components from nearby files, mark them deprecated and add a lint rule blocking new imports.

How do I stop AI using Tailwind default colours?

Remove the default palette from your Tailwind theme so only semantic colour names exist, and add a lint rule that flags default palette classes with a message naming the semantic alternative.

Will a better AI model fix this?

Partly at best. Better models follow instructions more reliably, but every model depends on the information and feedback it receives. System-side fixes help with every model.

What's the fastest way to get AI to use my design system?

Add a short AGENTS.md section with your package name, a never-use list and a check command, then add lint rules for deprecated imports and raw values. Most teams see a clear improvement within a day or two.

Further reading