design system
A design system built for humans and AI tooling alike.
Headless components, tagged releases, and a registry-and-audit backbone that keeps Shield coherent across squads, internal and external products, with synced outputs to multiple platforms.
- Design System Lead
- React, Base UI, Tailwind v4, OKLCH tokens
- Figma library, Storybook, Registry
- Accessibility, Cross-platform, AI-legible
@ch/ui · anatomyOrigin
From one product's components to a shared foundation.
Charlie Health's products were built on Ant Design. It shipped fast early on, but as the design team pushed for higher fidelity, the cracks showed: heavy style overrides, breaking changes on updates, and a growing gap between Figma and production.
I wrote a technical proposal to the wider org making the case for a headless component system built on ShadCN and Tailwind, packaged as an internal dependency. The pitch centred on three things: design parity, reduced vendor lock-in, and a phased migration that wouldn't stall feature work. Once it had buy-in, Shield started taking shape.
How it was built
From Figma library to shipped dependency.
Shield was designed in Figma first, then built with AI-assisted tooling. MCP servers bridged design specs directly into code generation.
Foundation in Figma
Tokens, components, and patterns designed as a Figma library before any code was written.
Technical setup
Monorepo scaffolding, Base UI primitives, and MCP servers bridging Figma specs to code generation.
Implementation
Figma-to-code with AI assistance. Every component built to spec, tested, and documented in Storybook.
Rollout & adoption
Packaged as a real dependency, backed by a registry, and adopted across three products and multiple squads.
The foundation
Base UI primitives, not a shadcn fork.
Rather than fork shadcn wholesale, Shield was rebuilt on Base UI primitives with Tailwind v4, an OKLCH token pipeline, cva variants, and Phosphor icons. Every component exposes a data-slot styling hook and composes through one consistent pattern.
Distribution
Installed as a dependency, not copy-pasted.
v1.0.0 turned Shield into a real dependency, consumed via git tag. Later releases committed the prebuilt dist/ into the tag itself, so installs need no build step, a small decision that made adoption frictionless.
The system, in parts
OKLCH tokens, Base UI primitives, one vocabulary.
Color, type, and radius tokens define the language. ~69 components inherit it through cva variants and data-slot hooks. Three apps, one system.
Core
Ink
Blue
Forest
Semantic
Emerald
Crimson
Amber
Wisteria
Neutral
Neutral
Typography
Geist · Text scale
Feijoa · Headings
Border radius
Application colors
Base
Primary
Secondary
Tertiary
Card / Popover
Sidebar
Surfaces
Borders / Inputs
Destructive
Success
Warning
Notice
Usage guidelines
Opinions baked into the components.
Every component ships with do/don't guidance drawn from real product decisions. The rules live in Storybook as well as .md guideline files for agentic development.
Component Guidelines
Primary action trigger with variant hierarchy: default, outline, link, ghost, destructive.
Dismissive actions
Icon buttons
Placement and emphasis
The screens
Building Shield
Origin
Figma is the source of truth. Components are designed there first, built into real code, then consumed by Claude Design as the foundation for spec-driven development.
Technical foundation
Base UI primitives, Tailwind v4, OKLCH token pipeline, cva variants, and Phosphor icons. Every component exposes a data-slot styling hook and composes through one consistent pattern.
A real dependency
v1.0.0 turned Shield into a real dependency consumed via git tag. Prebuilt dist/ committed into the tag so installs need no build step. Adoption without friction.
Full component coverage
Across v1.1 to v1.3 the library went from a handful to complete shadcn coverage plus domain-specific pieces: a full chat stack, charts on Recharts v3, and a bespoke clinical week-schedule. ~69 components today.
Machine-readable registry
A hand-authored registry (shield-registry.yaml) documents every component's scope, variants, dependencies, and divergences from shadcn, written to be read by both engineers and AI agents.
Cross-platform tokens
With mobile on the horizon, tokens migrated to a DTCG source of truth. A spike proved OKLCH + color-mix() round-trips to resolved sRGB with zero fidelity loss. One token set across web, iOS, and Android.
AppShell and product IA
As patterns stabilized they got promoted into components, most notably AppShell, which packages the whole app chrome into a single component. Examples realigned to Client, Provider, and Practice Management.
Hardening
Before broadening adoption, the entire library was audited across three lenses and fixed in four batches: RSC boundaries, CSS-injection hardening, render memoization, and API-consistency cleanups.
Where Shield stands
Shield is at v1.6.0: ~69 components, prebuilt and versioned, backed by a registry and an audit engine, with a cross-platform token path underway. It powers the Client, Provider, and Practice Management apps, with mobile on the horizon.