@peace_node/core/README.md

Core design system with Tailwind CSS tokens, typography, and semantic styling

# @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

```bash
npm install @styledoc/design-system
```

### Automatic Setup

Run the setup script to automatically configure your project:

```bash
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:**
```bash
npm install tailwindcss autoprefixer postcss tailwindcss-animate
```

2. **Create your Tailwind config:**
```javascript
// 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:**
```css
/* 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:**
```javascript
// 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:

```jsx
// 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
```jsx
<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
```jsx
// 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:

```jsx
// 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:

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

Or use a library like `next-themes`:

```jsx
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:

```javascript
// 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:

```javascript
// 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](LICENSE) file for details.

## Support

- 📖 [Documentation](https://github.com/yourusername/styledoc-design-system)
- 🐛 [Issues](https://github.com/yourusername/styledoc-design-system/issues)
- 💬 [Discussions](https://github.com/yourusername/styledoc-design-system/discussions)