DEV Community

Muhammad Shahabipour
Muhammad Shahabipour

Posted on

Comprehensive Guide to Building a Design Kit for Multiple React Projects (Part 1)

#react #architecture #design #tutorial

1. Define Goals and Establish a Single Source of Truth

Why? The design kit will be used across five different React projects, so it must be structured to ensure updates propagate everywhere. Both design tokens and components should live in a central repository with proper documentation.

  • Token-based design: Tokens hold foundational values (colors, font sizes, spacing, corner radius, etc.) to ensure consistent changes.
  • Central storage: Store all tokens in a JSON file and sync them via tools like Style Dictionary or Tokens Studio.
  • Version control: Manage each update with semantic versioning so projects can adopt new versions smoothly.

2. Extracting from Figma to Code

  • Use Figma Tokens Plugin to export colors, typography, and spacing into JSON.
  • Convert these JSON files into CSS variables or Tailwind configuration via Style Dictionary or Token Transformer.
  • Integrate tokens into your tailwind.config.js if using Tailwind CSS.
  • Optionally, set up Design Token Sync CI/CD for automatic updates.

3. Folder Structure 

design-system/
│
├── tokens/              # colors, typography, spacing, radius
├── components/          # buttons, inputs, cards, modals, etc.
├── icons/               # unified SVG icon set
├── hooks/               # reusable hooks for forms or accessibility
├── utils/               # helper functions
├── styles/              # CSS variables and Tailwind config
└── storybook/           # documentation and demos
Enter fullscreen mode Exit fullscreen mode

4. Core Elements of the Design Kit

Section Description
Typography Base font, size scale, weight, and line-height system (4pt or 8pt grid)
Colors Primary, Secondary, Background, Surface, Error, and Light/Dark modes
Spacing Spacing scale (4px, 8px, 16px, 24px...) for margins and paddings
Icons Use a unified SVG set (e.g., Lucide or custom set)
Components Button, Input, Select, Modal, Tooltip, etc.
Accessibility Built with Radix UI, React Aria, or Headless UI for a11y compliance
Theming Support light/dark mode using CSS variables and React context

5. Documentation and Distribution

  • Use Storybook for showcasing and testing components.
  • Each component should include Props, examples, and unit tests.
  • Publish via pnpm publish --filter design-system.
  • Install in projects with pnpm add @org/design-system.

6. Maintenance and Future Expansion

  • Follow Semantic Versioning (v1.2.3) for version control.
  • Add visual regression tests via Chromatic or Ladle.
  • Monitor Figma updates using GitHub Actions + Tokens Sync.
  • Establish Design Governance to review and approve new changes.

Top comments (0)