@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

npm install @styledoc/design-system

Automatic Setup

Run the setup script to automatically configure your project:

npx 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:

npm install tailwindcss autoprefixer postcss tailwindcss-animate

2. Create your Tailwind config:

// tailwind.config.js
const { createStyledocConfig } = require('@styledoc/design-system');

module.exports = createStyledocConfig({
  content: [
    './src/**/*.{js,ts,jsx,tsx}', // Adjust paths as needed
  ],
});

3. Create your CSS file:

/* src/styles/globals.css or src/index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    /* Light mode semantic tokens */
    --background: 0 0% 100%;
    --foreground: 240 10% 3.9%;
    --primary: 250 64% 50%;
    --primary-foreground: 0 0% 98%;
    /* ... more tokens */
  }

  :root.dark {
    /* Dark mode tokens */
    --background: 240 10% 3.9%;
    --foreground: 0 0% 98%;
    /* ... more tokens */
  }
}

4. Import the CSS in your app:

// Next.js: pages/_app.js or app/layout.js
import '../styles/globals.css'

// Vite: src/main.jsx
import './index.css'

Usage

Typography Tokens

The design system provides three font families with consistent sizing:

// Sans serif (default)
<h1 className="text-sans-4xl">Large Heading</h1>
<p className="text-sans-base">Body text</p>

// Serif
<h2 className="text-serif-3xl">Elegant Heading</h2>

// Monospace
<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

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

Custom Color Palettes

// Dodger blue palette
<div className="bg-dodger-500 text-white">Dodger blue</div>
<div className="bg-dodger-100 text-dodger-900">Light dodger</div>

// Hydrant red palette  
<div className="bg-hydrant-500 text-white">Hydrant red</div>
<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:

// These work out of the box with no classes needed
<h1>Automatically styled heading</h1>
<p>Automatically styled paragraph with proper spacing</p>
<ul>
  <li>List items with consistent styling</li>
  <li>Proper spacing and typography</li>
</ul>
<blockquote>Styled blockquotes</blockquote>
<code>Inline code styling</code>

Dark Mode

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

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

Or use a library like next-themes:

import { ThemeProvider } from 'next-themes'

function App({ children }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system">
      {children}
    </ThemeProvider>
  )
}

Advanced Usage

Custom Configuration

You can extend the design system with your own tokens:

// tailwind.config.js
const { createStyledocConfig } = require('@styledoc/design-system');

module.exports = createStyledocConfig({
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f0f9ff',
          500: '#3b82f6',
          900: '#1e3a8a',
        }
      }
    }
  }
});

Individual Plugin Usage

Import specific plugins if you only need certain features:

// tailwind.config.js
const { styledocTypographyPlugin, styledocSemanticPlugin } = require('@styledoc/design-system');

module.exports = {
  plugins: [
    styledocTypographyPlugin, // Only typography tokens
    styledocSemanticPlugin,   // Only semantic HTML styling
  ]
}

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