@cumulus-ui/design-tokens 0.1.0 → 0.2.0
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 +117 -0
- package/index.d.ts +1 -0
- package/index.js +438 -437
- package/package.json +1 -1
- package/tokens.css +736 -734
package/README.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# @cumulus-ui/design-tokens
|
|
2
|
+
|
|
3
|
+
CSS custom properties for Cumulus UI — light and dark mode tokens generated from Cloudscape Design System.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @cumulus-ui/design-tokens
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Usage
|
|
12
|
+
|
|
13
|
+
### CSS
|
|
14
|
+
|
|
15
|
+
Load the token stylesheet once in your application entry point:
|
|
16
|
+
|
|
17
|
+
```js
|
|
18
|
+
import '@cumulus-ui/design-tokens/tokens.css';
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Then use tokens as CSS custom properties anywhere:
|
|
22
|
+
|
|
23
|
+
```css
|
|
24
|
+
.my-component {
|
|
25
|
+
color: var(--color-text-body-default);
|
|
26
|
+
background: var(--color-background-layout-main);
|
|
27
|
+
border-radius: var(--border-radius-container);
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### JavaScript / TypeScript
|
|
32
|
+
|
|
33
|
+
For inline styles or JS-driven styling, import named token constants:
|
|
34
|
+
|
|
35
|
+
```js
|
|
36
|
+
import { colorTextBodyDefault, colorBackgroundLayoutMain } from '@cumulus-ui/design-tokens';
|
|
37
|
+
|
|
38
|
+
element.style.color = colorTextBodyDefault; // → "var(--color-text-body-default)"
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Dark mode
|
|
42
|
+
|
|
43
|
+
Tokens respond to the `.awsui-dark-mode` class on `<html>`:
|
|
44
|
+
|
|
45
|
+
```js
|
|
46
|
+
// Enable dark mode
|
|
47
|
+
document.documentElement.classList.add('awsui-dark-mode');
|
|
48
|
+
|
|
49
|
+
// Disable dark mode
|
|
50
|
+
document.documentElement.classList.remove('awsui-dark-mode');
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
All token values update automatically — no additional imports or class changes needed.
|
|
54
|
+
|
|
55
|
+
## Token naming
|
|
56
|
+
|
|
57
|
+
Tokens follow the Cloudscape [CTI naming convention](https://cloudscape.design/foundation/visual-foundation/design-tokens/) (Category → Type → Item → State):
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
--color-background-button-primary-default
|
|
61
|
+
│ │ │ │ └─ state
|
|
62
|
+
│ │ │ └───────── sub-item
|
|
63
|
+
│ │ └───────────────── item
|
|
64
|
+
│ └─────────────────────────── type
|
|
65
|
+
└─────────────────────────────────── category
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Design decisions
|
|
69
|
+
|
|
70
|
+
### No hashed variable names
|
|
71
|
+
|
|
72
|
+
Cloudscape uses content-hashed suffixes on CSS custom property names (e.g. `--color-text-body-default-vvtq8u`). The hash is an MD5 digest of the token's value set, designed to signal version changes and discourage direct CSS usage in their React ecosystem.
|
|
73
|
+
|
|
74
|
+
Cumulus strips these hashes. Our CSS properties use canonical token names directly:
|
|
75
|
+
|
|
76
|
+
```css
|
|
77
|
+
/* Cloudscape */
|
|
78
|
+
var(--color-text-body-default-vvtq8u, #0f141a)
|
|
79
|
+
|
|
80
|
+
/* Cumulus */
|
|
81
|
+
var(--color-text-body-default, #0f141a)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
**Why:** Hashed names provide collision avoidance and version signaling, but at the cost of developer experience. Every other web component design system (Shoelace, Spectrum, Carbon, Vaadin) uses clean, human-readable names. Since Cumulus owns both the token definitions and the component CSS, we can guarantee name-value consistency through our generation pipeline rather than encoding it in variable names. See the full rationale below.
|
|
85
|
+
|
|
86
|
+
**What Cloudscape's hashes solve and how we address each:**
|
|
87
|
+
|
|
88
|
+
| Cloudscape concern | Hash solution | Cumulus alternative |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| Value changes break silently | Hash changes → loud CSS failure | We regenerate tokens + components in the same release |
|
|
91
|
+
| Direct CSS usage discouraged | Names are unmemorable | Direct CSS usage is encouraged — clean names are the API |
|
|
92
|
+
| Multi-theme collision | Different hashes per theme | Not applicable; single-theme with light/dark mode |
|
|
93
|
+
|
|
94
|
+
### No namespace prefix
|
|
95
|
+
|
|
96
|
+
Unlike other design systems (`--sl-`, `--cds-`, `--spectrum-`), Cumulus tokens have no prefix. The CTI naming convention produces specific enough names (`--color-background-button-primary-default`) that collisions are impractical. If a prefix becomes necessary (e.g. for multi-system pages), it can be added to the generator with a one-line change.
|
|
97
|
+
|
|
98
|
+
### No fallbacks in JS exports
|
|
99
|
+
|
|
100
|
+
The JavaScript token exports contain `var()` references without fallback values:
|
|
101
|
+
|
|
102
|
+
```js
|
|
103
|
+
export const colorTextBodyDefault = "var(--color-text-body-default)";
|
|
104
|
+
// NOT: "var(--color-text-body-default, #0f141a)"
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
This is intentional. If `tokens.css` is not loaded, things should break visibly rather than silently rendering light-mode-only values. Component CSS retains inline fallbacks as a safety net for Shadow DOM isolation.
|
|
108
|
+
|
|
109
|
+
## Regenerating
|
|
110
|
+
|
|
111
|
+
Tokens are auto-generated from `@cloudscape-design/design-tokens`:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
npm run generate
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
This reads the upstream JSON (token names + light/dark values) and JS (to discover the token set), then outputs `tokens.css`, `index.js`, and `index.d.ts` with clean names.
|
package/index.d.ts
CHANGED