Saguaro Design System

Act 1 — The Bet

Treat the design system as engineering work, not a design artifact: build it where engineering builds, own it through engineering co-owners, defend it against the same review systems that gate features. That meant a Figma library that paired one-to-one with a Storybook component library in React + TypeScript, both fed from documentation that engineers wrote alongside shipping work. The cost was that the design lift, the political lift, and the engineering lift all had to happen in parallel, inside an org that didn't yet understand why a design system needed engineering investment in the first place.

Saguaro Design System architecture diagram — a system map showing qualitative data sources (Grain, Productboard) and quantitative data sources (Heap, Sisense) feeding into Trainual.design and Saguaro.trainual.com as the source of truth; from there into the UI component library (Chromatic for visual testing, Storybook for components) and the Design library (Figma application and universal components); with Asana tracking design work and Jira tracking development — The system the bet was for. Source-of-truth on the right; design library and UI component library composing against it; qualitative and quantitative data feeding prioritization upstream; Asana and Jira closing the design-tracking and development-tracking loops. Every Act below is some piece of this diagram getting argued into existence.

Act 2 — Constraints & Cost

I joined Trainual in early 2020 to take over a redesign already six months behind schedule from an external contractor. The work was nominally 75% complete, but what had been delivered was a style sheet rather than a component library — engineering was building against an inconsistent surface, and the product's brand-style feature let customers set their own button and link colors, meaning the primary purple could be re-skinned to orange, yellow, or red. It was an accessibility nightmare by construction.

The team had no real Figma library yet, no token discipline, and Figma in 2020 didn't have variants or variables. Component architecture had to be hand-rolled. My design peer was uninterested in systems work, and the leadership response to my requests for a second system designer was budgetary refusal. The cost was that the system work fell to one person at the same time the org was scaling squads.

Six months in, my performance review came back with no increase — the design-system work wasn't legible to a leadership team that measured designers on initiative throughput. The suggestion from my direct report was to drop the system work entirely. The uncomfortable lesson was that a system has to be defensible in the language the org already understands. The next phase had to be one where the system's value showed up in initiative velocity, not in slide decks about design.

The Trainual product surface as I inherited it — the mid-redesign state running on a stylesheet handoff rather than a component library — What I walked into: the redesign at 75%, running on a stylesheet handoff rather than a component library. Brand-style still let customers re-skin the primary purple to orange, yellow, or red — accessibility nightmare by construction.

The review caught me off-guard not because the rating was harsh — it was because the design-system contributions weren't part of the conversation at all. The work had rescued a redesign that had been mid-flight when I joined, built a usable Figma library from a style sheet, and produced one of the highest-performing squads in the org. None of it counted toward the review's initiative metric.

When I asked for specifics on how to improve, the feedback was vague — "maybe more collaborative design sessions, lunch and learns." When I named the actual gap — that I needed support for high-priority UI work — the suggestion was to drop the design-system work altogether.

The takeaway wasn't bitterness; it was a recalibration. From that point the work had to do double duty: ship the system, and make the velocity case in a language the review system actually measured. Every subsequent decision in this case study — the My Desk 2.0 Trojan Horse, the SCSS investment, the partnership with Matt — is downstream of that recalibration.

Act 3 — Decisions & Tradeoffs

Re-architect the inherited Figma file as a real component library

The first call was what to do with what I'd inherited. The contractor's handoff was a style sheet — a document describing how the UI looked — rather than a component library that engineering could build against. Figma in 2020 had no variants and only a primitive auto-layout, so every interactive component had to be hand-built across light/dark, hover, focus, disabled, with name conventions that would survive the arrival of the variants feature (which I knew was coming). The tradeoff was time — months of foundation work invisible to leadership — against the alternative of letting the existing stylesheet calcify into the surface that every squad ran against. Worth it. By the time Figma shipped variants in 2021, the library was already structured around them, so the migration was a refactor rather than a re-do.

Before/after of the Saguaro design files — handed-off stylesheet on the left, a structured component library with hover/focus/disabled states on the right — Design files, before and after. The rearchitecture wasn't a polish pass — it was the move from a stylesheet engineering couldn't build against to a component library they could.

Pick Zeroheight as the docs surface — and defend the choice

Leadership pushed back hard on Zeroheight. The pushback was sensible in shape — why aren't we documenting our design system in Trainual, our own documentation product? — but it ignored the engineering reality: Trainual at the time had no Figma integrations and no API, so it couldn't pull live design and code components into a doc page the way Zeroheight could. Using Trainual would have meant maintaining documentation by manual screenshot, divorced from the source of truth in Figma and Storybook. I had to make that case more than once. The decision held because the alternative would have produced documentation that drifted from the system within a sprint.

The Base Styles page at saguaro.trainual.com — full Zeroheight chrome with nav, sidebar, and live SCSS variables rendered as swatches — What won the argument. Base Styles on Zeroheight today: nav, sidebar, live SCSS variables rendered as swatches with their names. No manual screenshots, no drift.

Figma + Storybook + Zeroheight as a parity loop

The third call was the workflow. Storybook UI held the live components in React + TypeScript; Figma held the design components; Zeroheight knit the two together with documentation that pulled from both. The result was a three-way parity check: a discrepancy in any one surface was visible from the other two before it shipped. Designers and engineers caught divergence in real time instead of during release QA, which is where stylesheet drift had historically hidden.

Icon Button on saguaro.trainual.com, two tabs of the same component page. Left: the Overview tab — design-side anatomy with annotated components. Right: the Storybook tab — the live React + TypeScript component running inside the same docs surface, with real prop controls. Same component, both surfaces, one place to catch drift.

Grow the system by growing the team

The fourth call was who owned the system. Solo-owned systems die when the owner leaves; system squads scale when contribution is structured. Once Jen Fox joined as Design Lead, we used the system's accumulated proof to argue for dedicated systems headcount: a UI designer (Alex) who took ownership of the component library, then eventually a full design system squad. The transition required writing down what had been informal — a 30-60-90 onboarding plan for Alex, a contribution ladder for how squads proposed components into the system, documented quality bars for what shipped. The tradeoff was authoring overhead. The offset was that the system stopped depending on me to exist.

Dual Track Agile governance — two Asana boards side by side. Left: a 'Figma - Comp board' showing component debt metrics (167 items), Incomplete 6, Completed 142, with a task-completion chart over time. Right: a kanban board with columns 'In progress', 'Props/variants needed', 'Review' tracking components like Standard Buttons, Tabs, Tooltip, Badges, Modal Footer, Breadcrumbs, Dismissible Page Tip, Confirmation Modal, Multi Select Field — The contribution ladder made operational. Component debt tracked as a number; in-flight work tracked by stage; everything visible to anyone in the org. Dual Track Agile took the governance pattern out of my head and put it in a place the team could run on without me.

The DS1 squad that took over. The contribution ladder, the onboarding plan, the documentation — none of it mattered without the people the system was getting handed off to.

For the foundational color architecture that powered Saguaro — the SCSS palette, the brand-vs-theme decoupling, the migration through the legacy stylesheets with Matt — see the Palette System case study, which deep-dives the sub-initiative that Saguaro is built on.

Act 4 — Outcome

By the time the team grew through 2022, Saguaro was the substrate every squad shipped against. The development-time cost of new UI work dropped by roughly a third, design iteration speed by roughly half, and component reuse across squads reached ~90% — numbers that aligned with what the org could feel in cycle time even without instrumentation.

The Trainual product surface across three years — pre-Saguaro, mid-Saguaro, and Saguaro mature — showing how the system carried the surface through strategic pivots — The product surface across three years. Strategic pivots cancelled features, reshuffled pages, and rewrote navigation — the system carried through all of it because the foundation was real engineering code, not slides.

The system is still live. Three surfaces, one source of truth:

GitHub — trainual/saguaro — the open-source repo. Public, with the React + TypeScript component source, the SCSS palette, and the migration history.
Storybook — the live component browser. Every component renders with its prop surface so designers and engineers can compare against the Figma library in the same window.
Zeroheight — saguaro.trainual.com — the docs surface. Ties the Figma library and Storybook components together with usage guidance, design rationale, and color-perception docs.

What carried the system through the strategic pivots of 2021 — the cancelled Collections initiative, the Playbook Push, the new pricing architecture — wasn't the documentation. It was the architecture itself. Components built against the system survived the pivots because the foundation was real engineering code, not slides about a system; rebuilding surfaces against new pages cost minutes per component instead of hours. By the time I handed the work off, Saguaro had a dedicated design system squad, a contribution ladder, and a system identity that didn't depend on me.

"Already making converting designs to dark mode 4x faster and 4x less brain power." — Tyler R., Product Designer

"This is the best internal design documentation I've ever seen. Especially the color perception section, freaking amazing." — Jared G., Senior Engineer

"The design system you built at Trainual is so light years ahead — you have no idea." — Tyler R., Senior Product Designer

Saguaro lives across three publicly reachable surfaces, each doing a distinct job:

github.com/trainual/saguaro — the source. React + TypeScript components, SCSS palette and theme map, the commit history. Open-source on purpose; putting the repo where the engineering team's other repos lived made it harder to de-prioritize the system later.
saguaro-storybook.s3.amazonaws.com — the live component browser. Every component renders with its prop surface so a designer or developer can open it, see exactly what's available, and compare against the Figma equivalent in the same window. This is the executable source of truth.
saguaro.trainual.com — Zeroheight, on a custom subdomain. Knit Figma + Storybook together with usage guidance, the rationale for why decisions were made, the color-perception walkthrough that Jared called out. Documentation that pulls from both upstream sources rather than describing them after the fact.

The three-surface posture was the parity loop in practice. A discrepancy in any one surface — a Figma frame that no longer matched the Storybook prop, a Zeroheight page that referenced a removed token, a Storybook component drifting from its TypeScript source — was visible from the other two before it shipped.

Act 5 — Reflection

The honest lesson from Saguaro is that systems work survives leadership churn only when the system itself is defensible as engineering work, not as design taste. The Figma library was a design artifact and would have been the first thing cut in any prioritization meeting; the Storybook component browser and its tie into the codebase was an engineering artifact and couldn't be cut without breaking shipped surfaces. The system survived strategic pivots because the parts of it that mattered most were the parts engineering already owned.

The mistake I'd correct, if I were redoing it, is timing on dedicated headcount. The system needed a second pair of hands earlier than I argued for them — the year of solo lift was a tax I paid for not making the velocity case loudly enough. Design systems don't get funded as design; they get funded once leadership can read the velocity number. Saguaro made that case retroactively. The next system I built would make it up front, before headcount got requested.