@styledoc/design-system

A comprehensive design system with Tailwind CSS tokens, typography, and semantic styling for modern web applications.

Features

• 🎨 Custom Color Tokens - OKLCH-based color system with semantic tokens
• 📝 Typography System - Sans, serif, and mono font tokens with proper spacing
• 🏷️ Semantic HTML Styling - Pre-styled headings, paragraphs, lists, and more
• 🌙 Dark Mode Support - Built-in light and dark theme variables
• ⚡ Framework Agnostic - Works with Next.js, Vite, and other build tools
• 🔧 Easy Setup - One-command installation and configuration

Quick Start

Installation

1npm install @styledoc/design-system

Automatic Setup

Run the setup script to automatically configure your project:

1npx styledoc-setup

This will:

• Install required dependencies (Tailwind CSS, PostCSS, Autoprefixer)
• Create CSS files with design tokens
• Setup Tailwind and PostCSS configuration files
• Configure for your chosen framework (Next.js or Vite)

Manual Setup

If you prefer manual setup:

1. Install dependencies:

1npm install tailwindcss autoprefixer postcss tailwindcss-animate

2. Create your Tailwind config:

1// tailwind.config.js
2const { createStyledocConfig } = require('@styledoc/design-system');
3
4module.exports = createStyledocConfig({
5  content: [
6    './src/**/*.{js,ts,jsx,tsx}', // Adjust paths as needed
7  ],
8});

3. Create your CSS file:

1/* src/styles/globals.css or src/index.css */
2@tailwind base;
3@tailwind components;
4@tailwind utilities;
5
6@layer base {
7  :root {
8    /* Light mode semantic tokens */
9    --background: 0 0% 100%;
10    --foreground: 240 10% 3.9%;
11    --primary: 250 64% 50%;
12    --primary-foreground: 0 0% 98%;
13    /* ... more tokens */
14  }
15
16  :root.dark {
17    /* Dark mode tokens */
18    --background: 240 10% 3.9%;
19    --foreground: 0 0% 98%;
20    /* ... more tokens */
21  }
22}

4. Import the CSS in your app:

1// Next.js: pages/_app.js or app/layout.js
2import '../styles/globals.css'
3
4// Vite: src/main.jsx
5import './index.css'

Usage

Typography Tokens

The design system provides three font families with consistent sizing:

1// Sans serif (default)
2<h1 className="text-sans-4xl">Large Heading</h1>
3<p className="text-sans-base">Body text</p>
4
5// Serif
6<h2 className="text-serif-3xl">Elegant Heading</h2>
7
8// Monospace
9<code className="text-mono-sm">Code snippet</code>

Available sizes: xs, sm, base, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl, 7xl, 8xl, 9xl

Color Tokens

Semantic Colors

1<div className="bg-primary text-primary-foreground">Primary button</div>
2<div className="bg-secondary text-secondary-foreground">Secondary content</div>
3<div className="bg-muted text-muted-foreground">Muted text</div>
4<div className="bg-destructive text-destructive-foreground">Error state</div>

Custom Color Palettes

1// Dodger blue palette
2<div className="bg-dodger-500 text-white">Dodger blue</div>
3<div className="bg-dodger-100 text-dodger-900">Light dodger</div>
4
5// Hydrant red palette  
6<div className="bg-hydrant-500 text-white">Hydrant red</div>
7<div className="bg-hydrant-100 text-hydrant-900">Light hydrant</div>

Semantic HTML Styling

HTML elements are automatically styled when you include the design system:

1// These work out of the box with no classes needed
2<h1>Automatically styled heading</h1>
3<p>Automatically styled paragraph with proper spacing</p>
4<ul>
5  <li>List items with consistent styling</li>
6  <li>Proper spacing and typography</li>
7</ul>
8<blockquote>Styled blockquotes</blockquote>
9<code>Inline code styling</code>

Dark Mode

Toggle dark mode by adding the dark class to your root element:

1// Toggle dark mode
2document.documentElement.classList.toggle('dark');

Or use a library like next-themes:

1import { ThemeProvider } from 'next-themes'
2
3function App({ children }) {
4  return (
5    <ThemeProvider attribute="class" defaultTheme="system">
6      {children}
7    </ThemeProvider>
8  )
9}

Advanced Usage

Custom Configuration

You can extend the design system with your own tokens:

1// tailwind.config.js
2const { createStyledocConfig } = require('@styledoc/design-system');
3
4module.exports = createStyledocConfig({
5  theme: {
6    extend: {
7      colors: {
8        brand: {
9          50: '#f0f9ff',
10          500: '#3b82f6',
11          900: '#1e3a8a',
12        }
13      }
14    }
15  }
16});

Individual Plugin Usage

Import specific plugins if you only need certain features:

1// tailwind.config.js
2const { styledocTypographyPlugin, styledocSemanticPlugin } = require('@styledoc/design-system');
3
4module.exports = {
5  plugins: [
6    styledocTypographyPlugin, // Only typography tokens
7    styledocSemanticPlugin,   // Only semantic HTML styling
8  ]
9}

Framework-Specific Notes

Next.js

• CSS file should be in src/styles/globals.css
• Import in pages/_app.js or app/layout.js
• Supports both Pages Router and App Router

Vite

• CSS file should be in src/index.css
• Import in src/main.jsx
• Works with React, Vue, and other Vite-supported frameworks

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions