@helixui/tokens 3.9.0-next.150 → 3.9.0-next.154

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +39 -30
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  **Design tokens for the HELiX component library** — a structured set of CSS custom properties, JavaScript constants, and Lit CSS utilities that power the `@helixui/library` components.
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@helixui/tokens)](https://www.npmjs.com/package/@helixui/tokens)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
7
7
 
8
8
  ---
9
9
 
@@ -21,40 +21,43 @@ npm install @helixui/tokens
21
21
 
22
22
  ### JavaScript / TypeScript (token constants)
23
23
 
24
+ The default entry exports the nested token JSON plus the flattened `tokenEntries` / `darkTokenEntries` / `highContrastTokenEntries` arrays. Look up a value by category path:
25
+
24
26
  ```js
25
- import { tokens } from '@helixui/tokens';
27
+ import tokens from '@helixui/tokens';
26
28
 
27
- console.log(tokens.colorPrimary); // '#0057b8'
29
+ console.log(tokens.color.primary['700'].value); // '#0F6363'
28
30
  ```
29
31
 
32
+ Each `tokenEntries[i]` has `{ name, value, category, path }` — useful for documentation tooling and dynamic theming.
33
+
30
34
  ### Lit CSS utilities (for Lit component authors)
31
35
 
36
+ The Lit export ships pre-composed `CSSResult` blocks (light / dark / high-contrast). Token names themselves are emitted as CSS custom properties — reference them via `var()` in Lit's `css\`\`` template:
37
+
32
38
  ```ts
33
39
  import { css } from 'lit';
34
- import { colorPrimary, spacingMd } from '@helixui/tokens/lit';
35
40
 
36
41
  const styles = css`
37
42
  :host {
38
- color: ${colorPrimary};
39
- padding: ${spacingMd};
43
+ color: var(--hx-color-primary-700);
44
+ padding: var(--hx-space-4);
40
45
  }
41
46
  `;
42
47
  ```
43
48
 
44
- ### CSS custom properties (global stylesheet)
49
+ > **Note:** Since `@helixui/library@2.1.0`, tokens are adopted at the document level via `document.adoptedStyleSheets` and inherit through Shadow DOM. The `tokenStyles` / `darkTokenStyles` / `highContrastTokenStyles` exports from `@helixui/tokens/lit` are marked `@deprecated` and remain only for isolated test fixtures and iframe contexts.
45
50
 
46
- ```js
47
- import '@helixui/tokens/css';
48
- ```
51
+ ### CSS custom properties (global stylesheet)
49
52
 
50
- Or in CSS:
53
+ `@helixui/tokens/css` exports CSS **strings** (`tokensCSS`, `darkMediaCSS`, `darkManualCSS`) — it is not a side-effect entry. For side-effect adoption, load `@helixui/library` (which adopts the document-level stylesheet automatically) or `@import` the raw stylesheet:
51
54
 
52
55
  ```css
53
56
  @import '@helixui/tokens/tokens.css';
54
57
 
55
58
  .my-element {
56
- color: var(--hx-color-primary);
57
- padding: var(--hx-spacing-md);
59
+ color: var(--hx-color-primary-700);
60
+ padding: var(--hx-space-4);
58
61
  }
59
62
  ```
60
63
 
@@ -69,23 +72,29 @@ Useful for build tooling, style dictionaries, or design tool integrations.
69
72
  ### Utility helpers
70
73
 
71
74
  ```js
72
- import { toCssVar, resolveToken } from '@helixui/tokens/utils';
75
+ import { getTokensByPrefix, getColorSubgroups, getTokenStats } from '@helixui/tokens/utils';
76
+ import { tokenEntries } from '@helixui/tokens';
73
77
 
74
- toCssVar('color-primary'); // 'var(--hx-color-primary)'
78
+ const spacing = getTokensByPrefix(tokenEntries, '--hx-space-');
75
79
  ```
76
80
 
81
+ The `utils` entry exposes filter/group/stats helpers over `TokenEntry[]` — there are no `toCssVar` / `resolveToken` helpers; emit `var(--hx-…)` literals directly.
82
+
77
83
  ---
78
84
 
79
85
  ## Export Paths
80
86
 
81
- | Import path | Contents |
82
- |---|---|
83
- | `@helixui/tokens` | JavaScript token constants (default export) |
84
- | `@helixui/tokens/lit` | Lit CSS tagged template values |
85
- | `@helixui/tokens/css` | Side-effect import — injects CSS custom properties |
86
- | `@helixui/tokens/tokens.css` | Raw CSS file with all `--hx-*` custom properties |
87
- | `@helixui/tokens/tokens.json` | Source token definitions as JSON |
88
- | `@helixui/tokens/utils` | Helper utilities (`toCssVar`, etc.) |
87
+ | Import path | Contents |
88
+ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
89
+ | `@helixui/tokens` | Nested token JSON (default) + flattened `tokenEntries` / `darkTokenEntries` / `highContrastTokenEntries` |
90
+ | `@helixui/tokens/lit` | `tokenStyles`, `darkTokenStyles`, `highContrastTokenStyles` (Lit `CSSResult`; **deprecated** since `@helixui/library@2.1.0`) |
91
+ | `@helixui/tokens/css` | `tokensCSS`, `darkMediaCSS`, `darkManualCSS` — pre-built CSS strings (no side effects) |
92
+ | `@helixui/tokens/tokens.css` | Raw CSS file with all `--hx-*` custom properties (load via `@import` or `<link>`) |
93
+ | `@helixui/tokens/tokens.json` | Source token definitions as JSON |
94
+ | `@helixui/tokens/utils` | `getTokensByPrefix`, `getColorSubgroups`, `getTokenStats` helpers over `TokenEntry[]` |
95
+ | `@helixui/tokens/contrast-data` | Generated AAA contrast report |
96
+
97
+ Side-effect adoption (`document.adoptedStyleSheets`) lives in `@helixui/library`'s `ensureDocumentTokens` — load the library or `@import` the raw stylesheet to apply tokens globally.
89
98
 
90
99
  ---
91
100
 
@@ -93,13 +102,13 @@ toCssVar('color-primary'); // 'var(--hx-color-primary)'
93
102
 
94
103
  All CSS custom properties use the `--hx-` prefix:
95
104
 
96
- - **Color** — `--hx-color-primary`, `--hx-color-neutral-*`, `--hx-color-error`, etc.
97
- - **Spacing** — `--hx-spacing-xs` through `--hx-spacing-2xl`
98
- - **Typography** — `--hx-font-family-base`, `--hx-font-size-*`, `--hx-font-weight-*`
105
+ - **Color** — primitives like `--hx-color-primary-{50…900}`, `--hx-color-neutral-*`, plus action-layer semantics like `--hx-color-action-primary-bg`, `--hx-color-text-primary`, `--hx-color-surface-default`
106
+ - **Spacing** — `--hx-space-1` through `--hx-space-48` (numeric step scale, `--hx-space-4 = 1rem`)
107
+ - **Typography** — `--hx-font-family-sans`, `--hx-font-size-*`, `--hx-font-weight-*`
99
108
  - **Border** — `--hx-border-radius-*`, `--hx-border-width-*`
100
109
  - **Shadow** — `--hx-shadow-sm`, `--hx-shadow-md`, `--hx-shadow-lg`
101
110
  - **Motion** — `--hx-duration-fast`, `--hx-easing-standard`
102
- - **Z-index** — `--hx-z-dropdown`, `--hx-z-modal`, `--hx-z-toast`
111
+ - **Z-index** — `--hx-z-index-dropdown`, `--hx-z-index-modal`, `--hx-z-index-toast`, `--hx-z-index-popover`, `--hx-z-index-backdrop`, `--hx-z-index-sticky`, `--hx-z-index-fixed`, `--hx-z-index-tooltip`, `--hx-z-index-base`
103
112
 
104
113
  ---
105
114
 
@@ -109,9 +118,9 @@ Override semantic tokens at the `:root` level to apply a custom theme across all
109
118
 
110
119
  ```css
111
120
  :root {
112
- --hx-color-primary: #005eb8;
113
- --hx-color-primary-hover: #004f9f;
114
- --hx-font-family-base: 'Roboto', sans-serif;
121
+ --hx-color-action-primary-bg: #005eb8;
122
+ --hx-color-action-primary-bg-hover: #004f9f;
123
+ --hx-font-family-sans: 'Roboto', sans-serif;
115
124
  }
116
125
  ```
117
126
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@helixui/tokens",
3
- "version": "3.9.0-next.150",
3
+ "version": "3.9.0-next.154",
4
4
  "description": "Design tokens for the HELiX enterprise healthcare web component library",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",