Dezzy Design System CLI

A powerful CLI tool for creating comprehensive design systems with TypeScript, React, Storybook, and AI-powered development assistance.

Features

🎨 Complete Design System Scaffold

• Comprehensive design tokens (colors, typography, spacing, borders, shadows)
• Pre-built React components with TypeScript interfaces
• Storybook integration with accessibility testing
• Jest + Testing Library setup
• ESLint + Prettier configuration

🤖 AI Agent Integration

• Split-pane interface with live Storybook preview + chat
• Natural language component creation and modification
• Intelligent reuse-first suggestions
• Governance-driven validation and best practices
• Real-time DSL generation and compilation

🚀 Smart Code Generation

• Interactive CLI with sensible defaults
• Multiple project templates (Vite, Next.js, CRA, Storybook-only)
• Automatic documentation generation
• AI assistant integration (Claude, Cursor, etc.)

⚡ Developer Experience

• TypeScript-first approach
• DSL-driven component architecture
• Accessibility built-in
• Comprehensive testing utilities

Installation

Global Installation (Recommended)

npm install -g dezzy

Local Installation

npm install --save-dev dezzy

Quick Start

1. Create a Design System Project

# Interactive setup
dezzy create my-design-system

# Quick setup with defaults
dezzy create my-design-system --yes

# Specify template
dezzy create my-design-system --template vite-react

2. Launch the AI Agent

import React from 'react';
import { AgentUI } from 'dezzy';

function App() {
  return (
    <AgentUI 
      storybookUrl="http://localhost:6006"
      projectPath="./src"
    />
  );
}

export default App;

3. Start Building with Natural Language

👤 User: "Add a large variant to the Button section"
🤖 Agent: ✅ Successfully added "large" variant to Button section
         📖 Updated Storybook stories
         🧪 Generated example DSL

Usage

CLI Commands

# Create new project with interactive setup
dezzy create [directory] [options]

# Quick setup with defaults
dezzy create --yes --template vite-react

# Validate DSL files
dezzy validate <file>

# Initialize new DSL file
dezzy init <name> [options]

# Compile DSL to React component
dezzy compile <file> [options]

# Show version
dezzy --version

# Show help
dezzy --help

AI Agent API

import { 
  AgentUI, 
  AgentProvider,
  useAgentOperations,
  useProjectData 
} from 'dezzy';

// Complete agent interface
<AgentProvider>
  <AgentUI 
    storybookUrl="http://localhost:6006"
    projectPath="./src" 
  />
</AgentProvider>

// Programmatic operations
const { addVariant, createSection, validateDesign } = useAgentOperations();

// Add variant programmatically
await addVariant('Button', {
  name: 'large',
  props: { className: 'px-6 py-4 text-lg' },
  tokens: { fontSize: '$fontSizes.lg' }
});

Project Templates

• vite-react - Modern Vite + React setup (default)
• react-app - Create React App
• nextjs - Next.js application
• storybook-only - Storybook-focused setup

Generated Structure

my-design-system/
├── src/
│   ├── components/          # React components
│   ├── views/              # Page-level components
│   ├── tokens/             # Design tokens
│   ├── stories/            # Storybook stories
│   ├── __tests__/          # Test files
│   └── test-utils/         # Testing utilities
├── .storybook/             # Storybook configuration
├── package.json            # Dependencies & scripts
├── tsconfig.json           # TypeScript config
├── README.md               # Project documentation
├── CONTRIBUTING.md         # Development guidelines
├── DEVELOPMENT.md          # Human developer guide
└── CLAUDE.md              # AI assistant instructions

AI Agent Features

Natural Language Operations

• "Add a large variant to Button" → Creates new component variant
• "Create a ProductCard component" → Generates new section with schema
• "Update the dashboard layout" → Modifies ViewDSL structure
• "Validate my design system" → Runs governance checks

Governance & Validation

• Reuse-First Policy: Suggests existing components before creating new ones
• Token Consistency: Ensures design tokens are used correctly
• Accessibility Compliance: Validates ARIA attributes and keyboard support
• Schema Validation: Enforces section manifest requirements

DSL-First Architecture

All operations generate ViewDSL that compiles to React components:

// ViewDSL → React Component
{
  "meta": { "name": "Button Group", "id": "button-group" },
  "layout": { "type": "stack", "gap": "$space.2" },
  "sections": [
    {
      "use": "Button",
      "variant": "primary",
      "bindings": { "children": "Primary Action" }
    },
    {
      "use": "Button", 
      "variant": "secondary",
      "bindings": { "children": "Secondary Action" }
    }
  ]
}

Design Tokens

Dezzy generates a comprehensive design token system:

import { colors, spacing, typography, borders, shadows } from './tokens';

const buttonStyles = {
  backgroundColor: colors.primary[500],
  padding: `${spacing[3]} ${spacing[6]}`,
  borderRadius: borders.radius.md,
  fontFamily: typography.fontFamily.sans,
  boxShadow: shadows.md
};

Generated Components

Button Component

interface ButtonProps {
  variant?: 'primary' | 'secondary';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  onClick?: () => void;
}

Storybook Integration

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Click me'
  }
};

Development Features

Built-in Testing

• Jest configuration
• Testing Library setup
• Custom render utilities
• Accessibility testing
• Component test examples

Code Quality

• TypeScript strict mode
• ESLint + Prettier
• Pre-commit hooks ready
• CI/CD templates

Documentation

• Auto-generated README
• Component documentation
• Development guidelines
• AI assistant instructions

Configuration Options

The CLI supports extensive configuration:

• Languages: TypeScript, JavaScript
• Package Managers: npm, yarn, pnpm
• Features: Testing, Linting, Dark Mode, A11y
• Team Size: Solo, Small Team, Enterprise
• Complexity: Simple, Moderate, Complex

AI Assistant Integration

Dezzy generates specific instructions for AI assistants:

• Claude Code: Comprehensive development guidelines
• Cursor: IDE-specific workflows
• GitHub Copilot: Inline assistance patterns
• Windsurf: Collaborative development
• Generic: Universal AI assistant instructions

Examples

Create TypeScript Project with Full Features

dezzy create my-ds --template vite-react
# Select: TypeScript, all features enabled

Create JavaScript Storybook-Only Project

dezzy create storybook-ds --template storybook-only --yes

AI Agent Usage Examples

import { AgentUI, useAgentOperations } from 'dezzy';

// 1. Complete Agent Interface
function DesignSystemApp() {
  return (
    <AgentUI 
      storybookUrl="http://localhost:6006"
      projectPath="./src"
    />
  );
}

// 2. Programmatic Agent Operations
function CustomAgentIntegration() {
  const { 
    addVariant, 
    createSection, 
    processUserInput 
  } = useAgentOperations();

  const handleAddLargeButton = async () => {
    const result = await addVariant('Button', {
      name: 'large',
      description: 'Large button for hero sections',
      props: { className: 'px-6 py-4 text-lg' },
      tokens: { 
        fontSize: '$fontSizes.lg',
        padding: '$space.6' 
      }
    });
    
    if (result.success) {
      console.log('✅ Variant added successfully');
    }
  };

  const handleNaturalLanguage = async () => {
    await processUserInput('Create a ProductCard with image, title, and price');
  };

  return (
    <div>
      <button onClick={handleAddLargeButton}>
        Add Large Button Variant
      </button>
      <button onClick={handleNaturalLanguage}>
        Create Product Card
      </button>
    </div>
  );
}

Section Manifest Example

import { SectionManifest } from 'dezzy';

const cardManifest: SectionManifest = {
  id: 'card',
  name: 'Card',
  description: 'Flexible content container',
  version: '1.0.0',
  category: 'component',
  
  props: {
    title: { type: 'string', required: true },
    subtitle: { type: 'string' },
    children: { type: 'ReactNode', required: true }
  },
  
  variants: [
    {
      name: 'elevated',
      description: 'Card with shadow elevation',
      props: { className: 'bg-white rounded-lg shadow-md' },
      tokens: { shadow: '$shadows.md' }
    },
    {
      name: 'outlined', 
      description: 'Card with border outline',
      props: { className: 'bg-white rounded-lg border' },
      tokens: { border: '$borders.gray.200' }
    }
  ],
  
  accessibility: {
    role: 'article',
    keyboardSupport: false
  }
};

Validate DSL File

dezzy validate my-view.view.json

Documentation

• AI Agent Guide - Comprehensive AI agent documentation
• Testing Guide - Testing patterns and examples
• Contributing Guidelines - How to contribute to Dezzy
• Development Setup - Local development instructions

Contributing

Contributions are welcome! Please read the contributing guidelines.

License

MIT © Dan Delp

Links:

• GitHub Repository
• Issues
• NPM Package
• AI Agent Documentation