npm package: @maldarabseh/dga-tokens
Description: Design tokens for DGA Design System - Colors, Typography, Spacing, and more
Author: maldarabseh
Latest version: 1.0.7

# @maldarabseh/dga-tokens

<p align="center">
  <img src="https://img.shields.io/npm/v/@maldarabseh/dga-tokens?style=flat-square" alt="npm version">
  <img src="https://img.shields.io/npm/l/@maldarabseh/dga-tokens?style=flat-square" alt="license">
  <img src="https://img.shields.io/badge/SCSS-Ready-pink?style=flat-square" alt="SCSS">
  <img src="https://img.shields.io/badge/CSS-Ready-blue?style=flat-square" alt="CSS">
  <img src="https://img.shields.io/badge/status-under%20development-yellow?style=flat-square" alt="Status">
</p>

Design tokens for the **DGA Design System** - Colors, spacing, typography, shadows, and more for the Digital Government Authority (DGA) of the Kingdom of Saudi Arabia.

## 🚧 Under Active Development

This package is under active development. We are continuously refining tokens and adding new ones. Contributions and feedback are welcome!

## 🎯 Purpose

Design tokens are the foundational building blocks of the DGA Design System. They ensure consistency across all components and applications by providing:

- 🎨 **Colors** - Primary, neutral, semantic colors
- 📏 **Spacing** - Consistent spacing scale
- 📝 **Typography** - Font families, sizes, weights
- 🌗 **Shadows** - Elevation and depth
- 🔘 **Border Radius** - Rounded corner values
- 📐 **Breakpoints** - Responsive design values

## 📦 Installation

```bash
npm install @maldarabseh/dga-tokens
```

## 🚀 Usage

### SCSS Variables

```scss
@import '@maldarabseh/dga-tokens/scss/_variables.scss';

.my-button {
  background-color: $primary-500;
  color: $white;
  padding: $space-md $space-lg;
  border-radius: $radius-md;
  font-family: $font-family;
  font-size: $font-size-md;
  font-weight: $font-weight-semibold;
  box-shadow: $shadow-sm;
  
  &:hover {
    background-color: $primary-600;
  }
}
```

### CSS Variables

```css
@import '@maldarabseh/dga-tokens/css/tokens.css';

.my-button {
  background-color: var(--dga-primary-500);
  color: var(--dga-white);
  padding: var(--dga-space-md) var(--dga-space-lg);
  border-radius: var(--dga-radius-md);
}
```

### TypeScript/JavaScript

```typescript
import { colors, spacing, typography } from '@maldarabseh/dga-tokens';

const buttonStyles = {
  backgroundColor: colors.primary500,
  padding: `${spacing.md} ${spacing.lg}`,
  fontSize: typography.fontSizeMd,
};
```

## 📚 Token Reference

### Colors

#### Primary (Green)
| Token | Value | Usage |
|-------|-------|-------|
| `$primary-50` | `#e6f7ed` | Backgrounds |
| `$primary-100` | `#b3e6c9` | Hover states |
| `$primary-500` | `#00a651` | Primary actions |
| `$primary-600` | `#008c44` | Hover on primary |
| `$primary-700` | `#007338` | Active states |

#### Neutral (Gray)
| Token | Value | Usage |
|-------|-------|-------|
| `$gray-50` | `#f9fafb` | Page backgrounds |
| `$gray-100` | `#f3f4f6` | Card backgrounds |
| `$gray-300` | `#d1d5db` | Borders |
| `$gray-500` | `#6b7280` | Secondary text |
| `$gray-900` | `#111827` | Primary text |

#### Semantic
| Token | Usage |
|-------|-------|
| `$error-*` | Error states |
| `$warning-*` | Warning states |
| `$success-*` | Success states |
| `$info-*` | Information states |

### Spacing

| Token | Value |
|-------|-------|
| `$space-xs` | `4px` |
| `$space-sm` | `8px` |
| `$space-md` | `12px` |
| `$space-lg` | `16px` |
| `$space-xl` | `24px` |
| `$space-2xl` | `32px` |
| `$space-3xl` | `48px` |

### Typography

| Token | Value |
|-------|-------|
| `$font-family` | `'IBM Plex Sans Arabic', sans-serif` |
| `$font-size-xs` | `12px` |
| `$font-size-sm` | `14px` |
| `$font-size-md` | `16px` |
| `$font-size-lg` | `18px` |
| `$font-size-xl` | `20px` |
| `$font-weight-regular` | `400` |
| `$font-weight-medium` | `500` |
| `$font-weight-semibold` | `600` |
| `$font-weight-bold` | `700` |

### Border Radius

| Token | Value |
|-------|-------|
| `$radius-sm` | `4px` |
| `$radius-md` | `8px` |
| `$radius-lg` | `16px` |
| `$radius-xl` | `24px` |
| `$radius-full` | `9999px` |

### Shadows

| Token | Usage |
|-------|-------|
| `$shadow-sm` | Subtle elevation |
| `$shadow-md` | Cards, dropdowns |
| `$shadow-lg` | Modals, popovers |
| `$shadow-xl` | Floating elements |

## 🎨 Using with Components

The tokens are designed to work seamlessly with DGA components:

```scss
@import '@maldarabseh/dga-tokens/scss/_variables.scss';

// Custom component using DGA tokens
.custom-card {
  background-color: $white;
  border: 1px solid $gray-200;
  border-radius: $radius-lg;
  padding: $space-xl;
  box-shadow: $shadow-md;
  
  .custom-card__title {
    font-size: $font-size-lg;
    font-weight: $font-weight-semibold;
    color: $gray-900;
    margin-bottom: $space-sm;
  }
  
  .custom-card__description {
    font-size: $font-size-md;
    color: $gray-500;
  }
}
```

## 🔗 Related Packages

| Package | Description |
|---------|-------------|
| [@maldarabseh/dga-stencil](https://www.npmjs.com/package/@maldarabseh/dga-stencil) | Core web components |
| [@maldarabseh/dga-angular](https://www.npmjs.com/package/@maldarabseh/dga-angular) | Angular wrapper components |
| [@maldarabseh/dga-react](https://www.npmjs.com/package/@maldarabseh/dga-react) | React wrapper components |

## 🤝 Contributing

This project is under active development. We welcome:
- Bug reports
- Feature requests
- Pull requests
- Token suggestions

## 📄 License

MIT License - see LICENSE file for details.

---

<p align="center">
  Built with ❤️ for the Digital Government Authority of Saudi Arabia
</p>