@helixui/tokens 3.9.0 → 3.9.1
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.
- package/README.md +39 -30
- package/dist/__generated__/contrast-report.js +1 -1
- 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
|
[](https://www.npmjs.com/package/@helixui/tokens)
|
|
6
|
-
[](LICENSE)
|
|
6
|
+
[](../../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
|
|
27
|
+
import tokens from '@helixui/tokens';
|
|
26
28
|
|
|
27
|
-
console.log(tokens.
|
|
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:
|
|
39
|
-
padding:
|
|
43
|
+
color: var(--hx-color-primary-700);
|
|
44
|
+
padding: var(--hx-space-4);
|
|
40
45
|
}
|
|
41
46
|
`;
|
|
42
47
|
```
|
|
43
48
|
|
|
44
|
-
|
|
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
|
-
|
|
47
|
-
import '@helixui/tokens/css';
|
|
48
|
-
```
|
|
51
|
+
### CSS custom properties (global stylesheet)
|
|
49
52
|
|
|
50
|
-
|
|
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-
|
|
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 {
|
|
75
|
+
import { getTokensByPrefix, getColorSubgroups, getTokenStats } from '@helixui/tokens/utils';
|
|
76
|
+
import { tokenEntries } from '@helixui/tokens';
|
|
73
77
|
|
|
74
|
-
|
|
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
|
|
82
|
-
|
|
83
|
-
| `@helixui/tokens`
|
|
84
|
-
| `@helixui/tokens/lit`
|
|
85
|
-
| `@helixui/tokens/css`
|
|
86
|
-
| `@helixui/tokens/tokens.css`
|
|
87
|
-
| `@helixui/tokens/tokens.json`
|
|
88
|
-
| `@helixui/tokens/utils`
|
|
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-
|
|
97
|
-
- **Spacing** — `--hx-
|
|
98
|
-
- **Typography** — `--hx-font-family-
|
|
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-
|
|
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
|
|