@unpunnyfuns/swatchbook-addon 0.19.7 → 0.19.8

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.
Files changed (2) hide show
  1. package/README.md +27 -83
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
1
  # swatchbook-addon
2
2
 
3
- Published as `@unpunnyfuns/swatchbook-addon`. Storybook 10 addon for DTCG design tokens. Loads your tokens at config time (via `@unpunnyfuns/swatchbook-core`), exposes the resolved graph to the preview through a virtual module, renders a toolbar popover with one dropdown per modifier axis (`mode`, `brand`, and so on) alongside preset pills and a color-format picker, and ships a `useToken()` hook with typed paths. Re-exports the full blocks + switcher React surface so `import { TokenTable, ThemeSwitcher, useToken } from '@unpunnyfuns/swatchbook-addon'` works without a second install.
3
+ The Storybook 10 side of [swatchbook](https://github.com/unpunnyfuns/swatchbook).
4
4
 
5
- > **Documentation:** [unpunnyfuns.github.io/swatchbook](https://unpunnyfuns.github.io/swatchbook/). Token parsing powered by [Terrazzo](https://terrazzo.app/) by the [Terrazzo team](https://github.com/terrazzoapp) via `@unpunnyfuns/swatchbook-core`.
5
+ Loads your DTCG tokens at config time, exposes the resolved graph to the preview through a virtual module, and renders a toolbar popover with one dropdown per modifier axis (`mode`, `brand`, …), preset pills, and a color-format picker. Ships a typed `useToken()` hook for stories that need a resolved value at runtime.
6
+
7
+ One install pulls the whole React surface — toolbar, preview decorator, every MDX doc block, `ThemeSwitcher`, `useToken()`. `import { TokenTable, ThemeSwitcher, useToken } from '@unpunnyfuns/swatchbook-addon'` works without a second install line because the addon re-exports the full blocks + switcher API.
6
8
 
7
9
  ## Install
8
10
 
@@ -10,106 +12,48 @@ Published as `@unpunnyfuns/swatchbook-addon`. Storybook 10 addon for DTCG design
10
12
  npm install -D @unpunnyfuns/swatchbook-addon
11
13
  ```
12
14
 
13
- One package pulls the whole React surface — toolbar, preview decorator, `useToken()`, every MDX doc block (`TokenTable`, `ColorPalette`, `TokenDetail`, `SwatchbookProvider`, block-side hooks), and the standalone `ThemeSwitcher`. `swatchbook-core`, `-blocks`, and `-switcher` come along transitively; each is still independently installable for slice-only consumers.
14
-
15
15
  Peer requirements: `storybook@^10.3`, `react` / `react-dom` 18+.
16
16
 
17
- ## Register
18
-
19
- `.storybook/main.ts` — CSF Next. Inline config is the recommended path; the separate `swatchbook.config.ts` file is an escape hatch for sharing config with other tooling (see below).
20
-
21
- ```ts
22
- import { defineMain } from '@storybook/react-vite/node';
23
-
24
- export default defineMain({
25
- stories: ['../src/**/*.stories.@(ts|tsx)', '../src/**/*.mdx'],
26
- framework: '@storybook/react-vite',
27
- addons: [
28
- {
29
- name: '@unpunnyfuns/swatchbook-addon',
30
- options: {
31
- config: {
32
- resolver: 'tokens/resolver.json',
33
- default: { mode: 'Light' },
34
- cssVarPrefix: 'ds',
35
- },
17
+ ## Usage
18
+
19
+ The [Quickstart](https://unpunnyfuns.github.io/swatchbook/quickstart) walks through `.storybook/main.ts` + `.storybook/preview.ts` setup end to end. The short version:
20
+
21
+ ```ts title=".storybook/main.ts"
22
+ addons: [
23
+ {
24
+ name: '@unpunnyfuns/swatchbook-addon',
25
+ options: {
26
+ config: {
27
+ resolver: 'tokens/resolver.json',
28
+ cssVarPrefix: 'ds',
36
29
  },
37
30
  },
38
- ],
39
- });
31
+ },
32
+ ],
40
33
  ```
41
34
 
42
- `.storybook/preview.ts` — opt the preview into the addon's annotations (decorator, globalTypes, initialGlobals):
43
-
44
- ```ts
45
- import { definePreview } from '@storybook/react-vite';
35
+ ```ts title=".storybook/preview.ts"
46
36
  import swatchbookAddon from '@unpunnyfuns/swatchbook-addon';
47
-
48
- export default definePreview({
49
- addons: [swatchbookAddon()],
50
- });
37
+ export default definePreview({ addons: [swatchbookAddon()] });
51
38
  ```
52
39
 
53
- ## Options
54
-
55
- | Option | Type | What |
56
- | ------------ | -------- | ----------------------------------------------------------------- |
57
- | `config` | `Config` | Inline swatchbook config. Recommended for most projects. Mutually exclusive with `configPath`. |
58
- | `configPath` | `string` | Path to a config module relative to `.storybook/`. Loaded via jiti so `.ts` / `.mts` / `.js` / `.mjs` all work. Use when the same config is consumed by other tooling (a CLI, CI lint, external build script). |
59
-
60
40
  ## `useToken`
61
41
 
62
- ```ts
42
+ ```tsx
63
43
  import { useToken } from '@unpunnyfuns/swatchbook-addon';
64
44
 
65
45
  function Card() {
66
46
  const bg = useToken('color.surface.default');
67
- const radius = useToken('radius.lg');
68
- return (
69
- <div style={{ background: bg.cssVar, borderRadius: radius.cssVar }}>
70
- {bg.description}
71
- </div>
72
- );
47
+ return <div style={{ background: bg.cssVar }}>{bg.description}</div>;
73
48
  }
74
49
  ```
75
50
 
76
- Returns `{ value, cssVar, type?, description? }`. `cssVar` is stable across themes; `value` flips with the active theme. Paths autocomplete from the generated `.swatchbook/tokens.d.ts` once the addon has run against your project.
77
-
78
- ## Toolbar pills (presets)
79
-
80
- Add `presets` to your `swatchbook.config.ts` to surface quick-select pills next to the axis dropdowns:
81
-
82
- ```ts
83
- export default defineSwatchbookConfig({
84
- tokens: ['tokens/**/*.json'],
85
- resolver: 'tokens/resolver.json',
86
- presets: [
87
- { name: 'Default Light', axes: { mode: 'Light', brand: 'Default' } },
88
- { name: 'Brand A Dark', axes: { mode: 'Dark', brand: 'Brand A' }, description: 'Dark + violet accent.' },
89
- ],
90
- });
91
- ```
92
-
93
- Clicking a pill writes the full tuple — partial presets fill in omitted axes from each axis's default. The active pill is highlighted when the current tuple matches; if you tweak an axis dropdown after applying a preset, the pill shows a small "modified" dot so you can see that the current tuple has drifted from the named preset. Presets come from config only — there is no in-session "save as".
94
-
95
- ## Per-story overrides
96
-
97
- ```ts
98
- export const DarkBrandA = meta.story({
99
- parameters: { swatchbook: { axes: { mode: 'Dark', brand: 'Brand A' } } },
100
- });
101
- ```
102
-
103
- `axes` is a tuple of `{ axisName: contextName }` entries. Any axis left out falls back to its default; unknown keys or contexts are silently ignored. The legacy `theme: 'Composed Name'` form is still accepted for single-axis overrides.
51
+ Returns `{ value, cssVar, type?, description? }`. `cssVar` is stable across themes; `value` flips with the active tuple. Paths autocomplete from the generated `.swatchbook/tokens.d.ts`.
104
52
 
105
- ## Do / don't
53
+ ## Credits
106
54
 
107
- - ✅ Use `useToken` for typed lookups when you need the resolved value at runtime (aria labels, conditional rendering, …).
108
- - ✅ Prefer `var(--…)` in CSS; `useToken().cssVar` gives you the right string programmatically.
55
+ Token parsing and resolver evaluation come from [Terrazzo](https://terrazzo.app/) by the [Terrazzo team](https://github.com/terrazzoapp) via `@unpunnyfuns/swatchbook-core`.
109
56
 
110
- ## See also
57
+ ## Documentation
111
58
 
112
- - [`@unpunnyfuns/swatchbook-core`](../core) — the loader this addon wraps. Consume directly if you need DTCG processing outside Storybook.
113
- - [`@unpunnyfuns/swatchbook-blocks`](../blocks) — MDX doc blocks that build on this addon's virtual module.
114
- - [Project README](../../README.md) — install and wiring flow for the whole toolchain.
115
- - [Documentation](https://unpunnyfuns.github.io/swatchbook/) — concepts, guides, and full API reference.
59
+ [unpunnyfuns.github.io/swatchbook](https://unpunnyfuns.github.io/swatchbook/) — concepts, guides, and full API reference.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unpunnyfuns/swatchbook-addon",
3
- "version": "0.19.7",
3
+ "version": "0.19.8",
4
4
  "description": "Storybook addon for DTCG design tokens — toolbar, panel, and useToken hook.",
5
5
  "license": "MIT",
6
6
  "author": "unpunnyfuns <unpunnyfuns@gmail.com>",
@@ -70,9 +70,9 @@
70
70
  "dependencies": {
71
71
  "jiti": "^2.4.0",
72
72
  "picomatch": "^4.0.4",
73
- "@unpunnyfuns/swatchbook-blocks": "0.19.7",
74
- "@unpunnyfuns/swatchbook-core": "0.19.7",
75
- "@unpunnyfuns/swatchbook-switcher": "0.19.7"
73
+ "@unpunnyfuns/swatchbook-blocks": "0.19.8",
74
+ "@unpunnyfuns/swatchbook-core": "0.19.8",
75
+ "@unpunnyfuns/swatchbook-switcher": "0.19.8"
76
76
  },
77
77
  "peerDependencies": {
78
78
  "react": ">=18",