@umbra.ui/colors 0.2.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.
Files changed (2) hide show
  1. package/README.md +236 -0
  2. package/package.json +7 -7
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
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "@umbra.ui/colors",
3
- "version": "0.2.0",
3
+ "version": "0.5.0",
4
4
  "description": "Color system for Umbra UI",
5
+ "homepage": "https://www.umbraui.com/",
5
6
  "type": "module",
6
7
  "main": "dist/index.js",
7
8
  "types": "dist/index.d.ts",
@@ -20,11 +21,6 @@
20
21
  "node": ">=16",
21
22
  "bun": ">=1.0"
22
23
  },
23
- "scripts": {
24
- "build": "tsc",
25
- "dev": "tsc --watch",
26
- "prepublishOnly": "npm run build"
27
- },
28
24
  "keywords": [
29
25
  "colors",
30
26
  "design-system",
@@ -37,5 +33,9 @@
37
33
  },
38
34
  "publishConfig": {
39
35
  "access": "public"
36
+ },
37
+ "scripts": {
38
+ "build": "tsc",
39
+ "dev": "tsc --watch"
40
40
  }
41
- }
41
+ }