@clhaas/palette-kit 0.3.0 → 0.4.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 (312) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +80 -87
  3. package/dist/contrast/contrast.d.ts +16 -0
  4. package/dist/contrast/contrast.js +102 -0
  5. package/dist/core/intent-registry.d.ts +11 -0
  6. package/dist/core/intent-registry.js +70 -0
  7. package/dist/core/oklch.d.ts +16 -0
  8. package/dist/core/oklch.js +56 -0
  9. package/dist/create-palette-kit.d.ts +9 -0
  10. package/dist/create-palette-kit.js +67 -0
  11. package/dist/engine/context/context.d.ts +13 -0
  12. package/dist/engine/context/context.js +37 -0
  13. package/dist/engine/level/curves.d.ts +17 -0
  14. package/dist/engine/level/curves.js +49 -0
  15. package/dist/engine/level/level.d.ts +4 -0
  16. package/dist/engine/level/level.js +13 -0
  17. package/dist/engine/relation/relation.d.ts +105 -0
  18. package/dist/engine/relation/relation.js +137 -0
  19. package/dist/engine/resolve/resolve.d.ts +36 -0
  20. package/dist/engine/resolve/resolve.js +116 -0
  21. package/dist/engine/state/state.d.ts +46 -0
  22. package/dist/engine/state/state.js +68 -0
  23. package/dist/engine/usage/fill.d.ts +9 -0
  24. package/dist/engine/usage/fill.js +9 -0
  25. package/dist/engine/usage/lines.d.ts +9 -0
  26. package/dist/engine/usage/lines.js +9 -0
  27. package/dist/engine/usage/overlays.d.ts +9 -0
  28. package/dist/engine/usage/overlays.js +9 -0
  29. package/dist/engine/usage/strategy.d.ts +56 -0
  30. package/dist/engine/usage/strategy.js +30 -0
  31. package/dist/engine/usage/visualVocabulary.d.ts +9 -0
  32. package/dist/engine/usage/visualVocabulary.js +9 -0
  33. package/dist/export/serialize.d.ts +14 -0
  34. package/dist/export/serialize.js +89 -0
  35. package/dist/export/types.d.ts +37 -0
  36. package/dist/export/types.js +31 -0
  37. package/dist/index.d.ts +3 -3
  38. package/dist/index.js +2 -2
  39. package/dist/operators/convert.d.ts +32 -0
  40. package/dist/operators/convert.js +80 -0
  41. package/dist/presets/presets.d.ts +95 -0
  42. package/dist/presets/presets.js +308 -0
  43. package/dist/types/index.d.ts +111 -187
  44. package/dist/utils/errors/errors.d.ts +17 -0
  45. package/dist/utils/errors/errors.js +22 -0
  46. package/docs/API.md +167 -0
  47. package/docs/Alpha.md +14 -0
  48. package/docs/Architecture.md +56 -0
  49. package/docs/CLI.md +22 -0
  50. package/docs/Concepts.md +73 -0
  51. package/docs/Config.md +144 -0
  52. package/docs/Diagnostics.md +22 -0
  53. package/docs/Exporters.md +33 -0
  54. package/docs/FAQ.md +59 -0
  55. package/docs/Migration.md +61 -0
  56. package/docs/Overlays.md +33 -0
  57. package/docs/README.md +60 -0
  58. package/docs/Text.md +41 -0
  59. package/docs/Tokens.md +42 -0
  60. package/docs/Usage-JSON.md +39 -0
  61. package/docs/Usage-ReactNative.md +63 -0
  62. package/docs/Usage-Web.md +66 -0
  63. package/docs/Validation.md +97 -0
  64. package/docs/Why.md +37 -0
  65. package/docs/_api-surface.md +53 -0
  66. package/docs/snippets/serialize-oklch.md +9 -0
  67. package/docs/spec.md +98 -0
  68. package/package.json +74 -59
  69. package/.codex/skills/color-pipeline-implementer/SKILL.md +0 -23
  70. package/.codex/skills/commit-message-crafter/SKILL.md +0 -63
  71. package/.codex/skills/commit-message-crafter/references/benchmarks.md +0 -20
  72. package/.codex/skills/contrast-solver-helper/SKILL.md +0 -20
  73. package/.codex/skills/exporters-builder/SKILL.md +0 -20
  74. package/.codex/skills/markdownlint-writer/SKILL.md +0 -32
  75. package/.codex/skills/phase-implementation-runbook/SKILL.md +0 -92
  76. package/.codex/skills/type-contract-auditor/SKILL.md +0 -21
  77. package/.github/skills/review-guide/SKILL.md +0 -23
  78. package/.github/skills/review-guide/references/review-guide-v0.3.md +0 -629
  79. package/.markdownlint.json +0 -4
  80. package/AGENTS.md +0 -16
  81. package/biome.json +0 -43
  82. package/dist/cli/args.d.ts +0 -12
  83. package/dist/cli/args.js +0 -56
  84. package/dist/cli/args.test.d.ts +0 -1
  85. package/dist/cli/args.test.js +0 -22
  86. package/dist/cli/codegen/__snapshots__/tokens.test.js.snap +0 -87
  87. package/dist/cli/codegen/tokens.d.ts +0 -12
  88. package/dist/cli/codegen/tokens.js +0 -139
  89. package/dist/cli/codegen/tokens.test.d.ts +0 -1
  90. package/dist/cli/codegen/tokens.test.js +0 -51
  91. package/dist/cli/config.d.ts +0 -40
  92. package/dist/cli/config.js +0 -34
  93. package/dist/cli/validate.d.ts +0 -2
  94. package/dist/cli/validate.js +0 -33
  95. package/dist/cli/validate.test.d.ts +0 -1
  96. package/dist/cli/validate.test.js +0 -40
  97. package/dist/cli.d.ts +0 -2
  98. package/dist/cli.js +0 -148
  99. package/dist/contrast/apca.d.ts +0 -2
  100. package/dist/contrast/apca.js +0 -15
  101. package/dist/contrast/apca.test.d.ts +0 -1
  102. package/dist/contrast/apca.test.js +0 -16
  103. package/dist/contrast/index.d.ts +0 -4
  104. package/dist/contrast/index.js +0 -4
  105. package/dist/contrast/scoring.d.ts +0 -4
  106. package/dist/contrast/scoring.js +0 -31
  107. package/dist/contrast/scoring.test.d.ts +0 -1
  108. package/dist/contrast/scoring.test.js +0 -148
  109. package/dist/contrast/solver.d.ts +0 -13
  110. package/dist/contrast/solver.js +0 -170
  111. package/dist/contrast/solver.test.d.ts +0 -1
  112. package/dist/contrast/solver.test.js +0 -75
  113. package/dist/contrast/types.d.ts +0 -17
  114. package/dist/contrast/types.js +0 -1
  115. package/dist/contrast/utils.d.ts +0 -4
  116. package/dist/contrast/utils.js +0 -18
  117. package/dist/contrast/wcag2.d.ts +0 -3
  118. package/dist/contrast/wcag2.js +0 -19
  119. package/dist/contrast/wcag2.test.d.ts +0 -1
  120. package/dist/contrast/wcag2.test.js +0 -17
  121. package/dist/core/createTheme.d.ts +0 -35
  122. package/dist/core/createTheme.js +0 -24
  123. package/dist/core/dx-helpers.test.d.ts +0 -1
  124. package/dist/core/dx-helpers.test.js +0 -61
  125. package/dist/core/index.d.ts +0 -2
  126. package/dist/core/index.js +0 -2
  127. package/dist/core/onSolid.test.d.ts +0 -1
  128. package/dist/core/onSolid.test.js +0 -118
  129. package/dist/core/qa.v1.test.d.ts +0 -1
  130. package/dist/core/qa.v1.test.js +0 -112
  131. package/dist/core/resolve.d.ts +0 -3
  132. package/dist/core/resolve.js +0 -8
  133. package/dist/core/resolve.test.d.ts +0 -1
  134. package/dist/core/resolve.test.js +0 -89
  135. package/dist/core/resolveMany.d.ts +0 -8
  136. package/dist/core/resolveMany.js +0 -17
  137. package/dist/core/tokenRegistry.d.ts +0 -23
  138. package/dist/core/tokenRegistry.js +0 -83
  139. package/dist/core/tokenRegistry.test.d.ts +0 -1
  140. package/dist/core/tokenRegistry.test.js +0 -133
  141. package/dist/engine/applyOperators.d.ts +0 -3
  142. package/dist/engine/applyOperators.js +0 -23
  143. package/dist/engine/context.d.ts +0 -4
  144. package/dist/engine/context.js +0 -1
  145. package/dist/engine/gamut.d.ts +0 -13
  146. package/dist/engine/gamut.js +0 -101
  147. package/dist/engine/gamut.test.d.ts +0 -1
  148. package/dist/engine/gamut.test.js +0 -23
  149. package/dist/engine/generateScale.d.ts +0 -15
  150. package/dist/engine/generateScale.js +0 -29
  151. package/dist/engine/generateScale.test.d.ts +0 -1
  152. package/dist/engine/generateScale.test.js +0 -32
  153. package/dist/engine/index.d.ts +0 -8
  154. package/dist/engine/index.js +0 -4
  155. package/dist/engine/normalize.d.ts +0 -43
  156. package/dist/engine/normalize.js +0 -403
  157. package/dist/engine/normalize.test.d.ts +0 -1
  158. package/dist/engine/normalize.test.js +0 -136
  159. package/dist/engine/onSolid.d.ts +0 -3
  160. package/dist/engine/onSolid.js +0 -110
  161. package/dist/engine/resolveBaseColor.d.ts +0 -25
  162. package/dist/engine/resolveBaseColor.js +0 -127
  163. package/dist/engine/resolveBaseColor.test.d.ts +0 -1
  164. package/dist/engine/resolveBaseColor.test.js +0 -97
  165. package/dist/export/__snapshots__/exportTheme.test.js.snap +0 -74
  166. package/dist/export/exportTheme.d.ts +0 -47
  167. package/dist/export/exportTheme.js +0 -170
  168. package/dist/export/exportTheme.test.d.ts +0 -1
  169. package/dist/export/exportTheme.test.js +0 -118
  170. package/dist/export/index.d.ts +0 -1
  171. package/dist/export/index.js +0 -1
  172. package/dist/export/serializeColor.d.ts +0 -1
  173. package/dist/export/serializeColor.js +0 -1
  174. package/dist/export/serializeColor.test.d.ts +0 -1
  175. package/dist/export/serializeColor.test.js +0 -54
  176. package/dist/export.d.ts +0 -1
  177. package/dist/export.js +0 -1
  178. package/dist/operators/emphasis.d.ts +0 -3
  179. package/dist/operators/emphasis.js +0 -113
  180. package/dist/operators/emphasis.test.d.ts +0 -1
  181. package/dist/operators/emphasis.test.js +0 -69
  182. package/dist/operators/index.d.ts +0 -3
  183. package/dist/operators/index.js +0 -2
  184. package/dist/operators/state.d.ts +0 -3
  185. package/dist/operators/state.js +0 -102
  186. package/dist/operators/state.test.d.ts +0 -1
  187. package/dist/operators/state.test.js +0 -48
  188. package/dist/operators/types.d.ts +0 -13
  189. package/dist/operators/types.js +0 -1
  190. package/dist/operators/utils.d.ts +0 -16
  191. package/dist/operators/utils.js +0 -23
  192. package/dist/presets/curves.d.ts +0 -28
  193. package/dist/presets/curves.js +0 -145
  194. package/dist/presets/index.d.ts +0 -2
  195. package/dist/presets/index.js +0 -1
  196. package/dist/presets/tokens/index.d.ts +0 -3
  197. package/dist/presets/tokens/index.js +0 -3
  198. package/dist/presets/tokens/minimal-ui.d.ts +0 -6
  199. package/dist/presets/tokens/minimal-ui.js +0 -53
  200. package/dist/presets/tokens/modern-ui.d.ts +0 -5
  201. package/dist/presets/tokens/modern-ui.js +0 -83
  202. package/dist/presets/tokens/presets.test.d.ts +0 -1
  203. package/dist/presets/tokens/presets.test.js +0 -31
  204. package/dist/presets/tokens/radixLike-ui.d.ts +0 -6
  205. package/dist/presets/tokens/radixLike-ui.js +0 -77
  206. package/dist/serialize/index.d.ts +0 -1
  207. package/dist/serialize/index.js +0 -1
  208. package/dist/serialize/normalizeOutput.d.ts +0 -6
  209. package/dist/serialize/normalizeOutput.js +0 -45
  210. package/dist/serialize/serializeColor.d.ts +0 -21
  211. package/dist/serialize/serializeColor.js +0 -178
  212. package/dist/serialize/serializeResolved.test.d.ts +0 -1
  213. package/dist/serialize/serializeResolved.test.js +0 -45
  214. package/dist/serialize.d.ts +0 -1
  215. package/dist/serialize.js +0 -1
  216. package/dist/utils/clamp.d.ts +0 -1
  217. package/dist/utils/clamp.js +0 -1
  218. package/dist/utils/index.d.ts +0 -1
  219. package/dist/utils/index.js +0 -1
  220. package/dist/utils/lerp.d.ts +0 -1
  221. package/dist/utils/lerp.js +0 -1
  222. package/dist/utils/parseColor.d.ts +0 -6
  223. package/dist/utils/parseColor.js +0 -67
  224. package/dist/utils/parseColor.test.d.ts +0 -1
  225. package/dist/utils/parseColor.test.js +0 -51
  226. package/dist/utils/smoothstep.d.ts +0 -1
  227. package/dist/utils/smoothstep.js +0 -5
  228. package/planning/phase-10-review.md +0 -550
  229. package/planning/phase-7-review.md +0 -411
  230. package/planning/phase-8-review.md +0 -669
  231. package/planning/phase-9-review.md +0 -564
  232. package/planning/roadmap-v0.3.md +0 -284
  233. package/planning/spec-serializer-v0.3.md +0 -324
  234. package/planning/spec-v0.3.md +0 -305
  235. package/src/cli/args.test.ts +0 -28
  236. package/src/cli/args.ts +0 -66
  237. package/src/cli/codegen/__snapshots__/tokens.test.ts.snap +0 -87
  238. package/src/cli/codegen/tokens.test.ts +0 -61
  239. package/src/cli/codegen/tokens.ts +0 -191
  240. package/src/cli/config.ts +0 -71
  241. package/src/cli/validate.test.ts +0 -49
  242. package/src/cli/validate.ts +0 -38
  243. package/src/cli.ts +0 -183
  244. package/src/contrast/apca.test.ts +0 -20
  245. package/src/contrast/apca.ts +0 -26
  246. package/src/contrast/index.ts +0 -4
  247. package/src/contrast/scoring.test.ts +0 -188
  248. package/src/contrast/scoring.ts +0 -48
  249. package/src/contrast/solver.test.ts +0 -147
  250. package/src/contrast/solver.ts +0 -235
  251. package/src/contrast/types.ts +0 -20
  252. package/src/contrast/utils.ts +0 -28
  253. package/src/contrast/wcag2.test.ts +0 -21
  254. package/src/contrast/wcag2.ts +0 -24
  255. package/src/core/createTheme.ts +0 -78
  256. package/src/core/dx-helpers.test.ts +0 -82
  257. package/src/core/index.ts +0 -7
  258. package/src/core/onSolid.test.ts +0 -146
  259. package/src/core/qa.v1.test.ts +0 -149
  260. package/src/core/resolve.test.ts +0 -99
  261. package/src/core/resolve.ts +0 -11
  262. package/src/core/resolveMany.ts +0 -22
  263. package/src/core/tokenRegistry.test.ts +0 -153
  264. package/src/core/tokenRegistry.ts +0 -114
  265. package/src/engine/applyOperators.ts +0 -32
  266. package/src/engine/context.ts +0 -8
  267. package/src/engine/gamut.test.ts +0 -30
  268. package/src/engine/gamut.ts +0 -144
  269. package/src/engine/generateScale.test.ts +0 -46
  270. package/src/engine/generateScale.ts +0 -48
  271. package/src/engine/index.ts +0 -8
  272. package/src/engine/normalize.test.ts +0 -222
  273. package/src/engine/normalize.ts +0 -550
  274. package/src/engine/onSolid.ts +0 -178
  275. package/src/engine/resolveBaseColor.test.ts +0 -117
  276. package/src/engine/resolveBaseColor.ts +0 -203
  277. package/src/export/__snapshots__/exportTheme.test.ts.snap +0 -74
  278. package/src/export/exportTheme.test.ts +0 -144
  279. package/src/export/exportTheme.ts +0 -251
  280. package/src/export/index.ts +0 -1
  281. package/src/export/serializeColor.test.ts +0 -73
  282. package/src/export/serializeColor.ts +0 -1
  283. package/src/export.ts +0 -1
  284. package/src/index.ts +0 -3
  285. package/src/operators/emphasis.test.ts +0 -85
  286. package/src/operators/emphasis.ts +0 -132
  287. package/src/operators/index.ts +0 -3
  288. package/src/operators/state.test.ts +0 -66
  289. package/src/operators/state.ts +0 -122
  290. package/src/operators/types.ts +0 -14
  291. package/src/operators/utils.ts +0 -44
  292. package/src/presets/curves.ts +0 -168
  293. package/src/presets/index.ts +0 -2
  294. package/src/presets/tokens/index.ts +0 -3
  295. package/src/presets/tokens/minimal-ui.ts +0 -55
  296. package/src/presets/tokens/modern-ui.ts +0 -85
  297. package/src/presets/tokens/presets.test.ts +0 -46
  298. package/src/presets/tokens/radixLike-ui.ts +0 -79
  299. package/src/serialize/index.ts +0 -1
  300. package/src/serialize/normalizeOutput.ts +0 -63
  301. package/src/serialize/serializeColor.ts +0 -260
  302. package/src/serialize/serializeResolved.test.ts +0 -57
  303. package/src/serialize.ts +0 -1
  304. package/src/types/index.ts +0 -207
  305. package/src/utils/clamp.ts +0 -2
  306. package/src/utils/index.ts +0 -1
  307. package/src/utils/lerp.ts +0 -1
  308. package/src/utils/parseColor.test.ts +0 -66
  309. package/src/utils/parseColor.ts +0 -87
  310. package/src/utils/smoothstep.ts +0 -6
  311. package/tsconfig.build.json +0 -11
  312. package/tsconfig.json +0 -15
@@ -1,127 +0,0 @@
1
- import { parseColor } from "../utils/parseColor.js";
2
- import { mapColorContextToEngine } from "./context.js";
3
- import { generateScale } from "./generateScale.js";
4
- import { normalizeQuery } from "./normalize.js";
5
- const isCategoryVariant = (variant) => variant.startsWith("category:");
6
- const isChartVariant = (variant) => variant.startsWith("chart:");
7
- const aliasVariants = new Set(["success", "warning", "danger", "info"]);
8
- const inferVariantFromRole = (role) => {
9
- const normalizedRole = role.toLowerCase();
10
- if (normalizedRole.startsWith("action.")) {
11
- return "accent";
12
- }
13
- if (normalizedRole.startsWith("bg.") ||
14
- normalizedRole.startsWith("surface.") ||
15
- normalizedRole.startsWith("border.") ||
16
- normalizedRole.startsWith("text.")) {
17
- return "neutral";
18
- }
19
- return "neutral";
20
- };
21
- const resolveVariantSeed = (variant, role, config, contextKey) => {
22
- if (variant) {
23
- if (variant === "neutral" || variant === "accent") {
24
- return {
25
- variantUsed: variant,
26
- seedUsed: config.seeds[contextKey][variant],
27
- };
28
- }
29
- if (isCategoryVariant(variant) || isChartVariant(variant)) {
30
- const customSeed = config.variants?.[variant];
31
- if (customSeed) {
32
- return { variantUsed: variant, seedUsed: customSeed };
33
- }
34
- return { variantUsed: "accent", seedUsed: config.seeds[contextKey].accent };
35
- }
36
- if (aliasVariants.has(variant)) {
37
- return { variantUsed: "accent", seedUsed: config.seeds[contextKey].accent };
38
- }
39
- return { variantUsed: "accent", seedUsed: config.seeds[contextKey].accent };
40
- }
41
- const inferredVariant = inferVariantFromRole(role);
42
- return {
43
- variantUsed: inferredVariant,
44
- seedUsed: config.seeds[contextKey][inferredVariant],
45
- };
46
- };
47
- const clampStep = (value) => Math.min(12, Math.max(1, value));
48
- const resolveStep = (usage, surface) => {
49
- switch (usage) {
50
- case "bg": {
51
- switch (surface) {
52
- case "app":
53
- return 1;
54
- case "surface":
55
- return 2;
56
- case "subtle":
57
- return 3;
58
- case "solid":
59
- return 9;
60
- case "overlay":
61
- return 2;
62
- case "data":
63
- return 9;
64
- case "transparent":
65
- return 1;
66
- default:
67
- return 2;
68
- }
69
- }
70
- case "border": {
71
- switch (surface) {
72
- case "solid":
73
- case "data":
74
- return 8;
75
- default:
76
- return 6;
77
- }
78
- }
79
- case "text":
80
- return 11;
81
- case "icon":
82
- return 11;
83
- case "ring":
84
- return 8;
85
- case "stroke":
86
- return surface === "data" ? 9 : 8;
87
- case "fill":
88
- return 9;
89
- default:
90
- return 6;
91
- }
92
- };
93
- // Best-effort guard: ColorQuery may include state/emphasis already; a branded flag
94
- // from normalizeQuery would be the strict approach in a future version.
95
- const isNormalizedQuery = (value) => typeof value === "object" &&
96
- value !== null &&
97
- typeof value.role === "string" &&
98
- typeof value.usage === "string" &&
99
- typeof value.surface === "string" &&
100
- typeof value.context === "string" &&
101
- typeof value.state === "string" &&
102
- typeof value.emphasis === "string";
103
- export function resolveBaseColor(query, theme) {
104
- const normalized = isNormalizedQuery(query) ? query : normalizeQuery(query);
105
- const contextKey = mapColorContextToEngine(normalized.context);
106
- const { variantUsed, seedUsed } = resolveVariantSeed(normalized.variant, normalized.role, theme, contextKey);
107
- const parsedSeed = parseColor(seedUsed);
108
- const seed = {
109
- l: parsedSeed.okLch.channels[0] * 100,
110
- c: parsedSeed.okLch.channels[1],
111
- h: parsedSeed.okLch.channels[2],
112
- alpha: parsedSeed.okLch.alpha,
113
- };
114
- const scale = generateScale(seed, {
115
- context: contextKey,
116
- surface: normalized.surface,
117
- preset: theme.preset,
118
- });
119
- const step = clampStep(resolveStep(normalized.usage, normalized.surface));
120
- const oklch = scale[step - 1];
121
- return {
122
- oklch,
123
- step,
124
- variantUsed,
125
- seedUsed,
126
- };
127
- }
@@ -1 +0,0 @@
1
- export {};
@@ -1,97 +0,0 @@
1
- import { describe, expect, it } from "vitest";
2
- import { parseColor } from "../utils/parseColor.js";
3
- import { normalizeQuery } from "./normalize.js";
4
- import { resolveBaseColor } from "./resolveBaseColor.js";
5
- const themeConfig = {
6
- seeds: {
7
- light: { neutral: "#8B8D98", accent: "#3D63DD" },
8
- dark: { neutral: "#8B8D98", accent: "#3D63DD" },
9
- },
10
- variants: {
11
- "category:food": "#C2410C",
12
- },
13
- preset: "modern",
14
- };
15
- describe("resolveBaseColor", () => {
16
- const r = (query) => resolveBaseColor(normalizeQuery(query), themeConfig);
17
- it("defaults action roles to accent when variant is missing", () => {
18
- const result = r({
19
- role: "action.primary",
20
- usage: "bg",
21
- surface: "solid",
22
- context: "light",
23
- });
24
- expect(result.variantUsed).toBe("accent");
25
- expect(result.seedUsed).toBe(themeConfig.seeds.light.accent);
26
- });
27
- it("defaults text roles to neutral when variant is missing", () => {
28
- const result = r({
29
- role: "text.primary",
30
- usage: "text",
31
- surface: "surface",
32
- context: "light",
33
- });
34
- expect(result.variantUsed).toBe("neutral");
35
- expect(result.seedUsed).toBe(themeConfig.seeds.light.neutral);
36
- });
37
- it("uses custom category variants when provided", () => {
38
- const result = r({
39
- role: "bg.category",
40
- variant: "category:food",
41
- usage: "bg",
42
- surface: "surface",
43
- context: "light",
44
- });
45
- expect(result.variantUsed).toBe("category:food");
46
- expect(result.seedUsed).toBe(themeConfig.variants?.["category:food"]);
47
- });
48
- it("falls back to accent for missing category variants", () => {
49
- const result = r({
50
- role: "bg.category",
51
- variant: "category:missing",
52
- usage: "bg",
53
- surface: "surface",
54
- context: "light",
55
- });
56
- expect(result.variantUsed).toBe("accent");
57
- expect(result.seedUsed).toBe(themeConfig.seeds.light.accent);
58
- });
59
- it("chooses steps based on usage and surface", () => {
60
- const appBg = r({ role: "bg.app", usage: "bg", surface: "app", context: "light" });
61
- const solidBg = r({ role: "bg.solid", usage: "bg", surface: "solid", context: "light" });
62
- const borderSurface = r({
63
- role: "border.surface",
64
- usage: "border",
65
- surface: "surface",
66
- context: "light",
67
- });
68
- const ring = r({ role: "ring.focus", usage: "ring", surface: "surface", context: "light" });
69
- expect(appBg.step).toBe(1);
70
- expect(solidBg.step).toBe(9);
71
- expect(borderSurface.step).toBe(6);
72
- expect(ring.step).toBe(8);
73
- });
74
- it("returns valid OKLCH values with stable hue", () => {
75
- const result = r({
76
- role: "action.primary",
77
- usage: "bg",
78
- surface: "solid",
79
- context: "light",
80
- });
81
- const seed = parseColor(themeConfig.seeds.light.accent);
82
- expect(result.oklch.l).toBeGreaterThanOrEqual(0);
83
- expect(result.oklch.l).toBeLessThanOrEqual(100);
84
- expect(result.oklch.c).toBeGreaterThanOrEqual(0);
85
- expect(result.oklch.h).toBeCloseTo(seed.okLch.channels[2], 6);
86
- });
87
- it("accepts normalized queries without re-normalizing", () => {
88
- const normalized = normalizeQuery({
89
- role: "text.secondary",
90
- usage: "text",
91
- surface: "surface",
92
- context: "dark",
93
- });
94
- const result = resolveBaseColor(normalized, themeConfig);
95
- expect(result.step).toBe(11);
96
- });
97
- });
@@ -1,74 +0,0 @@
1
- // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
2
-
3
- exports[`exportTheme > exports deterministic CSS with @supports overrides 1`] = `
4
- ":root {
5
- --pk-bg-app: #dddee1;
6
- --pk-custom-alias: #f1f4fb;
7
- --pk-text-primary: #f1f4fb;
8
- }
9
-
10
- @supports (color: oklch(0% 0 0)) {
11
- :root {
12
- --pk-bg-app: oklch(90% 0.004 264.7);
13
- --pk-bg-app-oklch: oklch(90% 0.004 264.7);
14
- --pk-custom-alias: oklch(96.7% 0.01 264.7);
15
- --pk-custom-alias-oklch: oklch(96.7% 0.01 264.7);
16
- --pk-text-primary: oklch(96.7% 0.01 264.7);
17
- --pk-text-primary-oklch: oklch(96.7% 0.01 264.7);
18
- }
19
- }
20
-
21
- @supports (color: color(display-p3 1 1 1)) {
22
- :root {
23
- --pk-bg-app-p3: color(display-p3 0.866 0.87 0.88);
24
- --pk-custom-alias-p3: color(display-p3 0.947 0.957 0.981);
25
- --pk-text-primary-p3: color(display-p3 0.947 0.957 0.981);
26
- }
27
- }
28
- "
29
- `;
30
-
31
- exports[`exportTheme > exports deterministic JSON with light/dark contexts 1`] = `
32
- {
33
- "dark": {
34
- "bg.app": {
35
- "alpha": 1,
36
- "oklch": "oklch(6% 0.004 264.7)",
37
- "srgb": "#010101",
38
- "value": "oklch(6% 0.004 264.7)",
39
- },
40
- "custom.alias": {
41
- "alpha": 1,
42
- "oklch": "oklch(27.5% 0.01 264.7)",
43
- "srgb": "#25282d",
44
- "value": "oklch(27.5% 0.01 264.7)",
45
- },
46
- "text.primary": {
47
- "alpha": 1,
48
- "oklch": "oklch(27.5% 0.01 264.7)",
49
- "srgb": "#25282d",
50
- "value": "oklch(27.5% 0.01 264.7)",
51
- },
52
- },
53
- "light": {
54
- "bg.app": {
55
- "alpha": 1,
56
- "oklch": "oklch(90% 0.004 264.7)",
57
- "srgb": "#dddee1",
58
- "value": "oklch(90% 0.004 264.7)",
59
- },
60
- "custom.alias": {
61
- "alpha": 1,
62
- "oklch": "oklch(96.7% 0.01 264.7)",
63
- "srgb": "#f1f4fb",
64
- "value": "oklch(96.7% 0.01 264.7)",
65
- },
66
- "text.primary": {
67
- "alpha": 1,
68
- "oklch": "oklch(96.7% 0.01 264.7)",
69
- "srgb": "#f1f4fb",
70
- "value": "oklch(96.7% 0.01 264.7)",
71
- },
72
- },
73
- }
74
- `;
@@ -1,47 +0,0 @@
1
- import type { OkLchColor } from "../engine/generateScale.js";
2
- import type { ColorMeta, ColorQuery, OutputOptions } from "../types/index.js";
3
- export type ThemeToken = Omit<ColorQuery, "role" | "output"> & {
4
- role?: string;
5
- };
6
- export type ThemeTokens = Record<string, ThemeToken>;
7
- export type ExportableTheme = {
8
- resolve: (query: ColorQuery) => {
9
- oklch: OkLchColor;
10
- };
11
- };
12
- export type TokenValue = {
13
- value: string;
14
- srgb?: string;
15
- p3?: string;
16
- oklch?: string;
17
- alpha: number;
18
- meta?: ColorMeta;
19
- };
20
- export type ExportMeta = {
21
- gamutMapping: NonNullable<OutputOptions["gamutMapping"]>;
22
- preferSpace: NonNullable<OutputOptions["preferSpace"]>;
23
- includeSpaces: NonNullable<OutputOptions["includeSpaces"]>;
24
- precision: Required<NonNullable<OutputOptions["precision"]>>;
25
- srgbFormat: NonNullable<OutputOptions["srgbFormat"]>;
26
- strict: boolean;
27
- };
28
- /**
29
- * Export CSS variables for a token map with progressive fallbacks.
30
- *
31
- * - Base output uses sRGB for maximum compatibility.
32
- * - @supports blocks override the main token value with OKLCH and/or P3 as requested.
33
- */
34
- export declare const exportThemeCss: (theme: ExportableTheme, tokens: ThemeTokens, output?: OutputOptions) => {
35
- css: string;
36
- meta: ExportMeta | undefined;
37
- };
38
- /**
39
- * Export JSON tokens for both light and dark contexts.
40
- */
41
- export declare const exportThemeJson: (theme: ExportableTheme, tokens: ThemeTokens, output?: OutputOptions) => {
42
- tokens: {
43
- light: Record<string, TokenValue>;
44
- dark: Record<string, TokenValue>;
45
- };
46
- meta: ExportMeta | undefined;
47
- };
@@ -1,170 +0,0 @@
1
- import { serializeColorJson } from "../serialize/serializeColor.js";
2
- import { serializeColor } from "./serializeColor.js";
3
- const DEFAULT_OUTPUT = {
4
- preferSpace: "oklch",
5
- includeSpaces: [],
6
- gamutMapping: "preferP3ThenCompress",
7
- precision: { l: 1, c: 3, h: 1, alpha: 2 },
8
- srgbFormat: "hex",
9
- strict: false,
10
- includeMeta: false,
11
- };
12
- const normalizeExportOutput = (output) => ({
13
- preferSpace: output?.preferSpace ?? DEFAULT_OUTPUT.preferSpace,
14
- includeSpaces: output?.includeSpaces ?? DEFAULT_OUTPUT.includeSpaces,
15
- gamutMapping: output?.gamutMapping ?? DEFAULT_OUTPUT.gamutMapping,
16
- precision: {
17
- ...DEFAULT_OUTPUT.precision,
18
- ...output?.precision,
19
- },
20
- srgbFormat: output?.srgbFormat ?? DEFAULT_OUTPUT.srgbFormat,
21
- strict: output?.strict ?? DEFAULT_OUTPUT.strict,
22
- includeMeta: output?.includeMeta ?? DEFAULT_OUTPUT.includeMeta,
23
- });
24
- const buildExportMeta = (output) => ({
25
- gamutMapping: output.gamutMapping,
26
- preferSpace: output.preferSpace,
27
- includeSpaces: output.includeSpaces,
28
- precision: output.precision,
29
- srgbFormat: output.srgbFormat,
30
- strict: output.strict,
31
- });
32
- const getTokenEntries = (tokens) => {
33
- if (!tokens || Object.keys(tokens).length === 0) {
34
- throw new Error("Theme tokens are required for export");
35
- }
36
- return Object.entries(tokens).sort(([a], [b]) => a.localeCompare(b));
37
- };
38
- const getTokenRole = (name, token) => token.role ?? name;
39
- const buildTokenQuery = (name, token, context) => {
40
- const { role: _role, ...rest } = token;
41
- return {
42
- ...rest,
43
- role: getTokenRole(name, token),
44
- ...(context ? { context } : {}),
45
- };
46
- };
47
- const buildTokenMeta = (name, token, context) => ({
48
- role: getTokenRole(name, token),
49
- ...(token.variant ? { variant: token.variant } : {}),
50
- ...(token.usage ? { usage: token.usage } : {}),
51
- ...(context ? { context } : token.context ? { context: token.context } : {}),
52
- ...(token.surface ? { surface: token.surface } : {}),
53
- ...(token.state ? { state: token.state } : {}),
54
- ...(token.emphasis ? { emphasis: token.emphasis } : {}),
55
- ...(token.on ? { on: token.on } : {}),
56
- ...(token.contrast ? { contrast: token.contrast } : {}),
57
- });
58
- const buildTokenValue = (serialized) => ({
59
- value: serialized.value,
60
- ...(serialized.srgb !== undefined ? { srgb: serialized.srgb } : {}),
61
- ...(serialized.p3 !== undefined ? { p3: serialized.p3 } : {}),
62
- ...(serialized.oklch !== undefined ? { oklch: serialized.oklch } : {}),
63
- alpha: serialized.alpha,
64
- ...(serialized.meta !== undefined ? { meta: serialized.meta } : {}),
65
- });
66
- const toCssVarName = (name) => name.replace(/\./g, "-");
67
- const indent = (lines, prefix) => lines.length === 0 ? "" : lines.map((line) => `${prefix}${line}`).join("\n");
68
- /**
69
- * Export CSS variables for a token map with progressive fallbacks.
70
- *
71
- * - Base output uses sRGB for maximum compatibility.
72
- * - @supports blocks override the main token value with OKLCH and/or P3 as requested.
73
- */
74
- export const exportThemeCss = (theme, tokens, output) => {
75
- const normalized = normalizeExportOutput(output);
76
- const entries = getTokenEntries(tokens);
77
- const baseDecl = [];
78
- const oklchDecl = [];
79
- const p3Decl = [];
80
- const needsOklch = normalized.preferSpace === "oklch" || normalized.includeSpaces.includes("oklch");
81
- const needsP3 = normalized.preferSpace === "p3" || normalized.includeSpaces.includes("p3");
82
- for (const [name, token] of entries) {
83
- const query = buildTokenQuery(name, token);
84
- const resolved = theme.resolve(query);
85
- const meta = normalized.includeMeta ? buildTokenMeta(name, token) : undefined;
86
- const baseName = toCssVarName(name);
87
- // Base fallback MUST be sRGB (no silent OKLCH fallback).
88
- const baseSrgb = serializeColor(resolved.oklch, { ...normalized, preferSpace: "srgb", includeSpaces: [], strict: normalized.strict }, meta).value;
89
- baseDecl.push(`--pk-${baseName}: ${baseSrgb};`);
90
- if (normalized.includeSpaces.includes("srgb")) {
91
- baseDecl.push(`--pk-${baseName}-srgb: ${baseSrgb};`);
92
- }
93
- if (needsOklch) {
94
- const oklchValue = serializeColor(resolved.oklch, { ...normalized, preferSpace: "oklch", includeSpaces: [] }, meta).value;
95
- if (normalized.preferSpace === "oklch") {
96
- oklchDecl.push(`--pk-${baseName}: ${oklchValue};`);
97
- }
98
- if (normalized.includeSpaces.includes("oklch")) {
99
- oklchDecl.push(`--pk-${baseName}-oklch: ${oklchValue};`);
100
- }
101
- }
102
- if (needsP3) {
103
- const p3Text = serializeColor(resolved.oklch, { ...normalized, preferSpace: "oklch", includeSpaces: ["p3"] }, meta).p3;
104
- if (normalized.preferSpace === "p3") {
105
- if (!p3Text) {
106
- if (normalized.strict) {
107
- throw new Error("Unable to serialize preferred space: p3");
108
- }
109
- }
110
- else {
111
- p3Decl.push(`--pk-${baseName}: ${p3Text};`);
112
- }
113
- }
114
- if (normalized.includeSpaces.includes("p3") && p3Text) {
115
- p3Decl.push(`--pk-${baseName}-p3: ${p3Text};`);
116
- }
117
- }
118
- }
119
- const blocks = [];
120
- blocks.push(`:root {\n${indent(baseDecl, " ")}\n}\n`);
121
- if (oklchDecl.length > 0) {
122
- blocks.push(`@supports (color: oklch(0% 0 0)) {\n :root {\n${indent(oklchDecl, " ")}\n }\n}\n`);
123
- }
124
- if (p3Decl.length > 0) {
125
- blocks.push(`@supports (color: color(display-p3 1 1 1)) {\n :root {\n${indent(p3Decl, " ")}\n }\n}\n`);
126
- }
127
- return {
128
- css: `${blocks.join("\n").trimEnd()}\n`,
129
- meta: normalized.includeMeta ? buildExportMeta(normalized) : undefined,
130
- };
131
- };
132
- /**
133
- * Export JSON tokens for both light and dark contexts.
134
- */
135
- export const exportThemeJson = (theme, tokens, output) => {
136
- const normalized = normalizeExportOutput(output);
137
- const entries = getTokenEntries(tokens);
138
- const lightTokens = {};
139
- const darkTokens = {};
140
- const contexts = ["light", "dark"];
141
- for (const [name, token] of entries) {
142
- for (const context of contexts) {
143
- const query = buildTokenQuery(name, token, context);
144
- const resolved = theme.resolve(query);
145
- const meta = normalized.includeMeta ? buildTokenMeta(name, token, context) : undefined;
146
- const serialized = serializeColorJson(resolved.oklch, normalized, meta);
147
- const entry = buildTokenValue({
148
- value: serialized.value,
149
- srgb: serialized.srgb,
150
- p3: serialized.p3,
151
- oklch: serialized.oklch,
152
- alpha: serialized.alpha,
153
- meta: serialized.meta,
154
- });
155
- if (context === "light") {
156
- lightTokens[name] = entry;
157
- }
158
- else {
159
- darkTokens[name] = entry;
160
- }
161
- }
162
- }
163
- return {
164
- tokens: {
165
- light: lightTokens,
166
- dark: darkTokens,
167
- },
168
- meta: normalized.includeMeta ? buildExportMeta(normalized) : undefined,
169
- };
170
- };
@@ -1 +0,0 @@
1
- export {};
@@ -1,118 +0,0 @@
1
- import { describe, expect, it, vi } from "vitest";
2
- import { createTheme } from "../core/createTheme.js";
3
- import * as gamut from "../engine/gamut.js";
4
- import { exportThemeCss, exportThemeJson } from "./exportTheme.js";
5
- const buildTheme = () => {
6
- const theme = createTheme({
7
- seeds: {
8
- light: { neutral: "#111827", accent: "#3d63dd" },
9
- dark: { neutral: "#111827", accent: "#3d63dd" },
10
- },
11
- });
12
- const tokens = {
13
- "text.primary": {
14
- usage: "text",
15
- surface: "surface",
16
- emphasis: "default",
17
- },
18
- "bg.app": {
19
- usage: "bg",
20
- surface: "app",
21
- },
22
- "custom.alias": {
23
- role: "text.primary",
24
- usage: "text",
25
- surface: "surface",
26
- },
27
- };
28
- return {
29
- resolve: theme.resolve.bind(theme),
30
- tokens,
31
- };
32
- };
33
- describe("exportTheme", () => {
34
- it("throws when theme tokens are missing", () => {
35
- const theme = createTheme({
36
- seeds: {
37
- light: { neutral: "#111827", accent: "#3d63dd" },
38
- dark: { neutral: "#111827", accent: "#3d63dd" },
39
- },
40
- });
41
- expect(() => exportThemeCss(theme, {})).toThrow(/Theme tokens are required for export/i);
42
- expect(() => exportThemeJson(theme, {})).toThrow(/Theme tokens are required for export/i);
43
- });
44
- it("exports deterministic CSS with @supports overrides", () => {
45
- const theme = buildTheme();
46
- const { css } = exportThemeCss(theme, theme.tokens, {
47
- preferSpace: "oklch",
48
- includeSpaces: ["p3", "oklch"],
49
- });
50
- expect(css).toMatchSnapshot();
51
- });
52
- it("includes meta when requested and omits when not", () => {
53
- const theme = buildTheme();
54
- const withMeta = exportThemeJson(theme, theme.tokens, { includeMeta: true });
55
- expect(withMeta.tokens.light["bg.app"].meta?.gamutMapping).toBe("preferP3ThenCompress");
56
- expect(withMeta.meta).toEqual({
57
- gamutMapping: "preferP3ThenCompress",
58
- preferSpace: "oklch",
59
- includeSpaces: [],
60
- precision: { l: 1, c: 3, h: 1, alpha: 2 },
61
- srgbFormat: "hex",
62
- strict: false,
63
- });
64
- const withoutMeta = exportThemeJson(theme, theme.tokens, { includeMeta: false });
65
- expect(withoutMeta.tokens.light["bg.app"].meta).toBeUndefined();
66
- });
67
- it("includes export meta for CSS when requested", () => {
68
- const theme = buildTheme();
69
- const { meta } = exportThemeCss(theme, theme.tokens, { includeMeta: true });
70
- expect(meta).toEqual({
71
- gamutMapping: "preferP3ThenCompress",
72
- preferSpace: "oklch",
73
- includeSpaces: [],
74
- precision: { l: 1, c: 3, h: 1, alpha: 2 },
75
- srgbFormat: "hex",
76
- strict: false,
77
- });
78
- });
79
- it("exports deterministic JSON with light/dark contexts", () => {
80
- const theme = buildTheme();
81
- const { tokens } = exportThemeJson(theme, theme.tokens, {
82
- preferSpace: "oklch",
83
- includeSpaces: ["srgb"],
84
- });
85
- expect(tokens).toMatchSnapshot();
86
- });
87
- it("keeps ordering stable regardless of token map order", () => {
88
- const theme = buildTheme();
89
- const shuffled = {
90
- "custom.alias": theme.tokens["custom.alias"],
91
- "bg.app": theme.tokens["bg.app"],
92
- "text.primary": theme.tokens["text.primary"],
93
- };
94
- const cssA = exportThemeCss(theme, theme.tokens, { preferSpace: "oklch" }).css;
95
- const cssB = exportThemeCss(theme, shuffled, { preferSpace: "oklch" }).css;
96
- const jsonA = exportThemeJson(theme, theme.tokens, { preferSpace: "oklch" }).tokens;
97
- const jsonB = exportThemeJson(theme, shuffled, { preferSpace: "oklch" }).tokens;
98
- expect(cssA).toBe(cssB);
99
- expect(jsonA).toEqual(jsonB);
100
- });
101
- it("throws when strict preferred space cannot be serialized", () => {
102
- const theme = buildTheme();
103
- const original = gamut.toGamutRgb;
104
- const spy = vi
105
- .spyOn(gamut, "toGamutRgb")
106
- .mockImplementation((color, target) => (target === "p3" ? null : original(color, target)));
107
- try {
108
- expect(() => exportThemeCss(theme, theme.tokens, {
109
- preferSpace: "p3",
110
- includeSpaces: ["p3"],
111
- strict: true,
112
- })).toThrow(/Unable to serialize preferred space: p3/i);
113
- }
114
- finally {
115
- spy.mockRestore();
116
- }
117
- });
118
- });
@@ -1 +0,0 @@
1
- export * from "./exportTheme.js";
@@ -1 +0,0 @@
1
- export * from "./exportTheme.js";
@@ -1 +0,0 @@
1
- export { serializeColor } from "../serialize/serializeColor.js";
@@ -1 +0,0 @@
1
- export { serializeColor } from "../serialize/serializeColor.js";
@@ -1 +0,0 @@
1
- export {};