design-system-bootstrap

license	Apache-2.0
name	design-system-bootstrap
description	Guides the practical path from 'we have no design system' or 'we have a mess' to a real, functional design system. Component inventory, design token extraction, headless UI adoption (Radix, React Aria, Headless UI), migration order of operations, and the assessment-to-rollout pipeline. Activate on 'design system from scratch', 'bootstrap design system', 'no design system', 'design system migration', 'headless UI adoption', 'component audit', 'design token extraction', 'design system strategy'. NOT for building specific components once a system exists (use design-system-creator), not for generating token files/configs (use design-system-generator).
allowed-tools	Read,Write,Edit,Glob,Grep,WebSearch,WebFetch
metadata	{"category":"Design & UX","tags":["design-system","migration","headless-ui","radix","react-aria","design-tokens","component-audit","architecture"],"pairs-with":[{"skill":"design-system-creator","reason":"Creator builds the components after Bootstrap establishes the strategy"},{"skill":"design-system-generator","reason":"Generator outputs token files and configs that Bootstrap defines"},{"skill":"design-accessibility-auditor","reason":"Accessibility audit is step 1 of any design system bootstrap"}]}
category	Design & Creative
tags	["design-system","bootstrap","tokens","components","foundation"]

Design System Bootstrap

The practical guide to going from "we have nothing" (or "we have a mess") to a functional design system. This is not about building a component library from scratch in isolation — it is about assessing what exists, extracting what works, choosing the right foundations, and migrating incrementally without breaking production.

When to Use

Use for:

• Greenfield projects that need a design system from day one
• Existing apps with inconsistent styling and no shared components
• Migration from one component library to another (e.g., MUI to Radix)
• Extracting a design system from a mature but unsystematic codebase
• Deciding between headless UI libraries (Radix, React Aria, Headless UI, Ark UI)
• Establishing design tokens for the first time
• Planning the rollout order so the team sees value fast

Do NOT use for:

• Building specific components within an established system → use design-system-creator
• Generating token config files, Tailwind themes, or Figma exports → use design-system-generator
• Accessibility-specific audits → use design-accessibility-auditor
• Full brand/visual design direction → use web-design-expert

---

Phase 0: Assessment (Day 1-3)

Before building anything, understand what you have.

Component Inventory

Run a systematic audit of every UI component in the codebase.

Automated Discovery:

# Find all component files
find src -name "*.tsx" -o -name "*.jsx" | \
  xargs grep -l "export.*function\|export.*const.*=" | \
  sort

# Find all CSS/styling approaches in use
find src -name "*.css" -o -name "*.scss" -o -name "*.module.css" | wc -l
grep -r "styled(" src --include="*.tsx" -l | wc -l     # styled-components
grep -r "className=" src --include="*.tsx" -l | wc -l   
grep -r  src --include= -l |  -l         
grep -r  src --include= -l |  -l