Book a call

Writing

Field notes on design systems

How design systems are built, run and measured: tokens and components, governance and teams, and what actually changes once a system is in use. From work at CARS24, IBM and JPMorgan Chase.

74 articles14 reading paths7 topics

new course:

A twenty-part, step-by-step guide. Start at part 1, or jump to the question you have.

20 parts · 216 min · for designers and engineers

Making your design system AI-ready

How AI agents read a design system, and how to give them what they need: described tokens, component metadata, docs built for retrieval, AGENTS.md and llms.txt, an MCP server, a Figma library ready for Code Connect, guardrails and evals, and a phased plan for an existing system. Then the questions teams ask most: why AI ignores a system, context overload, accessibility, token drift, prototyping tools, shadcn/ui, designers' role, ownership, security and ROI.

  1. 1What is an AI-ready design system?14 min
  2. 2How AI coding agents use your design system, and where they go wrong12 min
  3. 3Design tokens for AI agents13 min
  4. 4Component metadata for AI agents14 min
  5. 5Writing design system documentation AI agents can use, and how retrieval finds it13 min
  6. 6AGENTS.md, llms.txt and rules files for design systems13 min
  7. 7Build an MCP server for your design system15 min
  8. 8Figma to code with AI12 min
  9. 9Guardrails for AI-generated UI11 min
  10. 10How to make a legacy design system AI-ready13 min
  11. 11Why does AI ignore my design system?10 min
  12. 12How much design system context does an AI agent need?9 min
  13. 13Why is AI-generated UI inaccessible, and how can a design system fix it?8 min
  14. 14Figma variables and code tokens out of sync?9 min
  15. 15How do I make Figma Make, v0 and Lovable use my design system?9 min
  16. 16Is shadcn/ui better for AI?8 min
  17. 17Can designers make a design system AI-ready without coding?8 min
  18. 18Who owns the AI rules?8 min
  19. 19Is it safe to connect your design system to AI tools?8 min
  20. 20How do you prove the ROI of an AI-ready design system?9 min
See the whole course

AI-ready design systemsWhy does AI ignore my design system? 10 causes and how to fix eachWhy Cursor, Claude Code, Copilot and AI prototyping tools ignore your components and tokens: ten causes, how to diagnose each in minutes, and the fixes.10 min readAI-ready design systemsHow much design system context does an AI agent need? Avoiding context overloadWhy giving AI agents your whole design system makes results worse: context windows, rules file length, too many MCP tools and progressive disclosure.9 min readAI-ready design systemsWhy is AI-generated UI inaccessible, and how can a design system fix it?Why AI-generated UI fails accessibility, what research shows, and how a design system fixes it: accessible components, rules, lint, axe and keyboard tests.8 min readAI-ready design systemsFigma variables and code tokens out of sync? How to fix token drift before AI copies itFix drift between Figma variables and code tokens: pick a source of truth, reconcile with a script, sync via DTCG import or Tokens Studio, check in CI.9 min readAI-ready design systemsHow do I make Figma Make, v0 and Lovable use my design system?Get AI prototyping tools to use your design system: Figma Make kits, v0 design systems and registries, Lovable design system projects, and guidelines that work.9 min readAI-ready design systemsIs shadcn/ui better for AI? Choosing a component library AI agents can useWhy AI tools favour shadcn/ui, which advantages your own design system can copy, when to switch or stay, and how to publish your components as a registry.8 min readAI-ready design systemsCan designers make a design system AI-ready without coding?What designers can do to make a design system AI-ready without code: token descriptions, usage rules, Figma prep, tool guidelines, templates and prompts.8 min readAI-ready design systemsWho owns the AI rules? Governance for an AI-ready design systemWho owns AGENTS.md, token descriptions and agent output: a decision-rights table, CODEOWNERS for AI rules, a policy for agent work and a feedback loop.8 min readAI-ready design systemsIs it safe to connect your design system to AI tools? Security, privacy and IPSecurity, privacy and IP when connecting a design system to AI tools: what's sensitive, data flows, prompt injection, MCP risks and a policy template.8 min readAI-ready design systemsHow do you prove the ROI of an AI-ready design system?Build a business case for an AI-ready design system from your own numbers: baseline evals, rework and review savings, a payback model and ranges.9 min readAI-ready design systemsWhat is an AI-ready design system? A complete guide for design system teamsWhat makes a design system AI-ready: one source of truth, machine-readable tokens and components, agent access via AGENTS.md and MCP, and guardrails.14 min read · GuideAI-ready design systemsHow AI coding agents use your design system, and where they go wrongWhat Claude Code, Cursor, Copilot and Codex read when they build UI, why they copy legacy code and hard-code values, and a one-hour audit to run.12 min readAI-ready design systemsDesign tokens for AI agentsMake design tokens usable by AI agents: DTCG 2025.10 JSON, semantic names, $description and $deprecated, an agent manifest from Style Dictionary, and checks.13 min readAI-ready design systemsComponent metadata for AI agentsDescribe components so AI agents use them correctly: typed props, JSDoc, react-docgen, Storybook manifests, Custom Elements Manifest and usage schemas.14 min readAI-ready design systemsWriting design system documentation AI agents can use, and how retrieval finds itHow to write design system docs for AI agents and RAG: self-contained sections, a page template, Markdown frontmatter, chunking, hybrid search and tests.13 min readAI-ready design systemsAGENTS.md, llms.txt and rules files for design systemsWhat a design system should put in AGENTS.md, CLAUDE.md, Cursor and Copilot rules, how to sync many repos, and how to write llms.txt for your docs.13 min readAI-ready design systemsBuild an MCP server for your design systemBuild a Model Context Protocol server for your design system: tool design, working code, Storybook and shadcn options, Inspector testing and setup.15 min readAI-ready design systemsFigma to code with AIGet on-system code from Figma: connect the Figma MCP server, match variables to tokens, mirror props in properties and map components with Code Connect.12 min readAI-ready design systemsGuardrails for AI-generated UIKeep AI-generated UI on-system: ESLint and Stylelint rules with fix-it messages, axe and visual tests, one check command, and evals that track progress.11 min readAI-ready design systemsHow to make a legacy design system AI-readyA phased plan to make an existing design system AI-ready without a rewrite: baseline, one source of truth, metadata, AGENTS.md, MCP, Figma and codemods.13 min readBuilding a systemComponent states: designing every state before you buildEvery state a design system component needs: interaction, data, content extremes and context, plus combinations and a stress test with real content.6 min readBuilding a systemComposition vs configurationWhen to give a component settings and when to compose it from parts: slots, compound components, recipes, and the signs a component should be split.5 min readFoundations & tokensComponent tokensWhat component tokens are, when a component deserves its own tokens, how to name them from its anatomy, and how to keep them healthy in Figma and code.5 min readBuilding a systemTesting a design system: visual, behaviour and accessibilityHow to test design system components: lint rules, behaviour tests, visual regression tests, automated accessibility checks and manual keyboard testing.6 min readBuilding a systemAccessibility in a design systemHow to build accessibility into a design system's foundations, components and patterns, and what product teams still own. WCAG 2.2 AA in plain words.5 min readBuilding a systemHow to organise a Figma design system library people can useHow to structure a Figma design system: separate libraries, pages grouped by job, names that match code, descriptions, life-cycle status and detach data.6 min readFoundations & tokensCross-platform design systemsHow to run one design system across web, iOS and Android: shared tokens generated for each platform, native components, and what to share or adapt.5 min readBuilding a systemA design system roadmap for the first twelve monthsA realistic first-year design system roadmap: four workstreams over four quarters, a gate that earns each next quarter, pilots and the rhythms to start.5 min readFundamentalsWhy design systems fail: ten failure modes and their antidotesThe ten ways design systems fail, from no engineering commitment to measuring usage instead of value, with the antidote and early warning signs for each.5 min readFundamentalsDesign systems for startups: the minimum that pays offWhat a startup actually needs from a design system: tokens in code, a themed component library, a small Figma library, two owners, and when to add more.5 min readBuilding a systemDesign system patterns: when components aren't enoughWhat design system patterns are, how they differ from components, the four pattern families to start with, and a template for documenting them.9 min readBuilding a systemForm design patterns: layout, validation and error messagesSeven form decisions a design system should make once: layout, required fields, when to validate, where errors go, what they say, long forms and buttons.7 min readBuilding a systemContent design in a design systemHow to put words into a design system: voice and tone, a shared vocabulary, formulas for buttons, errors and empty states, and writing for everyone.7 min readFoundations & tokensLayout grids and breakpoints for product UIHow to set up a layout grid for product UI: columns, gutters and margins, choosing breakpoints, named content widths, dashboards and layout tokens.7 min readFoundations & tokensLocalisation and right-to-left in a design systemGetting a design system ready for other languages: logical CSS, right-to-left mirroring, text that grows, plurals, locale formats and testing.7 min readBuilding a systemKeeping Figma and code in sync: five habits that stop driftHow to stop Figma and code drifting apart: one vocabulary, one token source, a shared definition of done, a monthly twin check and links between them.7 min readBuilding a systemDesign system tools by stageThe design system toolchain mapped: design, tokens, code, docs, quality and insight. The minimum tools for each stage, and what to automate first.6 min readGovernanceMigrating legacy products onto a design systemHow to migrate legacy products onto a design system without a big-bang rewrite: tokens first, screens as they're touched, codemods and clear end states.6 min readOperating model & teamsDesign system onboarding and training that keeps adoption growingHow to teach a design system continuously: first-week onboarding, a starter task, learning paths by role, training formats and finding knowledge gaps.7 min readOperating model & teamsDesign system research: how to learn what teams actually needHow to research a design system's users: interviews, observation, a five-minute survey, testing components and docs, and turning findings into a roadmap.7 min readFundamentalsThe design system maturity modelFive stages of design system maturity, how to tell which one you're at, what the next step takes, and why aiming for the top too early backfires.7 min readGovernanceDesign system versioningHow to version a design system so updates don't break products: what counts as breaking, visual breaking changes, deprecation and migration.6 min readFoundations & tokensDesign token naming conventions: a structure people can guessHow to name design tokens so people can guess them: the parts of a name, primitive, semantic and component patterns, common mistakes and a checklist.5 min readFoundations & tokensSpacing systems: 4px vs 8px, the scale, and how to use itHow to build a spacing system: choosing a 4px or 8px base, a spacing scale, inset, stack and inline space, density modes and responsive spacing.7 min readFoundations & tokensHow to build a type scale for a design systemHow to build a type scale: choosing a base and ratio, line height and letter spacing, naming text styles by role, fluid type and accessibility.6 min readFoundations & tokensColour contrast in design systemsHow to build colour contrast into a design system: WCAG 2.2 ratios, checking pairs not colours, a contrast matrix, pairing rules by step, and APCA.6 min readFoundations & tokensMulti-brand design systems: one core, many brandsHow to support several brands, platforms and products from one design system: what to share, what to vary, brand tokens and families of systems.5 min readBuilding a systemWhich components to build first: a prioritisation methodHow to choose your first design system components: count frequency and trouble, plot a 2×2, pick a pilot, and the eight components most teams start with.5 min readBuilding a systemBuild, borrow or buyShould you build design system components, use a headless library or theme a styled one? Trade-offs, a decision table and what we usually recommend.5 min readBuilding a systemComponent complexity: how to estimate design system workA scoring method for design system components: four levels of complexity, an eight-question rubric, and how complexity changes process and effort.6 min readBuilding a systemComponent props best practices: designing APIs people can useHow to design component props: the eight kinds of props, rules for good APIs, controlled vs uncontrolled, and keeping props in step between Figma and code.6 min readOperating model & teamsHow to run design system office hours people actually useHow to run design system office hours: format, hosts, outputs, timing across time zones, and what to do when nobody turns up.5 min readOperating model & teamsDesign system release notes and announcementsHow to announce design system changes: channels, timing, and copyable templates for releases, breaking changes, deprecations, token updates and digests.6 min readOperating model & teamsDesign system championsHow to run a design system champions programme and community: what champions do, time and recognition, community sessions and working groups.5 min readBuilding a systemAI in design systemsWhere AI genuinely helps design system teams today (docs, release notes, checks, migrations) and the cautions that matter when mistakes spread to every product.5 min readFundamentalsDesign system vs style guide vs component library vs UI kitFour terms people use interchangeably, and what each actually includes. A comparison table, a diagram of how they nest, and how to tell which one you have.8 min readFundamentalsDo you need a design system? A decision guide for startups and growing teamsSeven questions, five maturity stages and the signs you've outgrown a UI kit. A practical way to decide whether your team needs a design system yet.11 min readBuilding a systemHow to build a design systemAudit, foundations, tokens, first components, docs and governance, in order. A staged 12-month plan with gates, so you invest only as fast as it pays off.11 min read · GuideBuilding a systemHow to run a design system audit (with an interface inventory method)Screenshot, group, count and prioritise every button, field and colour in your product. A step-by-step UI audit that ends in a ranked plan, not a slide.8 min readFoundations & tokensDark mode with design tokensBuild dark mode by swapping semantic tokens, not redesigning screens. A worked example with checked contrast ratios, naming rules and the common traps.8 min readFoundations & tokensHow to build an accessible colour palette in OKLCHWhy OKLCH beats HSL for UI colour, and how to build even, accessible ramps step by step. With a computed palette and contrast numbers you can check.10 min readGovernanceDesign system governance: who decides what, and howGovernance without bureaucracy: decision rights, a lightweight review process, escalation paths and a decision log. How it should change as you grow.9 min read · GuideOperating model & teamsDesign system team structureWho you need on a design system team, at what company size, and where they report. Org charts, a role table and the signs it's time to grow the team.8 min readGovernanceDesign system contribution modelA contribution model that scales: one front door, a request form, a scoring formula for priorities, contribution levels and the review flow.8 min readBuilding a systemDesign system documentationWhat people actually read in design system docs, the sections every component page needs and how to structure the portal. A page template to copy.8 min readBusiness case & measurementHow to measure design system successWhich design system metrics to track at each stage: adoption, coverage, detach rate, satisfaction, time saved. With a dashboard layout and survey questions.7 min readBusiness case & measurementDesign system ROIWhat a design system really costs, where savings come from and when it pays back. A transparent model with break-even by team size and its limits.9 min readOperating model & teamsMost design system leads are just librariansWhy maintaining a library isn't the same as leading a design system, and what leading one actually involves.3 min readOperating model & teamsDesign systems as operational backbones5 min read · on Medium ↗FundamentalsMost design systems are just expensive UI libraries8 min read · on Medium ↗Foundations & tokensFoundations of modern design systems5 min read · on Medium ↗

reading paths:

Curated sequences for learning a subject from the start. Each article still stands on its own.

Path 01 · 4 articles · 39 min

Design Systems 101

The basics, for anyone new to design systems.

  1. 1What is a design system?13 min
  2. 2Design system vs style guide vs component library vs UI kit8 min
  3. 3Do you need a design system?11 min
  4. 4The design system maturity model7 min
Start the path
Path 02 · 3 articles · 27 min

Building one

From the first audit to a documented system people can use.

  1. 1How to build a design system11 min
  2. 2How to run a design system audit8 min
  3. 3Design system documentation8 min
Start the path
Path 03 · 6 articles · 43 min

Tokens in practice

Tokens, colour and themes, with real values you can check.

  1. 1Design tokens10 min
  2. 2Design token naming conventions5 min
  3. 3How to build an accessible colour palette in OKLCH10 min
  4. 4Dark mode with design tokens8 min
  5. 5Multi-brand design systems5 min
  6. 6Cross-platform design systems5 min
Start the path
Path 04 · 4 articles · 26 min

Foundations in depth

Spacing, type, contrast and layout: the decisions every screen inherits.

  1. 1Spacing systems7 min
  2. 2How to build a type scale for a design system6 min
  3. 3Colour contrast in design systems6 min
  4. 4Layout grids and breakpoints for product UI7 min
Start the path
Path 05 · 4 articles · 22 min

Components in depth

Choosing, scoping and shaping the components teams build with.

  1. 1Which components to build first5 min
  2. 2Build, borrow or buy5 min
  3. 3Component complexity6 min
  4. 4Component props best practices6 min
Start the path
Path 06 · 4 articles · 35 min

The operating model

How design systems are run after launch: teams, decisions and requests.

  1. 1The design system operating model10 min
  2. 2Design system team structure8 min
  3. 3Design system governance9 min
  4. 4Design system contribution model8 min
Start the path
Path 07 · 4 articles · 22 min

Running it day to day

The rituals that keep a system trusted: help, releases, change and community.

  1. 1How to run design system office hours people actually use5 min
  2. 2Design system release notes and announcements6 min
  3. 3Design system versioning6 min
  4. 4Design system champions5 min
Start the path
Path 08 · 4 articles · 30 min

Patterns and content

How components combine, what the words say, and getting ready for other languages.

  1. 1Design system patterns9 min
  2. 2Form design patterns7 min
  3. 3Content design in a design system7 min
  4. 4Localisation and right-to-left in a design system7 min
Start the path
Path 09 · 4 articles · 24 min

Tools and twins

Keeping Figma and code identical, the toolchain behind them, and where AI helps.

  1. 1Keeping Figma and code in sync7 min
  2. 2How to organise a Figma design system library people can use6 min
  3. 3Design system tools by stage6 min
  4. 4AI in design systems5 min
Start the path
Path 10 · 3 articles · 20 min

Growing adoption

Teaching the system, listening to the people who use it, and bringing older products along.

  1. 1Design system onboarding and training that keeps adoption growing7 min
  2. 2Design system research7 min
  3. 3Migrating legacy products onto a design system6 min
Start the path
Path 11 · 5 articles · 27 min

Building components well

States, composition, tokens, testing and accessibility: what makes a component last.

  1. 1Component states6 min
  2. 2Composition vs configuration5 min
  3. 3Component tokens5 min
  4. 4Testing a design system6 min
  5. 5Accessibility in a design system5 min
Start the path
Path 12 · 3 articles · 15 min

Planning the system

What to do at your size, a first-year plan, and the mistakes to avoid.

  1. 1Design systems for startups5 min
  2. 2A design system roadmap for the first twelve months5 min
  3. 3Why design systems fail5 min
Start the path
Path 13 · 2 articles · 16 min

Proving value

Metrics and money: how to show a design system is working.

  1. 1How to measure design system success7 min
  2. 2Design system ROI9 min
Start the path
Path 14 · 20 articles · 216 min

Making your design system AI-ready

Twenty parts, from what agents need to a phased plan, then the questions teams ask most.

  1. 1What is an AI-ready design system?14 min
  2. 2How AI coding agents use your design system, and where they go wrong12 min
  3. 3Design tokens for AI agents13 min
  4. 4Component metadata for AI agents14 min
  5. 5Writing design system documentation AI agents can use, and how retrieval finds it13 min
  6. 6AGENTS.md, llms.txt and rules files for design systems13 min
  7. 7Build an MCP server for your design system15 min
  8. 8Figma to code with AI12 min
  9. 9Guardrails for AI-generated UI11 min
  10. 10How to make a legacy design system AI-ready13 min
  11. 11Why does AI ignore my design system?10 min
  12. 12How much design system context does an AI agent need?9 min
  13. 13Why is AI-generated UI inaccessible, and how can a design system fix it?8 min
  14. 14Figma variables and code tokens out of sync?9 min
  15. 15How do I make Figma Make, v0 and Lovable use my design system?9 min
  16. 16Is shadcn/ui better for AI?8 min
  17. 17Can designers make a design system AI-ready without coding?8 min
  18. 18Who owns the AI rules?8 min
  19. 19Is it safe to connect your design system to AI tools?8 min
  20. 20How do you prove the ROI of an AI-ready design system?9 min
Start the path

explore by topic:

Older essays are on Medium.