@kiva/kv-tokens 4.0.0-next.0 → 4.0.0

package/README.md

@@ -18,10 +18,10 @@ import designTokens from '@kiva/kv-tokens';
 const primaryTextColor = designTokens.colors.theme.DEFAULT.text.primary;
 ```
 
-You can also import the generated tokens module directly (flat named exports plus the nested default):
+You can also import the generated JS module directly (flat named exports plus the nested default):
 
 ```js
-import tokens, { colorBrandDefault } from '@kiva/kv-tokens/tokens';
+import tokens, { colorBrandDefault } from '@kiva/kv-tokens/js';
 ```
 
 ## Using the Tailwind Preset
@@ -59,11 +59,54 @@ Our Tailwind config has some differences to the standard install. Notably
 | Subpath                        | Resolves to                 | Use for                                   |
 | ------------------------------ | --------------------------- | ----------------------------------------- |
 | `@kiva/kv-tokens`              | `index.js`                  | Default: tokens object + theme/tailwind helpers |
-| `@kiva/kv-tokens/tokens`       | `dist/js/tokens.js`         | Generated JS tokens (flat + nested)       |
+| `@kiva/kv-tokens/tokens`       | `dist/dtcg/tokens.json`     | Single merged DTCG source manifest (aliases preserved) |
+| `@kiva/kv-tokens/tokens/*`     | `tokens/*`                  | Individual DTCG source files              |
 | `@kiva/kv-tokens/tailwind`     | `configs/tailwind.config.js`| Tailwind preset                           |
+| `@kiva/kv-tokens/js`           | `dist/js/tokens.js`         | Generated JS tokens (flat + nested)       |
 | `@kiva/kv-tokens/css`          | `dist/css/tokens.css`       | Themed CSS custom properties              |
 | `@kiva/kv-tokens/scss`         | `dist/scss/tokens.scss`     | SCSS `$variable` map                      |
 
+## Importing Source Tokens
+
+The `./tokens` subpath exports the design tokens **as authored** in [W3C DTCG](https://design-tokens.github.io/community-group/format/) format, with aliases (e.g. `"{color.brand.DEFAULT}"`), `$type`, and `$description` metadata preserved. This is the canonical source for downstream tooling that wants the untransformed shape:
+
+-   Figma plugins / Tokens Studio / Specify and other DTCG-native tools
+-   Alternative build pipelines (e.g. a mobile app using a different token transform)
+-   Drift-detection scripts comparing an external export against our source of truth
+-   Documentation generators and agent reference material that reason about token intent
+
+### Single merged manifest
+
+```js
+import tokens from '@kiva/kv-tokens/tokens' with { type: 'json' };
+
+tokens.color.brand.DEFAULT;         // { $type: 'color', $value: '#2AA967' }
+tokens.theme.DEFAULT.text.primary;  // { $type: 'color', $value: '#223829' }
+```
+
+The manifest is produced by [`build/build-dtcg.js`](build/build-dtcg.js), which deep-merges every source file under [`tokens/`](tokens/) and errors if two files define a leaf at the same path.
+
+### Individual source files
+
+```js
+import coreColors from '@kiva/kv-tokens/tokens/core/color.json' with { type: 'json' };
+import defaultTheme from '@kiva/kv-tokens/tokens/semantic/themes/default.json' with { type: 'json' };
+```
+
+Or read them off disk from `node_modules/@kiva/kv-tokens/tokens/…` — useful for skill files and other tools that prefer file paths over module imports.
+
+**Note on stability:** once shipped, the on-disk layout of `tokens/` (directory names, file names) is part of this package's public contract. Reorganizing it is a breaking change.
+
+For the transformed, resolved-values-with-code-facing-names shape used by component code, prefer the default export of `@kiva/kv-tokens` or the flat-and-nested `@kiva/kv-tokens/js` module.
+
+## Local Development
+
+The `dist/` directory is gitignored but regenerated automatically by the `prepare` lifecycle script whenever you run `npm install` — both at the monorepo root and inside this package. After a fresh clone, `npm install` leaves `dist/` ready to use, so downstream workspace packages like [`@kiva/kv-components`](../kv-components/) can consume tokens without a separate build step.
+
+The same `prepare` hook runs before `npm publish` (and `lerna publish`), so published tarballs always contain a fresh `dist/`.
+
+If you edit a token source file during development, rerun `npm run build` to regenerate `dist/`. See [Editing Tokens](#editing-tokens) below.
+
 ## Editing Tokens
 
 Tokens live under [`tokens/`](tokens/) as DTCG JSON:

package/build/build-dtcg.js

@@ -0,0 +1,31 @@
+// Emits dist/dtcg/tokens.json — a single deep-merged DTCG manifest of every
+// source token under tokens/. Aliases (e.g. "{color.brand.DEFAULT}") and
+// $type/$description metadata are preserved verbatim so external consumers
+// (Figma plugins, alternative build pipelines, agent reference docs) get
+// the canonical authored shape, not a transformed view of it.
+
+import {
+	mkdirSync, readFileSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { findJsonFiles, mergeTokens } from './dtcg-merge.js';
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const TOKENS_DIR = join(PACKAGE_ROOT, 'tokens');
+const OUT_DIR = join(PACKAGE_ROOT, 'dist', 'dtcg');
+const OUT_FILE = join(OUT_DIR, 'tokens.json');
+
+const files = findJsonFiles(TOKENS_DIR);
+const sources = files.map((path) => ({
+	path: relative(PACKAGE_ROOT, path),
+	contents: JSON.parse(readFileSync(path, 'utf8')),
+}));
+
+const merged = mergeTokens(sources);
+
+mkdirSync(OUT_DIR, { recursive: true });
+writeFileSync(OUT_FILE, `${JSON.stringify(merged, null, '\t')}\n`, 'utf8');
+
+process.stdout.write(`dtcg: wrote ${relative(PACKAGE_ROOT, OUT_FILE)} from ${files.length} source files\n`);

package/build/dtcg-merge.js

@@ -0,0 +1,60 @@
+// Pure merge logic for the raw DTCG manifest. Kept side-effect free so the
+// CLI wrapper (build-dtcg.js) and the test suite share the same code path.
+
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const isLeaf = (node) => node && typeof node === 'object' && '$value' in node;
+
+export function findJsonFiles(rootDir) {
+	const out = [];
+	const walk = (dir) => {
+		readdirSync(dir).forEach((entry) => {
+			const full = join(dir, entry);
+			if (statSync(full).isDirectory()) {
+				walk(full);
+			} else if (entry.endsWith('.json')) {
+				out.push(full);
+			}
+		});
+	};
+	walk(rootDir);
+	return out.sort();
+}
+
+// Deep-merges DTCG token sources into a single object. Throws if two source
+// files both define a leaf at the same path — the canonical source must not
+// have ambiguous duplicates.
+export function mergeTokens(sources) {
+	const out = {};
+	const provenance = new Map();
+
+	const walk = (node, path, fromFile) => {
+		if (isLeaf(node)) {
+			const pathKey = path.join('.');
+			if (provenance.has(pathKey)) {
+				throw new Error(
+					`Leaf token collision at "${pathKey}" — defined in both `
+					+ `${provenance.get(pathKey)} and ${fromFile}`,
+				);
+			}
+			let cursor = out;
+			for (let i = 0; i < path.length - 1; i += 1) {
+				cursor[path[i]] = cursor[path[i]] ?? {};
+				cursor = cursor[path[i]];
+			}
+			cursor[path[path.length - 1]] = node;
+			provenance.set(pathKey, fromFile);
+			return;
+		}
+		if (node && typeof node === 'object' && !Array.isArray(node)) {
+			Object.keys(node).forEach((key) => walk(node[key], [...path, key], fromFile));
+		}
+	};
+
+	sources.forEach(({ path, contents }) => {
+		walk(contents, [], path);
+	});
+
+	return out;
+}

package/build/dtcg-merge.test.js

@@ -0,0 +1,140 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+
+import { mergeTokens } from './dtcg-merge.js';
+
+test('merges disjoint top-level keys from multiple sources', () => {
+	const result = mergeTokens([
+		{
+			path: 'a.json',
+			contents: { color: { red: { $type: 'color', $value: '#f00' } } },
+		},
+		{
+			path: 'b.json',
+			contents: {
+				space: { 1: { $type: 'dimension', $value: { value: 4, unit: 'px' } } },
+			},
+		},
+	]);
+
+	assert.equal(result.color.red.$value, '#f00');
+	assert.equal(result.space[1].$value.value, 4);
+});
+
+test('merges nested keys at the same branch without collision', () => {
+	const result = mergeTokens([
+		{
+			path: 'theme-default.json',
+			contents: {
+				theme: { DEFAULT: { text: { primary: { $type: 'color', $value: '#000' } } } },
+			},
+		},
+		{
+			path: 'theme-dark.json',
+			contents: {
+				theme: { dark: { text: { primary: { $type: 'color', $value: '#fff' } } } },
+			},
+		},
+	]);
+
+	assert.equal(result.theme.DEFAULT.text.primary.$value, '#000');
+	assert.equal(result.theme.dark.text.primary.$value, '#fff');
+});
+
+test('preserves alias references as literal strings', () => {
+	const result = mergeTokens([
+		{
+			path: 'core.json',
+			contents: { color: { brand: { $type: 'color', $value: '#2AA967' } } },
+		},
+		{
+			path: 'semantic.json',
+			contents: {
+				theme: { DEFAULT: { primary: { $type: 'color', $value: '{color.brand}' } } },
+			},
+		},
+	]);
+
+	assert.equal(result.theme.DEFAULT.primary.$value, '{color.brand}');
+});
+
+test('preserves $type and $description metadata', () => {
+	const result = mergeTokens([
+		{
+			path: 'a.json',
+			contents: {
+				color: {
+					red: {
+						$type: 'color',
+						$value: '#f00',
+						$description: 'danger signal',
+					},
+				},
+			},
+		},
+	]);
+
+	assert.equal(result.color.red.$type, 'color');
+	assert.equal(result.color.red.$description, 'danger signal');
+});
+
+test('preserves dimension $value object shape (does not unwrap)', () => {
+	const result = mergeTokens([
+		{
+			path: 'a.json',
+			contents: {
+				space: { 1: { $type: 'dimension', $value: { value: 4, unit: 'px' } } },
+			},
+		},
+	]);
+
+	assert.deepEqual(result.space[1].$value, { value: 4, unit: 'px' });
+});
+
+test('throws on leaf collision with both source paths in the message', () => {
+	assert.throws(
+		() => mergeTokens([
+			{
+				path: 'a.json',
+				contents: { color: { brand: { $type: 'color', $value: '#000' } } },
+			},
+			{
+				path: 'b.json',
+				contents: { color: { brand: { $type: 'color', $value: '#fff' } } },
+			},
+		]),
+		(err) => {
+			assert.match(err.message, /collision/);
+			assert.match(err.message, /color\.brand/);
+			assert.match(err.message, /a\.json/);
+			assert.match(err.message, /b\.json/);
+			return true;
+		},
+	);
+});
+
+test('leaves $value untouched when it is the literal string "0"', () => {
+	// Guard against a naive `!$value` check treating falsy values as missing.
+	const result = mergeTokens([
+		{
+			path: 'a.json',
+			contents: { opacity: { none: { $type: 'opacity', $value: 0 } } },
+		},
+	]);
+
+	assert.equal(result.opacity.none.$value, 0);
+});
+
+test('returns an empty object for empty input', () => {
+	assert.deepEqual(mergeTokens([]), {});
+});
+
+test('merges three sources sharing the same branch', () => {
+	const result = mergeTokens([
+		{ path: 'a.json', contents: { color: { a: { $type: 'color', $value: '#a' } } } },
+		{ path: 'b.json', contents: { color: { b: { $type: 'color', $value: '#b' } } } },
+		{ path: 'c.json', contents: { color: { c: { $type: 'color', $value: '#c' } } } },
+	]);
+
+	assert.deepEqual(Object.keys(result.color).sort(), ['a', 'b', 'c']);
+});