npm package: @sumitchavan/smt-design-system
Description: **A production-ready, token-first design system for data-heavy B2B applications**
Author: Sumit Chavan
Latest version: 1.0.2

# 🎨 B2B SaaS Design System - Complete Guide

**A production-ready, token-first design system for data-heavy B2B applications**

---

## 🚀 Quick Start - Choose Your Path

### 👨‍💻 **Developer: "I want to build a form"**
→ **START HERE:** [`/DEVELOPER_JOURNEY_GUIDE.md`](/DEVELOPER_JOURNEY_GUIDE.md)  
Complete tutorial building a customer create form from scratch (30 min)

### ⚡ **Developer: "I need it done NOW"** ⭐ **NEW!**
→ **USE TEMPLATES:** [`/TEMPLATES_GUIDE.md`](/TEMPLATES_GUIDE.md)  
Production-ready templates you can use immediately (5 min)

### 📖 **Developer: "I need quick component reference"**
→ **USE THIS:** [`/COMPONENT_QUICK_REFERENCE.md`](/COMPONENT_QUICK_REFERENCE.md)  
Fast lookup for all components with copy-paste examples (5 min)

### 🎨 **Designer/PM: "I want to customize colors"**
→ **START HERE:** [`/CUSTOM_THEME_QUICKSTART.md`](/CUSTOM_THEME_QUICKSTART.md)  
Create custom themes in 4 simple steps (5 min)

### 📚 **Team Lead: "I need the full overview"**
→ **START HERE:** [`/DEVELOPER_GUIDE_INDEX.md`](/DEVELOPER_GUIDE_INDEX.md)  
Complete navigation guide for all documentation (10 min)

### 📦 **Team Lead: "How do I distribute updates?"** ⭐ **NEW!**
→ **READ THIS:** [`/DESIGN_SYSTEM_DISTRIBUTION.md`](/DESIGN_SYSTEM_DISTRIBUTION.md)  
npm packages, versioning, and automated updates (15 min)

### 🧪 **QA/Testing: "I want to test everything"**
→ **OPEN APP:** Click "Testing Playground" in sidebar  
Interactive testing environment for all components

---

## 📖 Complete Documentation Library

### **New Developer Journey Guides** ⭐ **RECOMMENDED**

| Guide | Purpose | Time | Level |
|-------|---------|------|-------|
| [`DEVELOPER_GUIDE_INDEX.md`](/DEVELOPER_GUIDE_INDEX.md) | 📚 Start here - Navigation hub | 10 min | All |
| [`TEMPLATES_GUIDE.md`](/TEMPLATES_GUIDE.md) | 🚀 Production templates | 5 min | All |
| [`DEVELOPER_JOURNEY_GUIDE.md`](/DEVELOPER_JOURNEY_GUIDE.md) | 🛤️ Complete tutorial | 30 min | Beginner |
| [`COMPONENT_QUICK_REFERENCE.md`](/COMPONENT_QUICK_REFERENCE.md) | ⚡ Daily reference | 5 min | All |
| [`CUSTOM_THEME_QUICKSTART.md`](/CUSTOM_THEME_QUICKSTART.md) | 🎨 Theme basics | 5 min | All |
| [`CUSTOM_THEME_GUIDE.md`](/CUSTOM_THEME_GUIDE.md) | 🎨 Complete theming | 20 min | Intermediate |

### **Legacy Documentation** (Still Useful)

| Guide | Purpose | When to Use |
|-------|---------|-------------|
| [`GET_STARTED.md`](/GET_STARTED.md) | Quick overview | First time exploring |
| [`DEVELOPER_WORKFLOW.md`](/DEVELOPER_WORKFLOW.md) | Real-world patterns | Building components |
| [`DEVELOPER_THEME_GUIDE.md`](/DEVELOPER_THEME_GUIDE.md) | Theme deep dive | Advanced theming |
| [`THEME_CHEATSHEET.md`](/THEME_CHEATSHEET.md) | Quick CSS reference | Daily coding |
| [`DESIGN_SYSTEM_DOCS.md`](/DESIGN_SYSTEM_DOCS.md) | System overview | Understanding architecture |
| [`DOCUMENTATION_GUIDE.md`](/DOCUMENTATION_GUIDE.md) | Adding docs | Contributing |
| [`THEME_AND_TESTING_GUIDE.md`](/THEME_AND_TESTING_GUIDE.md) | Testing guide | QA workflows |

---

## 🎯 What You Get

### **Complete Design System**

✅ **Foundational Tokens**
- 20 customizable color parameters
- 12 spacing scales
- 8 typography scales
- 5 border radius sizes
- 3 shadow levels

✅ **Core Components** (9)
- Button, TextField, Select, Checkbox, RadioGroup
- Badge, Tabs, Switch, Tooltip

✅ **B2B Specialized Components** (3)
- DataGrid (tables), RecordCards (cards), FilterBar (search/filters)

✅ **Production-Ready Templates** ⭐ **NEW!**
- Customer Management (full CRUD)
- Product Catalog (inventory tracking)
- More templates: Orders, Team, Analytics, Tickets...

✅ **Advanced Features**
- Schema Renderer (backend-driven UI)
- Theme Customizer (visual color editor)
- Density Modes (Comfortable/Compact)
- Full TypeScript support
- Mobile-first responsive design
- WCAG AA accessibility

### **Theming System**

✅ **3 Preset Themes**
- Default Blue (light + dark)
- Purple (light + dark)
- Green (light + dark)

✅ **Unlimited Custom Themes** ⭐ **NEW!**
- Visual theme creator
- 20 customizable color parameters
- Save unlimited themes
- Export/Import as JSON
- Share with team
- localStorage persistence

✅ **Easy Switching**
- Click 🎨 icon in header
- Instant preview
- Persists across sessions

### **Production-Ready Documentation**

✅ **Interactive Playground**
- Test all components live
- Switch themes in real-time
- See responsive behavior
- Copy code examples

✅ **Comprehensive Guides**
- Step-by-step tutorials
- Real-world examples
- Best practices
- Troubleshooting

---

## 🏗️ Architecture

### **Tech Stack**
- **React 18** - UI framework
- **TypeScript** - Type safety
- **Tailwind CSS v4** - Styling
- **Radix UI** - Accessible primitives
- **Vite** - Build tool
- **Sonner** - Toast notifications
- **Lucide React** - Icons

### **Project Structure**

```
/
├── Documentation (Root Level)
│   ├── DEVELOPER_GUIDE_INDEX.md           📚 Start here!
│   ├── DEVELOPER_JOURNEY_GUIDE.md         🛤️ Complete tutorial
│   ├── COMPONENT_QUICK_REFERENCE.md       ⚡ Quick lookup
│   ├── CUSTOM_THEME_QUICKSTART.md         🎨 Theme basics
│   └── CUSTOM_THEME_GUIDE.md              🎨 Theme mastery
│
└── src/app/
    ├── components/
    │   ├── ds/                            🎨 Design System
    │   │   ├── Button.tsx
    │   │   ├── TextField.tsx
    │   │   ├── Select.tsx
    │   │   ├── DataGrid.tsx
    │   │   └── ... (17+ components)
    │   │
    │   └── schema/                        📋 Schema Renderer
    │       └── SchemaRenderer.tsx
    │
    ├── theme/                             🎨 Theming System
    │   ├── themes.ts
    │   ├── ThemeProvider.tsx
    │   ├── ThemeSwitcher.tsx
    │   └── ThemeCustomizer.tsx            ⭐ NEW!
    │
    ├── docs/                              📚 Documentation Site
    │   ├── DocsApp.tsx
    │   ├── DocsLayout.tsx
    │   └── pages/
    │       ├── TestingPage.tsx            🧪 Playground
    │       └── ... (7+ pages)
    │
    └── styles/
        └── theme.css                      🎨 Design Tokens
```

---

## 💡 Common Workflows

### **Workflow 1: Build a Customer Form** (30 min)

1. **Read the guide**
   ```
   Open: /DEVELOPER_JOURNEY_GUIDE.md
   Follow: Steps 1-8
   ```

2. **Create the component**
   ```tsx
   import { Button, TextField, Select } from '@/app/components/ds';
   // Follow tutorial code examples
   ```

3. **Add validation & submission**
   ```tsx
   // Complete validation patterns in guide
   ```

4. **Test & deploy**
   ```tsx
   // Testing checklist in guide
   ```

### **Workflow 2: Customize Brand Colors** (10 min)

1. **Open Theme Customizer**
   ```
   Click 🎨 icon → "Create Custom Theme"
   ```

2. **Adjust colors**
   ```
   - Change Primary Action to brand color
   - Adjust hover states
   - Update focus colors
   ```

3. **Save & export**
   ```
   - Name it "Company Brand"
   - Click "Save"
   - Click "Export" for backup
   ```

4. **Share with team**
   ```
   - Send JSON file OR
   - Share via "Paste JSON" option
   ```

### **Workflow 3: Build a Dashboard** (1 hour)

1. **Plan layout**
   ```
   - Header with filters
   - KPI cards grid
   - Data table/charts
   ```

2. **Use components**
   ```tsx
   import { FilterBar, DataGrid, RecordCards } from '@/app/components/ds';
   ```

3. **Make responsive**
   ```tsx
   <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4">
     {/* KPI cards */}
   </div>
   ```

4. **Apply theme**
   ```tsx
   // All components automatically theme-aware!
   ```

---

## 🎓 Learning Paths

### **Path 1: Quick Start** (1 hour)

```
1. Read: COMPONENT_QUICK_REFERENCE.md (5 min)
2. Explore: Testing Playground in app (15 min)
3. Try: Theme Customizer (10 min)
4. Build: Simple form with Button + TextField (30 min)
```

### **Path 2: Complete Mastery** (1 week)

```
Day 1: DEVELOPER_GUIDE_INDEX.md
       COMPONENT_QUICK_REFERENCE.md
       Explore Testing Playground

Day 2: DEVELOPER_JOURNEY_GUIDE.md
       Build customer form tutorial
       
Day 3: CUSTOM_THEME_GUIDE.md
       Create 3 custom themes
       
Day 4: Build CRUD interface
       Use DataGrid + FilterBar
       
Day 5: Build dashboard
       Multiple components
       Responsive layout
```

### **Path 3: Team Onboarding** (2 hours)

```
Hour 1:
  - Walkthrough: DEVELOPER_GUIDE_INDEX.md
  - Demo: Testing Playground
  - Show: Theme Customizer
  
Hour 2:
  - Code along: DEVELOPER_JOURNEY_GUIDE.md
  - Q&A: Common patterns
  - Setup: Team custom theme
```

---

## 📊 Component Reference

### **Core Components**

```tsx
// Buttons
<Button variant="primary">Save</Button>
<Button variant="secondary">Cancel</Button>
<Button variant="danger">Delete</Button>

// Form Fields
<TextField label="Email" value={email} onChange={setEmail} />
<Select label="Status" options={options} value={status} onChange={setStatus} />
<Checkbox label="Agree" checked={agreed} onChange={setAgreed} />

// Feedback
<Badge variant="success">Active</Badge>
<Badge variant="warning">Pending</Badge>
```

### **B2B Components**

```tsx
// Data Display
<DataGrid data={customers} columns={columns} />
<RecordCards data={products} fields={fields} />

// Data Filtering
<FilterBar
  searchValue={search}
  onSearchChange={setSearch}
  filters={filters}
/>
```

### **Theming**

```tsx
// Use theme hook
const { themeId, mode, setTheme, setMode } = useTheme();

// Access colors programmatically
const { currentTheme } = useTheme();
const primaryColor = currentTheme.colors.actionPrimary;

// Use CSS variables
<div className="bg-[var(--bg-surface)] text-[var(--text-primary)]">
  Content
</div>
```

---

## 🎨 Customization Examples

### **Example 1: Corporate Brand**

```tsx
// Open Theme Customizer
// Set these values:
{
  "actionPrimary": "#0052CC",        // Company blue
  "actionPrimaryHover": "#0747A6",   // Darker blue
  "borderFocus": "#0052CC",          // Match primary
  "statusInfo": "#0052CC"            // Brand info color
}
// Save as "Acme Corp Brand"
```

### **Example 2: High Contrast Dark**

```tsx
{
  "bgCanvas": "#000000",             // Pure black
  "bgSurface": "#1a1a1a",            // Near black
  "textPrimary": "#ffffff",          // Pure white
  "textSecondary": "#e5e7eb",        // Light gray
  "borderDefault": "#4b5563"         // Stronger borders
}
// Save as "High Contrast Dark"
```

### **Example 3: Pastel Theme**

```tsx
{
  "bgCanvas": "#fefce8",             // Soft yellow
  "actionPrimary": "#a78bfa",        // Soft purple
  "statusSuccess": "#86efac",        // Soft green
  "statusWarning": "#fcd34d",        // Soft yellow
  "statusDanger": "#fca5a5"          // Soft red
}
// Save as "Soft Pastels"
```

---

## ✅ Features Checklist

### **Design System**
- ✅ 17+ production-ready components
- ✅ Full TypeScript support
- ✅ Radix UI accessible primitives
- ✅ Mobile-first responsive
- ✅ WCAG AA compliant
- ✅ Dark mode support
- ✅ Density modes
- ✅ Schema-driven UI

### **Theming**
- ✅ 3 preset themes (6 variants)
- ✅ Unlimited custom themes
- ✅ Visual theme creator
- ✅ Save/Load themes
- ✅ Export/Import JSON
- ✅ Team sharing
- ✅ localStorage persistence
- ✅ Instant preview

### **Documentation**
- ✅ Interactive playground
- ✅ Component API docs
- ✅ Complete tutorials
- ✅ Code examples
- ✅ Best practices
- ✅ Troubleshooting
- ✅ Quick references
- ✅ Video-ready guides

---

## 🚀 Get Started Now

### **Option 1: Learn by Building** (Recommended)

```bash
# 1. Read the tutorial
Open: /DEVELOPER_JOURNEY_GUIDE.md

# 2. Follow along
Create: CustomerCreateForm.tsx

# 3. Test it
Open app → Test your form
```

### **Option 2: Explore & Experiment**

```bash
# 1. Run the app
npm run dev

# 2. Open Testing Playground
Click "Testing Playground" in sidebar

# 3. Try everything
- Switch themes (🎨 icon)
- Create custom theme
- Test components
- Copy code examples
```

### **Option 3: Quick Reference**

```bash
# Keep open while coding
Bookmark: /COMPONENT_QUICK_REFERENCE.md

# Need component props?
Lookup: Component section

# Need pattern?
Lookup: Common Patterns section
```

---

## 🤝 Contributing

### **Adding Components**

See: [`/DOCUMENTATION_GUIDE.md`](/DOCUMENTATION_GUIDE.md)

### **Adding Themes**

See: [`/DEVELOPER_THEME_GUIDE.md`](/DEVELOPER_THEME_GUIDE.md)

### **Adding Documentation**

See: [`/src/app/docs/README.md`](/src/app/docs/README.md)

---

## 🐛 Troubleshooting

### **Common Issues**

**Q: Styles not applying?**
```tsx
// ❌ Wrong
<div className="bg-primary">

// ✅ Correct
<div className="bg-[var(--action-primary)]">
```

**Q: Theme not updating?**
```tsx
// Make sure app is wrapped in ThemeProvider
<ThemeProvider>
  <App />
</ThemeProvider>
```

**Q: Custom theme disappeared?**
```
localStorage was cleared!
Solution: Import from exported JSON file
Prevention: Always export important themes
```

**More help:** See individual guide troubleshooting sections

---

## 📚 Additional Resources

### **In This Repo**
- Component source: `/src/app/components/ds/`
- Theme source: `/src/app/theme/`
- Documentation site: `/src/app/docs/`
- Design tokens: `/src/styles/theme.css`

### **External**
- Radix UI: https://www.radix-ui.com/
- Tailwind CSS: https://tailwindcss.com/
- Lucide Icons: https://lucide.dev/

---

## 📈 Stats

- **Components**: 17+ production-ready
- **Themes**: 3 presets + unlimited custom
- **Documentation**: 12 comprehensive guides
- **Code Examples**: 100+ copy-paste snippets
- **Tutorial Time**: 30 minutes to first feature
- **Test Coverage**: Complete interactive playground

---

## 🎉 You're Ready!

**Start with one of these:**

1. 👨‍💻 Developer → [`/DEVELOPER_JOURNEY_GUIDE.md`](/DEVELOPER_JOURNEY_GUIDE.md)
2. ⚡ Quick Ref → [`/COMPONENT_QUICK_REFERENCE.md`](/COMPONENT_QUICK_REFERENCE.md)
3. 🎨 Theming → [`/CUSTOM_THEME_QUICKSTART.md`](/CUSTOM_THEME_QUICKSTART.md)
4. 📚 Overview → [`/DEVELOPER_GUIDE_INDEX.md`](/DEVELOPER_GUIDE_INDEX.md)

**Happy building!** 🚀✨

---

**Version**: 3.0.0  
**Last Updated**: January 15, 2026  
**Status**: Production Ready ✅  
**License**: MIT