@unpunnyfuns/swatchbook-addon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unpunny Funs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# Addon
+
+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 one toolbar dropdown per modifier axis (`mode`, `brand`, and so on) plus a unified Design Tokens panel (hierarchical tree + diagnostics), and ships a `useToken()` hook with typed paths.
+
+> **Documentation:** [unpunnyfuns.github.io/swatchbook](https://unpunnyfuns.github.io/swatchbook/). Token parsing powered by [Terrazzo](https://terrazzo.app/) by [Drew Powers](https://github.com/drwpow) via `@unpunnyfuns/swatchbook-core`.
+
+## Install
+
+```sh
+npm install -D @unpunnyfuns/swatchbook-addon @unpunnyfuns/swatchbook-core
+```
+
+This gives you the toolbar, Design Tokens panel (hierarchical tree view with diagnostics), preview decorator, and the `useToken()` hook. The MDX doc blocks (`TokenTable`, `ColorPalette`, `TokenDetail`, `SwatchbookProvider`, block-side hooks) live in the sibling package — add it alongside if you want them:
+
+```sh
+npm install @unpunnyfuns/swatchbook-blocks
+```
+
+Peer requirements: `storybook@^10.3`, `react` / `react-dom` 18+.
+
+## Register
+
+`.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).
+
+```ts
+import { defineMain } from '@storybook/react-vite/node';
+
+export default defineMain({
+  stories: ['../src/**/*.stories.@(ts|tsx)', '../src/**/*.mdx'],
+  framework: '@storybook/react-vite',
+  addons: [
+    {
+      name: '@unpunnyfuns/swatchbook-addon',
+      options: {
+        config: {
+          resolver: 'tokens/resolver.json',
+          default: { mode: 'Light' },
+          cssVarPrefix: 'ds',
+        },
+      },
+    },
+  ],
+});
+```
+
+`.storybook/preview.ts` — opt the preview into the addon's annotations (decorator, globalTypes, initialGlobals):
+
+```ts
+import { definePreview } from '@storybook/react-vite';
+import swatchbookAddon from '@unpunnyfuns/swatchbook-addon';
+
+export default definePreview({
+  addons: [swatchbookAddon()],
+});
+```
+
+## Options
+
+| Option       | Type     | What                                                              |
+| ------------ | -------- | ----------------------------------------------------------------- |
+| `config`     | `Config` | Inline swatchbook config. Recommended for most projects. Mutually exclusive with `configPath`. |
+| `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). |
+
+## `useToken`
+
+```ts
+import { useToken } from '@unpunnyfuns/swatchbook-addon/hooks';
+
+function Card() {
+  const bg = useToken('color.sys.surface.default');
+  const radius = useToken('radius.sys.lg');
+  return (
+    <div style={{ background: bg.cssVar, borderRadius: radius.cssVar }}>
+      {bg.description}
+    </div>
+  );
+}
+```
+
+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.
+
+## Toolbar pills (presets)
+
+Add `presets` to your `swatchbook.config.ts` to surface quick-select pills next to the axis dropdowns:
+
+```ts
+export default defineSwatchbookConfig({
+  tokens: ['tokens/**/*.json'],
+  resolver: 'tokens/resolver.json',
+  presets: [
+    { name: 'Default Light', axes: { mode: 'Light', brand: 'Default' } },
+    { name: 'Brand A Dark', axes: { mode: 'Dark', brand: 'Brand A' }, description: 'Dark + violet accent.' },
+  ],
+});
+```
+
+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".
+
+## Per-story overrides
+
+```ts
+export const DarkBrandA = meta.story({
+  parameters: { swatchbook: { axes: { mode: 'Dark', brand: 'Brand A' } } },
+});
+```
+
+`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.
+
+## Do / don't
+
+- ✅ Use `useToken` for typed lookups when you need the resolved value at runtime (aria labels, conditional rendering, …).
+- ✅ Prefer `var(--…)` in CSS; `useToken().cssVar` gives you the right string programmatically.
+- ❌ Don't import from `virtual:swatchbook/tokens` directly in consumer code. Go through `useToken` / the panel / the doc blocks so the API stays stable if we change the virtual module's shape.
+- ❌ Don't combine `parameters.swatchbook.theme` *and* the toolbar for the same story — the parameter wins and the toolbar change won't stick.
+
+## See also
+
+- [`@unpunnyfuns/swatchbook-core`](../core) — the loader this addon wraps. Consume directly if you need DTCG processing outside Storybook.
+- [`@unpunnyfuns/swatchbook-blocks`](../blocks) — MDX doc blocks that build on this addon's virtual module.
+- [Project README](../../README.md) — install and wiring flow for the whole toolchain.
+- [Documentation](https://unpunnyfuns.github.io/swatchbook/) — concepts, guides, and full API reference.

package/dist/constants-1plfdgh7.mjs

@@ -0,0 +1,21 @@
+//#region src/constants.ts
+const ADDON_ID = "swatchbook";
+const TOOL_ID = `${ADDON_ID}/theme-switcher`;
+const PANEL_ID = `${ADDON_ID}/design-tokens`;
+const PARAM_KEY = "swatchbook";
+/** Canonical active-theme global: composed permutation ID (string). Read by toolbar, panel, blocks. */
+const GLOBAL_KEY = "swatchbookTheme";
+/** Tuple companion: `Record<axisName, contextName>`. Optional — when present, takes precedence over the string global. */
+const AXES_GLOBAL_KEY = "swatchbookAxes";
+/** Display-only color format for blocks (`hex` | `rgb` | `hsl` | `oklch` | `raw`). Emitted CSS is unaffected. */
+const COLOR_FORMAT_GLOBAL_KEY = "swatchbookColorFormat";
+const VIRTUAL_MODULE_ID = "virtual:swatchbook/tokens";
+const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
+const DATA_THEME_ATTR = "data-theme";
+const STYLE_ELEMENT_ID = "swatchbook-tokens";
+/** Channel event: preview → manager, carries theme list + mode. */
+const INIT_EVENT = "swatchbook/init";
+//#endregion
+export { GLOBAL_KEY as a, PARAM_KEY as c, TOOL_ID as d, VIRTUAL_MODULE_ID as f, DATA_THEME_ATTR as i, RESOLVED_VIRTUAL_MODULE_ID as l, AXES_GLOBAL_KEY as n, INIT_EVENT as o, COLOR_FORMAT_GLOBAL_KEY as r, PANEL_ID as s, ADDON_ID as t, STYLE_ELEMENT_ID as u };
+
+//# sourceMappingURL=constants-1plfdgh7.mjs.map

package/dist/constants-1plfdgh7.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants-1plfdgh7.mjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["export const ADDON_ID = 'swatchbook';\nexport const TOOL_ID = `${ADDON_ID}/theme-switcher`;\nexport const PANEL_ID = `${ADDON_ID}/design-tokens`;\nexport const PARAM_KEY = 'swatchbook';\n/** Canonical active-theme global: composed permutation ID (string). Read by toolbar, panel, blocks. */\nexport const GLOBAL_KEY = 'swatchbookTheme';\n/** Tuple companion: `Record<axisName, contextName>`. Optional — when present, takes precedence over the string global. */\nexport const AXES_GLOBAL_KEY = 'swatchbookAxes';\n/** Display-only color format for blocks (`hex` | `rgb` | `hsl` | `oklch` | `raw`). Emitted CSS is unaffected. */\nexport const COLOR_FORMAT_GLOBAL_KEY = 'swatchbookColorFormat';\n\nexport const VIRTUAL_MODULE_ID = 'virtual:swatchbook/tokens';\nexport const RESOLVED_VIRTUAL_MODULE_ID = `\\0${VIRTUAL_MODULE_ID}`;\n\nexport const DATA_THEME_ATTR = 'data-theme';\nexport const STYLE_ELEMENT_ID = 'swatchbook-tokens';\n\n/** Channel event: preview → manager, carries theme list + mode. */\nexport const INIT_EVENT = 'swatchbook/init';\n"],"mappings":";AAAA,MAAa,WAAW;AACxB,MAAa,UAAU,GAAG,SAAS;AACnC,MAAa,WAAW,GAAG,SAAS;AACpC,MAAa,YAAY;;AAEzB,MAAa,aAAa;;AAE1B,MAAa,kBAAkB;;AAE/B,MAAa,0BAA0B;AAEvC,MAAa,oBAAoB;AACjC,MAAa,6BAA6B,KAAK;AAE/C,MAAa,kBAAkB;AAC/B,MAAa,mBAAmB;;AAGhC,MAAa,aAAa"}

package/dist/hooks/index.d.mts

@@ -0,0 +1,37 @@
+//#region src/hooks/use-token.d.ts
+/**
+ * Consumers augment this interface (via the addon's generated
+ * `.swatchbook/tokens.d.ts`) to narrow {@link useToken}'s first parameter
+ * to their project's actual token paths. Without augmentation it's empty
+ * and {@link TokenPath} falls back to `string`.
+ */
+interface SwatchbookTokenMap {}
+type KnownPath = keyof SwatchbookTokenMap;
+/** Union of known token paths, or `string` when the addon codegen hasn't run. */
+type TokenPath = [KnownPath] extends [never] ? string : KnownPath;
+interface TokenInfo {
+  /** The resolved DTCG `$value`. Shape varies by `$type`. */
+  value: unknown;
+  /** `var(--prefix-token-path)` reference, ready to drop into any CSS value. */
+  cssVar: string;
+  /** DTCG `$type` of the token, if known. */
+  type?: string;
+  /** Optional DTCG `$description`. */
+  description?: string;
+}
+/**
+ * Read a DTCG token for the currently active theme. Re-reads on theme
+ * switch via the addon's `ThemeContext`. Returns `{ value, cssVar, type,
+ * description }`.
+ *
+ * Typed paths appear automatically once `.swatchbook/tokens.d.ts` is
+ * generated (happens on first storybook start/build). Until then
+ * `TokenPath` is `string`.
+ *
+ * Safe to call in autodocs / MDX renders — uses plain React context, not
+ * Storybook's preview-only hooks.
+ */
+declare function useToken(path: TokenPath): TokenInfo;
+//#endregion
+export { type SwatchbookTokenMap, type TokenInfo, type TokenPath, useToken };
+//# sourceMappingURL=index.d.mts.map

package/dist/hooks/index.mjs

@@ -0,0 +1,33 @@
+import { cssVarPrefix, defaultTheme, themesResolved } from "virtual:swatchbook/tokens";
+import { useActiveTheme } from "@unpunnyfuns/swatchbook-blocks";
+//#region src/hooks/use-token.ts
+function makeCssVar(path, prefix) {
+	const tail = path.replaceAll(".", "-");
+	return prefix ? `var(--${prefix}-${tail})` : `var(--${tail})`;
+}
+/**
+* Read a DTCG token for the currently active theme. Re-reads on theme
+* switch via the addon's `ThemeContext`. Returns `{ value, cssVar, type,
+* description }`.
+*
+* Typed paths appear automatically once `.swatchbook/tokens.d.ts` is
+* generated (happens on first storybook start/build). Until then
+* `TokenPath` is `string`.
+*
+* Safe to call in autodocs / MDX renders — uses plain React context, not
+* Storybook's preview-only hooks.
+*/
+function useToken(path) {
+	const token = (themesResolved[useActiveTheme() || (defaultTheme ?? "")] ?? {})[path];
+	const info = {
+		value: token?.$value,
+		cssVar: makeCssVar(path, cssVarPrefix)
+	};
+	if (token?.$type) info.type = token.$type;
+	if (token?.$description) info.description = token.$description;
+	return info;
+}
+//#endregion
+export { useToken };
+
+//# sourceMappingURL=index.mjs.map

package/dist/hooks/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/hooks/use-token.ts"],"sourcesContent":["import { cssVarPrefix, defaultTheme, themesResolved } from 'virtual:swatchbook/tokens';\nimport { useActiveTheme } from '@unpunnyfuns/swatchbook-blocks';\n\n/**\n * Consumers augment this interface (via the addon's generated\n * `.swatchbook/tokens.d.ts`) to narrow {@link useToken}'s first parameter\n * to their project's actual token paths. Without augmentation it's empty\n * and {@link TokenPath} falls back to `string`.\n */\nexport interface SwatchbookTokenMap {}\n\ntype KnownPath = keyof SwatchbookTokenMap;\n\n/** Union of known token paths, or `string` when the addon codegen hasn't run. */\nexport type TokenPath = [KnownPath] extends [never] ? string : KnownPath;\n\nexport interface TokenInfo {\n  /** The resolved DTCG `$value`. Shape varies by `$type`. */\n  value: unknown;\n  /** `var(--prefix-token-path)` reference, ready to drop into any CSS value. */\n  cssVar: string;\n  /** DTCG `$type` of the token, if known. */\n  type?: string;\n  /** Optional DTCG `$description`. */\n  description?: string;\n}\n\nfunction makeCssVar(path: string, prefix: string): string {\n  const tail = path.replaceAll('.', '-');\n  return prefix ? `var(--${prefix}-${tail})` : `var(--${tail})`;\n}\n\n/**\n * Read a DTCG token for the currently active theme. Re-reads on theme\n * switch via the addon's `ThemeContext`. Returns `{ value, cssVar, type,\n * description }`.\n *\n * Typed paths appear automatically once `.swatchbook/tokens.d.ts` is\n * generated (happens on first storybook start/build). Until then\n * `TokenPath` is `string`.\n *\n * Safe to call in autodocs / MDX renders — uses plain React context, not\n * Storybook's preview-only hooks.\n */\nexport function useToken(path: TokenPath): TokenInfo {\n  const contextTheme = useActiveTheme();\n  const themeName = contextTheme || (defaultTheme ?? '');\n  const tokens = themesResolved[themeName] ?? {};\n  const token = tokens[path];\n  const info: TokenInfo = {\n    value: token?.$value,\n    cssVar: makeCssVar(path, cssVarPrefix),\n  };\n  if (token?.$type) info.type = token.$type;\n  if (token?.$description) info.description = token.$description;\n  return info;\n}\n"],"mappings":";;;AA2BA,SAAS,WAAW,MAAc,QAAwB;CACxD,MAAM,OAAO,KAAK,WAAW,KAAK,IAAI;AACtC,QAAO,SAAS,SAAS,OAAO,GAAG,KAAK,KAAK,SAAS,KAAK;;;;;;;;;;;;;;AAe7D,SAAgB,SAAS,MAA4B;CAInD,MAAM,SADS,eAFM,gBAAgB,KACF,gBAAgB,QACP,EAAE,EACzB;CACrB,MAAM,OAAkB;EACtB,OAAO,OAAO;EACd,QAAQ,WAAW,MAAM,aAAa;EACvC;AACD,KAAI,OAAO,MAAO,MAAK,OAAO,MAAM;AACpC,KAAI,OAAO,aAAc,MAAK,cAAc,MAAM;AAClD,QAAO"}

package/dist/index.d.mts

@@ -0,0 +1,22 @@
+import { t as AddonOptions } from "./options-rvGQy0uV.mjs";
+import { definePreviewAddon } from "storybook/internal/csf";
+
+//#region src/constants.d.ts
+declare const ADDON_ID = "swatchbook";
+declare const PARAM_KEY = "swatchbook";
+/** Canonical active-theme global: composed permutation ID (string). Read by toolbar, panel, blocks. */
+declare const GLOBAL_KEY = "swatchbookTheme";
+/** Tuple companion: `Record<axisName, contextName>`. Optional — when present, takes precedence over the string global. */
+declare const AXES_GLOBAL_KEY = "swatchbookAxes";
+declare const VIRTUAL_MODULE_ID = "virtual:swatchbook/tokens";
+//#endregion
+//#region src/index.d.ts
+/**
+ * CSF Next factory. Consumers call this inside
+ * `definePreview({ addons: [swatchbookAddon()] })` so the preview annotations
+ * (decorator, globalTypes, initialGlobals) are added to the preview bundle.
+ */
+declare function swatchbookAddon(): ReturnType<typeof definePreviewAddon>;
+//#endregion
+export { ADDON_ID, AXES_GLOBAL_KEY, type AddonOptions, GLOBAL_KEY, PARAM_KEY, VIRTUAL_MODULE_ID, swatchbookAddon as default };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,16 @@
+import { i as preview_exports } from "./preview-DcMFt0cD.mjs";
+import { a as GLOBAL_KEY, c as PARAM_KEY, f as VIRTUAL_MODULE_ID, n as AXES_GLOBAL_KEY, t as ADDON_ID } from "./constants-1plfdgh7.mjs";
+import { definePreviewAddon } from "storybook/internal/csf";
+//#region src/index.ts
+/**
+* CSF Next factory. Consumers call this inside
+* `definePreview({ addons: [swatchbookAddon()] })` so the preview annotations
+* (decorator, globalTypes, initialGlobals) are added to the preview bundle.
+*/
+function swatchbookAddon() {
+	return definePreviewAddon(preview_exports);
+}
+//#endregion
+export { ADDON_ID, AXES_GLOBAL_KEY, GLOBAL_KEY, PARAM_KEY, VIRTUAL_MODULE_ID, swatchbookAddon as default };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["previewExports"],"sources":["../src/index.ts"],"sourcesContent":["import { definePreviewAddon } from 'storybook/internal/csf';\nimport * as previewExports from './preview.tsx';\n\nexport {\n  ADDON_ID,\n  AXES_GLOBAL_KEY,\n  GLOBAL_KEY,\n  PARAM_KEY,\n  VIRTUAL_MODULE_ID,\n} from '#/constants.ts';\nexport type { AddonOptions } from '#/options.ts';\n\n/**\n * CSF Next factory. Consumers call this inside\n * `definePreview({ addons: [swatchbookAddon()] })` so the preview annotations\n * (decorator, globalTypes, initialGlobals) are added to the preview bundle.\n */\nexport default function swatchbookAddon(): ReturnType<typeof definePreviewAddon> {\n  return definePreviewAddon(previewExports);\n}\n"],"mappings":";;;;;;;;;AAiBA,SAAwB,kBAAyD;AAC/E,QAAO,mBAAmBA,gBAAe"}

package/dist/manager.d.mts

@@ -0,0 +1 @@
+export { };