Pocketpills Design system
Pocketpills Design system
Making PocketPills’ design system easier for AI, to understand and build with
Design system ✦ AI Workflow ✦ Context Engineering
Design Systems, UX Architecture, Visual Design, AI-assisted Design Workflows, Documentation
Design Systems, UX Architecture, Visual Design, AI-assisted Design Workflows, Documentation
UX Team, Dev Team (MX, Treatments)
UX Team, Dev Team (MX, Treatments)
Designers (2), Developers (4)
Designers (2), Developers (4)
An AI-ready design system foundation
An AI-ready design system foundation
Added a context layer that helped Claude make better design decisions.
Added a context layer that helped Claude make better design decisions.
We thought we had given Claude everything.
We thought we had given Claude everything.
The PocketPills design system already had the foundations covered — tokens, components, variants, states, documentation and implementation. Figma defined the visual language, Storybook showed how it behaved, and index.js made the components available in code. So we handed it over to Claude with a fairly simple expectation: this is PocketPills. Build with it.
The PocketPills design system already had the foundations covered — tokens, components, variants, states, documentation and implementation. Figma defined the visual language, Storybook showed how it behaved, and index.js made the components available in code. So we handed it over to Claude with a fairly simple expectation: this is PocketPills. Build with it.
The system was ready. Or so we thought.
With Figma, Storybook and code in place, we gave Claude the PocketPills design system and expected it to simply build with it
Alright, enough theory. Let’s give Claude a real brief and see what it does.
So we gave Claude a real problem to solve.
So we gave Claude a real problem to solve.
We introduced a new PRD for a “Treatment” screen and asked Claude to build it using the PocketPills design system. The brief wasn’t intentionally complicated. The components, tokens and even coded values were already available. In theory, this should have been a fairly straightforward exercise.
We introduced a new PRD for a “Treatment” screen and asked Claude to build it using the PocketPills design system. The brief wasn’t intentionally complicated. The components, tokens and even coded values were already available. In theory, this should have been a fairly straightforward exercise.
Testing Claude with the existing DS across boards
We gave Claude the PRD, the DS and coded values. It still invented styles, patterns and components instead of consistently using what already existed
Claude could access our components, but without the context around them, it was still filling in the gaps with its own assumptions.
Turns out, having the pieces wasn’t the same as knowing what to do with them.
Turns out, having the pieces wasn’t the same as knowing what to do with them.
With access to our Figma library and Storybook, Claude knew what existed. Give it a Button, and it knew what a Button looked like. Give it a Card, and it knew what a Card looked like. But ask it to build a real flow, and the hard part wasn’t rendering the components, it was deciding which ones belonged together, what should take priority and, sometimes, when not to use them at all.
With access to our Figma library and Storybook, Claude knew what existed. Give it a Button, and it knew what a Button looked like. Give it a Card, and it knew what a Card looked like. But ask it to build a real flow, and the hard part wasn’t rendering the components, it was deciding which ones belonged together, what should take priority and, sometimes, when not to use them at all.
Usage of primary CTA twice in the same frame
Alignment & hierarchy issues
Usage of different colour tokens from DS Library
Inconsistent typography style usage
Not picking up existing components
Usage of primary CTA twice in the same frame
Usage of primary CTA twice in the same frame
Alignment & hierarchy issues
Usage of different colour tokens from DS Library
Usage of different colour tokens from DS Library
Inconsistent typography style usage
Not picking up existing components
Knowing what a component does is easy but knowing when it shouldn’t be used? That’s where things got interesting.
The missing ingredient wasn’t more UI. It was context.
The missing ingredient wasn’t more UI. It was context.
Our tokens and components gave Claude the visual vocabulary. But the important decisions often lived elsewhere, in usage notes, existing flows, small implementation examples, and the judgement designers apply almost automatically. So instead of adding more components, we started looking at the context surrounding them.
Our tokens and components gave Claude the visual vocabulary. But the important decisions often lived elsewhere, in usage notes, existing flows, small implementation examples, and the judgement designers apply almost automatically. So instead of adding more components, we started looking at the context surrounding them.
Our existing system documented the building blocks, from foundations and components to their variants, states and specifications
Could Claude make a design-system decision, not just a design-system-looking screen?
So we started giving Claude the stuff that usually lives in a designer’s head
So we started giving Claude the stuff that usually lives in a designer’s head
We fed it more than primitives, molecules and components. We added small built pieces, usage notes, sample flows and the rules behind them, enough real product context for Claude to see not just what we had built, but how those pieces were meant to come together.
We fed it more than primitives, molecules and components. We added small built pieces, usage notes, sample flows and the rules behind them, enough real product context for Claude to see not just what we had built, but how those pieces were meant to come together.
Updated figma design system
The same building blocks, now supported by clearer rules, usage guidance and instructions of do’s & don’ts
Beyond the library, we gave Claude the guidance behind the system — what components do, when to use them and the rules that shape how they come together
Did giving Claude more context actually change what it built?
Did giving Claude more context actually change what it built?
We ran the same kind of task again, but this time Claude had more than the library. We wanted to see whether that extra context changed its decisions — what it reused, how it structured the screen, which patterns it followed and what it stopped inventing.
We ran the same kind of task again, but this time Claude had more than the library. We wanted to see whether that extra context changed its decisions — what it reused, how it structured the screen, which patterns it followed and what it stopped inventing.
Screen generated without context
Using Figma DS + Storybook + Code
Screen generated with context
DS + Usage notes + Rules + Examples + Flows
The difference showed up in the decisions, not just the pixels.
The difference showed up in the decisions, not just the pixels.
A polished screen can still be wrong. So instead of judging the output by how closely it resembled a Figma reference, we looked at the decisions underneath it: which components were chosen, how they were composed, what hierarchy they created and whether existing system rules were respected.
A polished screen can still be wrong. So instead of judging the output by how closely it resembled a Figma reference, we looked at the decisions underneath it: which components were chosen, how they were composed, what hierarchy they created and whether existing system rules were respected.
Pushing back on decisions using the rules of {PP.md} file
Making decisions how a designer at PP would
Using components instead of inventing new ones
Including the new addition in existing boiler plate design
A component can describe itself. A flow can’t.
A component can describe itself. A flow can’t.
A component library can document individual building blocks very well. It becomes much more useful when it also explains how those building blocks work together. We needed to capture the patterns, flows, hierarchy, brand decisions and constraints that help designers move from individual components to complete experiences.
A component library can document individual building blocks very well. It becomes much more useful when it also explains how those building blocks work together. We needed to capture the patterns, flows, hierarchy, brand decisions and constraints that help designers move from individual components to complete experiences.
The more context we captured, the less AI had to guess.
We didn’t build a new design system for AI. We added a context layer to make the existing one easier to understand.
We didn’t build a new design system for AI. We added a context layer to make the existing one easier to understand.
The tokens, components, Figma library and Storybook implementation stayed the same. We built a context layer around them that captured the knowledge usually left to designer judgement: how components should be used, when patterns apply, what constraints matter, how flows come together and how the PocketPills brand should sound and behave. The result was still the same design system, but with a richer layer of context that Claude could actually use when making design decisions.
The tokens, components, Figma library and Storybook implementation stayed the same. We built a context layer around them that captured the knowledge usually left to designer judgement: how components should be used, when patterns apply, what constraints matter, how flows come together and how the PocketPills brand should sound and behave. The result was still the same design system, but with a richer layer of context that Claude could actually use when making design decisions.
Video of whole instruction sheet
The funny thing about teaching AI our design system? It made us explain our own system better.
The funny thing about teaching AI our design system? It made us explain our own system better.
Designers carry a surprising amount of system knowledge in their heads. We know when a button feels too prominent, when a component is being stretched beyond its purpose, or when two individually correct components create the wrong experience together. Claude made those invisible decisions visible. If we couldn’t explain the rule, we couldn’t reliably give it to AI.
Designers carry a surprising amount of system knowledge in their heads. We know when a button feels too prominent, when a component is being stretched beyond its purpose, or when two individually correct components create the wrong experience together. Claude made those invisible decisions visible. If we couldn’t explain the rule, we couldn’t reliably give it to AI.
The goal was that instead of teaching AI the system conversation by conversation, make the system capable of teaching itself.
From design system to context engine
From design system to context engine
Today, we still bring the right context to Claude ourselves. The next step is turning that knowledge into structured, reusable content that AI can retrieve and reason with independently. That could mean documenting component intent, usage, relationships and constraints in machine-readable formats, creating a foundation that tools, agents and workflows can all build from.
Today, we still bring the right context to Claude ourselves. The next step is turning that knowledge into structured, reusable content that AI can retrieve and reason with independently. That could mean documenting component intent, usage, relationships and constraints in machine-readable formats, creating a foundation that tools, agents and workflows can all build from.
The next layer - Pocketpills MCP
Making design knowledge reusable for AI
The goal isn’t to give AI the right context every time. It’s to make the design system capable of providing it.
