@nice2dev/design-tokens 1.0.28

package/README.md

@@ -0,0 +1,221 @@
+# @nice2dev/design-tokens
+
+W3C Design Tokens implementation for Nice2Dev UI library.
+
+## Features
+
+- 📋 **W3C Design Tokens Format** - Compliant with [W3C Design Tokens Community Group](https://tr.designtokens.org/format/)
+- 🎨 **Multiple Output Formats** - CSS, SCSS, JS, TypeScript, Tailwind
+- 🌙 **Theme Support** - Light, dark, high-contrast modes
+- 🔗 **Token References** - Reference tokens with `{category.token}` syntax
+- 🧮 **Computed Values** - Auto-resolve references and composite tokens
+- 🛠️ **CLI Tool** - Generate tokens from command line
+- 📦 **Programmatic API** - Use in build scripts
+
+## Installation
+
+```bash
+npm install @nice2dev/design-tokens
+# or
+pnpm add @nice2dev/design-tokens
+```
+
+## Quick Start
+
+### Using CLI
+
+```bash
+# Initialize a new tokens project
+npx nice-tokens init
+
+# Build tokens
+npx nice-tokens build -i ./tokens -o ./dist -f css,scss,ts
+
+# Watch mode
+npx nice-tokens build --watch
+```
+
+### Token Format (W3C)
+
+```json
+{
+  "color": {
+    "$type": "color",
+    "primary": {
+      "500": {
+        "$value": "#3b82f6",
+        "$description": "Primary brand color"
+      }
+    }
+  },
+  "spacing": {
+    "$type": "dimension",
+    "md": {
+      "$value": "1rem"
+    }
+  }
+}
+```
+
+### Using References
+
+```json
+{
+  "semantic": {
+    "button": {
+      "background": {
+        "$value": "{color.primary.500}"
+      }
+    }
+  }
+}
+```
+
+## API Usage
+
+```typescript
+import { createGenerator } from '@nice2dev/design-tokens';
+
+const generator = createGenerator({
+  formats: ['css', 'ts'],
+  outputDir: './dist',
+  prefix: 'nice',
+});
+
+generator.loadDirectory('./tokens');
+await generator.generate();
+```
+
+## Token Types
+
+| Type          | Description      | Example                        |
+| ------------- | ---------------- | ------------------------------ |
+| `color`       | Color values     | `#3b82f6`, `rgb(59, 130, 246)` |
+| `dimension`   | Sizes, spacing   | `1rem`, `16px`                 |
+| `fontFamily`  | Font stacks      | `["Inter", "sans-serif"]`      |
+| `fontWeight`  | Font weights     | `400`, `"bold"`                |
+| `duration`    | Animation timing | `200ms`, `0.3s`                |
+| `cubicBezier` | Easing curves    | `[0.4, 0, 0.2, 1]`             |
+| `shadow`      | Box shadows      | Complex object                 |
+| `typography`  | Font shorthand   | Complex object                 |
+
+## Output Formats
+
+### CSS
+
+```css
+:root {
+  --nice-color-primary-500: #3b82f6;
+  --nice-spacing-md: 1rem;
+}
+```
+
+### TypeScript
+
+```typescript
+export const tokens = {
+  color: {
+    primary: {
+      '500': '#3b82f6',
+    },
+  },
+  spacing: {
+    md: '1rem',
+  },
+};
+```
+
+### Tailwind
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          500: '#3b82f6',
+        },
+      },
+    },
+  },
+};
+```
+
+## Themes
+
+The package supports multiple themes:
+
+- `light` - Default light theme
+- `dark` - Dark mode
+- `high-contrast` - WCAG AAA compliant
+- `high-contrast-dark` - High contrast dark mode
+- `dim` - Reduced brightness mode
+
+### Theme Switcher
+
+```html
+<script src="./dist/theme-switcher.js"></script>
+<script>
+  // Set theme
+  setTheme('dark');
+
+  // Toggle between light/dark
+  toggleTheme();
+
+  // Use system preference
+  useSystemTheme();
+</script>
+```
+
+### React Theme Provider
+
+```tsx
+import { ThemeProvider, useTheme } from '@nice2dev/design-tokens/ThemeContext';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <MyComponent />
+    </ThemeProvider>
+  );
+}
+
+function MyComponent() {
+  const { theme, setTheme, toggleTheme } = useTheme();
+
+  return <button onClick={toggleTheme}>Current: {theme}</button>;
+}
+```
+
+## CLI Commands
+
+```bash
+# Build tokens
+nice-tokens build [options]
+  -i, --input <dir>     Input directory (default: ./tokens)
+  -o, --output <dir>    Output directory (default: ./dist)
+  -f, --formats <list>  Output formats (css,scss,js,ts,json,tailwind)
+  -p, --prefix <str>    CSS variable prefix (default: nice)
+  --separate            Generate separate files by category
+  --watch               Watch for changes
+
+# Initialize project
+nice-tokens init [-d <dir>]
+
+# Validate token files
+nice-tokens validate <files...>
+nice-tokens validate -d ./tokens
+
+# Convert formats
+nice-tokens convert <input> <output> -f <format>
+
+# Show token info
+nice-tokens info <dir>
+
+# Compare tokens
+nice-tokens diff <source> <target>
+```
+
+## License
+
+MIT © Nice2Dev