@phcdevworks/spectre-tokens 2.8.0 → 3.0.0
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 +97 -58
- package/dist/index.cjs +317 -11
- package/dist/index.cjs.map +1 -1
- package/dist/index.css +98 -2
- package/dist/index.d.cts +281 -3
- package/dist/index.d.ts +281 -3
- package/dist/index.js +317 -11
- package/dist/index.js.map +1 -1
- package/dist/tokens.dtcg.json +690 -6
- package/package.json +17 -9
- package/tokens/components.json +167 -0
- package/tokens/modes.json +408 -4
- package/tokens/primitives.json +45 -0
- package/tokens/semantic-roles.json +37 -0
package/README.md
CHANGED
|
@@ -1,5 +1,37 @@
|
|
|
1
1
|
# @phcdevworks/spectre-tokens
|
|
2
2
|
|
|
3
|
+
## Repository Snapshot
|
|
4
|
+
|
|
5
|
+
| Field | Value |
|
|
6
|
+
| ---------------------- | -------------------------------- |
|
|
7
|
+
| Project team | `project-design` |
|
|
8
|
+
| Repository role | Spectre L1 design-token contract |
|
|
9
|
+
| Package/artifact | `@phcdevworks/spectre-tokens` |
|
|
10
|
+
| Current version/status | 2.9.0 |
|
|
11
|
+
|
|
12
|
+
## Standard Workflow
|
|
13
|
+
|
|
14
|
+
1. Read [AGENTS.md](AGENTS.md), then the agent-specific guide for the task.
|
|
15
|
+
2. Check [TODO.md](TODO.md) and [ROADMAP.md](ROADMAP.md) for current scope.
|
|
16
|
+
3. Make the smallest repo-local change that satisfies the task.
|
|
17
|
+
4. Run `npm run check` when validation is required or practical.
|
|
18
|
+
5. Update docs and [CHANGELOG.md](CHANGELOG.md) only when behavior, public
|
|
19
|
+
contracts, or release-relevant metadata changed.
|
|
20
|
+
|
|
21
|
+
## Documentation Map
|
|
22
|
+
|
|
23
|
+
| Guide | Path |
|
|
24
|
+
| ----------- | ---------------------------- |
|
|
25
|
+
| Agent rules | [AGENTS.md](AGENTS.md) |
|
|
26
|
+
| Claude Code | [CLAUDE.md](CLAUDE.md) |
|
|
27
|
+
| Codex | [CODEX.md](CODEX.md) |
|
|
28
|
+
| Copilot | [COPILOT.md](COPILOT.md) |
|
|
29
|
+
| Jules | [JULES.md](JULES.md) |
|
|
30
|
+
| Roadmap | [ROADMAP.md](ROADMAP.md) |
|
|
31
|
+
| Todo | [TODO.md](TODO.md) |
|
|
32
|
+
| Changelog | [CHANGELOG.md](CHANGELOG.md) |
|
|
33
|
+
| Security | [SECURITY.md](SECURITY.md) |
|
|
34
|
+
|
|
3
35
|
[](https://www.npmjs.com/package/@phcdevworks/spectre-tokens)
|
|
4
36
|
[](https://github.com/phcdevworks/spectre-tokens/actions/workflows/ci.yml)
|
|
5
37
|
[](LICENSE)
|
|
@@ -25,13 +57,13 @@ and runtimes.
|
|
|
25
57
|
machine-readable contract authority. Everything else is derived from them or
|
|
26
58
|
validated against them.
|
|
27
59
|
|
|
28
|
-
| Layer
|
|
29
|
-
|
|
30
|
-
| Source token data
|
|
31
|
-
| Contract authority
|
|
32
|
-
| Public entry points
|
|
33
|
-
| Generated TypeScript | `src/generated/tokens.ts`
|
|
34
|
-
| Generated dist
|
|
60
|
+
| Layer | Path | Rule |
|
|
61
|
+
| -------------------- | ---------------------------------------------- | ------------------------------------------------------------------- |
|
|
62
|
+
| Source token data | `tokens/*.json` | All token value changes start here — never anywhere else |
|
|
63
|
+
| Contract authority | `contract.manifest.json` | Governs public namespaces and required output surfaces |
|
|
64
|
+
| Public entry points | `src/index.ts` · `src/types.ts` · `src/css.ts` | Contract-authority files — changes require changelog classification |
|
|
65
|
+
| Generated TypeScript | `src/generated/tokens.ts` | **Never edit directly** — regenerated by `npm run build` |
|
|
66
|
+
| Generated dist | `dist/` | **Never edit directly** — regenerated by `npm run build` |
|
|
35
67
|
|
|
36
68
|
After any source change: run `npm run build` to regenerate outputs, then
|
|
37
69
|
`npm run check` to validate the full contract.
|
|
@@ -60,18 +92,23 @@ This package is the correct place to define token meaning.
|
|
|
60
92
|
|
|
61
93
|
## When to use this package
|
|
62
94
|
|
|
63
|
-
- You are building a Spectre ecosystem package and need the visual language
|
|
64
|
-
|
|
65
|
-
- You
|
|
95
|
+
- You are building a Spectre ecosystem package and need the visual language
|
|
96
|
+
contract.
|
|
97
|
+
- You need design token values in JavaScript, TypeScript, CSS variables, or a
|
|
98
|
+
Tailwind theme.
|
|
99
|
+
- You want a single source of truth for semantic roles: `surface`, `text`,
|
|
100
|
+
`component`, `buttons`, `forms`, `modes`.
|
|
66
101
|
- You are consuming tokens as named values, not inventing new token meaning.
|
|
67
102
|
|
|
68
103
|
## When not to use this package
|
|
69
104
|
|
|
70
105
|
- You need UI components or component structure — use
|
|
71
106
|
[`@phcdevworks/spectre-ui`](https://github.com/phcdevworks/spectre-ui).
|
|
72
|
-
- You need framework-specific component delivery — use the appropriate adapter
|
|
73
|
-
|
|
74
|
-
|
|
107
|
+
- You need framework-specific component delivery — use the appropriate adapter
|
|
108
|
+
package.
|
|
109
|
+
- You want to define your own token meaning or override Spectre semantics
|
|
110
|
+
locally — this package is the authority; downstream consumers should consume,
|
|
111
|
+
not redefine.
|
|
75
112
|
|
|
76
113
|
## Installation
|
|
77
114
|
|
|
@@ -126,14 +163,15 @@ mode-aware styling.
|
|
|
126
163
|
|
|
127
164
|
### Semantic namespaces (prefer for all UI work)
|
|
128
165
|
|
|
129
|
-
| Namespace
|
|
130
|
-
|
|
131
|
-
| `surface`
|
|
132
|
-
| `text`
|
|
133
|
-
| `component` | Role-specific tokens for icon boxes, badges, ratings, testimonials, pricing cards |
|
|
134
|
-
| `buttons`
|
|
135
|
-
| `forms`
|
|
136
|
-
| `
|
|
166
|
+
| Namespace | What it expresses |
|
|
167
|
+
| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
168
|
+
| `surface` | Background roles: page, card, input, overlay, subtle, hero (gradient, hero sections only), hover, selected, active, divider |
|
|
169
|
+
| `text` | Foreground roles: default, muted, subtle, meta, on-surface, on-page |
|
|
170
|
+
| `component` | Role-specific tokens for icon boxes, badges, ratings, testimonials, pricing cards, nav, modal, toast, tooltip, dropdown |
|
|
171
|
+
| `buttons` | Button state tokens: default, hover, active, disabled, CTA |
|
|
172
|
+
| `forms` | Form state tokens: default, focused, error, disabled |
|
|
173
|
+
| `link` | Inline link color roles: default, hover, active, visited |
|
|
174
|
+
| `modes` | Mode-aware overrides under `modes.default` and `modes.dark` |
|
|
137
175
|
|
|
138
176
|
```ts
|
|
139
177
|
import tokens from '@phcdevworks/spectre-tokens'
|
|
@@ -141,13 +179,13 @@ import tokens from '@phcdevworks/spectre-tokens'
|
|
|
141
179
|
// Semantic — always prefer this for UI
|
|
142
180
|
const card = {
|
|
143
181
|
background: tokens.surface.card,
|
|
144
|
-
color: tokens.text.onSurface.default
|
|
182
|
+
color: tokens.text.onSurface.default
|
|
145
183
|
}
|
|
146
184
|
|
|
147
185
|
// Mode-aware semantic
|
|
148
186
|
const dark = {
|
|
149
187
|
background: tokens.modes.dark.surface.page,
|
|
150
|
-
color: tokens.modes.dark.text.onPage.default
|
|
188
|
+
color: tokens.modes.dark.text.onPage.default
|
|
151
189
|
}
|
|
152
190
|
```
|
|
153
191
|
|
|
@@ -161,7 +199,7 @@ tooling that inspects palette data directly.
|
|
|
161
199
|
// Raw palette — only when fixed color access is deliberate
|
|
162
200
|
const chart = {
|
|
163
201
|
series1: tokens.colors.brand[500],
|
|
164
|
-
series2: tokens.colors.neutral[300]
|
|
202
|
+
series2: tokens.colors.neutral[300]
|
|
165
203
|
}
|
|
166
204
|
```
|
|
167
205
|
|
|
@@ -252,6 +290,7 @@ The generated token object includes these namespaces:
|
|
|
252
290
|
- `accessibility`
|
|
253
291
|
- `buttons`
|
|
254
292
|
- `forms`
|
|
293
|
+
- `link`
|
|
255
294
|
- `surface`
|
|
256
295
|
- `text`
|
|
257
296
|
- `component`
|
|
@@ -304,11 +343,11 @@ The following semantic groups are locked. Their values must not change without
|
|
|
304
343
|
explicit approval from Bradley Potts. This applies to all contributors and all
|
|
305
344
|
AI agents — apparent visual improvements still require human sign-off.
|
|
306
345
|
|
|
307
|
-
| Protected group
|
|
308
|
-
|
|
309
|
-
| `success`
|
|
310
|
-
| `warning`
|
|
311
|
-
| `danger` semantic roles
|
|
346
|
+
| Protected group | Backed by | Guarded by |
|
|
347
|
+
| ----------------------------------- | ------------------------------ | --------------------------------- |
|
|
348
|
+
| `success` | `colors.success` palette | `check:locked` + `check:contrast` |
|
|
349
|
+
| `warning` | `colors.warning` palette | `check:locked` + `check:contrast` |
|
|
350
|
+
| `danger` semantic roles | `colors.error` palette | `check:locked` + `check:contrast` |
|
|
312
351
|
| CTA / primary action / brand-action | `colors.brand` + `buttons.cta` | `check:locked` + `check:contrast` |
|
|
313
352
|
|
|
314
353
|
`check:locked` fails immediately if any protected value changes from the
|
|
@@ -352,11 +391,11 @@ If a downstream package depends on specific token paths or semantic meaning:
|
|
|
352
391
|
Every contract-affecting change is classified in `CHANGELOG.md [Unreleased]`
|
|
353
392
|
with a `Contract change type:` line before release.
|
|
354
393
|
|
|
355
|
-
| Classification
|
|
356
|
-
|
|
357
|
-
| `additive`
|
|
358
|
-
| `semantic change` | Path stays the same but meaning, intent, or visual output shifts
|
|
359
|
-
| `breaking`
|
|
394
|
+
| Classification | When to use | Examples |
|
|
395
|
+
| ----------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------- |
|
|
396
|
+
| `additive` | New tokens, new paths, new CSS variables — existing consumers unaffected | Adding a namespace, adding a token inside an existing family |
|
|
397
|
+
| `semantic change` | Path stays the same but meaning, intent, or visual output shifts | Adjusting the role of an existing surface or text token |
|
|
398
|
+
| `breaking` | Existing consumers may need code changes | Renaming a token path, removing a namespace, changing mode names |
|
|
360
399
|
|
|
361
400
|
Renames and removals are always breaking regardless of perceived scope.
|
|
362
401
|
|
|
@@ -427,22 +466,22 @@ npm install
|
|
|
427
466
|
npm run check
|
|
428
467
|
```
|
|
429
468
|
|
|
430
|
-
This project expects Node.js `^22.12.0 || >=24.0.0` and npm `11.
|
|
469
|
+
This project expects Node.js `^22.12.0 || >=24.0.0` and npm `11.17.0`.
|
|
431
470
|
|
|
432
471
|
### Common commands
|
|
433
472
|
|
|
434
|
-
| Command
|
|
435
|
-
|
|
436
|
-
| `npm run build`
|
|
437
|
-
| `npm run check`
|
|
438
|
-
| `npm run lint`
|
|
439
|
-
| `npm run format`
|
|
440
|
-
| `npm run generate`
|
|
441
|
-
| `npm run check:manifest` | Validate public namespaces against `contract.manifest.json`
|
|
442
|
-
| `npm run check:docs`
|
|
443
|
-
| `npm run check:locked`
|
|
444
|
-
| `npm run check:contrast` | Confirm all paired tokens meet WCAG AA
|
|
445
|
-
| `npm run check:dist`
|
|
473
|
+
| Command | What it does |
|
|
474
|
+
| ------------------------ | ------------------------------------------------------------ |
|
|
475
|
+
| `npm run build` | Regenerate all outputs — run after any token source change |
|
|
476
|
+
| `npm run check` | Full validation gate — all 15 steps must pass before commit |
|
|
477
|
+
| `npm run lint` | Run ESLint against all source files |
|
|
478
|
+
| `npm run format` | Apply Prettier formatting to all files |
|
|
479
|
+
| `npm run generate` | Regenerate `src/generated/tokens.ts` from token sources only |
|
|
480
|
+
| `npm run check:manifest` | Validate public namespaces against `contract.manifest.json` |
|
|
481
|
+
| `npm run check:docs` | Validate README and TOKEN_CONTRACT headings against manifest |
|
|
482
|
+
| `npm run check:locked` | Confirm protected color families are unchanged |
|
|
483
|
+
| `npm run check:contrast` | Confirm all paired tokens meet WCAG AA |
|
|
484
|
+
| `npm run check:dist` | Confirm `dist/` artifacts are in sync with source |
|
|
446
485
|
|
|
447
486
|
### Key source areas
|
|
448
487
|
|
|
@@ -458,15 +497,15 @@ treated as downstream UI primitives.
|
|
|
458
497
|
|
|
459
498
|
## Troubleshooting
|
|
460
499
|
|
|
461
|
-
| Failure
|
|
462
|
-
|
|
463
|
-
| `check:regression` fails
|
|
464
|
-
| `check:locked` fails
|
|
465
|
-
| `check:contrast` fails
|
|
466
|
-
| `check:dist` fails
|
|
467
|
-
| `check:manifest` fails
|
|
468
|
-
| `check:docs` fails
|
|
469
|
-
| `check:classification` fails | A contract-authority file changed without a classification entry
|
|
500
|
+
| Failure | Cause | Fix |
|
|
501
|
+
| ---------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
502
|
+
| `check:regression` fails | A token value changed vs the recorded baseline | Revert the unintended change, or update the baseline if the change was intentional |
|
|
503
|
+
| `check:locked` fails | A protected color family was modified | Revert unless Bradley Potts has explicitly approved the change |
|
|
504
|
+
| `check:contrast` fails | A text/background token pair does not meet WCAG AA | Adjust the token value or the `metadata.pair` reference in the source JSON |
|
|
505
|
+
| `check:dist` fails | Generated dist is out of sync | Run `npm run build` then re-run `npm run check` |
|
|
506
|
+
| `check:manifest` fails | A namespace exists in outputs but is not declared in `contract.manifest.json` | Add the namespace to the manifest or remove it from the source |
|
|
507
|
+
| `check:docs` fails | README or TOKEN_CONTRACT.md has drifted from the manifest | Update the doc to match the current contract |
|
|
508
|
+
| `check:classification` fails | A contract-authority file changed without a classification entry | Add `Contract change type: additive`, `semantic change`, or `breaking` to `CHANGELOG.md [Unreleased]` |
|
|
470
509
|
|
|
471
510
|
## AI and automation boundaries
|
|
472
511
|
|
|
@@ -482,8 +521,8 @@ validation gates pass.
|
|
|
482
521
|
|
|
483
522
|
**Protected from automated change:** locked color families (`success`,
|
|
484
523
|
`warning`, `danger`, CTA/brand-action), `contract.manifest.json`, and
|
|
485
|
-
`src/generated/tokens.ts`. See [AGENTS.md](AGENTS.md) for full agent
|
|
486
|
-
|
|
524
|
+
`src/generated/tokens.ts`. See [AGENTS.md](AGENTS.md) for full agent governance
|
|
525
|
+
and boundary rules.
|
|
487
526
|
|
|
488
527
|
## Contributing
|
|
489
528
|
|