← All work
CASEThis portfolio · Design systems · AI workflows

An AI-ready design system

Tokens and rules written for humans and machines, so AI generates on-brand UI by default.

Book a 30-min call ↘
Role
Designer & builder
Team
Solo, with Claude as pair
Scope
Tokens, components, AI rules, this site
Duration
Oct 2026
What I did
Token architecture, component specs, AI rules file, generated pages, automated checks.
source of truth (tokens.json)
1
raw colours outside tokens (tested)
0
The problem

AI tools generate UI fast, but off-brand: random colours, spacing and type drift with every prompt. A design system only helps if the AI can read it.

Research

How I went to the field.

  1. 01

    Audit of AI output

    Generated pages with AI tools and listed where they drifted: colours, spacing, type, tone.

  2. 02

    Source of truth

    Found that drift came from rules living in several places, written for people only.

What we learned

What the field told us.

01

AI follows files, not intentions.

Rules written for machines (exact tokens, anatomy, do/don’t) beat a style guide written for people.

02

One source of truth or drift.

If colours live in three places, the AI picks the wrong one.

Design

From evidence to screens.

  1. 03

    Tokens

    Moved every colour, size, space and radius into tokens.json, compiled to tokens.css.

    Tokens
  2. 04

    Components

    Ported the InStudy components (hero, kicker, pillars, tiles, timeline) on top of the tokens only.

    Components
  3. 05

    Rules for AI

    Wrote llms.txt: structure, components, do and don’t, in plain text an AI can load.

    Rules for AI
  4. 06

    Automated checks

    Tests fail if a page uses a raw colour, a missing link or an em dash.

    Automated checks
Key design decisions

What I chose, and what it cost.

01

Tokens as the only source of truth

Options
Hand-written CSS · or W3C design tokens compiled to CSS
Trade-off
One build step
Choice
tokens.json → tokens.css; pages may only use variables (a test fails otherwise).
02

Rules written for machines

Options
A Notion style guide · or a plain-text rules file (llms.txt)
Trade-off
Less pretty, far more usable by AI
Choice
/system/llms.txt: tokens, component anatomy, do/don’t, copy tone.
Outcome

Every page of this site is generated from the system. Open /system to see the components, and /system/llms.txt for the file an AI loads.