npm package: @mehdashti/tokens
Description: Design tokens for Smart Platform - colors, spacing, typography, and themes
Author: mehdashti
Latest version: 0.2.1

# @smart/tokens

> Design system tokens for Smart Platform - Colors, spacing, typography, and more

Enterprise-grade design tokens built with the Industrial Petrol Palette. Provides consistent styling across all Smart Platform applications.

## Features

- ✅ **Industrial Petrol Palette** - Professional color scheme aligned with APISmith
- ✅ **HSL Color Format** - Easy to manipulate and customize
- ✅ **Dark/Light Themes** - Automatic theme switching support
- ✅ **Semantic Colors** - Success, warning, error, info with backgrounds and borders
- ✅ **Spacing Scale** - 4px base scale from 0 to 384px
- ✅ **Typography System** - Font sizes, weights, and line heights
- ✅ **Border Radius** - Consistent corner rounding
- ✅ **Shadows** - Elevation system
- ✅ **Z-Index** - Layering scale

---

## Installation

```bash
# Using pnpm (recommended)
pnpm add @smart/tokens

# Using npm
npm install @smart/tokens

# Using yarn
yarn add @smart/tokens
```

---

## Usage

### Import CSS Theme

```typescript
// In your main entry file (e.g., main.tsx or App.tsx)
import '@smart/tokens/theme.css'
```

This imports the complete theme with:
- Base design tokens (spacing, typography, etc.)
- Light theme (default)
- Dark theme (`[data-theme="dark"]`)

### Theme Switching

```typescript
// Set theme via data attribute
document.documentElement.setAttribute('data-theme', 'dark')  // Dark mode
document.documentElement.setAttribute('data-theme', 'light') // Light mode

// Or use a theme store (recommended)
import { create } from 'zustand'

interface ThemeStore {
  theme: 'light' | 'dark' | 'system'
  setTheme: (theme: 'light' | 'dark' | 'system') => void
}

export const useThemeStore = create<ThemeStore>((set) => ({
  theme: 'system',
  setTheme: (theme) => {
    const effectiveTheme = theme === 'system'
      ? window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
      : theme

    document.documentElement.setAttribute('data-theme', effectiveTheme)
    set({ theme })
  }
}))
```

### Using Tokens in CSS

All tokens are available as CSS custom properties:

```css
.my-component {
  /* Colors (use with hsl()) */
  background-color: hsl(var(--background));
  color: hsl(var(--foreground));
  border: 1px solid hsl(var(--border));

  /* Primary color */
  background-color: hsl(var(--primary));
  color: hsl(var(--primary-foreground));

  /* Spacing */
  padding: var(--spacing-4);      /* 16px */
  margin: var(--spacing-2);       /* 8px */
  gap: var(--spacing-0-5);        /* 2px */

  /* Typography */
  font-size: var(--font-size-base);   /* 1rem */

  /* Border radius */
  border-radius: var(--radius-md);    /* 3px */

  /* Shadows */
  box-shadow: var(--shadow-md);

  /* Z-index */
  z-index: var(--z-modal);
}
```

---

## Color Palette

### Light Theme

| Token | HSL | Hex | Usage |
|-------|-----|-----|-------|
| `--background` | `220 14% 96%` | `#F3F4F6` | Page background |
| `--foreground` | `221 39% 11%` | `#1F2937` | Text color |
| `--primary` | `195 100% 28%` | `#006D8F` | Primary actions, links |
| `--primary-foreground` | `0 0% 100%` | `#FFFFFF` | Text on primary |
| `--border` | `220 13% 91%` | `#E5E7EB` | Borders |

### Dark Theme

| Token | HSL | Hex | Usage |
|-------|-----|-----|-------|
| `--background` | `221 39% 11%` | `#111827` | Page background |
| `--foreground` | `220 14% 96%` | `#F3F4F6` | Text color |
| `--primary` | `195 45% 38%` | `#35778C` | Primary actions (matte) |
| `--border` | `217 19% 27%` | `#374151` | Borders |

### Semantic Colors

#### Success (Green)
- **Light:** `--success: 142 64% 24%` (#166534)
- **Dark:** `--success: 156 72% 67%` (#6EE7B7)
- **Background:** `--success-bg`
- **Border:** `--success-border`

#### Warning (Orange)
- **Light:** `--warning: 26 83% 31%` (#92400E)
- **Dark:** `--warning: 43 96% 65%` (#FCD34D)

#### Error (Red)
- **Light:** `--error: 0 74% 35%` (#991B1B)
- **Dark:** `--error: 0 94% 82%` (#FCA5A5)

#### Info (Blue)
- **Light:** `--info: 224 76% 40%` (#1E40AF)
- **Dark:** `--info: 213 93% 78%` (#93C5FD)

---

## Spacing Scale

| Token | Value | Pixels |
|-------|-------|--------|
| `--spacing-0-5` | `0.125rem` | 2px |
| `--spacing-1` | `0.25rem` | 4px |
| `--spacing-2` | `0.5rem` | 8px |
| `--spacing-4` | `1rem` | 16px |
| `--spacing-8` | `2rem` | 32px |

[See full table in docs]

---

## Examples

### Button with Primary Color

```tsx
function PrimaryButton() {
  return (
    <button
      style={{
        backgroundColor: 'hsl(var(--primary))',
        color: 'hsl(var(--primary-foreground))',
        padding: 'var(--spacing-2) var(--spacing-4)',
        borderRadius: 'var(--radius-md)',
      }}
    >
      Click me
    </button>
  )
}
```

### Alert with Semantic Colors

```tsx
<div
  style={{
    backgroundColor: 'hsl(var(--success-bg))',
    color: 'hsl(var(--success))',
    border: '1px solid hsl(var(--success-border))',
    padding: 'var(--spacing-3)',
    borderRadius: 'var(--radius-md)',
  }}
>
  Success message
</div>
```

---

## Related Packages

- [@smart/ui](../ui) - UI components
- [@smart/auth-react](../auth-react) - Authentication
- [@smart/data-client](../data-client) - API client

---

**Version:** 0.1.1