Picasso IR's design system, built to be read by people and agents
Picasso is the design system for every IR product: 132 semantic tokens in light and dark, five theme axes, 44 documented components, one version across Figma, npm and the docs. The repo is the source of truth and Figma is a consumer. Every page is also served as Markdown, and the whole system ships as llms.txt files, so an agent building a screen reads the same rules an engineer does.
Impact the short version
- One token set powering Clarion, the provisioning portal and future IR cloud products
- Five theme axes (colour, radius, spacing, main and mono type) so a brand is a block of values, not a fork
- Published as llms.txt files, so an agent with the token table cannot invent a hex code
- Live components in the docs, with variants, states and content guidance beside them
Brew guide how to make one of these
- Dose
- 132 semantic tokens, 44 components, 5 theme axes
- Grind
- Tokens in the repo, then components, then docs and Figma sync from the same source
- Temperature
- On-colours are measured, not chosen: lightness is solved down until white text passes
- Time
- One version number across Figma, npm and the docs, released together
- Yield
- Clarion, the provisioning portal and future products themed off one token set, by people or by agents
The repo is the source of truth
Most design systems start in Figma and get ported to code, and the two drift. Picasso runs the other way. Tokens and components live in the repo as @ir/tokens and @ir/ui, the docs render the real React components, and Figma is synced from the same values. A change lands once and shows up everywhere with one version number.
Try the theming axes
Colour, radius, spacing, main type and mono type are the five axes. Below is a small piece of a Clarion screen built on Picasso's real token values. Flip the mode and the radius and spacing scales and watch every component follow, because none of them know their own colours.
- bg/app #F8FAFC
- bg/card #FFFFFF
- bg/primary/emphasis #007DA8
- radius 10px
- spacing x1
Agent readable
Every docs page is also served as Markdown, and the whole system is published as a set of llms.txt files: an index, the foundations, the components and the token table. When Claude Code or the Figma MCP builds a screen for IR, it reads these first. An agent with the token table cannot invent a hex code, and the content rules travel with it, so the copy comes out in IR's register too.
# https://ir-picasso.vercel.app/llms-tokens.txt bg/app surface-app light #F8FAFC dark #121926 bg/canvas surface-canvas light #EEF2F6 dark #0A0E15 bg/card surface-card light #FFFFFF dark #202939 status/healthy status-healthy light #079455 dark #47CD89 status/warning status-warning light #DC6803 dark #FDB022 status/critical status-critical light #D92D20 dark #F97066 # Never use a raw hex. Every colour in Picasso is one of these.
Foundations and content, not just components
- Foundations: grid, spacing, radius, typography, colour, with tokens and brand blocks that generate [data-brand] CSS
- Content: voice and register, casing, buttons and labels, errors, empty and loading states, numbers, units and time, terminology
- Components: 44 live React components with variants, states and guidance, from Accordion to Tooltip, including KpiTile, Meter, Stepper and ThresholdSlider for monitoring work
- Contributing: a component checklist, and a route for reporting off-system output back into the system
Where it lives
The docs are at ir-picasso.vercel.app. Clarion and the provisioning portal are built on it, and the design agents work that comes next is what it was built for: a machine-readable design contract that a prototype can be checked against.