@design-token-kit/cli 0.3.0 → 0.3.2

package/README.md

@@ -1,18 +1,29 @@
 # @design-token-kit/cli
 
-Command line interface for Design Token Kit.
-
-It provides commands to:
-
-- validate design tokens
-- convert between DTCG JSON, HRDT YAML, and CSS
-- generate HTML showcase pages
+The CLI package of Design Token Kit provides the `dtokens` command for
+validating, converting, and previewing design tokens from the terminal.
+
+## Features
+
+* **DTCG 2025.10 validation** - schema validation for DTCG JSON token
+  documents
+* **Semantic checks** - unresolved references, circular references,
+  group references, type mismatches, and deprecated token usage
+* **HRDT YAML support** - a compact, human-readable alternative to
+  DTCG JSON
+* **Token format conversion** - read and write DTCG JSON and HRDT YAML
+* **CSS generation** - base and theme token sets rendered as CSS
+  custom properties
+* **Static showcase** - HTML showcase generation from token sources or
+  existing CSS
+* **Source abstraction** - local files, stdin, URLs, and raw token
+  content strings
 
 Node.js 18 or newer is required.
 
 ## Install
 
-Run without installation:
+Run without installing:
 
 ```bash
 npx @design-token-kit/cli validate tokens.json
@@ -22,64 +33,131 @@ Install globally:
 
 ```bash
 npm install -g @design-token-kit/cli
-dtokens validate tokens.json
+dtokens --version
 ```
 
-Install as a local dependency:
+Install locally:
 
 ```bash
 npm install @design-token-kit/cli
 ```
 
-Show CLI version:
+## Quick Start
 
 ```bash
-dtokens -v
-dtokens --version
+dtokens validate tokens.json
+dtokens convert tokens.yaml --inform hrdt --outform css --out ./tokens.css
+dtokens showcase tokens.json --out ./showcase.html --open
 ```
 
+## Input Formats
+
+### DTCG JSON
+
+Use DTCG JSON token documents as the canonical source format for
+validation, conversion, CSS generation, and showcase generation.
+
+### HRDT YAML
+
+Use HRDT YAML as a compact, human-readable alternative to DTCG JSON.
+
+### Base and theme sources
+
+When multiple token sources are provided, the first source is treated
+as the base token set and the remaining sources are treated as theme
+overrides.
+
+### Stdin
+
+Pass `-` or omit source arguments to read from standard input.
+
+## Output Formats
+
+### CSS custom properties
+
+Generate CSS variables from token sources. Base tokens are emitted
+under `:root`; theme overrides are emitted under
+`:root[data-theme="<theme>"]`.
+
+### HTML showcase
+
+Generate a static HTML preview from DTCG JSON, HRDT YAML, or existing
+CSS custom properties.
+
+### Serialized token documents
+
+Convert token documents between DTCG JSON and HRDT YAML.
+
 ## Commands
 
-### `validate`
+| Command | Description |
+| --- | --- |
+| `validate [files...]` | Validate DTCG JSON or HRDT YAML token files. |
+| `convert [options] [files...]` | Convert a token file to DTCG JSON, HRDT YAML, or CSS. |
+| `showcase [options] [files...]` | Create HTML showcase from DTCG JSON, HRDT YAML, or CSS. |
+
+## Options
+
+### convert
 
-Validate one or more DTCG JSON or HRDT YAML token files.
+| Option | Description |
+| --- | --- |
+| `-i, --inform [format]` | Input format: `dtcg`, `hrdt` |
+| `-f, --outform [format]` | Output format: `dtcg`, `hrdt`, `css` |
+| `-o, --out [file]` | Output file, defaults to stdout |
+
+### showcase
+
+| Option | Description |
+| --- | --- |
+| `-o, --out <file>` | Output HTML file name or path |
+| `--open` | Open the generated HTML in browser, only with `--out` |
+
+## Validation
+
+Validate one or more DTCG JSON or HRDT YAML token sources.
 
 ```bash
 dtokens validate tokens.json
 dtokens validate tokens.yaml
+dtokens validate tokens.yaml tokens.dark.yaml
 ```
 
-### `convert`
-
-Convert a token file to DTCG JSON, HRDT YAML, or CSS.
+## Document Conversion
 
-Defaults:
-
-- `--inform` defaults to `dtcg`
-- `--outform` defaults to `css`
+Convert token documents between DTCG JSON and HRDT YAML.
 
 ```bash
-dtokens convert tokens.json
-dtokens convert tokens.yaml --inform hrdt --outform css --out ./dist/tokens.css
 dtokens convert tokens.json --outform hrdt
+dtokens convert tokens.yaml --inform hrdt --outform dtcg
 ```
 
-Options:
+Use `--out` to write the result to a file instead of stdout.
+
+```bash
+dtokens convert tokens.json --outform hrdt --out tokens.yaml
+```
 
-- `--inform <format>`: input format override, `dtcg` or `hrdt`
-- `--outform <format>`: output format, `dtcg`, `hrdt`, or `css`
-- `--out <file>`: write output to a file instead of stdout
+Multiple input sources are only supported when `--outform css`.
 
-### `showcase`
+## CSS Conversion
 
-Generate an HTML showcase from token files or CSS.
+Convert a base token set and optional theme overrides to CSS custom
+properties.
 
 ```bash
-dtokens showcase tokens.yaml --out ./dist/showcase.html
+dtokens convert tokens.json
+dtokens convert tokens.yaml --inform hrdt --outform css
+dtokens convert tokens.json tokens.dark.json --out ./tokens.css
 ```
 
-## Supported Formats
+## HTML Showcase
+
+Generate an HTML showcase from token sources or from a single CSS
+source.
 
-- `dtcg` - Design Tokens Community Group JSON format
-- `hrdt` - Human-Readable Design Tokens YAML format
-- `css` - CSS custom properties output
+```bash
+dtokens showcase tokens.yaml --out ./showcase.html
+dtokens showcase tokens.css --out ./showcase.html
+dtokens showcase - < tokens.yaml
+```

package/bin/index.mjs

@@ -121,14 +121,13 @@ import { writeFile as writeFile2 } from "fs/promises";
 import { spawn } from "child_process";
 import path from "path";
 import { tmpdir } from "os";
-import { Source, createTokenHtmlShowcase } from "@design-token-kit/core";
+import { createTokenHtmlShowcase } from "@design-token-kit/core";
 var EXIT_FAILURE3 = 1;
 var showcaseCommand = new Command3("showcase").description("Create HTML showcase from DTCG JSON, HRDT YAML, or CSS.").argument("[files...]", "Paths to token JSON, HRDT, or CSS files (reads from stdin when omitted)").option("-o, --out <file>", "Output HTML file name or path").option("--open", "Open the generated HTML in browser (only with --out)").addHelpText("after", "\nExit status:\n  0  success\n  1  showcase failed").action(async (files, options) => {
   try {
     const showcase = createTokenHtmlShowcase();
-    const sources = (files.length > 0 ? files : ["-"]).map((f) => new Source(f));
-    const filePaths = await Promise.all(sources.map((s) => s.getFile()));
-    const html = await showcase.showcase(filePaths);
+    const sources = files.length > 0 ? files : ["-"];
+    const html = await showcase.showcase(sources);
     if (options.out) {
       const targetFile = resolveOutputPath(options.out);
       await writeFile2(targetFile, html);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@design-token-kit/cli",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "description": "CLI for Design Token Kit: validate, convert, showcase.",
     "keywords": [
         "design-tokens",
@@ -42,7 +42,7 @@
         "test": "vitest run"
     },
     "dependencies": {
-        "@design-token-kit/core": "0.3.0",
+        "@design-token-kit/core": "0.3.2",
         "commander": "14.0.1"
     },
     "devDependencies": {