Spring Design Library — A Guide for UX Engineers

Audience: UX engineers, designers, and design-minded builders who are new to React and the code environment Purpose: Explain — in plain language — how this platform is built, how it works, who it serves, and how you would use it to build a brand-new application flow in a separate repository. You do NOT need to know React to read this. Where code appears, it is there to show you shape, not to require memorization. Read the words around it.

---

Table of Contents

1. The 60-Second Summary
2. The Mental Model (no code)
3. How We Built This Platform
4. How It Actually Works — The Loop
5. A Small Vocabulary So Nothing Is Scary
6. User Scenarios — Who Uses This and For What
7. Seeing It With Your Own Eyes (run it locally)
8. Next Steps — Building a Brand-New Flow in a Separate Repo
9. What You Can Do Safely vs. What Needs a Developer
10. Cheat Sheet

---

1. The 60-Second Summary

We built a shared kit of pre-made screen parts (buttons, input fields, modals, progress bars, loan cards) plus a shared palette of design decisions (colors, spacing, fonts). Every Spring product can pull from this one kit instead of rebuilding the same parts over and over.

The kit lives in one place and ships as a single installable package. Three things consume it:

• A gallery website that documents and previews every part (this replaces Storybook).
• A finished example — the full 24-step personal loan application — that proves the kit works in a real product.
• Any future app you or a developer create, which can install the same kit and instantly look and behave like Spring.

The magic is that design and code share one source of truth. When a designer changes a color in Figma, that change can flow all the way into the live product without anyone hand-copying hex codes. That is the whole point.

---

2. The Mental Model (no code)

Think of it like LEGO for financial product screens.

You never carve a new brick from scratch when one already exists. You snap existing bricks together. When you genuinely need a new brick, it gets added to the shared box so everyone can use it next time.

One rule underlies everything: you never type a raw color like #1A1A2E. You reference a named decision like "primary text color." That name is a token. If Spring rebrands, the name stays the same and the value behind it changes once — everywhere.

---

3. How We Built This Platform

3.1 It is a "monorepo"

A monorepo is a single project folder that holds several related sub-projects. Ours holds four:

spring-design-library/            ← the one project folder
├── packages/
│   ├── spring-ds-react/          ← THE KIT (components, tokens, icons, rules)
│   └── personal-loan-appflow/    ← the logic for the 24-step loan flow
├── apps/
│   ├── design-library/           ← the GALLERY website (docs + previews)
│   └── personal-loan/            ← the standalone example loan app
├── scripts/                      ← automation (e.g. pulling tokens from Figma)
└── docs/                         ← all documentation (this file lives here)

• packages/ = things meant to be installed and reused elsewhere. The kit.
• apps/ = runnable websites that use the kit.

The most important idea: the kit is a package first, and the gallery is just a customer of it. This keeps the gallery's needs from leaking into the shared kit. The gallery can be redesigned tomorrow and the kit is untouched.

3.2 The four pieces, in plain terms

3.3 The technology, and why you don't need to fear it

The stack is Next.js (a website framework), React (the way screens are built from components), TypeScript (JavaScript with labels that catch mistakes), and Tailwind CSS (a shorthand way to apply styles).

You do not need to write these fluently to be effective. As a UX engineer you mostly need to:

• Recognize a component when you see it (<SpringButton> is a button).
• Understand that its behavior is controlled by "props" (settings passed to it).
• Know that styling comes from tokens, not hand-typed values.

That's genuinely most of it. The rest of this guide builds on those three ideas.

---

4. How It Actually Works — The Loop

The platform is not a static folder of files. It is a loop between design and code:

Figma design
      ↓
Design tokens        ← the single source of visual truth (colors, spacing, type)
      ↓
React components      ← the tokens automatically flow into every component
      ↓
Application flow      ← components snap together into full screens
      ↓
Gallery              ← every component & screen is previewed here, always current
      ↓
Product app          ← a real app installs the same package
      ↓
Feedback to design    ← gaps and new needs go back to Figma

Why this matters to you: because tokens sit at the bottom, one approved change in Figma can ripple through every screen automatically. No one hunts through files to swap a color. No screen gets missed. This is the difference between a design system and a folder of components.

The token pipeline (the part that feels like magic)

Figma Variables
   ↓  (a command pulls them in)
design-tokens.mjs          ← the visual source of truth in code
   ↓  npm run tokens:sync   (one command, under 2 seconds)
css-variables.css          ← 254 named values every component reads
   ↓
Every screen, automatically styled and consistent

A designer changes --spring-color-plum-600 in Figma → a developer runs one sync command → every button, header, and card that uses that token updates at once.

---

5. A Small Vocabulary So Nothing Is Scary

You will keep seeing these words. Here is all you need to know:

Example of "props" in plain terms — this is a button that says "Apply Now," is the primary style, and is large:

<SpringButton variant="primary" size="lg">Apply Now</SpringButton>

variant and size are props. You are not writing logic — you are configuring a brick. That's the whole feel of building with this kit.

---

6. User Scenarios — Who Uses This and For What

This platform is deliberately built to serve several kinds of people at once.

6.1 Designers

6.2 UX engineers (you)

6.3 Developers

6.4 AI agents / automated codegen

The repo ships rules and skills that let AI assistants generate code that lands in the right folder, reuses existing components, never invents raw colors, and validates itself before handing back. As a UX engineer, this means the AI helper in this repo is guardrailed — it follows the same conventions you're learning here.

---

7. Seeing It With Your Own Eyes (run it locally)

You can run the gallery on your own machine even if you've never run a website before. Open the Terminal, go to the project folder, and run:

npm install        # one-time: downloads everything the project needs
npm run dev        # starts the gallery at http://localhost:3000

Then open http://localhost:3000/ in your browser.

To walk the finished loan flow:

• In the gallery: /page/appflow/personal-loan/start
• As the standalone app: run npm run dev:personal-loan, then visit /personal-loans/start

If a token was changed and colors look stale, the fix is one command and a restart:

npm run tokens:sync   # regenerate the color/spacing values
# then stop and restart: npm run dev

That's the entire "developer environment" you need to see the system working.

---

8. Next Steps — Building a Brand-New Flow in a Separate Repo

This is the part you asked about: how would you start a completely new application flow, in its own repository, using these components?

The key insight: the kit is a published package. A brand-new repo doesn't need to live inside this monorepo — it just installs the kit the same way it installs any other dependency.

Step 0 — Decide what you're building (before any code)

Answer these first. This mirrors how the team intakes every request:

• What is the flow? (e.g. "auto loan application," "account onboarding")
• Who is the user? (applicant, returning customer, partner)
• What are the steps, in order? Write them as a numbered list — this becomes your registry.
• What states does each step need? (empty, error, loading, success, declined)
• Do you need any component that doesn't exist yet? If yes, that part is a developer task (a new brick in the shared box), not something to hand-build in your app.

Step 1 — Create the new app

npx create-next-app@latest my-new-flow --typescript --tailwind --app
cd my-new-flow
npm install spring-design-library-react

This gives you an empty Next.js website and installs the Spring kit into it.

Step 2 — Turn on the Spring look (done once)

Two small wiring steps let the kit style your app:

1. Import Spring's colors/spacing in the app's root layout file so every screen can see them:

// src/app/layout.tsx
import 'spring-design-library-react/tokens/generated/css-variables.css'
import './globals.css'

2. Point Tailwind at Spring's tokens (copy the pattern from this repo's apps/design-library/tailwind.config.mjs). A developer can do this in a few minutes; after that, bg-background, text-foreground, and friends "just work."

Step 3 — Build each screen by snapping components together

Every screen is a composition of kit components. You are not inventing widgets — you are arranging existing ones and writing the copy. A single step looks like this:

'use client'
import { LoanAmountSlider, SpringButton } from 'spring-design-library-react'
import { useState } from 'react'

export function AmountScreen({ onNext, onBack }) {
  const [amount, setAmount] = useState(5000)
  return (
    <div className="flex flex-col gap-space-8 max-w-stage mx-auto px-space-4">
      <h1 className="text-heading-xl text-foreground">How much would you like to borrow?</h1>
      <LoanAmountSlider value={amount} min={1000} max={35000} onChange={setAmount} />
      <div className="flex gap-space-4">
        <SpringButton variant="outlined" size="lg" onClick={onBack}>Back</SpringButton>
        <SpringButton variant="primary" size="lg" onClick={() => onNext(amount)}>Continue</SpringButton>
      </div>
    </div>
  )
}

Notice: no hex colors, no pixel values — only tokens (gap-space-8, text-heading-xl, text-foreground) and named components. That is a "correct" screen.

Step 4 — Drive the flow with one registry list

Rather than wiring screens together by hand, follow the pattern this repo uses for the loan flow: one list describes every step, and the app reads that list to build order, navigation, and progress. Conceptually:

const STEPS = [
  { order: 1, slug: 'amount',   title: 'How much do you need?', Screen: AmountScreen },
  { order: 2, slug: 'purpose',  title: 'What is it for?',        Screen: PurposeScreen },
  { order: 3, slug: 'review',   title: 'Review & submit',        Screen: ReviewScreen },
  // add a step by adding one line here
]

Adding, removing, or reordering steps becomes a one-line edit, not a five-file change. This is exactly how the personal loan flow's personalLoanFlow.ts registry works today.

Step 5 — Keep data separate from screens

Screens should only display; they should not fetch data or call production services directly. Fetch data one level above the screen and pass it in as props. This keeps every screen easy to preview, test, and reuse — the same discipline the gallery relies on.

Step 6 — If you need a brick that doesn't exist

Do not hand-build a new reusable component inside your app. Instead, request it be added to the shared kit (packages/spring-ds-react). That way every future flow gets it too, it's documented in the gallery, and it's connected to Figma. This is the single most important habit for keeping the system healthy.

The realistic division of labor

You can own a large share of the "what and how it looks" while a developer handles the one-time plumbing and any new bricks.

---

9. What You Can Do Safely vs. What Needs a Developer

Safe to do on your own

• Browse and demo the gallery and the loan flow.
• Copy component snippets from gallery pages into a prototype.
• Change copy (text), the order of steps, and how existing components are arranged.
• Swap one existing component's props (e.g. change a button from outlined to primary).
• Run npm run dev to preview, and npm run tokens:sync after a token change.

Pair with (or hand to) a developer

• Creating a brand-new reusable component (a new brick for the shared box).
• Changing a token value (needs approval, a sync, and a build check — it affects everything).
• Backend / data integration and authentication.
• Initial project setup and token wiring for a fresh repo.
• Anything that touches the framework's routing "plumbing."

The golden rules (from the team's guardrails)

1. Never type a raw color or pixel value. Always use a token.
2. Reuse before you create. Check the gallery first.
3. New reusable parts belong in the kit, not copied into your app.
4. Screens display; they don't fetch data.
5. Don't add half-finished pages to the gallery's navigation.

---

10. Cheat Sheet

Where things live

Commands you'll actually use

npm install                 # one-time setup
npm run dev                 # open the gallery at localhost:3000
npm run dev:personal-loan   # open the standalone loan app
npm run tokens:sync         # regenerate colors/spacing after a token change

Live URLs once it's running

• Gallery home: /
• Component docs: /components/<category>/<component>
• Loan flow (gallery): /page/appflow/personal-loan/start
• Loan flow (standalone): /personal-loans/start

The one sentence to remember

You build Spring screens by arranging existing, token-styled components — not by writing styles or widgets from scratch. When a component doesn't exist yet, it goes into the shared kit so everyone benefits.

---

Deeper technical detail lives in DEVELOPER_GUIDE.md. The business/leadership view is in LEADERSHIP_BRIEF.md. Start with this guide, then reach for those when you're ready.