@kiva/kv-tokens 4.0.0-next.1 → 4.0.1

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: