Spring Design Library - Project Kickoff Plan

Audience: Leadership, product, design, engineering, DevOps Purpose: The kickoff and roadmap document for the Spring Design Library project Starting point: Ship the live Personal Loan prototype (happy path) and use it to drive every decision that follows Reference model: Marty Cagan, Inspired - discovery and delivery together, four product risks, outcomes over outputs Last updated: June 2026

---

1. Executive Summary

The Spring Design Library is more than a component catalog. It is an internal product platform for building, testing, and scaling Spring product experiences with reusable UI, shared tokens, AppFlow prototypes, and AI-assisted workflows.

The project starts with one concrete thing: ship the live personal-loan application prototype (happy path). This is ready and is our first kickoff deliverable.

We start here on purpose. Moving a complete application journey with the library is the fastest way to learn whether the system is:

• Fast - can we build and change real screens quickly?
• Stable - does a full flow hold together end to end?
• Adoptable - can other teams reuse this without rebuilding UI?

Once the live prototype is shared, we gather feedback from designers, stakeholders, developers, and DevOps, align on architecture, and then decide which future track to invest in. We do not try to do everything at once.

Operating principle: Publish first, learn fast, then iterate in waves. Each phase gets real time for feedback and improvement before we call it done.

---

2. The Big Picture

The project moves up a simple ladder. Each rung depends on the one below it.

flowchart TD
  v1["V1: Live Personal Loan prototype (happy path) - ready"]
  learn["Learn: feedback from design, stakeholders, dev, DevOps"]
  decide["Decide: which future track to invest in"]
  build["Build: chosen track in iterative waves"]
  iterate["Iterate: test, improve, then expand"]

  v1 --> learn --> decide --> build --> iterate
  iterate --> learn

After the live prototype, four future project tracks are possible. They can run in sequence or partly in parallel, but each one has a clear gate.

These are current assumptions for future projects. Test plans for each are intentionally light right now and will be filled in as each track is chosen.

---

3. What We Are Building

The Spring product UI platform has these parts today:

• @spring/ds-react - the reusable React design system: components, tokens, icons, and visual foundations.
• apps/design-library - the Next.js gallery and documentation surface under /library/*.
• apps/personal-loan - the standalone Personal Loan application that runs the flow outside the gallery.
• @spring/personal-loan-appflow - the packaged AppFlow logic: step registry, routing, screens, and shared shell.
• Playground - the experimentation lane for vibe-coded screens, component candidates, and live prototypes.
• Injectable DS layer (future) - a packaged way for other teams to apply Spring look and feel to their own apps.

Future Project Tracks

Track A - Full Personal Loan application implementation

• Review the existing flow map (documentation already exists).
• Build the missing pages and all edge cases.
• Decide the future direction: keep this as the primary AppFlow, or treat it as Variant B / legacy comparison if a new AppFlow design is chosen.

Track B - Library platform and system enhancement

• Gather insight from designers, stakeholders, and developers.
• Refine usability and prioritize feature updates.
• Align the developer-facing injectable structure.
• Define and test how the design system and agentic workflow become injectable into other apps.
• Test and iterate toward a v2 platform.

Track C - Design system token, theme, and look-and-feel

• Add a new theme or new design direction if Spring moves toward a fresh application look.
• Prove that changing a few token values can update the whole experience.
• Define how theme switching works across the platform (and how far it reaches into components).
• Update components only where token changes alone are not enough.

Track D - Playground feature development

• Define how a user delivers a candidate item into the design system.
• Explore direct vibe coding from /library/playground.
• Support people who build prototypes in different tools and publish a final prototype into Playground.
• Use Playground as a sign-off and communication surface.
• Target a v3 release: refined library plus Playground workflow.

---

4. Why It Matters

The value is not "we have components." The value is speed, consistency, and confidence:

• Designers can see whether design decisions survive real implementation.
• Stakeholders can review a working flow instead of static screens.
• Developers can reuse package components instead of rebuilding one-off UI.
• DevOps can evaluate how the package, app, and CI model should scale.
• AI-assisted builders and vibe coders can start from Spring look and feel instead of inventing UI from scratch.

Current Baseline From The Repo

---

5. Goals And Success Signals

Non-Goals For The First Release

• Production loan APIs, databases, analytics, Flinks, Twilio, or real eligibility logic.
• Public npm publishing before architecture alignment.
• Rebranding before injectable adoption is proven.
• Building every possible component before testing token-level adoption.

---

6. How We Work (Inspired Operating Model)

We use Inspired as a discipline, not a waterfall. Discovery and delivery run together.

flowchart LR
  subgraph discovery [Discovery]
    prototype[Prototype]
    feedback[Feedback]
    riskReview[Test four risks]
    backlog[Prioritized backlog]
  end
  subgraph delivery [Delivery]
    build[Build]
    validate[Validate]
    publish[Publish]
    measure[Measure]
  end
  prototype --> feedback --> riskReview --> backlog
  backlog --> build --> validate --> publish --> measure
  measure --> feedback

The Four Risks We Always Test

Iteration Is Built In

Every phase includes at least one feedback-and-improvement loop before it is considered done. We do not treat any phase as a single one-pass delivery. The roadmap dates below already include this iteration time.

---

7. Roadmap

This roadmap is a planning guide, not a fixed contract. Each phase leaves room for iteration.

gantt
  title Spring Design Library Roadmap
  dateFormat YYYY-MM-DD
  section Publish
    KickoffAlignment        :a1, 2026-06-29, 2d
    LivePrototypePublish    :a2, 2026-07-01, 12d
    M1LivePrototype         :milestone, m1, 2026-07-13, 0d
  section LearnAndDecide
    FeedbackAndDecision     :b1, 2026-07-14, 21d
    M2DirectionLocked       :milestone, m2, 2026-08-03, 0d
  section Architecture
    DevDevOpsAlignment      :c1, 2026-08-04, 21d
    M3ArchitectureAligned   :milestone, m3, 2026-08-24, 0d
  section ChosenTrack
    TrackDelivery           :d1, 2026-08-25, 42d
    M4TrackComplete         :milestone, m4, 2026-10-05, 0d
  section Expand
    ThemeOrPlayground       :e1, 2026-10-06, 49d
    M5ExpandComplete        :milestone, m5, 2026-11-23, 0d

---

8. Phase Plan

Every phase uses the same simple shape: Goal -> Key tasks -> Success measures -> Expected outcome -> Next iteration trigger.

Phase 0 - Kickoff Alignment

Timing: 1-2 days Goal: Agree on scope, owners, and what "done" means for the live prototype.

Key tasks

• Confirm V1 is a live prototype, not production loan software.
• Assign owners for design, engineering, DevOps, QA, and stakeholder review.
• Confirm the demo URLs and review path.

Success measures

• Team agrees on the V1 release bar and what is intentionally deferred.

Expected outcome: A shared, written scope for the first release.

Next iteration trigger: Scope is confirmed and the publish sprint can start.

---

Phase 1 - Ship The Live Personal Loan Prototype (V1)

Timing: 1-2 weeks Primary risk: Value and usability Goal: Publish the happy-path Personal Loan flow on the standalone app so the team can prove the library carries a full journey quickly and stably.

Key tasks

Technical readiness checks

npm run lint
npm run build
npm run build:personal-loan

Minimum walkthrough paths

Success measures

• Happy path completes without engineering help.
• The standalone app is stable across a full run.
• Lint and build pass; manual walkthrough is signed.

Expected outcome: A live, shareable Personal Loan prototype.

Next iteration trigger: Prototype is published and ready for structured feedback.

Scope lock: No new large features, branding, or package publishing during V1 unless it unblocks the publish.

---

Phase 2 - Learn And Decide The Direction

Timing: 2-3 weeks Primary risk: Value, usability, business viability Goal: Turn real feedback into a clear decision about which future track to invest in.

Key tasks

The decision (a real gate)

After feedback, choose the direction:

• Go to Track A (full implementation) if the Personal Loan flow should become the primary reusable AppFlow reference. Build missing pages and edge cases.
• Treat the current flow as Variant B / legacy if a new AppFlow design is the future direction. Keep it as a comparison and plan the new design separately.
• Go to Track B (platform and system enhancement) first if the biggest risk is adoption, tooling, and architecture rather than finishing every legacy edge case.

Success measures

• Feedback is grouped by screen, component, copy, and architecture area.
• Each item is tagged by risk: value, usability, feasibility, or viability.
• A single chosen direction is written down with its reason.

Expected outcome: A prioritized backlog and a confirmed track choice.

Next iteration trigger: Direction is locked and architecture alignment can begin.

---

Phase 3 - Architecture And DevOps Alignment

Timing: 2-3 weeks Primary risk: Feasibility Goal: Agree on the final structure before scaling the chosen track.

Key tasks

Success measures

• An architecture decision record is approved by engineering and DevOps.
• CI builds both apps and runs a smoke manual QA path.
• A package import smoke test passes in a clean workspace.

Expected outcome: A signed architecture and delivery plan.

Next iteration trigger: Structure is approved, so the chosen track can build safely.

---

Phase 4 - Deliver The Chosen Track

This phase runs the track chosen in Phase 2. Each track below uses the same shape and includes iteration time.

Track A - Full Application Implementation

Goal: Complete the Personal Loan flow as a full, reliable reference.

Key tasks

• Review the existing flow map and documentation.
• Build the missing pages and all edge cases.
• Wire recovery paths, skip paths, and outcome variants.
• Confirm whether this stays the primary AppFlow or becomes Variant B.

Success measures

• Happy path plus edge cases complete without manual URL edits.
• High component reuse; minimal one-off UI.
• The standalone app is stable across all paths.

Expected outcome: A complete AppFlow reference, with a clear decision on its future role.

Next iteration trigger: Full flow is tested and the team is ready to expand or harden the platform.

Track B - Platform And System Enhancement (toward v2)

Goal: Make the library easier to adopt and easier to build with.

Key tasks

• Refine usability and prioritize feature updates from Phase 2 feedback.
• Align the developer-facing injectable structure.
• Define and test how the design system and agentic workflow become injectable (see Section 9).
• Test and iterate.

Success measures

• A host app can adopt Spring tokens and core components using the written guide.
• The agentic workflow rules can be reused outside this repo.
• Adoption time and manual edits go down across pilots.

Expected outcome: A v2 platform that other teams can adopt with guidance.

Next iteration trigger: Adoption is proven, so theme and Playground work can scale.

---

Phase 5 - Expand (Theme And Playground)

These tracks come after the chosen core track is validated. They can run in either order based on business need.

Track C - Token, Theme, And Look-And-Feel

Goal: Support a new look and easy theme switching, mostly through tokens.

Key tasks

• Confirm that changing a few token values updates the whole experience.
• Add a new theme or design direction if Spring moves to a new application look.
• Define how theme switching works across the platform.
• Update components only where tokens alone are not enough.

Success measures

• Theme switches without forking components.
• Core screens render correctly under each theme.
• Contrast and accessibility pass for each theme.

Expected outcome: A working theme switch and a clear rule for token-driven look changes.

Next iteration trigger: A second theme works, so broader brand variants can be considered.

Track D - Playground Feature Development (toward v3)

Goal: Make Playground the lane for delivering and signing off prototypes.

Key tasks

• Define how a user delivers a candidate item into the design system.
• Explore direct vibe coding from /library/playground.
• Let people build in different tools, then publish final prototypes into Playground.
• Use Playground as a sign-off and communication surface.
• Define the graduation path: Playground -> package -> gallery doc.

Success measures

• At least one prototype is delivered, reviewed, and graduated.
• Status and ownership are clear for each Playground project.
• Stakeholders can review prototypes through shared preview URLs.

Expected outcome: A v3 release: refined library plus a working Playground workflow.

Next iteration trigger: The delivery and sign-off loop works repeatably.

---

9. Injectable Design System And Agentic Workflow

This section explains how a team outside this repo can apply Spring look and feel to their own app with the least manual work. This is the core of Track B.

The Scenario

An engineer builds an internal tool, often with a vibe-coding tool, and relies on rough generated UI. Before finalizing, they want to apply the Spring design system without manually restyling every screen.

The Adoption Kit

To support this, Spring ships an adoption kit, not just components:

• @spring/ds-react (components)
• generated token CSS
• a Tailwind or token preset
• an AI rules and skills bundle
• a migration prompt and checklist
• a component gap matrix

The "Springify Existing App" Workflow

flowchart TD
  install["1. Install package + token CSS"]
  preset["2. Add Tailwind / token preset"]
  rules["3. Add Spring AI rules"]
  audit["4. Audit existing UI"]
  map["5. Map current UI to Spring components"]
  one["6. Convert one page first"]
  review["7. Review and iterate"]
  rest["8. Apply to the rest of the app"]
  gaps["9. Log component gaps"]

  install --> preset --> rules --> audit --> map --> one --> review --> rest --> gaps
  gaps --> map

The AI follows clear rules: replace generic buttons and inputs with Spring components, use Spring tokens instead of raw values, keep business logic intact, and report missing components instead of inventing one-off UI.

Adoption Layers

Not every component will exist for every host app, so adoption is layered:

Success Measures

• A host app reaches Spring look and feel in under ~4 hours for the pilot scope.
• 70-90% of common UI maps to existing DS components or tokens.
• Manual style edits drop after applying tokens and the preset.
• A new engineer can follow the guide without live support.
• Missing components are documented and prioritized, not patched ad hoc.

Note: @spring/ds-react is currently private and source-consumed. The L1+L2 layers can work through CSS and token import before any npm publishing decision. Publishing is gated by the Phase 3 architecture decision.

---

10. Validation And Learning Strategy

Validation means learning whether the product works for people and whether the system can scale. Local commands are necessary checks but not the whole picture.

V1 Live Prototype Readiness

Measures We Track Through The Project

Feedback Becomes Iteration

---

11. Decision Framework

Use this to decide what to do next without overloading any single phase.

Quick answers for meetings

• "Can we rebrand for a partner next sprint?" Not yet. First prove injectable adoption and token theming.
• "Can we add feature Y?" Yes if M2 feedback prioritized it and it reduces a named risk.
• "Can we improve copy on a step?" Yes, anytime after V1.
• "Can we publish to npm?" After the Phase 3 architecture decision.
• "When is the flow live?" V1 target is ~Jul 13, 2026. It is a prototype, not production.

---

12. Governance And Ownership

Decision Log Template

Cadence

---

13. Risks And Mitigations

---

14. Kickoff Agenda

1. Confirm the vision: Spring Design Library as an internal product platform.
2. Confirm the first deliverable: live Personal Loan prototype (happy path).
3. Review V1 scope: what is in and what is deferred.
4. Assign owners for design, engineering, DevOps, QA, and stakeholder review.
5. Confirm review audiences and dates for Phase 2.
6. Confirm the M2 decision gate: how we choose the future track.
7. Confirm architecture questions to answer by Phase 3.
8. Confirm that theme and Playground work is gated behind proven adoption.

Open Questions For Leadership

---

15. Definition Of Done

Live Prototype (V1) Done

• Standalone publish URL is available.
• Happy path runs without manual engineering help.
• Manual walkthrough checklist is complete.
• Known limitations are documented.

Learn And Decide Done

• Designer, stakeholder, developer, and DevOps feedback is captured and tagged by risk.
• A single future track is chosen and written down with its reason.
• A prioritized backlog has owners.

Architecture Done

• Package boundaries, consumption model, CI, and deploy path are approved.
• A clean-workspace import smoke test passes.

Chosen Track Done

• Track A: missing pages and edge cases complete; future role decided.
• Track B: a host app adopts tokens and components via the guide; adoption time and manual edits measured.

Theme / Playground Done

• Theme switches without forking components, with accessibility checks.
• At least one Playground prototype is delivered, reviewed, and graduated.

---

16. Related Planning Pack

This kickoff plan is the leadership-facing summary. Use these for execution detail:

• Project overview and goals
• Roadmap and milestones
• Phase playbook
• Product decision framework
• AppFlow master plan
• Repository structure
• Agentic workflow overview