Spring Design Library — Leadership Brief

Audience: Leadership, Product, Business stakeholders
Purpose: What we built, why it matters, and what it enables
Last updated: July 2026

---

The One Thing to Understand

We built a single source of truth for every customer-facing product Spring Financial ships — and we wired it to AI.

This is not a component library. It is a product platform — the infrastructure that lets Spring's team discover, design, build, and ship financial experiences faster, more consistently, and at lower risk than before.

---

1. What We Had Before — and Why It Was Slowing Us Down

Before the Spring Design Library, building any customer-facing screen meant:

The compounding cost: Every product iteration started almost from zero. Design decisions were not reusable. Engineering time was consumed by reinvention rather than differentiation.

---

2. What We Built

The Spring Design Library is a monorepo design system composed of four interlocking pieces:

┌─────────────────────────────────────────────────────────┐
│           spring-design-library (monorepo)              │
│                                                         │
│  ┌──────────────────────┐  ┌─────────────────────────┐  │
│  │  @spring/ds-react    │  │  @spring/personal-loan  │  │
│  │  Published package   │  │  -appflow               │  │
│  │                      │  │  Application flow logic │  │
│  │  • 20+ components    │  │  • 24-step loan flow    │  │
│  │  • 254 design tokens │  │  • Step registry        │  │
│  │  • 1,173 icons       │  │  • Screen components    │  │
│  │  • Design rules      │  └─────────────────────────┘  │
│  └──────────────────────┘                               │
│                                                         │
│  │  Design Gallery      │  │  Personal Loan App      │  │
│  │  / (gallery root)    │  │  /personal-loans/*      │  │
│  │  • Documentation     │  │  • Production-style     │  │
│  │  • Live previews     │  │    standalone app       │  │
│  │  • Full AppFlow      │  │  • Proves injectability │  │
│  │  • Playground        │  │                         │  │
│  └──────────────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

The published package (@spring/ds-react)

Everything a product team needs to build a Spring-branded experience ships in one installable package:

The design gallery (/)

A live, always-current documentation site that replaces Storybook. Every component has:

• Interactive playground to see all states and variants
• Copy-ready code snippets
• Token reference
• Direct link back to the Figma source

The gallery is the approved visual handoff surface. Product engineers build from it; product managers and designers review from it; stakeholders demo from it.

---

3. How the System Works — The Virtuous Loop

The design library is not a static artifact. It is a living loop between design and code:

Figma Design
      ↓
  Design Tokens          ← single source of visual truth
      ↓
  React Components       ← tokens enforce consistency automatically
      ↓
  Application Flow       ← components compose into full product screens
      ↓
  Gallery (documentation)← living preview, always current
      ↓
  Product App            ← real app consumes the same package
      ↓
  Feedback to Design     ← gap reports, token updates, new components

The key insight: Because tokens sit at the foundation, a single approved visual change flows through every component and every screen automatically. No hunting. No inconsistency. No missed files.

---

4. What It Delivers Today

The Personal Loan Application Flow — fully built

The complete 24-step personal loan application — from landing screen through identity verification, income verification, bank connection, and outcomes — is implemented as a clickable, stakeholder-ready prototype.

Every screen is:

• Built entirely from @spring/ds-react components (≥90% DS usage)
• Accessible via gallery at /page/appflow/personal-loan/<step>
• Navigable as a standalone app at /personal-loans/<step>
• Registered in a single step registry — order, routing, sidebar state, and progress indicators all driven from one source

The component set — production-grade

The token system — design and code in sync

254 CSS custom properties covering:

• Primitive colors (the full Spring palette: plum, violet, blue, green, yellow, red, gray)
• Semantic colors (background, text, borders, graphics — named by purpose, not value)
• Typography (every text style defined and consistent)
• Spacing, radius, shadow, opacity, z-index, breakpoints
• Component-level tokens (button, input, overlay, surface — allowing per-component overrides)

The Figma bridge: Tokens are pulled directly from Figma's Variables API. A single command (npm run tokens:figma && npm run tokens:sync) regenerates all CSS variables from the design file. Design decisions propagate to code without manual translation.

Code Connect — Figma shows real component usage

20 Figma Code Connect files map Figma component properties to real component props. Designers inspecting a Figma component see actual production-ready code snippets, not generated approximations. This closes the handoff gap between design and engineering.

---

5. Why This Architecture Is Right

Three structural decisions distinguish this from a conventional component library:

Decision 1: Token-first, not component-first

Most teams build components and bolt on tokens later. We started with a validated token system. The result: every component automatically inherits visual changes, multi-brand theming is an architectural property (not a feature to be added), and design decisions are traceable from Figma to CSS to component.

Decision 2: The gallery replaces Storybook — intentionally

Storybook is excellent tooling for pure component development. We chose a living Next.js documentation gallery because:

• It is the same stack as our product apps (Next.js App Router)
• It can host full AppFlow screens, not just isolated components
• Stakeholders can navigate it without a developer present
• It proves the component set works in real compositions, not just in isolation

Decision 3: Package-first, gallery second

The gallery documents the package. The package ships the product. This separation means:

• Any React/Next.js app can install spring-design-library-react and inherit Spring's full design language
• The gallery can be rebuilt, reorganized, or replaced without touching the component API
• Product teams get a clear, stable import: import { SpringButton } from '@spring/ds-react'

---

6. The Agentic Workflow — AI as a Force Multiplier

The problem with AI-assisted development (before)

AI tools can generate code quickly. But without guardrails, they place files in the wrong location, skip validation, duplicate components that already exist, use raw color values instead of tokens, and produce handoffs that require significant rework.

Our approach: Outcome-first, human-in-the-loop

We built a structured agentic workflow that treats AI as a disciplined team member — not an autonomous code generator.

The core principle: Every AI-assisted task is classified by outcome before any code is written. There are seven outcome types:

Five agent roles ensure clean execution:

The human approval gate: The workflow stops for human review when:

• A new component would be created
• A token value would change
• A routing or structural decision is uncertain
• Three validation loops have failed

The result: Predictable file placement, no duplication, no raw visual values, no broken builds handed off without notice.

What this means in practice

A developer working with AI assistance on this codebase produces:

• Correctly placed files — every component, screen, and token in its documented location
• Wired injection points — every new component automatically exported, routed, and added to navigation
• Validated output — npm run build and npm run lint pass before handoff
• Reviewable handoff — a structured summary of what changed, where, and what was validated

The agentic workflow does not replace engineering judgment. It ensures AI-generated work meets the same standards as hand-written code.

---

7. The Roadmap — Where We Are and Where We Go

The dependency that matters most

M1 (working prototype)
  → M2 (validated by design + stakeholders + engineers)
    → M3 (architecture locked by DevOps)
      → M4 (injectable into any host app)
        → M6 (multi-brand theming)

M1 is the gate for everything. A walkable prototype is the prerequisite for every meaningful feedback loop, architecture decision, and external adoption step.

---

8. What This Enables — Business Value

Near-term (now)

Faster product iteration. When stakeholders want to see a different flow, a new screen, or a revised component state, it is a design token change or a gallery page update — not a multi-week development effort. The prototype is always one command from being current.

Shared vocabulary between design and engineering. Designers work in Figma with variables that map directly to CSS variables in code. When a designer changes --spring-color-plum-600, they know exactly what happens in the product app.

Consistent customer experience. With 254 tokens enforcing visual decisions, two engineers building two different screens will produce the same typography, spacing, and color — without a design review for every element.

AI-safe codebase. The agentic workflow with guardrails means AI tools cannot silently introduce technical debt. Every AI-generated addition is validated, placed correctly, and handed off with a clear record.

Medium-term (M4 — M5)

Any React app becomes a Spring app in hours. Once the injectable DS guide ships (M4), a partner product, vibe-coded prototype, or third-party integration can import Spring tokens and look like Spring Financial without forking the codebase.

Experiments without risk. The Playground lane (M5) lets designers and product managers propose new UI patterns, test them in the gallery, and graduate proven ideas into the package — without ever touching production code.

Long-term (M6+)

Multi-brand from a single codebase. Because tokens sit at the foundation, a Foundation-branded experience or a white-label partner app is a CSS variable override, not a separate design system. One codebase. Multiple visual identities. Zero duplication.

Platform for future financial products. Every new Spring product — auto loan, home equity, business credit — can start with the full Spring component set, AppFlow infrastructure, and agentic workflow tooling from day one.

---

9. Honest Assessment — What Is Production-Ready and What Is Not

Unambiguously production-ready

Not yet production-ready — and why it is the right call

This is not a gap list. It is a phased delivery plan where each milestone unlocks the next responsibly.

---

10. What Leadership Needs to Know

Three questions this system answers

1. Can we move faster without losing quality? Yes. The token-first architecture means visual changes propagate automatically. The agentic workflow means AI tools produce correctly placed, validated code. The component set means no screen is built from scratch.

2. Can we adopt this without a full rewrite? Yes. The injectable DS path (M4) is designed for exactly this — a host app imports one CSS file and one npm package. Spring's visual language applies without restructuring the host.

3. Can this scale to multiple products and brands? Yes, architecturally. The token layer supports CSS variable overrides per brand. The component API is brand-agnostic. The AppFlow registry generalizes to any multi-step flow. The practical path to multi-brand is M4 → M6, not a parallel effort.

The decisions that need leadership input

The ask

The design library is built. The AppFlow prototype is live. The agentic workflow is in active use. The token system is Figma-synced and regenerating correctly.

What we need now is stakeholder time: one walkthrough of the full personal loan flow, one design review session, and one architecture session with DevOps. Three meetings. That is what unlocks M2 and puts every subsequent milestone on track.

---

11. Scalability — Where We Are Honest

As a senior engineering team, we see the friction points clearly. Here is where the system will need investment as it grows:

These are known, tracked, and sequenced. None of them block delivery. All of them have clear resolution paths tied to the milestone map.

---

Appendix — Quick Facts

---

For the technical implementation guide, see docs/DEVELOPER_GUIDE.md.
For the full repo structure, see docs/REPOSITORY_STRUCTURE.md.
For the roadmap detail, see docs/planning/02-roadmap-and-milestones.md.