@phcdevworks/spectre-tokens 2.2.0 → 2.3.0

package/README.md

@@ -27,6 +27,27 @@ translate those contracts for specific frameworks and runtimes.
 - Keeps visual meaning centralized so downstream consumers do not redefine token
   contracts
 
+## What this package owns
+
+- Visual language expressed as token data in `tokens/`
+- Semantic roles and token contracts consumed downstream
+- Generated token outputs for JavaScript, TypeScript, CSS variables, and
+  Tailwind theme exports
+- Theme and mode definitions used by downstream consumers
+
+This package is the correct place to define token meaning.
+
+## What this package does not own
+
+- Component structure or composition That belongs in downstream UI packages such
+  as [`@phcdevworks/spectre-ui`](https://github.com/phcdevworks/spectre-ui).
+- Framework-specific delivery Adapter packages translate Spectre contracts for
+  specific frameworks and runtimes.
+- Local redefinition of token meaning Downstream consumers should consume these
+  contracts rather than recreate them independently.
+- Example app architecture The `example/` directory documents token usage; it is
+  not the contract source and should not become a downstream UI layer.
+
 ## Installation
 
 ```bash
@@ -72,17 +93,103 @@ export default {
 }
 ```
 
-Prefer semantic tokens such as `surface`, `text`, `component`, `buttons`, and
-`forms` for application UI. Raw palette values remain available when fixed color
-access is appropriate.
+## Consumer usage
 
-## What this package owns
+### Source of truth
 
-- Visual language expressed as token data in `tokens/`
-- Semantic roles and token contracts consumed downstream
-- Generated token outputs for JavaScript, TypeScript, CSS variables, and
-  Tailwind theme exports
-- Theme and mode definitions used by downstream consumers
+- Change token data in `tokens/`.
+- Treat generated outputs as derived artifacts.
+- Treat `contract.manifest.json` as the machine-readable contract authority for
+  public namespaces and required outputs.
+
+### JavaScript and TypeScript tokens
+
+Use the runtime token object when a consumer needs token values directly in
+code.
+
+```ts
+import tokens from '@phcdevworks/spectre-tokens'
+
+const card = {
+  background: tokens.surface.card,
+  color: tokens.text.onSurface.default,
+  borderColor: tokens.component.iconBox.border,
+  padding: tokens.space['16']
+}
+```
+
+Use named exports when you need generated helpers or Tailwind integration:
+
+```ts
+import tokens, {
+  generateCssVariables,
+  tailwindPreset,
+  tailwindTheme
+} from '@phcdevworks/spectre-tokens'
+
+const css = generateCssVariables(tokens)
+```
+
+### Generated CSS variables
+
+Import `index.css` when a downstream package or app wants the generated Spectre
+CSS variable contract.
+
+```css
+@import '@phcdevworks/spectre-tokens/index.css';
+
+.card {
+  background: var(--sp-surface-card);
+  color: var(--sp-text-on-surface-default);
+}
+```
+
+The CSS entry point is intended for consumers that want the token contract as
+variables rather than reading values in JavaScript.
+
+### Tailwind preset
+
+Use the Tailwind preset when a consumer wants Tailwind theme values derived from
+the same token contract.
+
+```ts
+import { tailwindPreset } from '@phcdevworks/spectre-tokens'
+
+export default {
+  presets: [tailwindPreset]
+}
+```
+
+Use `tailwindTheme` directly only when a consumer needs the generated theme
+object outside the preset shape.
+
+### Semantic tokens first
+
+Prefer semantic namespaces for downstream UI work:
+
+- `surface`
+- `text`
+- `component`
+- `buttons`
+- `forms`
+- `modes`
+
+These namespaces are the main consumer-facing contract because they express UI
+meaning rather than raw color selection.
+
+### When raw palette access is acceptable
+
+Raw palette access through `colors` is acceptable when a consumer deliberately
+needs fixed palette values.
+
+Typical cases:
+
+- data visualization or non-semantic decorative use
+- compatibility layers that need a specific raw ramp
+- tooling that inspects or serializes palette data directly
+
+Raw palette access should not replace semantic token usage for normal UI
+surfaces, text, buttons, forms, or mode-aware styling.
 
 ### Token model
 
@@ -100,6 +207,8 @@ The generated token object includes these namespaces:
 - `transitions`
 - `animations`
 - `opacity`
+- `aspectRatios`
+- `icons`
 - `border`
 - `accessibility`
 - `buttons`
@@ -113,23 +222,74 @@ 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.
 
+## Public contract guarantees
+
+`contract.manifest.json` is the machine-readable contract authority for this
+package.
+
+It defines:
+
+- public namespaces
+- required output surfaces for JavaScript, CSS, and Tailwind
+- protected semantic groups
+
+Every contract-facing surface in this repository must match that manifest.
+Validation fails fast on token overwrite across files, undocumented namespaces,
+output drift, and README mismatch with the contract authority.
+
 ### Themes and modes
 
 The package includes mode-aware semantic tokens under `modes`, with `default`
 and `dark` mode definitions in the generated output.
 
-Raw palette tokens are stable values. Semantic tokens are the preferred
-interface for theme-aware usage because they can map across modes without
-changing consumer code.
+Use semantic mode-aware values when the consumer needs light/dark or
+mode-specific behavior without branching on raw palette values.
 
-## What this package does not own
+```ts
+import tokens from '@phcdevworks/spectre-tokens'
 
-- Component structure or composition That belongs in downstream UI packages such
-  as [`@phcdevworks/spectre-ui`](https://github.com/phcdevworks/spectre-ui).
-- Framework-specific delivery Adapter packages translate Spectre contracts for
-  specific frameworks and runtimes.
-- Local redefinition of token meaning Downstream consumers should consume these
-  contracts rather than recreate them independently.
+const darkPage = tokens.modes.dark.surface.page
+const darkText = tokens.modes.dark.text.onPage.default
+```
+
+Guidance:
+
+- Prefer semantic tokens for theme-aware UI.
+- Prefer `modes` when a consumer explicitly needs mode-specific values.
+- Do not invent local light/dark token contracts when this package already
+  provides the semantic path.
+
+## Downstream boundaries
+
+Downstream packages should never redefine locally:
+
+- the meaning of `surface`, `text`, `component`, `buttons`, `forms`, or `modes`
+- protected semantic groups such as `success`, `warning`, `danger`, or CTA /
+  brand-action semantics
+- public namespace shape that this package already exports
+
+Downstream packages may:
+
+- compose UI structure on top of this contract
+- map these tokens into framework-specific delivery
+- use raw palette values when the usage is intentionally non-semantic
+
+## Upgrade expectations for consumers
+
+Consumers should treat this package as a SemVer-governed contract.
+
+Practical guidance:
+
+- additive token paths are intended to be safe for existing consumers
+- semantic shifts may keep the same path but still affect visual meaning
+- renames and removals are breaking
+- generated JS, TS, CSS, and Tailwind outputs are expected to stay aligned
+
+If a downstream package depends on specific token paths or semantic meaning:
+
+- read `CHANGELOG.md` for contract change classification
+- read `TOKEN_CONTRACT.md` for contract rules
+- prefer documented public namespaces over undocumented internal assumptions
 
 ## Package exports / API surface
 
@@ -140,7 +300,7 @@ changing consumer code.
 - `default` / `tokens`
 - `tailwindTheme`
 - `tailwindPreset`
-- `generateCssVariables()`
+- `generateCssVariables`
 - TypeScript types including `SpectreTokens`, `TailwindTheme`,
   `SpectreModeTokens`, and `SpectreModeName`
 
@@ -177,6 +337,18 @@ Spectre keeps responsibilities separate:
 That separation keeps token meaning centralized while letting the package system
 expand by responsibility.
 
+## Consumer checklist
+
+For downstream packages and compatible apps:
+
+- import tokens from the package root when you need runtime values
+- import `index.css` when you need generated CSS variables
+- use `tailwindPreset` when you need Tailwind theme integration
+- prefer semantic namespaces for UI behavior
+- use raw palette values only when fixed palette access is intentional
+- treat `tokens/` as source of truth and generated outputs as derived
+- do not redefine Spectre semantic contracts locally
+
 ## Development
 
 Regenerate package outputs:
@@ -199,9 +371,9 @@ 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.
+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
 
@@ -215,6 +387,7 @@ When contributing:
 - 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
+- keep `README.md`, generated outputs, and `contract.manifest.json` aligned
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
 

package/dist/index.cjs

@@ -75,7 +75,7 @@ var coreTokens = {
       "text": "{colors.neutral.700}",
       "authorName": "{colors.neutral.900}",
       "authorTitle": "{colors.neutral.500}",
-      "quoteMark": "{colors.neutral.300}"
+      "quoteMark": "{colors.neutral.500}"
     },
     "pricingCard": {
       "bg": "{colors.white}",
@@ -103,7 +103,7 @@ var coreTokens = {
       "text": "{colors.white}",
       "textDisabled": "{colors.neutral.400}",
       "focusRing": "{colors.info.500} / 0.4",
-      "focusVisible": "{buttons.primary.focusRing}"
+      "focusVisible": "{colors.info.500} / 0.4"
     },
     "secondary": {
       "bg": "{colors.white}",
@@ -115,7 +115,7 @@ var coreTokens = {
       "border": "{colors.info.700}",
       "borderDisabled": "{colors.neutral.200}",
       "focusRing": "{colors.info.500} / 0.4",
-      "focusVisible": "{buttons.secondary.focusRing}"
+      "focusVisible": "{colors.info.500} / 0.4"
     },
     "ghost": {
       "bg": "transparent",
@@ -125,7 +125,7 @@ var coreTokens = {
       "text": "{colors.info.700}",
       "textDisabled": "{colors.neutral.400}",
       "focusRing": "{colors.info.500} / 0.4",
-      "focusVisible": "{buttons.ghost.focusRing}"
+      "focusVisible": "{colors.info.500} / 0.4"
     },
     "danger": {
       "bg": "{colors.error.600}",
@@ -163,7 +163,7 @@ var coreTokens = {
       "text": "{colors.white}",
       "textDisabled": "{colors.neutral.400}",
       "focusRing": "{colors.accent.500} / 0.4",
-      "focusVisible": "{buttons.accent.focusRing}"
+      "focusVisible": "{colors.accent.500} / 0.4"
     }
   },
   "forms": {
@@ -181,8 +181,8 @@ var coreTokens = {
       "ring": "{colors.info.500}"
     },
     "focusVisible": {
-      "border": "{forms.focus.border}",
-      "ring": "{forms.focus.ring}"
+      "border": "{colors.info.500}",
+      "ring": "{colors.info.500}"
     },
     "valid": {
       "border": "{colors.success.500}",
@@ -295,7 +295,7 @@ var coreTokens = {
         "input": "{colors.neutral.700}",
         "overlay": "{colors.neutral.800}",
         "alternate": "{colors.neutral.800}",
-        "hero": "linear-gradient(135deg, {colors.accent.900} 0%, {colors.accent.700} 100%)"
+        "hero": "linear-gradient(135deg, {colors.accent.700} 0%, {colors.accent.900} 100%)"
       },
       "text": {
         "onPage": {
@@ -679,7 +679,8 @@ var coreTokens = {
     "xs": {
       "size": "0.75rem",
       "lineHeight": "1.25rem",
-      "weight": 400
+      "weight": 400,
+      "letterSpacing": "0.02em"
     },
     "sm": {
       "size": "0.875rem",
@@ -863,6 +864,10 @@ var createCssVariableMap = (tokens2, options = {}) => {
     map[name] = resolveValue(tokens2, value);
   };
   Object.entries(baseTokens.colors).forEach(([group, scale]) => {
+    if (typeof scale === "string" || typeof scale === "number") {
+      assign(toVariableName(prefix, "color", group), scale);
+      return;
+    }
     Object.entries(scale).forEach(([step, value]) => {
       assign(toVariableName(prefix, "color", group, step), value);
     });
@@ -1028,15 +1033,18 @@ var generateCssVariables = (tokens2, options = {}) => {
   addBase(toVariableName(prefix, "surface", "card"), pickSemantic(tokens2, getPath(defaultMode, ["surface", "card"]), getPath(surfaceAliases, ["card"])));
   addBase(toVariableName(prefix, "surface", "input"), pickSemantic(tokens2, getPath(defaultMode, ["surface", "input"]), getPath(surfaceAliases, ["input"])));
   addBase(toVariableName(prefix, "surface", "overlay"), pickSemantic(tokens2, getPath(defaultMode, ["surface", "overlay"]), getPath(surfaceAliases, ["overlay"])));
+  addBase(toVariableName(prefix, "surface", "alternate"), pickSemantic(tokens2, getPath(defaultMode, ["surface", "alternate"])));
   addBase(toVariableName(prefix, "surface", "hero"), pickSemantic(tokens2, getPath(defaultMode, ["surface", "hero"]), getPath(surfaceAliases, ["hero"])));
   addBase(toVariableName(prefix, "text", "on", "page", "default"), pickSemantic(tokens2, getPath(defaultMode, ["text", "onPage", "default"]), getPath(textAliases, ["onPage", "default"])));
   addBase(toVariableName(prefix, "text", "on", "page", "muted"), pickSemantic(tokens2, getPath(defaultMode, ["text", "onPage", "muted"]), getPath(textAliases, ["onPage", "muted"])));
   addBase(toVariableName(prefix, "text", "on", "page", "subtle"), pickSemantic(tokens2, getPath(defaultMode, ["text", "onPage", "subtle"]), getPath(textAliases, ["onPage", "subtle"])));
   addBase(toVariableName(prefix, "text", "on", "page", "meta"), pickSemantic(tokens2, getPath(defaultMode, ["text", "onPage", "meta"]), getPath(textAliases, ["onPage", "meta"])));
+  addBase(toVariableName(prefix, "text", "on", "page", "brand"), pickSemantic(tokens2, getPath(defaultMode, ["text", "onPage", "brand"]), getPath(textAliases, ["onPage", "brand"])));
   addBase(toVariableName(prefix, "text", "on", "surface", "default"), pickSemantic(tokens2, getPath(defaultMode, ["text", "onSurface", "default"]), getPath(textAliases, ["onSurface", "default"])));
   addBase(toVariableName(prefix, "text", "on", "surface", "muted"), pickSemantic(tokens2, getPath(defaultMode, ["text", "onSurface", "muted"]), getPath(textAliases, ["onSurface", "muted"])));
   addBase(toVariableName(prefix, "text", "on", "surface", "subtle"), pickSemantic(tokens2, getPath(defaultMode, ["text", "onSurface", "subtle"]), getPath(textAliases, ["onSurface", "subtle"])));
   addBase(toVariableName(prefix, "text", "on", "surface", "meta"), pickSemantic(tokens2, getPath(defaultMode, ["text", "onSurface", "meta"]), getPath(textAliases, ["onSurface", "meta"])));
+  addBase(toVariableName(prefix, "text", "on", "surface", "brand"), pickSemantic(tokens2, getPath(defaultMode, ["text", "onSurface", "brand"]), getPath(textAliases, ["onSurface", "brand"])));
   addBase(toVariableName(prefix, "component", "card", "text"), pickSemantic(tokens2, getPath(defaultMode, ["component", "card", "text"]), getPath(componentAliases, ["card", "text"])));
   addBase(toVariableName(prefix, "component", "card", "text-muted"), pickSemantic(tokens2, getPath(defaultMode, ["component", "card", "textMuted"]), getPath(componentAliases, ["card", "textMuted"])));
   addBase(toVariableName(prefix, "component", "input", "text"), pickSemantic(tokens2, getPath(defaultMode, ["component", "input", "text"]), getPath(componentAliases, ["input", "text"])));
@@ -1080,6 +1088,10 @@ var generateCssVariables = (tokens2, options = {}) => {
     toVariableName(prefix, "surface", "overlay"),
     pickSemantic(tokens2, getPath(darkMode, ["surface", "overlay"]), getPath(defaultMode, ["surface", "overlay"]), getPath(surfaceAliases, ["overlay"]))
   );
+  addDark(
+    toVariableName(prefix, "surface", "alternate"),
+    pickSemantic(tokens2, getPath(darkMode, ["surface", "alternate"]), getPath(defaultMode, ["surface", "alternate"]))
+  );
   addDark(
     toVariableName(prefix, "surface", "hero"),
     pickSemantic(tokens2, getPath(darkMode, ["surface", "hero"]), getPath(defaultMode, ["surface", "hero"]), getPath(surfaceAliases, ["hero"]))
@@ -1120,6 +1132,15 @@ var generateCssVariables = (tokens2, options = {}) => {
       getPath(textAliases, ["onPage", "meta"])
     )
   );
+  addDark(
+    toVariableName(prefix, "text", "on", "page", "brand"),
+    pickSemantic(
+      tokens2,
+      getPath(darkMode, ["text", "onPage", "brand"]),
+      getPath(defaultMode, ["text", "onPage", "brand"]),
+      getPath(textAliases, ["onPage", "brand"])
+    )
+  );
   addDark(
     toVariableName(prefix, "text", "on", "surface", "default"),
     pickSemantic(
@@ -1156,6 +1177,15 @@ var generateCssVariables = (tokens2, options = {}) => {
       getPath(textAliases, ["onSurface", "meta"])
     )
   );
+  addDark(
+    toVariableName(prefix, "text", "on", "surface", "brand"),
+    pickSemantic(
+      tokens2,
+      getPath(darkMode, ["text", "onSurface", "brand"]),
+      getPath(defaultMode, ["text", "onSurface", "brand"]),
+      getPath(textAliases, ["onSurface", "brand"])
+    )
+  );
   addDark(
     toVariableName(prefix, "component", "card", "text"),
     pickSemantic(