design-system-bootstrap

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).

仓库: curiositech/windags-skills
最近来源活动: 2026年3月25日 05:03
检测到的 SKILL.md 语言: 英语
星标: 10
分支: 2

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

返回搜索返回安装

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

Component	Variants Found	Files	Styling Method	Accessible?	Notes
Button	7 different styles	12 files	Mixed CSS + inline	Partial	3 lack focus states
Modal	3 implementations	5 files	styled-components	No	No trap focus, no ESC close
Input	4 styles	8 files	CSS modules	Partial	Inconsistent validation
Dropdown	2 custom, 1 library	4 files	Mixed	No	No keyboard nav

# Find all hex colors in use
grep -roh '#[0-9a-fA-F]\{3,8\}' src --include="*.tsx" --include="*.css" | \
  sort | uniq -c | sort -rn | head -30

# Find all rgb/rgba/hsl values
grep -roP 'rgba?\([^)]+\)|hsla?\([^)]+\)' src --include="*.tsx" --include="*.css" | \
  sort | uniq -c | sort -rn | head -20

# Find padding/margin values
grep -roP '(padding|margin|gap):\s*[^;]+' src --include="*.css" | \
  sort | uniq -c | sort -rn | head -20

# Tailwind spacing classes in use
grep -roP '(p|m|gap|space)-[a-z0-9\[\]]+' src --include="*.tsx" | \
  sort | uniq -c | sort -rn | head -30

# Font sizes
grep -roP 'font-size:\s*[^;]+' src --include="*.css" | \
  sort | uniq -c | sort -rn

# Font families
grep -roP "font-family:\s*[^;]+" src --include="*.css" | \
  sort | uniq -c | sort -rn

Dimension	1 (Crisis)	3 (Manageable)	5 (Solid)
Consistency	Every component styled differently	Some shared patterns	Unified visual language
Accessibility	No ARIA, no keyboard nav	Partial, inconsistent	Full WCAG AA compliance
Token usage	Hardcoded values everywhere	Some CSS variables	Full token system
Component reuse	Copy-paste culture	Some shared components	Single-source library
Documentation	None	README per component	Full Storybook

:root {
  /* Colors — semantic, not descriptive */
  --color-text-primary: #111827;
  --color-text-secondary: #6b7280;
  --color-text-muted: #9ca3af;
  --color-text-inverse: #ffffff;

  --color-bg-primary: #ffffff;
  --color-bg-secondary: #f9fafb;
  --color-bg-tertiary: #f3f4f6;

  --color-border-default: #e5e7eb;
  --color-border-strong: #d1d5db;

  --color-accent-primary: #6366f1;
  --color-accent-primary-hover: #4f46e5;

  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-error: #ef4444;

  /* Spacing — constraint scale */
  --space-1: 0.25rem;   /* 4px */
  --space-2: 0.5rem;    /* 8px */
  --space-3: 0.75rem;   /* 12px */
  --space-4: 1rem;      /* 16px */
  --space-6: 1.5rem;    /* 24px */
  --space-8: 2rem;      /* 32px */
  --space-12: 3rem;     /* 48px */
  --space-16: 4rem;     /* 64px */
  --space-24: 6rem;     /* 96px */

  /* Typography */
  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;

  --text-xs: 0.75rem;     /* 12px */
  --text-sm: 0.875rem;    /* 14px */
  --text-base: 1rem;      /* 16px */
  --text-lg: 1.125rem;    /* 18px */
  --text-xl: 1.25rem;     /* 20px */
  --text-2xl: 1.5rem;     /* 24px */
  --text-3xl: 1.875rem;   /* 30px */
  --text-4xl: 2.25rem;    /* 36px */

  /* Border radius */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-full: 9999px;

  /* Shadows */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
  --shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.12);

  /* Transitions */
  --transition-fast: 0.1s ease;
  --transition-default: 0.2s ease;
  --transition-slow: 0.3s ease;
}

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        accent: {
          DEFAULT: '#6366f1',
          hover: '#4f46e5',
        },
      },
      fontFamily: {
        sans: ['Inter', ...defaultTheme.fontFamily.sans],
        mono: ['JetBrains Mono', ...defaultTheme.fontFamily.mono],
      },
    },
  },
};

Criteria	Radix UI	React Aria	Headless UI	Ark UI	Base UI (MUI)
Component count	28	43	10	30+	20+
API style	Compound components	Hooks + Components	Compound components	Compound components	Hooks
Accessibility	Very good	Best-in-class	Good	Very good	Good
Styling freedom	Full (unstyled)	Full (unstyled)	Full (unstyled)	Full (unstyled)	Full (unstyled)
React Server Comp.	Partial	Yes	Partial	Yes	Partial
Animation support	data-state attrs	Built-in transitions	Transition component	data-state attrs	Minimal
Bundle size (Dialog)	~8KB	~12KB	~5KB	~10KB	~7KB
Ecosystem	shadcn/ui, Radix Themes	Adobe Spectrum	Tailwind ecosystem	Panda CSS	Joy UI
Documentation	Excellent	Very good	Good	Good	Good
Framework support	React only	React only	React + Vue	React + Vue + Solid	React only

Do you need Vue/Solid support?
├── Yes → Ark UI or Headless UI
└── No → Continue
    │
    Do you need maximum accessibility (gov, enterprise, WCAG AAA)?
    ├── Yes → React Aria
    │         (strictest ARIA implementation, Adobe-backed)
    └── No → Continue
        │
        Do you want the largest pre-built ecosystem (shadcn/ui)?
        ├── Yes → Radix UI
        │         (shadcn/ui is built on Radix, largest component community)
        └── No → Continue
            │
            Do you need the fewest dependencies possible?
            ├── Yes → Headless UI (smallest, Tailwind team)
            └── No → Radix UI (safe default, best DX)

# Bootstrap shadcn/ui into an existing project
npx shadcn-ui@latest init

# Add components as needed
npx shadcn-ui@latest add button input card dialog dropdown-menu \
  tabs tooltip popover command separator badge

Component	Why First	Headless Primitive
Button	Used everywhere, most inconsistency	None needed (semantic HTML)
Input + Label	Every form, biggest a11y gap	React Aria: useTextField
Dialog/Modal	High visibility, hardest to get right	Radix: Dialog, React Aria: useDialog
Dropdown Menu	Navigation, actions, context menus	Radix: DropdownMenu

Component	Why	Headless Primitive
Select	Form-critical, notoriously hard	Radix: Select, React Aria: useSelect
Tabs	Layout organization	Radix: Tabs
Toast/Notification	Feedback system, often inconsistent	Radix: Toast
Card	Content container, used everywhere	None needed (styled div)

Component	Why	Headless Primitive
Tooltip	Contextual help	Radix: Tooltip
Popover	Rich contextual content	Radix: Popover
Toggle/Switch	Settings, preferences	Radix: Switch
Checkbox + Radio	Form elements	Radix: Checkbox, RadioGroup
Accordion	Content disclosure	Radix: Accordion

Step 1: Create new <Button> component in design system
Step 2: Import it alongside old buttons
Step 3: Replace old buttons one page at a time
Step 4: When all old buttons replaced, delete old code
Step 5: Repeat for next component

// 1. New component in your design system
// packages/ui/src/Button.tsx
import { forwardRef } from 'react';
import { cva, type VariantProps } from 'class-variance-authority';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        primary: 'bg-accent-primary text-white hover:bg-accent-hover',
        secondary: 'border border-border-default bg-transparent hover:bg-bg-secondary',
        ghost: 'hover:bg-bg-secondary',
        destructive: 'bg-error text-white hover:bg-red-600',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4 text-sm',
        lg: 'h-12 px-6 text-base',
      },
    },
    defaultVariants: {
      variant: 'primary',
      size: 'md',
    },
  }
);

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant, size, className, ...props }, ref) => (
    <button
      ref={ref}
      className={buttonVariants({ variant, size, className })}
      {...props}
    />
  )
);

// 2. Migration wrapper for gradual adoption
// src/components/LegacyButtonAdapter.tsx
import { Button } from '@your-org/ui';

// Map old prop API to new
export function LegacyButtonAdapter({ type, ...props }) {
  const variantMap = {
    primary: 'primary',
    secondary: 'secondary',
    danger: 'destructive',
    link: 'ghost',
  };
  return <Button variant={variantMap[type] || 'primary'} {...props} />;
}

// .eslintrc.js — warn on old component imports
module.exports = {
  rules: {
    'no-restricted-imports': ['warn', {
      paths: [
        {
          name: './components/OldButton',
          message: 'Use <Button> from @your-org/ui instead.',
        },
        {
          name: './components/OldModal',
          message: 'Use <Dialog> from @your-org/ui instead.',
        },
      ],
    }],
  },
};

Component: Button
Total instances: 47
Migrated: 32/47 (68%)
├── /dashboard     ████████████████████░░░░  85% (17/20)
├── /settings      ████████████████████████  100% (8/8)
├── /onboarding    ██████░░░░░░░░░░░░░░░░░░  25% (3/12)
└── /billing       █████████████░░░░░░░░░░░  57% (4/7)

npx storybook@latest init

Metric	Target	How to Measure
Component coverage	80%+ of UI uses DS components	grep for DS imports vs raw HTML
Token compliance	90%+ of colors/spacing from tokens	grep for hardcoded values
Accessibility score	0 axe violations per page	Storybook a11y addon, Lighthouse
Developer satisfaction	4+/5 in quarterly survey	Internal survey
Time to build new page	50% reduction	Track sprint velocity