tokvista 1.3.4 → 1.4.1

package/README.md

@@ -23,11 +23,10 @@ Design token documentation is often static and hard to scan. **Tokvista** gives
 - 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`
-- One-click copy with format-aware variable names
-- Semantic + component token views with aliases resolved
-- Generic **All Tokens** view for non-standard JSON structures
-- Interactive playground for previews
-- Two usage modes: zero-setup CLI and React component library
+- One-click copy with format-aware variable names
+- Semantic + component token views with aliases resolved
+- Generic **All Tokens** view for non-standard JSON structures
+- Two usage modes: zero-setup CLI and React component library
 
 ---
 
@@ -42,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
@@ -63,9 +92,13 @@ 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
 
@@ -234,11 +267,13 @@ Need a full setup guide? See **[GUIDE.md](./GUIDE.md)**.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `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 |
-| `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. |
+| `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 |
+| `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. |
@@ -268,36 +303,36 @@ 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/',
-})
-```
+### 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/',
+})
+```
 
 ---
 
@@ -325,19 +360,27 @@ const livePreview = createGitHubPreviewUrl({
 ## 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
-```
+# 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/`.
 
 ---