Durple Design System

A modern, production-ready design system template built with shadcn/ui, Tailwind CSS, Inter typography, and lucide-react icons. Fork this repo to jumpstart your next project with a solid foundation of design tokens, typography scales, and component patterns.

Why Use This Template?

• Ready to go — Pre-configured Tailwind with custom spacing, colors, and typography scales
• Dark mode built-in — CSS variables automatically adapt to light/dark preferences
• AI-friendly — Includes component generation guidelines for Claude, Cursor, and other AI tools
• Fully documented — Comprehensive docs for colors, spacing, typography, and component patterns
• shadcn/ui integration — Works seamlessly with the shadcn component library

Quick Start

1. Fork or Clone

# Clone the repo
git clone https://github.com/YOUR_USERNAME/durple-design-system.git

# Or use as a template on GitHub

2. Copy Configuration Files

Copy the config files into your Next.js or React project:

cp tailwind.config.ts /your-project/
cp global.css /your-project/src/styles/globals.css

3. Install Dependencies

npm install tailwindcss-animate lucide-react

4. Initialize shadcn/ui

npx shadcn-ui@latest init

5. Install Core Components

npx shadcn-ui@latest add button input label select card alert dialog table badge tabs

Recommended: Install the shadcn MCP Server

For the best experience when using this design system with AI assistants, install the shadcn MCP server. This enables your AI to directly install components, check documentation, and work seamlessly with shadcn/ui.

# For Claude Code
npx shadcn@latest mcp init --client claude

# For Cursor
npx shadcn@latest mcp init --client cursor

# For VS Code
npx shadcn@latest mcp init --client vscode

See the full setup guide: https://ui.shadcn.com/docs/mcp

What's Included

File	Purpose
tailwind.config.ts	Tailwind configuration with custom spacing, colors, and typography
global.css	CSS variables, typography classes, and utility components
Durple_Design_System.md	Complete design system documentation
SKILL_Component_Generator.md	Component generation guidelines for AI-assisted development

Design Tokens

Spacing Scale (4px base)

Token	Value	Class Example
2xs	2px	p-2xs, gap-2xs
xs	4px	p-xs, m-xs
sm	8px	p-sm, gap-sm
md	16px	p-md, m-md
lg	24px	p-lg, gap-lg
xl	32px	p-xl, m-xl
2xl	40px	p-2xl, m-2xl

Colors

The design system includes 10 color palettes, each with a full 50-900 scale:

• Brand — Primary purple for buttons, links, and accents
• Neutral — Grays for text, backgrounds, and borders
• Status — Red (error), Green (success), Yellow (warning), Blue (info)
• Accent — Cyan, Orange, Pink for additional variety

// Examples
<div className="bg-brand-600 text-white">Primary button</div>
<div className="bg-neutral-50 border-neutral-200">Card background</div>
<div className="text-red-600">Error message</div>

Typography Classes

Pre-built typography classes for consistent text styling:

<h1 className="h1">Page Title</h1>           {/* 36px, bold */}
<h2 className="h2">Section Header</h2>       {/* 30px, bold */}
<h3 className="h3">Subsection</h3>           {/* 24px, semibold */}
<p className="body-md">Standard paragraph</p> {/* 16px */}
<p className="body-sm">Smaller text</p>       {/* 14px */}
<span className="label">Form Label</span>     {/* 14px, medium */}
<span className="hint">Helper text</span>     {/* 12px, muted */}

Customizing Colors

Colors are defined in two places that should stay in sync:

1. tailwind.config.ts — Tailwind Classes

Edit the colors object to change colors used with classes like bg-brand-600:

brand: {
  50: '#F7F8FE',   // Lightest
  100: '#E0D3F5',
  // ...
  500: '#7A4ED6',  // Base
  600: '#602FCD',  // Primary (buttons, links)
  // ...
  900: '#190D38',  // Darkest
},

2. global.css — CSS Variables

Edit the CSS variables for dark mode support and direct CSS access:

--color-brand-50: #F7F8FE;
--color-brand-100: #E0D3F5;
/* ... */

Generating a Custom Color Scale

If you have a single brand color and need a full 50-900 scale:

• Tailwind CSS Color Generator
• Realtime Colors
• Coolors

IDE Setup

Your IDE may show warnings for Tailwind directives like @tailwind, @apply, and @layer. These are false positives—the CSS works correctly when processed by Tailwind.

VS Code

Install the Tailwind CSS IntelliSense extension for the best experience.

Or add to .vscode/settings.json:

{
  "css.customData": [".vscode/tailwind.json"],
  "css.validate": true
}

JetBrains IDEs

Go to Settings > Languages & Frameworks > Style Sheets > Tailwind CSS and enable Tailwind support.

Documentation

• Full design system docs — See Durple_Design_System.md
• Component generation — See SKILL_Component_Generator.md
• shadcn/ui components — https://ui.shadcn.com/docs/components
• Tailwind CSS — https://tailwindcss.com/docs
• Lucide icons — https://lucide.dev

Contributing

Contributions are welcome! Feel free to:

• Open issues for bugs or feature requests
• Submit pull requests with improvements
• Share how you're using Durple in your projects

License

MIT License — free for personal and commercial use. See LICENSE for details.

Created with ❤️ and care by John Carter