@umbra.ui/colors 0.4.0 → 0.5.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 +236 -0
- package/package.json +2 -1
package/README.md
ADDED
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
# @umbra.ui/colors
|
|
2
|
+
|
|
3
|
+
Color tokens for Umbra UI.
|
|
4
|
+
|
|
5
|
+
This package provides:
|
|
6
|
+
|
|
7
|
+
- **30 color families** with 12-step scales
|
|
8
|
+
- **light + dark** tokens
|
|
9
|
+
- **opaque + alpha** variants
|
|
10
|
+
- **sRGB + Display P3** values
|
|
11
|
+
- a **semantic token layer** (`semantic-colors.css`)
|
|
12
|
+
- fully typed **JavaScript/TypeScript exports**
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
Install with your preferred package manager:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install @umbra.ui/colors
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pnpm add @umbra.ui/colors
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
yarn add @umbra.ui/colors
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
bun add @umbra.ui/colors
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Quick start
|
|
35
|
+
|
|
36
|
+
1. Install the package.
|
|
37
|
+
2. Import semantic tokens once in your app entry.
|
|
38
|
+
3. Toggle `.light` or `.dark` on a root container.
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
// main.ts
|
|
42
|
+
import "@umbra.ui/colors/semantic-colors.css";
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```html
|
|
46
|
+
<body class="light">
|
|
47
|
+
<div id="app"></div>
|
|
48
|
+
</body>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
```css
|
|
52
|
+
.panel {
|
|
53
|
+
background: var(--background-1);
|
|
54
|
+
color: var(--text-1);
|
|
55
|
+
border: 1px solid var(--border-2);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
.panel a {
|
|
59
|
+
color: var(--link);
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
// Optional: use raw scales from JS/TS
|
|
65
|
+
import { blue, blueDark } from "@umbra.ui/colors";
|
|
66
|
+
|
|
67
|
+
const brandLight = blue.blue9;
|
|
68
|
+
const brandDark = blueDark.blue9;
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## How the color system is structured
|
|
72
|
+
|
|
73
|
+
Each family follows a consistent naming model:
|
|
74
|
+
|
|
75
|
+
- `blue1 ... blue12` for opaque scale steps
|
|
76
|
+
- `blueA1 ... blueA12` for alpha scale steps
|
|
77
|
+
- `blueDark1 ...` does **not** exist as flattened keys; dark tokens are exposed as separate objects like `blueDark`
|
|
78
|
+
- `blueP3` / `blueP3A` (and dark P3 variants) contain Display P3 values
|
|
79
|
+
|
|
80
|
+
In CSS variables:
|
|
81
|
+
|
|
82
|
+
- Opaque tokens are `--blue-1 ... --blue-12`
|
|
83
|
+
- Alpha tokens are `--blue-a1 ... --blue-a12`
|
|
84
|
+
|
|
85
|
+
## Available families
|
|
86
|
+
|
|
87
|
+
### Neutral families
|
|
88
|
+
|
|
89
|
+
- `gray`
|
|
90
|
+
- `mauve`
|
|
91
|
+
- `slate`
|
|
92
|
+
- `sage`
|
|
93
|
+
- `olive`
|
|
94
|
+
- `sand`
|
|
95
|
+
|
|
96
|
+
### Chromatic families
|
|
97
|
+
|
|
98
|
+
- `tomato`, `red`, `ruby`, `crimson`, `pink`, `plum`, `purple`, `violet`
|
|
99
|
+
- `iris`, `indigo`, `blue`, `cyan`, `teal`, `jade`, `green`, `grass`
|
|
100
|
+
- `brown`, `bronze`, `gold`, `sky`, `mint`, `lime`, `yellow`, `amber`, `orange`
|
|
101
|
+
|
|
102
|
+
### Utility alpha families
|
|
103
|
+
|
|
104
|
+
- `blackA` / `blackP3A`
|
|
105
|
+
- `whiteA` / `whiteP3A`
|
|
106
|
+
|
|
107
|
+
## Theme behavior
|
|
108
|
+
|
|
109
|
+
The CSS files are authored to respond to standard theme selectors:
|
|
110
|
+
|
|
111
|
+
- Light selectors: `:root`, `.light`, `.light-theme`
|
|
112
|
+
- Dark selectors: `.dark`, `.dark-theme`
|
|
113
|
+
|
|
114
|
+
This means you can switch token values by toggling a theme class on a parent element.
|
|
115
|
+
|
|
116
|
+
## Using the package
|
|
117
|
+
|
|
118
|
+
### 1) Use tokens in JS/TS
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
import { blue, blueDark, blueA, blueDarkA } from "@umbra.ui/colors";
|
|
122
|
+
|
|
123
|
+
const buttonBgLight = blue.blue9;
|
|
124
|
+
const buttonBgDark = blueDark.blue9;
|
|
125
|
+
const focusRing = blueA.blueA8;
|
|
126
|
+
const focusRingDark = blueDarkA.blueA8;
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### 2) Use semantic CSS tokens
|
|
130
|
+
|
|
131
|
+
Import once:
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
import "@umbra.ui/colors/semantic-colors.css";
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Then consume semantic variables in your styles:
|
|
138
|
+
|
|
139
|
+
```css
|
|
140
|
+
.card {
|
|
141
|
+
background: var(--background-1);
|
|
142
|
+
border: 1px solid var(--border-2);
|
|
143
|
+
color: var(--text-1);
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
.card a {
|
|
147
|
+
color: var(--link);
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
`semantic-colors.css` includes:
|
|
152
|
+
|
|
153
|
+
- Accent and neutral ramps (`--accent-*`, `--neutral-*`)
|
|
154
|
+
- Surface/control/border/text aliases
|
|
155
|
+
- `--background-0..2`
|
|
156
|
+
- `--control-1..3`
|
|
157
|
+
- `--border-1..3`
|
|
158
|
+
- `--text-1..3`
|
|
159
|
+
- Status/intent aliases
|
|
160
|
+
- `--link`, `--info`, `--success`, `--warning`, `--error`
|
|
161
|
+
|
|
162
|
+
## Scale guidance (1-12)
|
|
163
|
+
|
|
164
|
+
The 12-step ramp is intentionally role-based:
|
|
165
|
+
|
|
166
|
+
| Step | Typical use |
|
|
167
|
+
| --- | --- |
|
|
168
|
+
| 1 | App/page background |
|
|
169
|
+
| 2 | Subtle background areas |
|
|
170
|
+
| 3 | Component background (rest) |
|
|
171
|
+
| 4 | Component background (hover) |
|
|
172
|
+
| 5 | Component background (active/selected) |
|
|
173
|
+
| 6 | Subtle borders and separators |
|
|
174
|
+
| 7 | Interactive borders |
|
|
175
|
+
| 8 | Stronger interactive borders / focus rings |
|
|
176
|
+
| 9 | Solid fills (primary color block) |
|
|
177
|
+
| 10 | Hovered solid fills |
|
|
178
|
+
| 11 | Lower-contrast text |
|
|
179
|
+
| 12 | High-contrast text |
|
|
180
|
+
|
|
181
|
+
Notes:
|
|
182
|
+
|
|
183
|
+
- Steps `9` and `10` are for strong fills and accents.
|
|
184
|
+
- Steps `11` and `12` are text-oriented values.
|
|
185
|
+
- On a step `2` background from the same scale, steps `11` and `12` are designed for readable text contrast targets.
|
|
186
|
+
|
|
187
|
+
## Palette composition guidance
|
|
188
|
+
|
|
189
|
+
### Choose an accent scale
|
|
190
|
+
|
|
191
|
+
Scales generally suited for **light foreground text** on step `9/10`:
|
|
192
|
+
|
|
193
|
+
- `bronze`, `gold`, `brown`, `orange`, `tomato`, `red`, `ruby`, `crimson`
|
|
194
|
+
- `pink`, `plum`, `purple`, `violet`, `iris`, `indigo`, `blue`, `cyan`
|
|
195
|
+
- `teal`, `jade`, `green`, `grass`
|
|
196
|
+
|
|
197
|
+
Scales generally suited for **dark foreground text** on step `9/10`:
|
|
198
|
+
|
|
199
|
+
- `sky`, `mint`, `lime`, `yellow`, `amber`
|
|
200
|
+
|
|
201
|
+
### Choose a neutral scale
|
|
202
|
+
|
|
203
|
+
- `gray`: pure neutral
|
|
204
|
+
- `mauve`: purple-leaning neutral
|
|
205
|
+
- `slate`: blue-leaning neutral
|
|
206
|
+
- `sage`: green-leaning neutral
|
|
207
|
+
- `olive`: yellow-green-leaning neutral
|
|
208
|
+
- `sand`: warm yellow-leaning neutral
|
|
209
|
+
|
|
210
|
+
Practical rule:
|
|
211
|
+
|
|
212
|
+
- Use `gray` for a cleaner, less saturated foundation.
|
|
213
|
+
- Use a tinted neutral (for example `slate` with blue accents) when you want a more atmospheric palette.
|
|
214
|
+
|
|
215
|
+
### Choose semantic scales
|
|
216
|
+
|
|
217
|
+
Common pairings:
|
|
218
|
+
|
|
219
|
+
- Error: `red`, `ruby`, `tomato`, `crimson`
|
|
220
|
+
- Success: `green`, `teal`, `jade`, `grass`, `mint`
|
|
221
|
+
- Warning: `yellow`, `amber`, `orange`
|
|
222
|
+
- Info: `blue`, `indigo`, `sky`, `cyan`
|
|
223
|
+
|
|
224
|
+
## API surface summary
|
|
225
|
+
|
|
226
|
+
- Root JS/TS import: `@umbra.ui/colors`
|
|
227
|
+
- Exposes all token objects (`blue`, `blueA`, `blueP3`, `blueDark`, `blueDarkA`, `blueDarkP3`, etc.)
|
|
228
|
+
- Exposes `blackA`, `blackP3A`, `whiteA`, `whiteP3A`
|
|
229
|
+
- CSS semantic entry: `@umbra.ui/colors/semantic-colors.css`
|
|
230
|
+
|
|
231
|
+
## Tips and best practices
|
|
232
|
+
|
|
233
|
+
- Prefer semantic tokens (`--text-1`, `--border-2`, `--error`) in component code.
|
|
234
|
+
- Use raw scale tokens (`--blue-9`, `blue.blue9`) for brand/accent-specific UI.
|
|
235
|
+
- Keep neutral backgrounds conservative if your UI already has many saturated badges/labels.
|
|
236
|
+
- Treat token ramps as system primitives; if you need brand-specific colors, add custom tokens alongside Umbra tokens rather than modifying these scales directly.
|
package/package.json
CHANGED