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

Muhammad Shahabipour — Wed, 29 Oct 2025 07:36:08 +0000

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

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.