Verdant UI

Overview

Spring Health was growing fast: three distinct products (Member, Clinician, Care Group), more than 20 designers, and a product surface that kept splintering. Every new feature was a re-negotiation of type scales, spacing, color meanings, and component behavior. Engineers were reinterpreting designs on every handoff. Brand consistency was slipping. Accessibility was a per-feature conversation rather than a default.

The problem wasn't a lack of taste — it was a lack of system. Design decisions needed to stop being re-litigated on every ticket and start being encoded once, correctly, and reused everywhere.

Verdant UI is that system. Token-first, multi-product, multi-mode, currently at v3.0.0-alpha.31 with 40+ production components, 82 library pages, and a guiding thesis:

"More than 20 designers contributing across the product, but the experience should feel as though it was crafted by one steady hand."

Three Decisions That Shaped the System

Semantic tokens, not appearance tokens. Every design decision is encoded as a variable whose name describes intent, not appearance. color.content.primary always means primary text — never green-500. This makes the system mode-aware (day/night switch for free), regionally portable (the positive role can remap from green to red in markets where red reads as positive), and machine-readable for AI. Variable scoping ensures a spacing token simply doesn't appear in color pickers — misuse is structurally impossible, not merely discouraged.

One system, many surfaces. Three products share the same component library but receive different visual treatments via product variable modes (member, atlas, compass). Components don't fork per product — tokens do. New product surfaces can be themed by flipping a mode rather than forking files.

The design file IS the handoff. Component properties in Figma map 1:1 to React props via Code Connect. Auto layout is mandatory. Hex values are banned. If a designer does it right, engineering builds it deterministically — no red-lining, no interpretation, no accessibility debt baked in at the source.

What I Built

Token architecture: Nine semantic color roles — primary, accent, magic (for AI and guided experiences), info, positive, warning, negative, neutral, media. Each role exposes 6 sub-tokens: base, on-base, bold, on-bold, subtle, on-subtle. The on- tokens are pre-validated for WCAG AA contrast against their paired backgrounds, so accessibility compliance is a property of the system, not a per-ticket audit.

Component library: 40+ published components (🍃 prefix), including 540 Button variants encoding emphasis × size × color scheme × state, and 104 Avatar variants. An emoji-prefix taxonomy makes production status legible at a glance: 🍃 Published, 🌱 Seedling (internal sub-component), 🪴 Slot (prototyping only), 🍂 Deprecated. Product-specific "cookie" components like 🍪 Navigation for Spring Care come pre-configured so teams don't re-assemble common surfaces from scratch.

Canonical page layout: Every Spring Care page composes from the same hierarchy — Screen → Navigation + Activity Wrapper → Activity → Activity.Content → Sections → Rows → Components. The Figma frame tree mirrors the React component tree, so engineering handoff is deterministic.

AI-ready infrastructure: Code Connect maps every VUI component to its production React counterpart. More importantly, I codified the system into a machine-readable skill (SKILL.md + 8 reference docs) that LLM agents — including Claude Code and Figma-generation skills — load before generating designs or code. The Atrium agents Iris and Sheena auto-load the verdant-design skill via frontmatter, so their Figma output stays inside the system by default. Verdant now has two kinds of users: designers and AI.

Typography: Muoto VAR as the primary brand typeface; a 4px-baseline scale across Heading (4 levels), Body (6 levels), and Data (2 levels). The strong variant uses a specific weight token rather than Figma's bold toggle — so weight is semantic, not ad hoc.

Outcome

Three products unified under one system. 20+ designers contributing on a shared spine. 82 library pages. Support for 30+ languages with 40–300% text-expansion tolerance built in from the start. Dark mode comes free with every new screen. Accessibility is a property of the system.

The downstream evidence shows up in Design Perception Score verbatims — prospects repeatedly citing consistency and polish as reasons Spring Health stands apart in the market. The system's job is to make that consistency structural rather than heroic.