What Your AGENTS.md Should Say About Your Design System
Nezar Mansour · 17 November 2026
Read the originalSupernova, which sells design system software, checked 30 public design system repositories and found no AI agent instruction file written for the product teams that use those systems.
Nezar Mansour, a content writer at Supernova, which sells design system software, reports on the AI agent instruction files in 30 public design system repositories. Sixteen had such a file on 16 November 2026, and every one was written for people who contribute to the design system. He offers a short section that a product team can add to the instruction file in its own repository.
- Of the 16 files, ten mention design tokens, the named values for colour and spacing, and five tell the AI agent to use tokens instead of hard-coded values.
- The suggested section tells the AI agent to import components from the design system's package and never to build a button, input or table from scratch.
- It also tells the AI agent to stop and ask when no token fits, and to name the component it would need when none exists.
- Mansour advises keeping the section short and pointing the AI agent to a live source for current values, because the file is read on every task.
A product team that builds on a design system can state its rules in the instruction file of its own repository, where its AI agents read them. This is a vendor's account, and the live source it recommends is the kind of product Supernova sells.
In the product repository's AI agent instruction file, require the agent to import components from the design system package and use its design tokens for colour and spacing.
Tell AI agents in writing which components and properties are deprecated, and what to do when no component or token fits.
Derived by Working Surface from the article; more in the Playbook. Source line: If you build a product on a design system, your agent needs the instruction in your repo, not in the design system's.
20 November 2026: as AI agents make prototypes, design tools and code cheap, the scarce work becomes a person's judgement and a named person answering for the result.