This is the first document an agent should read before planning work in the Spring Design Library.
For the full workflow, continue to:
1. Technical Baseline
- Framework: Next.js App Router, React, TypeScript (
.tsx), and Tailwind CSS. - UI package: One published package,
spring-design-library-react, ships tokens, components, icons, rules, and the AppFlow/page map via tiered subpath exports (/tokens,/rules,/icons, root//components,/appflow). Internally it is linked as@spring/ds-react. - Tokens:
packages/spring-ds-react/src/tokens/design-tokens.mjsis the visual source of truth. - Gallery:
apps/design-libraryexposes documentation and previews under/library/*. - Rule: Ignore legacy stack or non-Spring UI library references. Translate implementation work into the current Spring DS React stack.
2. Mandatory Intake Protocol
If the request is underspecified, stop and ask for the missing critical context before planning.
Required intake:
- Outcome type: component, gallery page, AppFlow screen, static page, token/foundation change, icon change, or documentation/rule change.
- Project label: App-Flow, Static, DPP, component, token, icon, or documentation.
- Primary goal: the user-facing job the output must perform.
- Target user: applicant, returning user, product developer, designer, AI agent, or maintainer.
- Source input: Figma URL/node, screenshot, written instructions, existing file, or route.
- Missing states: loading, empty, error, disabled, hover, focus, success, validation, or branch behavior.
- Validation expectation: build, lint, manual QA, Code Connect parse, token sync, or documentation review.
Ask only for critical missing details. Use sensible defaults for minor copy or layout details when existing patterns make the answer clear.
3. Outcome Routing
| Outcome | Use when | Primary contract |
|---|---|---|
| Reusable design system component | The result should be imported from @spring/ds-react | workflow-contracts.md - Component Injection Contract |
| Gallery documentation page | The result documents or demonstrates existing UI | workflow-contracts.md - Gallery Page Contract |
| AppFlow screen | The result is a personal loan flow step | workflow-contracts.md - AppFlow Screen Contract |
| Static design library page | The result is informational, foundation, or guide content | workflow-contracts.md - Gallery Page Contract |
| Token/foundation change | The result changes visual primitives or semantics | workflow-contracts.md - Token Change Contract |
| Documentation/rule change | The result changes operating guidance | operational-manifesto.md and workflow-test-plan.md |
4. Layout Defaults
- App-Flow: 700px center-aligned flow layout. Use existing AppFlow shell and registry patterns.
- Static: 1200px informational grid unless a nearby gallery pattern suggests otherwise.
- DPP: Partner-branded flow. Ask for partner-specific token overrides before implementing visual deviations.
- Reusable component: Build in the package first, then document in the gallery when requested or needed.
5. Standard Paths
| Area | Path |
|---|---|
| Design tokens | packages/spring-ds-react/src/tokens/ |
| Token sync script | scripts/sync-tokens.js |
| React components | packages/spring-ds-react/src/components/ |
| Package public exports | packages/spring-ds-react/src/index.ts |
| Gallery implementation | apps/design-library/src/gallery/ |
| App routes | apps/design-library/src/app/library/ |
| Gallery navigation | apps/design-library/src/gallery/navigation/libraryNav.ts |
| AppFlow screens | apps/design-library/src/gallery/page/appflow/screens/ |
| AppFlow registry | apps/design-library/src/gallery/page/appflow/personalLoanFlow.ts |
| AI workflow docs | docs/ai/ |
| Cursor rules | .cursor/rules/ |
| Cursor skills | .cursor/skills/ |
6. Planning Rule
Before implementation, produce or confirm a build plan with:
- outcome type
- reuse decision
- files to read
- files to change
- injection points
- route or import path
- validation commands
- whether user approval is required