npm package: @miikad/design-tokens
Description: Shared design tokens for all company applications
Author: miikad>
Latest version: 1.0.2

# @miikad/design-tokens

Shared design tokens and design system documentation for all company applications.

## Installation

```bash
npm install @miikad/design-tokens
```

## Usage

### In React/Vite

```javascript
// main.jsx or main.tsx
import '@miikad/design-tokens/design-tokens.css';
import './styles/global.css';
```

### In CSS

```css
@import '@miikad/design-tokens/design-tokens.css';

.button {
  background: var(--primary-color);
  padding: var(--space-2) var(--space-4);
  border-radius: var(--radius-md);
  font-size: var(--font-size-base);
  transition: all var(--transition-base);
}
```

### In JavaScript

```javascript
// Get token value at runtime
const primaryColor = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-primary');
```

## Documentation

Complete design system documentation is available in the `docs/` folder:

- **[Design System](./docs/DESIGN_SYSTEM.md)** - Comprehensive design system guide with colors, typography, components, and patterns
- **[Quick Reference](./docs/DESIGN_QUICK_REFERENCE.md)** - Quick lookup guide for common tokens and patterns
- **[CSS Architecture](./docs/CSS_ARCHITECTURE.md)** - How to structure and share design tokens across multiple applications
- **[Architecture Summary](./docs/ARCHITECTURE_SUMMARY.md)** - Multi-app design system overview

## Available Tokens

### Colors
- **Primary**: `--color-primary`, `--color-primary-hover`, `--color-primary-light`
- **Semantic**: `--color-success`, `--color-warning`, `--color-error`, `--color-info`
- **Theme**: `--bg-primary`, `--text-primary`, etc. (auto-switch light/dark)

### Spacing (4px base unit)
- `--space-1` (4px) through `--space-20` (80px)

### Typography
- **Sizes**: `--font-size-xs` through `--font-size-4xl`
- **Weights**: `--font-weight-light` through `--font-weight-bold`
- **Families**: `--font-family-base`, `--font-family-mono`
- **Line Heights**: `--line-height-tight`, `--line-height-normal`, etc.

### Border Radius
- `--radius-xs` through `--radius-3xl`, `--radius-round`

### Shadows
- `--shadow-sm` through `--shadow-2xl`
- Theme-aware: `--shadow`, `--shadow-hover`

### Transitions
- `--transition-fast` (0.15s), `--transition-base` (0.2s), `--transition-slow` (0.3s)
- Easing functions: `--easing-linear`, `--easing-in`, `--easing-out`, `--easing-in-out`

### Z-Index
- `--z-index-dropdown`, `--z-index-modal`, `--z-index-tooltip`, etc.

### Breakpoints
- `--breakpoint-sm` (480px) through `--breakpoint-2xl` (1400px)

See the complete list in [design-tokens.css](./design-tokens.css)

## Theme Support

Automatically switches between light and dark themes:

```javascript
// Toggle theme
document.documentElement.setAttribute('data-theme', 'dark');
document.documentElement.setAttribute('data-theme', 'light');
```

Theme-aware variables (like `--bg-primary`, `--text-primary`) automatically switch - no need to write separate dark mode CSS!

## Best Practices

✅ **DO:**
- Always use CSS variables: `color: var(--primary-color)`
- Use semantic spacing: `padding: var(--space-4)`
- Use theme-aware colors: `background: var(--bg-primary)`

❌ **DON'T:**
- Hardcode values: `color: #f46524`
- Use fixed pixels: `padding: 16px`
- Use light/dark specific vars: `background: var(--light-bg-primary)`

## Multi-App Usage

This package is designed to be shared across multiple applications:

1. Install in each app: `npm install @miikad/design-tokens`
2. Import in your main entry file
3. Override specific tokens in your app's `app-specific.css` if needed
4. Update all apps: `npm update @miikad/design-tokens`

See [CSS Architecture](./docs/CSS_ARCHITECTURE.md) for detailed multi-app setup guide.

## Updating

```bash
npm update @miikad/design-tokens
```

## Version History

See [CHANGELOG.md](./CHANGELOG.md)

## Contributing

1. Make changes to `design-tokens.css` or documentation
2. Update version in `package.json`
3. Update `CHANGELOG.md`
4. Publish: `npm publish`

## License

MIT

## Support

For questions or issues:
- Check the [documentation](./docs/)
- Open an issue in the repository
- Contact the development team