tokvista 1.3.3 → 1.4.0

package/README.md

@@ -10,7 +10,7 @@
 
 Visualize colors, spacing, typography, and component tokens with zero configuration.
 
-[Live Demo](https://nibin-org.github.io/tokvista/) · [Figma Setup Guide](./GUIDE.md) · [Report Issue](https://github.com/nibin-org/tokvista/issues)
+[Live Demo](https://tokvista-demo.vercel.app/) · [Figma Setup Guide](./GUIDE.md) · [Report Issue](https://github.com/nibin-org/tokvista/issues)
 
 </div>
 
@@ -21,11 +21,11 @@ Visualize colors, spacing, typography, and component tokens with zero configurat
 Design token documentation is often static and hard to scan. **Tokvista** gives you:
 
 - Beautiful visuals for colors, spacing, sizes, radius, and typography
+- **Global format selector** - Switch between CSS Variables, SCSS, and Tailwind formats
 - Instant search with `Cmd+K` / `Ctrl+K`
-- Copy-ready CSS variables and resolved values
+- One-click copy with format-aware variable names
 - Semantic + component token views with aliases resolved
-- Built-in dark mode
-- Interactive playground for previews
+- Generic **All Tokens** view for non-standard JSON structures
 - Two usage modes: zero-setup CLI and React component library
 
 ---
@@ -41,7 +41,37 @@ npx tokvista tokens.json
 Optional flags:
 
 ```bash
-npx tokvista ./tokens.json --port 4000 --no-open
+npx tokvista ./tokens.json --config ./tokvista.config.ts --port 4000 --no-open
+```
+
+Create a starter config (recommended for branding/customization):
+
+```bash
+npx tokvista init
+```
+
+`init` asks for title/subtitle/logo/theme/brand color/categories, writes `tokvista.config.ts`, and starts a live preview automatically.
+
+### Tokvista Config (Recommended)
+
+`tokvista init` creates `tokvista.config.ts` in your project root. You can customize it like this:
+
+```ts
+export default {
+  title: 'Acme Design System',
+  subtitle: 'Interactive design tokens documentation',
+  logo: './logo.svg',
+  tokens: './tokens.json',
+  theme: 'system',
+  brandColor: '#6366f1',
+  categories: ['foundation', 'semantic', 'components'],
+}
+```
+
+Then run:
+
+```bash
+npx tokvista
 ```
 
 ### Option B: React Component Library
@@ -62,17 +92,108 @@ export default function DesignSystem() {
 
 ### CLI Options
 
+- `tokvista init` - Interactive setup for `tokvista.config.ts` + auto preview
 - `tokvista [tokens.json]` - Token file path (default: `./tokens.json`)
+- `--config` / `-c` - Config file path (default auto-detect: `tokvista.config.ts|js|mjs|cjs|json`)
+- `--force` / `-f` - Overwrite existing `tokvista.config.ts` (with `tokvista init`)
 - `--port` / `-p` - Preferred port (default: `3000`)
 - `--no-open` - Do not auto-open browser
+- `--no-preview` - Skip auto-start after `tokvista init`
 - `--help` / `-h` - Show help
 - `Ctrl+C` - Stop the local server
 
+### Try with a Sample `tokens.json`
+
+You can copy this into a local `tokens.json` file and run Tokvista immediately:
+
+```json
+{
+  "Foundation/Value": {
+    "base": {
+      "color": {
+        "blue": {
+          "500": { "value": "#2563EB", "type": "color" },
+          "600": { "value": "#1D4ED8", "type": "color" }
+        },
+        "gray": {
+          "100": { "value": "#F3F4F6", "type": "color" },
+          "900": { "value": "#111827", "type": "color" }
+        }
+      },
+      "space": {
+        "xs": { "value": "4px", "type": "spacing" },
+        "sm": { "value": "8px", "type": "spacing" },
+        "md": { "value": "16px", "type": "spacing" }
+      },
+      "size": {
+        "md": { "value": "40px", "type": "sizing" },
+        "lg": { "value": "48px", "type": "sizing" }
+      },
+      "radius": {
+        "sm": { "value": "6px", "type": "borderRadius" },
+        "md": { "value": "10px", "type": "borderRadius" }
+      },
+      "font-size": {
+        "sm": { "value": "12px", "type": "fontSize" },
+        "md": { "value": "14px", "type": "fontSize" }
+      }
+    }
+  },
+  "Semantic/Value": {
+    "fill": {
+      "primary": { "value": "{base.color.blue.500}", "type": "color" },
+      "surface": { "value": "{base.color.gray.100}", "type": "color" }
+    },
+    "stroke": {
+      "primary": { "value": "{base.color.blue.600}", "type": "color" }
+    },
+    "text": {
+      "primary": { "value": "{base.color.gray.900}", "type": "color" },
+      "inverse": { "value": "#FFFFFF", "type": "color" }
+    }
+  },
+  "Components/Mode 1": {
+    "button": {
+      "Primary": {
+        "fill": { "value": "#2563EB", "type": "color" },
+        "text": { "value": "#FFFFFF", "type": "color" },
+        "stroke": { "value": "#1D4ED8", "type": "color" }
+      },
+      "height": {
+        "md": { "value": "40px", "type": "dimension" }
+      },
+      "padding-x": {
+        "md": { "value": "16px", "type": "dimension" }
+      },
+      "padding-y": {
+        "md": { "value": "10px", "type": "dimension" }
+      },
+      "radius": {
+        "md": { "value": "10px", "type": "dimension" }
+      },
+      "font-size": {
+        "md": { "value": "14px", "type": "dimension" }
+      },
+      "line-height": {
+        "md": { "value": "20px", "type": "dimension" }
+      }
+    }
+  }
+}
+
+```
+
+If you're contributing in this repository, a larger real-world sample is available at `tokens.json`.
+For package users, run Tokvista with your own exported `tokens.json` file.
+
 
 ---
 
 ## What You Get
 
+### Global Format Selector
+Switch between CSS Variables (`var(--token)`), SCSS Variables (`$token`), and Tailwind Classes (`token`) with a single click. Your preference is saved and applied across all token displays and copy operations.
+
 ### Foundation Tokens
 Visualize base tokens like colors, spacing, sizes, radius, and typography.
 
@@ -88,11 +209,14 @@ Export CSS, SCSS, JavaScript, or Tailwind config with high‑contrast syntax hig
 ### Playground
 Preview components using your tokens and custom class names.
 
+### All Tokens (Any JSON Shape)
+Even when your file does not follow `Foundation/Value` or `Semantic/Value`, Tokvista now shows every token path/value/type in the **All Tokens** tab.
+
 ---
 
 ## Demo
 
-Live demo: https://nibin-org.github.io/tokvista/
+Live demo: https://tokvista-demo.vercel.app/
 
 Run it locally: see Local Development below.
 
@@ -146,11 +270,13 @@ Need a full setup guide? See **[GUIDE.md](./GUIDE.md)**.
 | `tokens` | `FigmaTokens` | Required | Tokens object (W3C format or Token Studio) |
 | `title` | `string` | `"Design Tokens"` | Main header title |
 | `subtitle` | `string` | `"View and copy design tokens"` | Subtitle text |
-| `darkMode` | `boolean` | `false` | Initial theme state |
+| `logo` | `string` | `undefined` | Optional logo URL (or data URL) rendered in the header |
+| `categories` | `("foundation" \| "semantic" \| "components")[]` | `undefined` | Restrict which top-level tabs are shown |
 | `fontFamilySans` | `string` | `undefined` | Override the UI sans font-family (CSS value). Load the font in your app. |
 | `fontFamilyMono` | `string` | `undefined` | Override the UI mono font-family (CSS value). Load the font in your app. |
 | `loadDefaultFonts` | `boolean` | `true` | When `true`, loads Inter + JetBrains Mono from Google Fonts. Set `false` to use only your app fonts. |
 | `onTokenClick` | `(token) => void` | `undefined` | Callback when a token is clicked |
+| `snapshotHistory` | `SnapshotHistoryOptions` | `undefined` | Enable built-in snapshot history panel. Use `accessMode: "preview"` for locked teaser mode and `"full"` for full access. |
 
 ### Custom Fonts
 
@@ -177,13 +303,46 @@ Use these to build custom layouts:
 
 Each accepts `tokens` and optional `title`.
 
+### Snapshot History
+
+```tsx
+import { TokenDocumentation, createGitHubSnapshotHistory } from 'tokvista'
+
+<TokenDocumentation
+  tokens={tokens}
+  snapshotHistory={createGitHubSnapshotHistory({
+    owner: 'org',
+    repo: 'repo',
+    branch: 'main',
+    path: 'tokens.json',
+    accessMode: 'full', // use "preview" for hosted teaser links
+  })}
+/>
+```
+
+Generate share links for hosted preview:
+
+```ts
+import { createGitHubPreviewUrl } from 'tokvista'
+
+const livePreview = createGitHubPreviewUrl({
+  owner: 'org',
+  repo: 'repo',
+  branch: 'main',
+  path: 'tokens.json',
+  previewBaseUrl: 'https://tokvista-demo.vercel.app/',
+})
+```
+
 ---
 
 ## Search and Copy
 
-- Search across token names and values
+- Search across token names and values with `Cmd+K` / `Ctrl+K`
 - Keyboard navigation with Enter to focus
-- Copy action returns `var(--token)` when available
+- **Format-aware copying** - Choose between CSS Variables, SCSS, or Tailwind
+- Variable names display in your selected format
+- Preference persists across sessions
 
 ---
 
@@ -201,25 +360,34 @@ Each accepts `tokens` and optional `title`.
 ## Local Development
 
 ```bash
-# root package
+# package users (published npm package)
+npx tokvista init
+npx tokvista
+
+# contributors testing local unpublished changes (this repo)
+source ~/.nvm/nvm.sh
+nvm use 20
 npm install
 npm run build
-node dist/bin/tokvista.js ../tokens.json --port 4000
+node dist/bin/tokvista.js init --no-preview
+node dist/bin/tokvista.js --config ./tokvista.config.ts --port 4000
 
 # demo app
 cd demo
 npm install
+# optional: copy demo/.env.example to demo/.env.local and set NEXT_PUBLIC_DEMO_SOURCE
 npm run dev
 ```
 
 CLI defaults to `http://localhost:3000` and demo dev runs at `http://localhost:3000/`, so use a custom CLI port (for example `4000`) when running both.
+Package users should use `npx tokvista ...`. `node dist/bin/tokvista.js ...` is only for local testing before publish.
 Note: production demo is served under `/tokvista/`.
 
 ---
 
 ## Resources
 
-- [Live Demo](https://nibin-org.github.io/tokvista/)
+- [Live Demo](https://tokvista-demo.vercel.app/)
 - [Figma Setup Guide](./GUIDE.md)
 - [GitHub Repository](https://github.com/nibin-org/tokvista)
 - [Issue Tracker](https://github.com/nibin-org/tokvista/issues)