@ai.to.design/design-token-extractor 1.3.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -0
- package/dist/cli.js +1597 -0
- package/package.json +63 -0
package/README.md
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# design-token-extractor
|
|
2
|
+
|
|
3
|
+
A one-command CLI that extracts a W3C DTCG-compatible design token set from any public website or local HTML file.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm i -g @ai.to.design/design-token-extractor
|
|
9
|
+
npx playwright install chromium
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Requires Node.js >= 18. The Chromium download is a one-time ~200 MB.
|
|
13
|
+
|
|
14
|
+
## Usage
|
|
15
|
+
|
|
16
|
+
### Extract from a URL
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
design-token-extractor extract https://example.com --out tokens.json
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
### Extract from a local HTML file (bypasses auth walls)
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
design-token-extractor extract --file ./page.html --out tokens.json
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### Output formats
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# W3C DTCG JSON (default) — canonical
|
|
32
|
+
design-token-extractor extract https://example.com --format json --out tokens.json
|
|
33
|
+
|
|
34
|
+
# CSS custom properties under :root (+ @media prefers-color-scheme: dark)
|
|
35
|
+
design-token-extractor extract https://example.com --format css --out tokens.css
|
|
36
|
+
|
|
37
|
+
# ES module exporting a default object
|
|
38
|
+
design-token-extractor extract https://example.com --format js --out tokens.js
|
|
39
|
+
|
|
40
|
+
# Markdown with color swatches and usage tables
|
|
41
|
+
design-token-extractor extract https://example.com --format md --out tokens.md
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Filter low-confidence tokens
|
|
45
|
+
|
|
46
|
+
Each token is scored 0..1 based on how many selectors use it. Drop one-offs:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
design-token-extractor extract https://example.com --min-confidence 0.5
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### Theme emulation
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
design-token-extractor extract https://example.com --theme auto # default; emits both if dark rules exist
|
|
56
|
+
design-token-extractor extract https://example.com --theme light
|
|
57
|
+
design-token-extractor extract https://example.com --theme dark
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Output shape (DTCG)
|
|
61
|
+
|
|
62
|
+
Tokens follow the [W3C Design Tokens Community Group](https://tr.designtokens.org/format/) draft. Each token is a `$value / $type / $extensions` envelope:
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
{
|
|
66
|
+
"color": {
|
|
67
|
+
"color-1": {
|
|
68
|
+
"$value": "#3b82f6",
|
|
69
|
+
"$type": "color",
|
|
70
|
+
"$extensions": {
|
|
71
|
+
"com.dte.usage": { "selectors": ["button.primary", "a"], "count": 12 },
|
|
72
|
+
"com.dte.confidence": 0.9,
|
|
73
|
+
"com.dte.source": "stylesheet",
|
|
74
|
+
"com.dte.theme": "light"
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Top-level keys (always present, empty when no tokens observed): `color`, `typography`, `spacing`, `radius`, `shadow`, `zIndex`, `breakpoint`, `motion`.
|
|
82
|
+
|
|
83
|
+
## Exit codes
|
|
84
|
+
|
|
85
|
+
| Code | Meaning |
|
|
86
|
+
|------|---------|
|
|
87
|
+
| `0` | Success |
|
|
88
|
+
| `1` | User error — bad URL, missing file, invalid flag |
|
|
89
|
+
| `2` | Extraction failure — timeout, 401/403, DNS, connection refused |
|
|
90
|
+
| `3` | Internal error |
|
|
91
|
+
|
|
92
|
+
No partial output file is written on failure (atomic temp + rename).
|
|
93
|
+
|
|
94
|
+
## Current limitations (v1)
|
|
95
|
+
|
|
96
|
+
- **No authentication.** Public URLs only. Use `--file` with a saved rendered HTML for auth-walled sites.
|
|
97
|
+
- **No source CSS parsing.** Token values come from `getComputedStyle`, which the browser has already resolved. `var()` chains are pre-resolved before we see them, so the `resolve/css-vars.ts` module is kept for v2 but unused in v1 output.
|
|
98
|
+
- **Breakpoints not extracted from live renders.** `TokenSet.breakpoint` is always emitted as `{}` in v1 — the renderer does not surface stylesheet text, so the `@media` walker has nothing to consume.
|
|
99
|
+
- **`$metadata.version` is hardcoded `"0.1.0"`** instead of being injected from `package.json` at build time.
|
|
100
|
+
- **Per-theme slicing** — categorizers run once per theme and results are concatenated, rather than the single-pass described in the SDD pseudocode. Output is equivalent; implementation differs.
|
|
101
|
+
- **Playwright Chromium required.** The `--fast` (static-only) flag is accepted but not implemented in v1 — a warning is printed and the headless renderer is used.
|
|
102
|
+
|
|
103
|
+
## Spec
|
|
104
|
+
|
|
105
|
+
See the full specification, ADRs, and decisions log at [`.start/specs/005-design-token-extractor/`](../../.start/specs/005-design-token-extractor/).
|
|
106
|
+
|
|
107
|
+
## License
|
|
108
|
+
|
|
109
|
+
MIT
|