# Grist // Season 1 – The AI-ready Design System > Make a design system that coding agents use correctly. Human-curated loot for your AI tools, battle tested by Dawid Młynarz. ## Tokens-only Guardrail > A rule that keeps AI tools building UI from your design tokens and nothing else. - Drop: Rule (common) - Season 1 – The AI-ready Design System - Status: Tested (used on real work) - Published: 2026-08-28 - URL: https://www.mlynarz.com/grist/tokens-only-guardrail - Curated by: Dawid Młynarz **Hint:** Add it to the rules file of any repo with a design system, and the AI builds from your tokens and asks you before it adds a new value. ### Why I want control over the output. I don't want stray styles flying around the codebase. So I give it a guardrail, a rule it reads before writing any code. Without one, agents make styles up on the spot or hard-code everything. With it, colours, spacing and sizes all come from the system. When something really does need a custom style, the agent asks me first, and if I agree we add a token. ### The drop ````markdown When writing UI, use the design system's tokens for every colour, spacing, size, radius, shadow and font. Never write a raw value (hex, px, rem) if a token exists. If no token fits, stop and tell me which value you need instead of inventing one. ```` ## Token Description Writer > Write a one-line description for every token, by the job it does. - Drop: Prompt (uncommon) - Season 1 – The AI-ready Design System - Status: Tested (used on real work) - Published: 2026-09-04 - URL: https://www.mlynarz.com/grist/token-description-writer - Curated by: Dawid Młynarz **Hint:** For tokens that have names but no descriptions. Each one gets a $description you can paste into your token file. ### Why I used AI to write the descriptions for my tokens. It's quick across a whole token file, as long as I check what it guesses, because I know what each token is for and the model doesn't. Agents pick tokens by reading about them. A line that says when to use a token, and when not to, helps more than a clever naming scheme. ### How to use it 1. Paste a group of tokens at a time (all text colours, all spacing). 2. Correct anything that guesses wrong; you know the intent, the tool doesn't. 3. Add the descriptions to your token source, not to generated files. ### The drop ````markdown Write a description for each design token below. - One sentence: what it's for, by role ("text for errors and destructive actions") - Then "Don't use for:" one common misuse - Base it on the token's name, value and group. If the purpose isn't clear, write [ASK] instead of guessing. Output as JSON with the token path and "$description". Tokens: [paste] ```` ## Design System Audit > The things a design system hasn't decided yet, written down before anyone builds on it. - Drop: Checklist (rare) - Season 1 – The AI-ready Design System - Status: Tested (used on real work) - Published: 2026-09-11 - URL: https://www.mlynarz.com/grist/design-system-audit - Curated by: Dawid Młynarz **Hint:** When you document a design system or hand it to agents. You get an honest list of what's missing, each gap with an owner. ### Why When I documented a company website's design system, the most useful page turned out to be the list of what wasn't there yet. No design owner, no accessibility target, buttons drawn as static frames, spacing and radius not tokenised. Writing it down stopped people, and agents, from treating the gaps as decisions. The team took the list under consideration, and it gave everyone the same picture of where the system stood. It also made the build or adopt call easy. We adopted shadcn/ui, an open-source component library, instead of drawing every variant in Figma. It was the faster way forward, and the Figma side only had to match it. ### How to use it 1. Run it on the system as it is today, not as it's planned. 2. Write every unchecked item into the docs as an open item, with an owner and a date. 3. Link the open items from DESIGN.md or the README, so agents read them too. ### The drop ````markdown ## Design system audit ### Ownership - [ ] A named design owner, and who approves changes - [ ] A way to ask for a new component or token ### Accessibility - [ ] A written target (for example WCAG 2.2 AA, the common web accessibility standard) - [ ] Contrast checked for every text and background token pair - [ ] Focus styles defined as tokens ### Tokens - [ ] Colour, type, spacing and radius are all tokens; anything still hard-coded is listed - [ ] Raw values (primitives) and named roles (semantic tokens) are separate, and components use only the named roles - [ ] Every semantic token has a one-line description ### Components - [ ] Components are real components with variants, not static frames - [ ] Every component has its states (hover, focus, disabled, error, loading), or the missing ones are listed - [ ] Build or adopt is decided for each component family, with the reason ### Docs - [ ] Docs link to the source tokens and components instead of copying values - [ ] Open items are listed where agents read them (DESIGN.md or README) ```` ## DESIGN.md > One plain file that explains how your design system works, for people and agents alike. - Drop: Spec (epic) - Season 1 – The AI-ready Design System - Status: Tested (used on real work) - Published: 2026-09-18 - URL: https://www.mlynarz.com/grist/design-md - Curated by: Dawid Młynarz **Hint:** For when your system lives in a docs site, some Figma files and a few people's heads. You end up with a DESIGN.md at the root of the repo that agents read first. ### Why I wrote one for my own design system. Agents read files in the repo, not your documentation site, so this is the first thing they open. It links to the real tokens and components instead of copying their values, which keeps it from going stale. Once it existed, what the agents built came out more streamlined and consistent. DESIGN.md is becoming a common name for this file, and that helps. An agent that has seen one before knows what to look for. Don't paste token values in. Within a month they won't match the real ones. Below the drop is the one for this site, filled in from the same template. #### Example Here's an illustration of the _Layout_ section. _Pages use the 12-column grid (layout/grid). Content never touches the viewport edge; use space-page for margins. Do: stack cards with space-section between groups. Don't: nest cards inside cards; use list-item instead._ ### How to use it 1. Write it in under 300 lines; split into linked files if it grows. 2. Link to token and component files; never paste values. 3. Write rules as do and don't, naming the component each applies to. ### The drop ````markdown # DESIGN.md ## What this system is Who it's for and which products use it, in three lines. ## Principles 3–5 principles, each with a "this means" example. ## Where things live - Tokens: [path] (a JSON token file in the W3C design tokens format, with descriptions) - Components: [path], contracts in [path] - Patterns: [path] ## Foundations Colour, type, spacing, layout, motion: one paragraph each on how they're used, linking to the tokens. ## Components The 10 most-used components, one line each on when to use it, linking to its contract. ## Rules Do and don't pairs, each naming a component or token. ## Accessibility The guarantees the system makes, and what's left to product teams. ## Changing the system How to propose a change, and who decides. ```` ## Design Token Pipeline > Get Figma variables into code in one direction, through one standard token file. - Drop: Spec (legendary) - Season 1 – The AI-ready Design System - Status: Tested (used on real work) - Published: 2026-09-25 - URL: https://www.mlynarz.com/grist/design-token-pipeline - Curated by: Dawid Młynarz **Hint:** For tokens that live in Figma and keep drifting from the code. Figma becomes the source, and the code is generated from it. ### Why I built a small Figma plugin that turns Figma variables straight into a token file Style Dictionary can read. It keeps the links between tokens (a role pointing at a raw colour) and exports text styles too. I needed one specific export, JSON that follows the W3C design tokens format and that Style Dictionary reads as it is. So I built it. It's in the .zip with this drop now. From there Style Dictionary builds the code for each platform, and Storybook shows the result. For agents the important part is that code only ever sees the semantic layer, the names that say what a value is for. #### Example An illustration of a semantic token in the exported file. It points at a raw colour instead of copying its value, and says where it goes: ```json "link": { "$type": "color", "$value": "{color.blue.600}", "$description": "Links in body text" } ``` ### How to use it 1. Set up two Figma variable collections: primitives for the raw values (blue-600), and semantic tokens that point at them by role (color-text-link), with light and dark modes. 2. Export them with the Figma plugin in the .zip. It writes one JSON file and keeps the links between tokens. 3. Turn that file into code for each platform with Style Dictionary, an open-source token build tool. 4. Check the result in a page that shows every token, such as Storybook, before anyone builds with it. ### The drop ````markdown # Token pipeline ## Source - Tool: Figma variables - Primitives collection: raw values only (blue-600, space-16), no modes - Semantic collection: tokens named by role (color-text-link, space-section) that point at primitives; modes for light and dark - Rule: components and code use semantic tokens only ## Naming - Pattern: category-role-variant (color-text-muted, space-4, radius-md) - Every semantic token has a $description: where it goes, in one line ## Export - Format: one JSON file in the W3C design tokens format (also called DTCG, after the W3C Design Tokens Community Group), which Style Dictionary reads - Links between tokens stay links ({color.blue.600}), never copied values - Text styles export as typography tokens ## Build - Tool: Style Dictionary (open source) - Outputs: [the platforms you ship to: CSS variables, iOS, Android, React Native] - One build command; generated files are never edited by hand ## Check - One page (Storybook or similar) shows every semantic token in both modes - The automated build fails if the generated files don't match the latest export ## Owner - The design system designer exports after every change to the variables - A developer reviews the generated files in a pull request before they merge ```` ### When not to use it If your system has a handful of tokens that rarely change, keep one hand-written token file instead. If tokens are decided in code, not in Figma, don't make Figma the source. ## Token Description Lint > Check your token names and descriptions the way a coding agent reads them. - Drop: Prompt (uncommon) - Season 1 – The AI-ready Design System - Status: Tested (used on real work) - Published: 2026-10-02 - URL: https://www.mlynarz.com/grist/agent-readable-tokens - Curated by: Dawid Młynarz **Hint:** For any system coding agents build from. They pick the wrong colour or size a lot less often. ### Why Other designers have been flagging this one online. An agent picks the wrong token when all it has is a name. Reading `blue-500`, it has to guess what the colour is for. Reading `color-text-link`, with a line saying it's for links in running text, it mostly doesn't. So every semantic token gets its purpose written down. Primitives like `blue-500` don't need one, because components shouldn't use them anyway. ### How to use it 1. Paste the prompt with your token file, or the semantic tokens and their descriptions. 2. Fix what it flags. Use Token Description Writer for the tokens with no description. 3. Run it again after every batch of new tokens. ### The drop ````markdown Check these design tokens the way a coding agent will read them. For each semantic token, flag: - No description, or one that only repeats the name - A description of how it looks ("dark grey") instead of what it's for - Two tokens whose descriptions overlap, so an agent can't tell which to pick - A name built on a raw value (blue-500) on a token components use Skip primitives. Components shouldn't use them, so they don't need descriptions. Output a table: Token | Problem | Suggested description Then list any token you couldn't judge, marked [ASK]. Tokens: [paste your token file] ```` ## Component Usage Guidelines > Turn a component's code and docs into a contract that says what it's for, what it isn't for and what it promises. - Drop: Prompt (rare) - Season 1 – The AI-ready Design System - Status: Tested (used on real work) - Published: 2026-10-09 - URL: https://www.mlynarz.com/grist/component-usage-guidelines - Curated by: Dawid Młynarz **Hint:** For documenting components that agents will use. Each one gets a short contract in markdown. ### Why Every component page in my design system opens with a short description, and agents are the ones reading it. Props tell an agent what a component accepts. They don't tell it when to use one, so the description has to. The line that does the most work is what the component isn't for. For a button, that's "Don't use it to go to another page. Use a link." ### How to use it 1. Paste the component's code, props and any docs. 2. Fix the "don't use for" section; it's the most valuable line and the tool's weakest guess. 3. Save it next to the component. ### The drop ````markdown Write a contract for this component, under 200 words: - Purpose: one sentence - Use when: two or three situations - Don't use for: two or three common misuses, each with the component to use instead - Props that matter: only the ones that change behaviour - States: every state it supports - Easily confused with: the components an agent might pick instead, and how to tell them apart - Limits: content limits (max items, max characters) and accessibility promises Mark anything you inferred rather than read as [CHECK]. Component: [paste code and docs] ```` ## Design System for Conversational AI > Plan a design system for conversational AI products, with agent components first and names that match the code. - Drop: Skill (legendary) - Season 1 – The AI-ready Design System - Status: Tested (used on real work) - Published: 2026-10-16 - URL: https://www.mlynarz.com/grist/design-system-for-conversational-ai - Curated by: Dawid Młynarz **Hint:** For starting a design system for an AI product, or checking the one you have. It plans the components, pages and variable groups, and lists the gaps. ### Why I built [Anvil UI](/work/zazmic-anvil-ui), a design system for conversational AI agents, in four weeks. A few choices did most of the work. Agent components lived on their own page, apart from the global ones. Every component page opened with a short description. Colour variables were grouped by category and named exactly like the component library the developers used, so Figma and code read the same. And anything new that came out of client prototypes was flagged as a candidate, never added straight in. It ended up as a GitHub repo with Storybook, a browsable catalogue of every component in code. If I did it again, I'd start with only the components the first product ships, and add the rest when a second product asks for them. #### Example Here's an illustration for a booking assistant. The inventory starts with Message (agent), Plan card (agent), Approval (agent), Offer card (global card variant), Date picker (global). ### How to use it 1. Download the .zip and unzip it into your AI tool's skills folder. It holds `SKILL.md` and a list of agent components with their states. 2. Give it the product's agent surfaces, current screens and the code library you use. 3. Review the inventory before building anything; cut what the product doesn't need yet. ### The drop ````markdown --- name: agent-design-system description: Plans or audits a design system for conversational AI products. Use when starting a design system for agents, or checking one against the components agent experiences need. --- # Design system for conversational AI Ask for anything missing before you start. Never invent components the product doesn't need. ## Ask for - The product's agent surfaces (chat, side panel, inline suggestions, voice) - Screens or flows that exist today - The component library the developers use in code, if any ## Step 1: Inventory List the components the work actually needs. Split them into global (button, input, card) and agent-specific. Check the agent-specific ones against `references/agent-components.md`, and leave out any the product doesn't need. ## Step 2: Structure Propose pages: one per global component family, and one Agent page for agent-specific components. Every component page opens with two lines: what it's for, and when not to use it. ## Step 3: Variables Propose variable groups by category (colour, type, space, radius, motion), named like the component library in code, so a token reads the same in Figma and in code. ## Step 4: States For each agent component, list its states. Start from the states in `references/agent-components.md` and drop the ones it never reaches. ## Step 5: Intake rule Components found in client or product work are flagged as candidates, with where they came from. They're never added to the system directly. ## Report - Inventory: Component | Global or agent | States | Exists today? - Page structure - Variable groups and naming - Candidates and gaps ## Done when - Every agent surface from the inputs maps to components - Every agent component lists its states ## Agent components and their states Use this as a checklist, not a shopping list. Most products need half of these at first. | Component | What it's for | States | | ------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------ | | Message | One turn from the person or the agent | sending, streaming, done, error, edited | | Composer | Where the person writes or attaches | empty, typing, sending, disabled while the agent works | | Thinking indicator | Shows the agent is working before any text | thinking, taking long, cancelled | | Plan | The steps the agent will take, before it acts | draft, waiting for approval, running, done, changed | | Tool call | One action the agent takes, like a search or a booking | queued, running, done, failed, skipped | | Approval | Stops before an action that can't be undone, spends money or speaks for the person | waiting, approved, changed, declined, expired | | Citation | Where a claim came from | inline, expanded, source unavailable | | Result card | A structured answer, like an offer or a summary | loading, ready, outdated | | Error and retry | Something failed and what to do next | recoverable, needs the person, permanent | | Undo | Reverses what the agent just did | available, counting down, expired | | Handoff | Passes the conversation to a person | offered, waiting, connected, unavailable | | Activity log | What the agent did, in order, readable later | live, complete, filtered | | Feedback | Thumbs, flags or corrections on an answer | idle, given, sent | ```` ### When not to use it If the product has no chat, assistant or agent surfaces, start with Design system audit instead.