@gridui/palette 0.0.0-stage → 1.0.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.
@@ -0,0 +1,286 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "name": "@gridui/palette",
4
+ "version": "1.0.0",
5
+ "category": "foundation",
6
+ "description": "Composable color engines, scales, semantic roles, and contrast diagnostics",
7
+ "usage": "Generate a complete GridUI color palette from a seed with a replaceable color engine. The package runs in browsers, build scripts, and servers without React, CSS, or a DOM.",
8
+ "documentation": [
9
+ "README.md",
10
+ "docs/color-configuration.md"
11
+ ],
12
+ "exports": [
13
+ {
14
+ "name": "assertColorTheme",
15
+ "kind": "function",
16
+ "importPath": "@gridui/palette"
17
+ },
18
+ {
19
+ "name": "BuiltInPaletteEngineName",
20
+ "kind": "type",
21
+ "importPath": "@gridui/palette"
22
+ },
23
+ {
24
+ "name": "builtInPaletteEngines",
25
+ "kind": "value",
26
+ "importPath": "@gridui/palette"
27
+ },
28
+ {
29
+ "name": "ColorBase",
30
+ "kind": "type",
31
+ "importPath": "@gridui/palette"
32
+ },
33
+ {
34
+ "name": "colorFromOklch",
35
+ "kind": "function",
36
+ "importPath": "@gridui/palette"
37
+ },
38
+ {
39
+ "name": "ColorMode",
40
+ "kind": "type",
41
+ "importPath": "@gridui/palette"
42
+ },
43
+ {
44
+ "name": "ColorOverrides",
45
+ "kind": "type",
46
+ "importPath": "@gridui/palette"
47
+ },
48
+ {
49
+ "name": "colorRoles",
50
+ "kind": "value",
51
+ "importPath": "@gridui/palette"
52
+ },
53
+ {
54
+ "name": "ColorScale",
55
+ "kind": "type",
56
+ "importPath": "@gridui/palette"
57
+ },
58
+ {
59
+ "name": "ColorScales",
60
+ "kind": "type",
61
+ "importPath": "@gridui/palette"
62
+ },
63
+ {
64
+ "name": "ColorScaleStep",
65
+ "kind": "type",
66
+ "importPath": "@gridui/palette"
67
+ },
68
+ {
69
+ "name": "ColorSources",
70
+ "kind": "type",
71
+ "importPath": "@gridui/palette"
72
+ },
73
+ {
74
+ "name": "ColorThemeContrast",
75
+ "kind": "type",
76
+ "importPath": "@gridui/palette"
77
+ },
78
+ {
79
+ "name": "ColorThemeDiagnostics",
80
+ "kind": "type",
81
+ "importPath": "@gridui/palette"
82
+ },
83
+ {
84
+ "name": "ColorThemePalette",
85
+ "kind": "type",
86
+ "importPath": "@gridui/palette"
87
+ },
88
+ {
89
+ "name": "ColorThemePaletteName",
90
+ "kind": "type",
91
+ "importPath": "@gridui/palette"
92
+ },
93
+ {
94
+ "name": "ColorThemeRole",
95
+ "kind": "type",
96
+ "importPath": "@gridui/palette"
97
+ },
98
+ {
99
+ "name": "ColorThemeSimilarity",
100
+ "kind": "type",
101
+ "importPath": "@gridui/palette"
102
+ },
103
+ {
104
+ "name": "ColorThemeStatus",
105
+ "kind": "type",
106
+ "importPath": "@gridui/palette"
107
+ },
108
+ {
109
+ "name": "colorToOklch",
110
+ "kind": "function",
111
+ "importPath": "@gridui/palette"
112
+ },
113
+ {
114
+ "name": "ColorVariant",
115
+ "kind": "type",
116
+ "importPath": "@gridui/palette"
117
+ },
118
+ {
119
+ "name": "ColorVariantConfig",
120
+ "kind": "type",
121
+ "importPath": "@gridui/palette"
122
+ },
123
+ {
124
+ "name": "colorVariantNames",
125
+ "kind": "value",
126
+ "importPath": "@gridui/palette"
127
+ },
128
+ {
129
+ "name": "ColorVariants",
130
+ "kind": "type",
131
+ "importPath": "@gridui/palette"
132
+ },
133
+ {
134
+ "name": "complementary",
135
+ "kind": "value",
136
+ "importPath": "@gridui/palette"
137
+ },
138
+ {
139
+ "name": "createPalette",
140
+ "kind": "function",
141
+ "importPath": "@gridui/palette"
142
+ },
143
+ {
144
+ "name": "defaultColorSeed",
145
+ "kind": "value",
146
+ "importPath": "@gridui/palette"
147
+ },
148
+ {
149
+ "name": "isBuiltInPaletteEngineName",
150
+ "kind": "value",
151
+ "importPath": "@gridui/palette"
152
+ },
153
+ {
154
+ "name": "LCH",
155
+ "kind": "type",
156
+ "importPath": "@gridui/palette"
157
+ },
158
+ {
159
+ "name": "modes",
160
+ "kind": "value",
161
+ "importPath": "@gridui/palette"
162
+ },
163
+ {
164
+ "name": "monochromatic",
165
+ "kind": "value",
166
+ "importPath": "@gridui/palette"
167
+ },
168
+ {
169
+ "name": "normalizeThemeColor",
170
+ "kind": "function",
171
+ "importPath": "@gridui/palette"
172
+ },
173
+ {
174
+ "name": "PaletteConfig",
175
+ "kind": "type",
176
+ "importPath": "@gridui/palette"
177
+ },
178
+ {
179
+ "name": "PaletteEngine",
180
+ "kind": "type",
181
+ "importPath": "@gridui/palette"
182
+ },
183
+ {
184
+ "name": "PaletteEngineResult",
185
+ "kind": "type",
186
+ "importPath": "@gridui/palette"
187
+ },
188
+ {
189
+ "name": "PaletteMapping",
190
+ "kind": "type",
191
+ "importPath": "@gridui/palette"
192
+ },
193
+ {
194
+ "name": "paletteNames",
195
+ "kind": "value",
196
+ "importPath": "@gridui/palette"
197
+ },
198
+ {
199
+ "name": "ResolvedColorVariant",
200
+ "kind": "type",
201
+ "importPath": "@gridui/palette"
202
+ },
203
+ {
204
+ "name": "ResolvedPalette",
205
+ "kind": "type",
206
+ "importPath": "@gridui/palette"
207
+ },
208
+ {
209
+ "name": "runPaletteEngine",
210
+ "kind": "function",
211
+ "importPath": "@gridui/palette"
212
+ },
213
+ {
214
+ "name": "scaleSteps",
215
+ "kind": "value",
216
+ "importPath": "@gridui/palette"
217
+ },
218
+ {
219
+ "name": "surfaceAppearance",
220
+ "kind": "function",
221
+ "importPath": "@gridui/palette"
222
+ },
223
+ {
224
+ "name": "BuiltInPaletteEngineName",
225
+ "kind": "type",
226
+ "importPath": "@gridui/palette/engine"
227
+ },
228
+ {
229
+ "name": "builtInPaletteEngines",
230
+ "kind": "value",
231
+ "importPath": "@gridui/palette/engine"
232
+ },
233
+ {
234
+ "name": "colorFromOklch",
235
+ "kind": "function",
236
+ "importPath": "@gridui/palette/engine"
237
+ },
238
+ {
239
+ "name": "colorToOklch",
240
+ "kind": "function",
241
+ "importPath": "@gridui/palette/engine"
242
+ },
243
+ {
244
+ "name": "complementary",
245
+ "kind": "function",
246
+ "importPath": "@gridui/palette/engine"
247
+ },
248
+ {
249
+ "name": "isBuiltInPaletteEngineName",
250
+ "kind": "function",
251
+ "importPath": "@gridui/palette/engine"
252
+ },
253
+ {
254
+ "name": "LCH",
255
+ "kind": "type",
256
+ "importPath": "@gridui/palette/engine"
257
+ },
258
+ {
259
+ "name": "monochromatic",
260
+ "kind": "function",
261
+ "importPath": "@gridui/palette/engine"
262
+ },
263
+ {
264
+ "name": "PaletteEngine",
265
+ "kind": "type",
266
+ "importPath": "@gridui/palette/engine"
267
+ },
268
+ {
269
+ "name": "PaletteEngineResult",
270
+ "kind": "type",
271
+ "importPath": "@gridui/palette/engine"
272
+ },
273
+ {
274
+ "name": "PaletteMapping",
275
+ "kind": "type",
276
+ "importPath": "@gridui/palette/engine"
277
+ },
278
+ {
279
+ "name": "runPaletteEngine",
280
+ "kind": "function",
281
+ "importPath": "@gridui/palette/engine"
282
+ }
283
+ ],
284
+ "styles": [],
285
+ "examples": []
286
+ }
@@ -0,0 +1,66 @@
1
+ # Color configuration
2
+
3
+ ## Resolution order
4
+
5
+ The public `PaletteConfig` is partial. The resolved `ResolvedPalette` is complete.
6
+ The generator does not mutate input and has no DOM, storage, or React dependency.
7
+ Every stage has a fixed, acyclic dependency order:
8
+
9
+ 1. `seed` supplies brand and default neutral tint; `sources` overrides secondary,
10
+ neutral, success, warning, and danger. Engine suggestions precede explicit source overrides.
11
+ 2. `scales.<source>.key` replaces the source for that scale before generating its
12
+ nodes. Individual nodes then override generated nodes. Steps are 0, 10, 20, 30,
13
+ 40, 50, 60, 70, 80, 90, 95, 98, 100; they describe target OKLCH lightness, not
14
+ guaranteed contrast. Full scale replacement supplies `key` and every step.
15
+ 3. `colorVariants.<variant>.<mode>.base` chooses background, surface, and accent. An
16
+ overridden background feeds an unspecified surface. Plain-variant base defaults
17
+ are deliberately untinted; its actions still use the brand scale.
18
+ 4. Surface hover/pressed/selection follow the resolved surface. Text, links,
19
+ indicators, and statuses are solved against **all final surface fills**.
20
+ Accent hover/pressed follow the resolved accent; accent foreground follows all
21
+ three final accent fills. Selection-tint follows selection-background.
22
+
23
+ Final `roles.background`, `roles.surface`, and `roles["accent-background"]` pin
24
+ those base inputs **before** downstream roles resolve. Other explicit roles pin
25
+ only their named result; e.g. foreground does not recolor muted text. Overrides
26
+ are exact after HEX normalization; contrast solving only changes derived values.
27
+ Scale 50 supplies link/focus/status candidates; scale key supplies light primary
28
+ fill and scale 70 supplies dark primary fill. Filled brand/secondary palettes use
29
+ an opposing primary fill. Generated primary fills are solved for 3:1 against
30
+ final surfaces; explicit base/role accent colors remain pinned. Resolved bases
31
+ include the final action fill.
32
+ Changing a node affects only consumers of that node, not adjacent scale nodes.
33
+
34
+ `colorVariants.*.*.palettes` configures optional neutral/brand/secondary/status surfaces.
35
+ Top-level `base` and `roles` abbreviate the neutral palette. A corresponding
36
+ `palettes.neutral` value wins when both are supplied. Palette surfaces are not a
37
+ fourth color variant; each resolves within the selected variant and appearance.
38
+ Use one palette class per surface. Full customization supplies every role in every
39
+ palette of all six variant/appearance pairs; `seed` can be omitted.
40
+
41
+ ## Diagnostics
42
+
43
+ `diagnostics.contrast` measures rounded output pairs; `failures` contains only
44
+ pairs below the requirement, with colorVariant, appearance, palette and both role names.
45
+ `strict: true` or `assertColorTheme(palette)` throws on final failures. Editing tools
46
+ can leave strict disabled and display diagnostics without losing explicit colors.
47
+ Impossible custom combinations return the best derived black/white candidate
48
+ and report the remaining failures. Production themes should pass strict validation.
49
+
50
+ Text, links, and local status text require 4.5:1 on background, surface, hover,
51
+ pressed, and selection. Required control/focus/selection/status indicators require
52
+ 3:1 on those fills. Primary action fill requires 3:1 on the surface fills. Accent foreground requires 4.5:1 on normal, hover and pressed
53
+ accent fills. Border and decoration are decorative and have no minimum guarantee.
54
+ The default foreground solver targets 7:1 where possible; its contract is 4.5:1.
55
+
56
+ `diagnostics.similarities` reports brand/secondary hues close to status hues; it is
57
+ advisory, not an accessibility verdict. Status labels/icons remain necessary.
58
+ The `backdrop` role is an opaque pigment derived from neutral scale 0; overlays
59
+ compose it once with `--gridui-backdrop-opacity` (25% on light surfaces, 60% on
60
+ dark surfaces). That opacity is generated from the resolved background, independent
61
+ of application mode, and can be overridden with CSS. Loading colors rebind at every
62
+ color scope. Feature-link seeds affect decoration; destination text uses local link.
63
+
64
+ Transparency, images, disabled opacity, and caller CSS are not covered by opaque
65
+ pair diagnostics. Focus color contrast alone does not establish full focus AAA
66
+ conformance. Forced-colors mode continues to use system colors.
package/package.json CHANGED
@@ -1,6 +1,39 @@
1
1
  {
2
2
  "name": "@gridui/palette",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.0.0",
4
+ "description": "Composable color engines, scales, semantic roles, and contrast diagnostics",
5
+ "license": "UNLICENSED",
6
+ "type": "module",
7
+ "files": [
8
+ "dist",
9
+ "README.md",
10
+ "docs"
11
+ ],
12
+ "sideEffects": false,
13
+ "exports": {
14
+ ".": {
15
+ "types": "./dist/index.d.ts",
16
+ "import": "./dist/index.js"
17
+ },
18
+ "./engine": {
19
+ "types": "./dist/engine.d.ts",
20
+ "import": "./dist/engine.js"
21
+ }
22
+ },
23
+ "publishConfig": {
24
+ "access": "public"
25
+ },
26
+ "devDependencies": {
27
+ "@gridui-internal/configuration": "0.0.0-internal",
28
+ "@jest/globals": "30.5.2",
29
+ "@types/jest": "30.0.0",
30
+ "@types/node": "26.6.6",
31
+ "jest": "30.5.2",
32
+ "typescript": "6.0.3"
33
+ },
34
+ "scripts": {
35
+ "build": "node ../../scripts/compilation/package.ts",
36
+ "compile": "tsc --project tsconfig.json",
37
+ "test": "jest"
38
+ }
6
39
  }