@phcdevworks/spectre-tokens 2.1.1 → 2.2.0

package/README.md

@@ -18,8 +18,8 @@ translate those contracts for specific frameworks and runtimes.
 ## Key capabilities
 
 - Uses `tokens/` as the source of truth for design-token data
-- Generates JavaScript, TypeScript, Tailwind, and CSS outputs from shared token
-  sources
+- Generates JavaScript, TypeScript, CSS, and Tailwind theme exports from shared
+  token sources
 - Defines semantic token contracts for surfaces, text, components, buttons,
   forms, and modes
 - Exposes primitives and semantic roles for downstream packages and compatible
@@ -80,8 +80,8 @@ access is appropriate.
 
 - Visual language expressed as token data in `tokens/`
 - Semantic roles and token contracts consumed downstream
-- Generated token outputs for JavaScript, TypeScript, Tailwind, and CSS
-  variables
+- Generated token outputs for JavaScript, TypeScript, CSS variables, and
+  Tailwind theme exports
 - Theme and mode definitions used by downstream consumers
 
 ### Token model
@@ -109,6 +109,10 @@ The generated token object includes these namespaces:
 - `component`
 - `modes`
 
+The exported runtime token object is a flattened string-based tree generated
+from `tokens/`. Source-only wrapper fields such as `value` and `metadata` are
+internal generation details and are not part of the public package contract.
+
 ### Themes and modes
 
 The package includes mode-aware semantic tokens under `modes`, with `default`
@@ -181,7 +185,7 @@ Regenerate package outputs:
 npm run build
 ```
 
-Run validation checks:
+Run the full validation and release gate:
 
 ```bash
 npm run check
@@ -195,6 +199,10 @@ Key source areas:
 - `scripts/` for build and validation scripts
 - `example/` for usage examples
 
+The files in `example/` are illustrative token demos only. They help explain
+the token contract, but they are not the package contract itself and should not
+be treated as downstream UI primitives.
+
 ## Contributing
 
 PHCDevworks maintains this package as part of the Spectre system.
@@ -204,7 +212,9 @@ When contributing:
 - treat `tokens/` as the source of truth
 - keep generated outputs derived from source data
 - avoid breaking token contracts without an intentional major-version change
-- run `npm run build` and `npm run check` before opening a pull request
+- run `npm run build` to regenerate outputs when sources change
+- run `npm run check` as the full validation gate before opening a pull request
+- do not modify locked semantic color families without explicit approval
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.