Central index for the spring-design-library monorepo. Start here if you are new to the repo or returning after the POC reorganization.
Reading order
| Step | Document | Who |
|---|---|---|
| 0 | planning/01-project-overview-and-goals.md | Leadership / kickoff — vision, OKRs, Inspired framework, current maturity |
| 0b | planning/02-roadmap-and-milestones.md | Leadership / kickoff — timeline anchored to AppFlow publish in 1–2 weeks |
| 0c | ai/agentic-workflow-overview.md | Leadership — agentic workflow, roles, rules, and skills (Google Docs–ready) |
| 1 | DEVELOPER_GUIDE.md | Everyone — entry points, component usage, structure, production build, agentic workflow, scalability |
| 1b | UX_ENGINEER_GUIDE.md | UX engineers / designers new to React — plain-language platform overview, user scenarios, and how to build a new flow in a separate repo |
| 2 | REPOSITORY_STRUCTURE.md | Everyone — full repo map, architecture, and debt register |
| 3 | CONTRIBUTING.md | Developers — setup, commands, PR workflow |
| 4 | COMPONENT_ADDITION.md | Component authors — Figma → package → gallery checklist |
| 5 | PLACEHOLDER_POLICY.md | Gallery maintainers — scaffold vs live routes |
| 6 | ai/operational-manifesto.md | AI agents — outcome-first orchestration model |
By role
Design system / frontend engineers
- DEVELOPER_GUIDE.md — entry points, components, structure, production, scalability
- REPOSITORY_STRUCTURE.md §4–5 — app and package layout
- COMPONENT_ADDITION.md
- packages/spring-ds-react/README.md — Figma → code path rules
- apps/design-library/README.md — routing and Tailwind wiring
AI agents / codegen
- ai/project-context.md — intake protocol and standard paths
- ai/operational-manifesto.md — outcome-first agentic workflow
- ai/workflow-contracts.md — file placement, injection points, and handoff contracts
- ai/workflow-test-plan.md — validation strategy for automated workflows
- ai/review-checklist.md — pre-delivery quality gate
- .cursor/rules/ — short executable rules derived from
docs/ai/ - .cursor/skills/spring-agentic-workflow/SKILL.md — repeatable outcome-first workflow skill
- .cursor/skills/spring-ux-variant/SKILL.md — optional persona and UX variant playbook
Planning / kickoff
- planning/01-project-overview-and-goals.md — vision, goals, OKRs, Inspired framework
- planning/02-roadmap-and-milestones.md — milestones M1–M6 and 15-week timeline
- planning/03-phase-playbook.md — per-wave tasks, testing, exit criteria
- planning/04-product-decision-framework.md — when to rebrand, add features, or enhance UX
UX / product / AppFlow
- UX_ENGINEER_GUIDE.md — plain-language guide for UX engineers new to React (how the platform works, scenarios, building a new flow in a separate repo)
- ux/personal-loans-flow.md — product routing spec (production step order, branches, footnotes)
- ux/personal-loan-appflow-master-plan.md — gallery implementation status and end-to-end plan (tokens, components, connectivity, phased build)
- ux/ux-strategy-logic.md — strategy pillars
- ux/user-insights-report.md — persona research
History / migration context
- history/migration-vite-to-next.md — Vite → Next.js migration (completed)
Reorganization summary (2025)
This repo began as an AI-assisted POC and was reorganized into a harmonized npm-workspace structure:
| Before | After |
|---|---|
Scattered root markdown (MIGRATION.md, project-context.md, UX reports) | Consolidated under docs/ |
Duplicate/orphan folders (Spring-library/, nested spring-design-library/) | Removed from the active workspace — see REPOSITORY_STRUCTURE.md §12 |
| Vite/vue migration leftovers | Removed (vite-env.d.ts, components.json, duplicate logos) |
| No single structure reference | REPOSITORY_STRUCTURE.md |
Inconsistent package name (design-ui-ai-system) | Root package renamed to spring-design-library |
Folder layout
docs/
├── README.md ← you are here
├── planning/
│ ├── 01-project-overview-and-goals.md
│ ├── 02-roadmap-and-milestones.md
│ ├── 03-phase-playbook.md
│ └── 04-product-decision-framework.md
├── LEADERSHIP_BRIEF.md ← leadership brief: value, roadmap, business case
├── DEVELOPER_GUIDE.md ← comprehensive developer guide (start here)
├── UX_ENGINEER_GUIDE.md ← plain-language guide for UX engineers new to React
├── REPOSITORY_STRUCTURE.md ← canonical repo map
├── CONTRIBUTING.md
├── COMPONENT_ADDITION.md
├── PLACEHOLDER_POLICY.md
├── ai/
│ ├── agentic-workflow-overview.md ← leadership overview (copy to Google Docs)
│ ├── project-context.md
│ ├── operational-manifesto.md
│ ├── workflow-contracts.md
│ ├── workflow-test-plan.md
│ └── review-checklist.md
├── ux/
│ ├── personal-loans-flow.md
│ ├── personal-loan-appflow-master-plan.md
│ ├── ux-strategy-logic.md
│ └── user-insights-report.md
└── history/
└── migration-vite-to-next.md
Quick commands
See CONTRIBUTING.md for the full list. Most common:
npm install && npm run dev # local gallery
npm run tokens:sync # regenerate token CSS; restart dev after token changes
npm run lint && npm run build # pre-PR checks