Repository Structure

Canonical reference for the spring-design-library monorepo: what every folder is, why it exists, and how the pieces connect.

---

1. Purpose & Quick Start

This repository is the Spring Design System for the Opportunity Generation team at Spring Financial. It contains:

1. @spring/ds-react — React components, design tokens, and Figma-synced icons (the product UI source of truth).
2. @spring/design-library — A Next.js documentation gallery at /library/* (replaces Storybook).

Commands (from repo root)

Environment

Copy .env.example to .env for Figma sync:

• FIGMA_TOKEN — Figma personal access token
• FIGMA_FILE_ID — Foundation file ID for token pull

---

2. Architecture Overview

flowchart TB
  subgraph monorepo [Active Monorepo]
    root["Root npm workspace\nspring-design-library"]
    app["apps/design-library\nNext.js gallery"]
    pkg["packages/spring-ds-react\nComponents + tokens + icons"]
    scripts["scripts/"]
    figma["figma.config.json"]
  end
  root --> app
  root --> pkg
  root --> scripts
  root --> manual-qa
  figma --> app
  figma --> pkg
  scripts --> pkg
  app --> pkg
  manual-qa --> app

Scale: ~1,350 files total; ~1,173 are auto-generated icon components under packages/spring-ds-react/src/icons/.

Workspaces: npm workspaces (apps/*, packages/*). No Turborepo or pnpm.

---

3. Top-Level Map

---

4. apps/design-library — Documentation Gallery

Package: @spring/design-library
Stack: Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS
URL base: /library/*

Architecture Pattern

The app uses thin route shells + gallery implementations:

• src/app/library/**/page.tsx — Next.js routes (filesystem routing)
• src/gallery/** — Doc UI, navigation, component pages, AppFlow previews

Most routes are one-liners that re-export a gallery page:

import TextFieldPage from '@/gallery/pages/components/inputs/TextFieldPage'
export default TextFieldPage

Directory Tree

apps/design-library/
├── next.config.ts          # transpilePackages + @spring/ds-react aliases
├── postcss.config.js
├── tailwind.config.mjs     # theme from @spring/ds-react/tokens
├── tsconfig.json           # excludes *.figma.tsx from typecheck
├── package.json
└── src/
    ├── app/                # Next.js App Router (~50 page.tsx routes)
    │   ├── layout.tsx      # root: Inter font, token CSS, globals.css
    │   ├── page.tsx        # redirect → /library/getting-started
    │   ├── not-found.tsx
    │   └── library/
    │       ├── layout.tsx  # LibraryAppLayout wrapper
    │       ├── getting-started/
    │       ├── design-tokens/   # colors, typography, space, styles, layout (placeholder)
    │       ├── icons/
    │       ├── components/      # navigations, actions, inputs, overlays, etc.
    │       ├── design-libraries/  # reserved (no routes until product libraries ship)
    │       └── page/appflow/    # personal loan flow
    ├── gallery/
    │   ├── layout/         # LibraryAppLayout, LibraryShellSidebar
    │   ├── navigation/     # libraryNav.ts (sidebar source of truth)
    │   ├── components/     # Doc primitives: CodeBlock, TokenRoleSwatch, etc.
    │   ├── pages/          # Full doc pages + 7 *.figma.tsx Code Connect files
    │   ├── foundations/    # Token foundation pages (typography, spacing, radius)
    │   └── page/appflow/   # Personal loan flow (14 screens + registry)
    ├── lib/                # App-only: tokenDatasets, iconManifest, utils, useHash
    ├── styles/globals.css
    └── middleware.ts       # Redirects / and non-/library/* → /library/getting-started

Route Categories

Placeholder policy: see PLACEHOLDER_POLICY.md.

Key Integration Points

Figma Code Connect (app-side)

7 files under src/gallery/pages/components/**:

• Navigations: SpringHeader, SpringFooter, SpringFooterLegal
• Overlays: ExitModal, InfoModal, ConfirmModal, ActionModal
• Selection: SpringSearchBar

Excluded from TypeScript build (tsconfig.json); parsed by figma.config.json.

---

5. packages/spring-ds-react — Design System

Package: spring-design-library-react (linked internally as @spring/ds-react)
Role: The single published package — React components, tokens, icons, design-system rules, and the AppFlow/page map.

Directory Tree

packages/spring-ds-react/
├── package.json            # exports: ., ./components, ./icons, ./tokens, ./tokens/generated/css-variables.css, ./rules, ./appflow
├── tsconfig.json
├── tsup.config.ts          # builds index, icons, rules, appflow; copies tokens to dist
├── scripts/
│   ├── sync-spring-icons-from-figma.mjs
│   └── publish-manifest.mjs
└── src/
    ├── index.ts            # Public API barrel (~20 components) — root + ./components
    ├── gallery-order.ts    # GALLERY_COMPONENT_CATEGORIES
    ├── tokens/             # SOURCE OF TRUTH — ./tokens
    │   ├── design-tokens.mjs   # primitives + semantic + figmaMap
    │   ├── core.mjs            # runtime assembly, getByPath, figmaNameToCssVar
    │   ├── index.mjs           # spring-design-library-react/tokens export
    │   ├── build-utils.mjs
    │   └── generated/
    │       ├── css-variables.css   # 254 CSS variables (committed)
    │       └── sync-manifest.json
    ├── rules/              # Structured design-system rules — ./rules
    ├── appflow/            # AppFlow/page-map barrel — ./appflow (bundles @spring/personal-loan-appflow)
    ├── components/
    │   ├── inputs/         # 11 components + index.ts + 10 *.figma.tsx
    │   ├── navigations/    # SpringHeader, SpringFooter, SpringFooterLegal, SpringLogo
    │   ├── actions/        # SpringButton
    │   ├── overlays/       # ExitModal, InfoModal, ConfirmModal, ActionModal (modals.tsx)
    │   ├── selection-input/# SpringSearchBar
    │   ├── feedback/       # SpringProgress
    │   └── [reserved]/     # layout-structure, lists, tables, image-icons, utilities (empty)
    ├── icons/              # 20 Figma categories, ~1,173 .tsx (auto-synced)
    ├── assets/             # Canonical logos, tile-selector glyphs, bank logos
    ├── layout/             # Reserved: app-shell, layout-shell (empty)
    ├── patterns/           # Reserved for composed screens (.gitkeep)
    └── design-libraries/   # Reserved for product libraries (empty)

Public Exports

Published as spring-design-library-react; internal imports use the @spring/ds-react link.

Implemented Components (~20)

Token Pipeline

flowchart LR
  FigmaAPI["Figma Variables API"]
  DTM["design-tokens.mjs"]
  Sync["scripts/sync-tokens.js"]
  CSS["generated/css-variables.css"]
  TW["tailwind.config.mjs"]
  App["layout.tsx SSR import"]
  FigmaAPI -->|"npm run tokens:figma"| Sync
  DTM -->|"npm run tokens:sync"| Sync
  Sync --> CSS
  CSS --> App
  DTM --> TW

1. Source: design-tokens.mjs — primitives, semantics, figmaMap, usage metadata.
2. Build: npm run tokens:sync → Zod validation + generated/css-variables.css.
3. Optional pull: npm run tokens:figma → figma-variables.json (gitignored).
4. Consumption: SSR CSS import, Tailwind theme, gallery token docs.

Figma Code Connect (package-side)

11 files under src/components/inputs/*.figma.tsx:

BoxSelector, ConsentBox, DropdownField, FileUploader, LoanAmountSlider, OtpField, PhoneNumberField, SearchField, SplitPillInput, TextField, TileSelector

Icon Sync

npm run icons:sync runs scripts/sync-spring-icons-from-figma.mjs in the package workspace. Icons are organized into 20 categories (General, Arrows, Charts, Communication, etc.) with barrel exports.

---

6. Scripts & Tooling

Figma Code Connect Config

figma.config.json:

• Parser: React, TypeScript
• Includes: app gallery *.figma.tsx, package component *.figma.tsx and all *.tsx
• Paths: @/* → design-library src, @spring/ds-react → package index

---

7. manual QA Testing

---

8. Documentation Index

Full hub with reading order: docs/README.md.

---

9. Data Flows

Component: Figma → Code → Gallery

Figma component
  → Code Connect (*.figma.tsx) OR manual implementation
  → packages/spring-ds-react/src/components/<category>/
  → Export from src/index.ts
  → Gallery page in apps/design-library/src/gallery/pages/
  → Route shell in apps/design-library/src/app/library/
  → Nav entry in libraryNav.ts

See COMPONENT_ADDITION.md for the full checklist.

Token: Design → Runtime

Figma Variables (optional pull)
  → design-tokens.mjs (source of truth)
  → npm run tokens:sync
  → clear apps/design-library/.next before production build validation
  → generated/css-variables.css
  → SSR import in layout.tsx + Tailwind theme

AppFlow: Screen Registry

personalLoanFlow.ts (step registry)
  → screens/*.tsx (14 screen components)
  → [slug]/page.tsx (dynamic route)
  → LivePageEmbedPreview / MiniPagePreview

Agentic Workflow: Outcome → Files → Validation

User request
  → docs/ai/project-context.md (intake + outcome routing)
  → docs/ai/operational-manifesto.md (agent roles + workflow)
  → docs/ai/workflow-contracts.md (file targets + injection points)
  → implementation in package, gallery, AppFlow, tokens, docs or rules
  → docs/ai/workflow-test-plan.md (validation matrix)
  → docs/ai/review-checklist.md (handoff quality gate)

Outcome routing:

Code Connect placement is intentionally explicit: new reusable mappings default package-side, input mappings must live under packages/spring-ds-react/src/components/inputs/, and existing gallery-side mappings remain limited to navigations, overlays, and SpringSearchBar until a migration is planned.

---

10. Technical Debt Register

---

Cleanup Candidates Requiring Confirmation

Do not remove these automatically during agentic workflows. Confirm with a maintainer first:

---

11. Future Considerations

These are documented but not yet implemented:

1. Turborepo — Add if the monorepo grows beyond 2 workspaces (parallel build/cache).
2. Package build step — Add tsup or similar if @spring/ds-react needs external npm publish.
3. Empty categories — Implement layout-structure, lists, tables, image-icons, utilities as Figma components become available.
4. Multi-framework tokens — Tokens ship framework-agnostic via spring-design-library-react/tokens; a separate package is only needed if consumers cannot depend on this one.

---

12. Reorganization Status

Summary of the POC → harmonized monorepo cleanup (see also docs/README.md).

Completed

Pending (maintainer actions)

Removed (do not reintroduce)

• Vite app entry (main.tsx, App.tsx, index.html) from apps/design-library
• Vue/shadcn-vue config (components.json)
• Duplicate Spring logo SVGs in apps/design-library/src/assets/

---

13. Related Links

• docs/README.md — documentation hub and reading order
• COMPONENT_ADDITION.md — Adding a new component end-to-end
• PLACEHOLDER_POLICY.md — Placeholder route conventions
• apps/design-library/README.md — App-specific routing docs
• packages/spring-ds-react/README.md — Figma → code path rules