tokvista 1.12.0 → 1.13.0

package/README.md

@@ -22,7 +22,12 @@ Zero configuration. Multiple formats. One command.
 - 🔄 **Multi-format support** - Token Studio, W3C, Style Dictionary, Supernova, Figma API
 - 📋 **Smart copy** - CSS Variables, SCSS, or Tailwind with one click
 - 🔍 **Instant search** - `Cmd+K` / `Ctrl+K` to find any token
-- 🎯 **Zero config** - Works out of the box with any token format
+- 🔗 **Deep linking** - Share direct URLs to specific tokens
+- 🔬 **Token scanner** - Find unused tokens and hardcoded values
+- ✅ **Validation** - Check token structure and catch errors
+- 🔄 **Format conversion** - Convert between token formats
+- 📤 **Export** - Generate CSS, SCSS, JS, or Tailwind config
+- 🎯 **Zero config** - Works out of the box
 - ⚡ **Two modes** - CLI for quick preview or React component for apps
 - 🔥 **Live reload** - Auto-refresh on file changes
 
@@ -72,139 +77,159 @@ No configuration needed - just pass your tokens.
 
 ---
 
-## CLI Usage
+## CLI Commands
 
-### Basic
+### Preview & Documentation
 
 ```bash
-# Use default tokens.json
-npx tokvista
-
-# Specify token file
-npx tokvista ./design-tokens.json
+# Start interactive documentation
+npx tokvista tokens.json
 
 # Custom port
 npx tokvista tokens.json --port 4000
 
 # Don't open browser
 npx tokvista tokens.json --no-open
+
+# Disable live reload
+npx tokvista tokens.json --no-watch
 ```
 
-### Export Tokens
+### Setup & Configuration
 
 ```bash
-# Export to CSS
-npx tokvista export tokens.json --format css --output tokens.css
+# Interactive setup wizard
+npx tokvista init
 
-# Export to SCSS
-npx tokvista export tokens.json --format scss --output _tokens.scss
+# Force overwrite existing config
+npx tokvista init --force
 
-# Export to JavaScript
-npx tokvista export tokens.json --format json --output tokens.js
+# Skip preview after setup
+npx tokvista init --no-preview
+```
 
-# Export to Tailwind config
-npx tokvista export tokens.json --format tailwind --output tailwind.config.js
+### Scan & Analyze
 
-# Print to stdout (for piping)
-npx tokvista export tokens.json --format css
+```bash
+# Scan for token usage and issues
+npx tokvista scan tokens.json
+
+# Scan specific directory
+npx tokvista scan ./src --tokens tokens.json
+
+# Finds:
+# - Unused tokens (safe to remove)
+# - Hardcoded colors that should use tokens
+# - Hardcoded spacing values
+# - Semantic tokens with hardcoded values
 ```
 
-### Validate Tokens
+### Validate & Quality
 
 ```bash
-# Check for errors
+# Validate token structure
 npx tokvista validate tokens.json
 
-# Use in CI/CD (exits with code 1 on errors)
-npm run validate-tokens
+# Checks for:
+# - Invalid color values
+# - Invalid dimension values
+# - Broken token aliases
+# - Missing type fields
+# Exit code 1 on errors (perfect for CI/CD)
 ```
 
-### Compare Tokens
+### Compare & Diff
 
 ```bash
 # Compare two token files
 npx tokvista diff tokens-v1.json tokens-v2.json
 
-# Perfect for:
-# - Version control reviews
-# - Release changelogs  
-# - Migration tracking
+# Shows:
+# - Added tokens
+# - Removed tokens
+# - Modified tokens with old/new values
+# - Unchanged count
+```
+
+### Export & Generate
+
+```bash
+# Export to CSS
+npx tokvista export tokens.json --format css --output tokens.css
+
+# Export to SCSS
+npx tokvista export tokens.json --format scss --output _tokens.scss
+
+# Export to JavaScript
+npx tokvista export tokens.json --format json --output tokens.js
+
+# Export to Tailwind
+npx tokvista export tokens.json --format tailwind --output tailwind.config.js
+
+# Print to stdout (for piping)
+npx tokvista export tokens.json --format css
 ```
 
 ### Convert Formats
 
 ```bash
-# Convert to W3C DTCG format
+# Convert to W3C DTCG
 npx tokvista convert tokens.json --to w3c --output tokens-w3c.json
 
 # Convert to Style Dictionary
 npx tokvista convert tokens.json --to style-dictionary --output tokens-sd.json
 
-# Convert to Supernova array format
+# Convert to Supernova
 npx tokvista convert tokens.json --to supernova --output tokens-sn.json
 
-# Print to stdout
-npx tokvista convert tokens.json --to w3c
+# Convert to Token Studio
+npx tokvista convert tokens.json --to token-studio --output tokens-ts.json
 ```
 
-### Build All Formats
+### Build Pipeline
 
 ```bash
-# Build everything in one command
+# Build all formats at once
 npx tokvista build tokens.json --output-dir ./dist
 
 # Creates:
-# - tokens.css
-# - tokens.scss
-# - tokens.js
-# - tailwind.config.js
+# - tokens.css (CSS Variables)
+# - tokens.scss (SCSS Variables)
+# - tokens.js (JavaScript/TypeScript)
+# - tailwind.config.js (Tailwind Config)
 
 # Skip validation for faster builds
 npx tokvista build tokens.json --output-dir ./dist --skip-validation
 ```
 
-### Interactive Setup
+### CLI Options Reference
 
-```bash
-npx tokvista init
-```
-
-Creates `tokvista.config.ts` with your branding:
-
-```ts
-export default {
-  title: 'Acme Design System',
-  subtitle: 'Design tokens documentation',
-  logo: './logo.svg',
-  tokens: './tokens.json',
-  theme: 'system',
-  brandColor: '#6366f1',
-  categories: ['foundation', 'semantic', 'components'],
-}
-```
-
-Then run `npx tokvista` to use your config.
-
-### CLI Options
+| Command | Description |
+|---------|-------------|
+| `tokvista [file]` | Start documentation server |
+| `tokvista init` | Interactive configuration setup |
+| `tokvista scan <dir\|file>` | Analyze token usage and find issues |
+| `tokvista validate <file>` | Validate token structure |
+| `tokvista diff <old> <new>` | Compare two token files |
+| `tokvista export <file>` | Export tokens to various formats |
+| `tokvista convert <file>` | Convert between token formats |
+| `tokvista build <file>` | Build all formats (validate + export) |
 
 | Option | Description |
 |--------|-------------|
-| `tokvista [file]` | Token file path (default: `./tokens.json`) |
-| `tokvista init` | Interactive config setup |
-| `tokvista export <file> --format <type>` | Export tokens (css, scss, json, tailwind) |
-| `tokvista validate <file>` | Validate token structure and values |
-| `tokvista diff <old> <new>` | Compare two token files |
-| `tokvista convert <file> --to <format>` | Convert between token formats |
-| `tokvista build <file> --output-dir <dir>` | Build all formats (validate + export) |
-| `--config`, `-c` | Config file path |
-| `--port`, `-p` | Server port (default: `3000`) |
-| `--format` | Export format (export only) |
-| `--output`, `-o` | Output file path (export only) |
-| `--no-open` | Don't open browser |
+| `--config`, `-c` | Path to config file |
+| `--port`, `-p` | Server port (default: 3000) |
+| `--format` | Export format: css, scss, json, tailwind |
+| `--output`, `-o` | Output file path |
+| `--output-dir` | Output directory for build command |
+| `--to` | Target format for convert command |
+| `--tokens` | Token file path for scan command |
+| `--no-open` | Don't open browser automatically |
 | `--no-watch` | Disable live reload |
 | `--no-preview` | Skip preview after init |
-| `--force`, `-f` | Overwrite existing config |
-| `--help`, `-h` | Show help |
+| `--skip-validation` | Skip validation in build command |
+| `--force`, `-f` | Overwrite existing files |
+| `--help`, `-h` | Show help message |
 
 ---
 
@@ -327,6 +352,13 @@ See [GUIDE.md](./GUIDE.md) for complete setup instructions.
 - Keyboard navigation
 - Click result to copy
 
+### 🔗 Deep Linking
+
+- Share direct links to tokens
+- URL updates when clicking tokens
+- Auto-scroll and highlight on page load
+- Example: `https://yoursite.com/tokens#color-primary-500`
+
 ### 📤 Code Export
 
 Export all tokens as:

package/dist/bin/tokvista.js

@@ -1099,18 +1099,19 @@ function isTokenLike5(obj) {
 }
 function validateTokenStructure(tokens) {
   const issues = [];
-  function walk(node, path2 = [], level = 0) {
+  function walk(node, path2 = [], category = "") {
     if (!isRecord7(node)) return;
     if (path2.length === 0 && Object.keys(node).some((k) => k.includes("/"))) {
-      Object.values(node).forEach((val) => walk(val, [], level));
+      Object.entries(node).forEach(([key, val]) => {
+        const cat = key.toLowerCase().includes("semantic") ? "semantic" : key.toLowerCase().includes("component") ? "component" : "";
+        walk(val, [], cat);
+      });
       return;
     }
     if (isTokenLike5(node)) {
       const tokenPath = path2.join(".");
       const value = String(node.value || "");
-      const isSemanticToken = path2.some(
-        (p) => p.toLowerCase().includes("semantic") || p.toLowerCase().includes("component")
-      );
+      const isSemanticToken = category === "semantic" || category === "component";
       if (isSemanticToken && !value.startsWith("{")) {
         if (/#[0-9A-Fa-f]{3,8}/.test(value) || /rgba?\(/.test(value)) {
           issues.push({
@@ -1130,7 +1131,7 @@ function validateTokenStructure(tokens) {
       return;
     }
     Object.entries(node).forEach(([key, val]) => {
-      walk(val, [...path2, key], level + 1);
+      walk(val, [...path2, key], category);
     });
   }
   walk(tokens);