Spring — Design Library home
All docs

Docs

Component Addition Workflow

Step-by-step guide for adding a new Spring Design System component end-to-end.

1. Implement in the Design System Package

Path: packages/spring-ds-react/src/components/<category>/<ComponentName>.tsx

Category must match gallery-order.ts:

  1. inputs
  2. navigations
  3. actions
  4. layout-structure
  5. selection-input
  6. image-icons
  7. feedback-indicators
  8. overlays
  9. lists
  10. tables
  11. utilities
  12. modules

Rules

  • Use semantic design tokens from @spring/ds-react/tokens — no raw hex values
  • Prefix with Spring where applicable (e.g. SpringButton)
  • Export types alongside the component
  • Add export to packages/spring-ds-react/src/index.ts

2. Add Figma Code Connect (optional)

Follow the Code Connect decision tree in docs/ai/workflow-contracts.md:

  • New reusable components default to package-side Code Connect beside the component.
  • Input components must place Code Connect under packages/spring-ds-react/src/components/inputs/.
  • Existing navigations, overlays, and SpringSearchBar mappings remain gallery-side until a migration is planned.

Package-side example:

packages/spring-ds-react/src/components/inputs/TextField.figma.tsx

Validate: npm run code-connect:parse

3. Create Gallery Doc Page

Path: apps/design-library/src/gallery/pages/components/<category>/<ComponentName>Page.tsx

Follow existing pages (e.g. TextFieldPage.tsx):

  • Import component from @spring/ds-react
  • Use gallery doc primitives: LibraryDocPage, CodeBlock, etc.
  • Include install snippet, props table, live playground

4. Add Next.js Route

Path: apps/design-library/src/app/library/components/<category>/<kebab-name>/page.tsx

import ComponentPage from '@/gallery/pages/components/<category>/<ComponentName>Page'
export default ComponentPage

5. Add Sidebar Navigation Entry

Edit apps/design-library/src/gallery/navigation/libraryNav.ts:

  • Add the component under the correct category branch
  • Use kebab-case path matching the route

Do not add placeholder-only pages to the nav. See PLACEHOLDER_POLICY.md.

6. Verify

npm run dev          # check /library/components/... route
npm run build        # ensure production build passes
npm run code-connect:parse  # if figma.tsx added

Checklist

  • Component in packages/spring-ds-react/src/components/<category>/
  • Exported from src/index.ts
  • Gallery page in src/gallery/pages/
  • Route shell in src/app/library/
  • Nav entry in libraryNav.ts
  • Figma Code Connect file (if applicable)
  • Uses design tokens (no raw hex)
  • Build and manual QA pass