Storybook’s Semantic Color Tokens page — Brand and Text colour swatches, each labelled with its token name and hex value, beside the sidebar tree of token groups and components.
semantic tokens, rendered from the source of truth

The Problem

When you’re the founding designer at a company scaling toward an 8+ product portfolio, consistency isn’t a nice-to-have — it’s the only way one design practice can cover that surface area. Every product team building its own buttons, tables, and chat interfaces means duplicated effort, drifting quality, and an engineering handoff that starts from scratch each time.

Trinity also had a problem most design systems don’t address at all: its products are increasingly AI products. There was no shared pattern language for chat threads, model reasoning, citations, or explainability.

Most design systems stop at buttons and forms. This one needed a vocabulary for how AI earns trust.

The Approach

I framed the system as a product with its own users — engineers shipping screens under deadline, designers picking up new domains, PMs who need to know what’s possible. The question I optimized for wasn’t "what’s the right shade of blue?" It was "how do I make the right shade of blue the path of least resistance?"

Architecturally: a token architecture feeding modular bundles, feeding 100+ React + CSS components, 17 chart types, and 18 custom hooks, all distributed as one versioned npm package. Storybook is the single source of truth, with a synced Figma library — designers and engineers build from one foundation, and the handoff gap disappears.

On evidence: this is the one project where my proxy users were the real ones. The system’s users are Trinity’s own engineers, designers, and PMs — the people I sit with every day, whose complaints arrive unfiltered. Distribution is observable too: npm reports ~510 weekly downloads of the package across 38 releases. What I don’t have is the harder measure. A download is not a team, a component imported is not a component used as intended, and a forked copy in someone’s branch looks identical to compliance from the outside. The closing section names what I’d instrument.

Evidence base — daily contact with the system’s actual users · design critique · adoption review with product teams · npm download and release counts. Per-team usage not yet instrumented.

Icon Library in Storybook — search, a Material Icons / Feather Icons switch set to Material, and category filters above a grid of named icons under “125 icons found”.
Illustrations gallery in Storybook — search, Download All (15), and Empty States, Error States, Actions and Feedback filters above cards for Empty Table, Empty Drafts, Getting Started and Empty Documents.
WCAG Contrast Requirements in the Accessibility foundation — Level AA (4.5:1 normal text, 3:1 large) and Level AAA (7:1 normal, 4.5:1 large) cards, above a Testing Tools list of three tools for checking contrast.
DataTable’s Density Compact story in Storybook — a “Compact View” table header with search, columns, filter, density and download buttons; the sidebar lists the Density Comfortable and Density Comparison stories.
TransferList’s With Search story — an Available Members list of eight people with their departments and an empty Team Members list, each with its own search field, and four move buttons between them.
Chart Color Palettes in Storybook — numbered swatch rows for Primary (brand-anchored), Categorical, Sequential (light to dark purple), Diverging (red through neutral to purple) and a four-colour Status set.
AppLayout’s Sidebar With AI story — a Trinity top bar with search and a client dropdown, a sidebar of pages ending in an AI Assistant item, and Controls setting navStyle and aiTrigger to “sidebar”.
DashboardTemplate’s Default story — Total Revenue, Active Users, Orders and Conversion Rate KPI cards, a Revenue Trend chart slot, Sales by Category and Customer Demographics panels, and a Recent Activity feed.
ChatThread’s With Sources story — a user asks “Analyze the Q4 sales data”; the AI reply has copy, rating, share and download actions, a collapsed Sources (2) panel and two related questions.
AIChainOfThought’s Pipeline Analysis story — a collapsed Thought Process bar, an Analysis Complete summary (total time, rows processed, tables joined), three artifacts (dataset, charts, pivot tables) and a Top Regions Driving Growth card.
AIExplainability’s With Details story — an AI Classification card listing the model, 87% confidence, category, language and tokens used, with title, description, modelName and confidence controls below.
1 / 11 Tokens to templates to the AI module

Key Decisions

A token architecture that separates intent from value

Four layers — base → semantic → component → dark-mode. A designer picks text.primary or surface.elevated; the system handles the rest.

Modules, not a monolith

Seven independent bundles — tokens, theme, forms, data, charts, navigation, ai — so a product pulls only what it needs. The library shrank from 169 MB to 261 KB between releases: a 99.85% reduction.

AI as a first-class module

Most design systems treat AI as someone else’s problem. This one ships a dedicated AI module — chat threading, reasoning chains, citation panels, related-question suggestions, explainability surfaces.

Storybook as the single source of truth

The coded component is the canonical component. A synced Figma library keeps design and engineering looking at the same thing; token-aware linting catches hardcoded values in PR review.

Extended into AI prototyping

Replit and Perplexity skills integrations, an agent guide that also works in Claude, and a prompt library let PMs and leadership generate on-brand prototypes from the same foundation production builds on.

The Modules

M-01 · Tokenscolors, spacing, typography, shadows, easing — the foundation every module rests on
M-02 · Themetheme objects, CSS-variable generation, light + dark modes
M-03 · Formstext fields, comboboxes, file upload, rich text — built for dense, regulated workflows
M-04 · Datadata table, transfer list, tree view — three density modes for how enterprise reads tables
M-05 · Chartsline, bar, area, pie, scatter, radial, composed — brand spectrum for distinction, semantic for status
M-06 · Navigationtop nav, sidebar shell, breadcrumbs, drawer — the bones of a Trinity product
M-07 · AIchat threading, reasoning chains, citation panels, prompt input, explainability

The Figma Bridge

A synced Figma library is easy to claim and hard to keep true. Ours is held together by a mapping file: 86 components resolved from their Storybook story to a specific Figma node, so a component in code has one — and only one — counterpart in design.

The library is organised the way people actually build: atoms for single elements, patterns for Trinity-specific composites, templates for whole pages. A navigation guide turns the awkward question — "which page do I even open?" — into a lookup table from what you need to the exact component that provides it.

Drift is caught by CI rather than by memory. Scheduled jobs check Figma coverage against the component list, refresh snapshots, and inject design links back into Storybook, so the gap between the two shows up as a failing check instead of a surprise in review.

The Figma library’s “Which page do I use?” navigation guide — three cards for the atoms, patterns and templates layers, above an “I need…” → “Drag from here” table giving each need’s Figma page, component and layer.
the Figma library, mapped to the same names as the code
The Figma Icons page — an Outline icon set grid, each glyph a variant of one Icon component, above a coverage-gaps callout listing icons the React Icon component uses that are likely missing from the outline set.
parity tracked in the open: the icon page names its own gaps against the React source

Building With AI

The people who most need a design system are often the ones least equipped to use it — a product owner sketching a concept, an engineer on an unfamiliar surface, anyone who needs something on-brand by Thursday. Component libraries don't help them much. Prompts do.

So the system ships an agent guide: a set of instruction files you load once into whatever AI tool you already use, plus prompts you paste when you want something built. Three files, one job each — system rules that stay loaded, a new app prompt, and a migration prompt for an existing codebase that needs to become Trinity.

Setup is written per tool, because that's where people get stuck: drop the file in the project root for Replit, save it as .cursorrules for Cursor, as .github/copilot-instructions.md for Copilot, or paste it as the first message in Claude or ChatGPT. There's a slimmer variant for chat windows where pasting a long file is painful.

The system stops being a library you have to know how to use, and becomes an instruction the tool already understands.
The AI Agent Guide in Storybook — a “Build Trinity Apps with AI — No Coding Required” hero above eight What You Get cards: navy navigation, Montserrat type, pill buttons, card layouts, coral accents, charts, dark mode, responsive grids.
the agent guide, shipped inside the design system itself
Quick Setup by AI Tool — Replit, Cursor, GitHub Copilot and Claude or ChatGPT cards, each saying how to load the instructions file, above Download INSTRUCTIONS.md and Copy to Clipboard buttons and the file’s opening lines.
setup written per tool, with the instructions downloadable or copied in one click

Outcome

~510weekly npm downloads of the versioned package — an observable distribution signal, not a count of teams using it
38versioned releases, used across product teams for both production and AI-assisted prototyping
100+React + CSS components alongside 17 chart types and 18 custom hooks, with 74+ interactive Storybook stories
35+AI-specific patterns — chat threading, reasoning chains, citation panels, explainability
86components mapped component-for-component between code and Figma, with coverage checked in CI
~80%test coverage held as a contract — with token-aware linting and visual regression on every change
99.85%bundle-size reduction between releases — 169 MB → 261 KB
3prompt files — system rules, new app, migration — so PMs and leadership can prototype on-brand in the AI tool they already use
8+products in the portfolio the system was built to serve

The system is the reason a UX function of 3 senior designers plus 2 contractors can set direction across an 8+ product portfolio — and the reason Trinity’s AI products share one coherent language of trust.

What I’d Validate Next

Most numbers in the outcome above measure what the system is. The npm downloads are the exception: they show the package is being pulled, but not by which teams or how it’s used. None of them measures whether the system is working. These four would.

Is adoption real or nominal?

Downloads and imports are easy to count and easy to misread. I’d instrument component usage against forked copies and one-off overrides in each product repo — because the override rate, not the install count, is the honest adoption metric.

Does Storybook-as-canon survive a deadline?

Governance holds until a release is late. I’d track how often teams ship a local variant under pressure and treat every instance as a gap in the system rather than a failure of someone’s discipline — the system should be the fast path, not the virtuous one.

Does the Figma bridge stay synced?

86 mapped components is a snapshot, and the real question is drift six months on. CI coverage checks catch structural breaks but not semantic ones — a component that still maps but no longer means the same thing in both places.

On-brand, or merely on-brand-looking?

A non-designer generating a Trinity app is the strongest claim on this page. I’d have people outside the design team build something with the prompt files, then review the output against the system myself — the gap between those two judgements is the real result.

More
Works

← All work

Planning your next flagship product?

I work with teams building enterprise AI — where trust, data density, and compliance shape every pixel.

Start a conversation →
Available for new work · 2026