@nibin-org/tokens 1.0.0

package/README.md

@@ -0,0 +1,195 @@
+# @nibin-org/tokens
+
+[![npm version](https://img.shields.io/npm/v/@nibin-org/tokens.svg?style=flat-square)](https://www.npmjs.com/package/@nibin-org/tokens)
+[![npm downloads](https://img.shields.io/npm/dm/@nibin-org/tokens.svg?style=flat-square)](https://www.npmjs.com/package/@nibin-org/tokens)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square)](https://www.typescriptlang.org/)
+
+> 🎨 Beautiful, interactive visual documentation for Figma design tokens — **the missing UI layer that Style Dictionary doesn't provide.**
+
+## ✨ Features
+
+- **🎨 Rich Color Visualization** — Base palettes with shade scales + semantic tokens (fill, stroke, text)
+- **📏 Spacing & Size Scales** — Visual bar charts with proportional representation
+- **⬜ Radius Showcase** — Actual rounded boxes demonstrating each radius value
+- **🌙 Dark Mode** — Built-in light/dark theme toggle
+- **📋 Copy-to-Clipboard** — Click any token to copy its value instantly
+- **🔍 Search** — Filter tokens quickly (coming soon)
+- **📱 Responsive** — Works beautifully on any screen size
+- **🔌 Zero Config** — Just pass your tokens.json and go!
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install @nibin-org/tokens
+# or
+yarn add @nibin-org/tokens
+# or
+pnpm add @nibin-org/tokens
+```
+
+### Usage
+
+```tsx
+import { TokenDocumentation } from '@nibin-org/tokens';
+import '@nibin-org/tokens/styles.css';
+import tokens from './tokens.json';
+
+export default function DesignTokensPage() {
+  return (
+    <TokenDocumentation 
+      tokens={tokens}
+      title="My Design System"
+      subtitle="Design tokens synced from Figma"
+    />
+  );
+}
+```
+
+## 📊 Token Structure
+
+This library works with tokens exported from [Figma Tokens Studio](https://tokens.studio/). The expected structure is:
+
+```json
+{
+  "Colors/Value": {
+    "base": { "blue": { "50": { "value": "#1369e9", "type": "color" } } },
+    "fill": { "primary": { "value": "{base.blue.50}", "type": "color" } },
+    "stroke": { "default": { "value": "{base.gray.30}", "type": "color" } },
+    "text": { "default": { "value": "{base.gray.90}", "type": "color" } }
+  },
+  "Spacing/Mode 1": {
+    "space-sm": { "value": "8px", "type": "dimension" }
+  },
+  "Size/Mode 1": {
+    "size-lg": { "value": "16px", "type": "dimension" }
+  },
+  "Radius/Mode 1": {
+    "radius-md": { "value": "6px", "type": "dimension" }
+  }
+}
+```
+
+## 🔄 Figma-to-Code Workflow
+
+```
+┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
+│                 │      │                  │      │                 │
+│   Figma +       │──────▶  tokens.json    │──────▶   CSS + Docs    │
+│   Token Studio  │      │                  │      │                 │
+│                 │      │                  │      │                 │
+└─────────────────┘      └──────────────────┘      └─────────────────┘
+        │                         │                        │
+   Design tokens            Export/sync              Build script
+   in Figma                 via plugin               generates CSS
+                                                     + visual docs
+```
+
+### Recommended Setup
+
+1. **Design Phase**: Use [Figma Tokens Studio](https://tokens.studio/) to manage tokens in Figma
+2. **Sync Phase**: Export tokens.json to your repo (manual or GitHub sync)
+3. **Build Phase**: Run your token build script to generate CSS
+4. **Document Phase**: Use this library to display beautiful token documentation
+
+### Next.js Configuration
+
+For Next.js projects (especially Next.js 15+), add the package to `transpilePackages` in your `next.config.ts`:
+
+```typescript
+const nextConfig = {
+  transpilePackages: ['@nibin-org/tokens'],
+};
+
+export default nextConfig;
+```
+
+> **Note**: If you experience module resolution issues with Next.js 16+ Turbopack during local development with linked packages, you can use `next dev --webpack` as a workaround.
+
+## 📦 Components
+
+### `<TokenDocumentation />` — Main Component
+
+The all-in-one solution for displaying all your tokens.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tokens` | `FigmaTokens` | required | Your tokens.json content |
+| `title` | `string` | `"Design Tokens"` | Page title |
+| `subtitle` | `string` | `"..."` | Subtitle text |
+| `defaultTab` | `'colors' \| 'spacing' \| 'sizes' \| 'radius'` | `'colors'` | Initial tab |
+| `showSearch` | `boolean` | `true` | Show search input |
+| `darkMode` | `boolean` | `false` | Start in dark mode |
+| `onTokenClick` | `(token) => void` | - | Callback when token is clicked |
+
+### Individual Components
+
+For custom layouts, use components individually:
+
+```tsx
+import { ColorGrid, SpacingScale, RadiusShowcase, SizeScale } from '@nibin-org/tokens';
+
+<ColorGrid 
+  baseColors={tokens['Colors/Value'].base}
+  fillColors={tokens['Colors/Value'].fill}
+/>
+
+<SpacingScale tokens={tokens['Spacing/Mode 1']} />
+
+<RadiusShowcase tokens={tokens['Radius/Mode 1']} />
+
+<SizeScale tokens={tokens['Size/Mode 1']} />
+```
+
+## 🎨 Theming
+
+The styles use CSS custom properties, making it easy to customize:
+
+```css
+:root {
+  --ftd-accent: #6366f1;           /* Primary accent color */
+  --ftd-bg-primary: #ffffff;        /* Main background */
+  --ftd-text-primary: #0f172a;      /* Main text color */
+  --ftd-radius-lg: 16px;            /* Card border radius */
+}
+```
+
+## 🆚 Why Not Just Style Dictionary?
+
+| Feature | Style Dictionary | @nibin-org/tokens |
+|---------|-----------------|------------------|
+| Token Transformation | ✅ Excellent | ❌ Not included |
+| Multi-platform Output | ✅ Yes | ❌ No |
+| **Visual Documentation** | ❌ None | ✅ Beautiful UI |
+| **Interactive Exploration** | ❌ No | ✅ Yes |
+| **Copy-to-Clipboard** | ❌ No | ✅ Yes |
+| **Dark Mode** | ❌ No | ✅ Yes |
+
+**Use both together!** Style Dictionary for transformation, @nibin-org/tokens for documentation.
+
+## 🛠 Development
+
+```bash
+# Clone and install
+git clone https://github.com/nibinlab99-dev/next-storybook.git
+cd next-storybook
+npm install
+
+# Build tokens
+npm run tokens:build
+
+# Run dev server
+npm run dev
+```
+
+## 📄 License
+
+MIT © [nibinlab99-dev](https://github.com/nibinlab99-dev)
+
+---
+
+<p align="center">
+  Made with ❤️ for design systems
+</p>