@clhaas/palette-kit 0.1.7 → 0.3.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 (293) hide show
  1. package/.codex/skills/color-pipeline-implementer/SKILL.md +23 -0
  2. package/.codex/skills/commit-message-crafter/SKILL.md +63 -0
  3. package/.codex/skills/commit-message-crafter/references/benchmarks.md +20 -0
  4. package/.codex/skills/contrast-solver-helper/SKILL.md +20 -0
  5. package/.codex/skills/exporters-builder/SKILL.md +20 -0
  6. package/.codex/skills/markdownlint-writer/SKILL.md +32 -0
  7. package/.codex/skills/phase-implementation-runbook/SKILL.md +92 -0
  8. package/.codex/skills/type-contract-auditor/SKILL.md +21 -0
  9. package/.github/skills/review-guide/SKILL.md +23 -0
  10. package/.github/skills/review-guide/references/review-guide-v0.3.md +629 -0
  11. package/.markdownlint.json +4 -0
  12. package/AGENTS.md +16 -0
  13. package/CHANGELOG.md +34 -0
  14. package/README.md +79 -169
  15. package/biome.json +43 -0
  16. package/dist/cli/args.d.ts +12 -0
  17. package/dist/cli/args.js +56 -0
  18. package/dist/cli/args.test.js +22 -0
  19. package/dist/cli/codegen/__snapshots__/tokens.test.js.snap +87 -0
  20. package/dist/cli/codegen/tokens.d.ts +12 -0
  21. package/dist/cli/codegen/tokens.js +139 -0
  22. package/dist/cli/codegen/tokens.test.d.ts +1 -0
  23. package/dist/cli/codegen/tokens.test.js +51 -0
  24. package/dist/cli/config.d.ts +40 -0
  25. package/dist/cli/config.js +34 -0
  26. package/dist/cli/validate.d.ts +2 -0
  27. package/dist/cli/validate.js +33 -0
  28. package/dist/cli/validate.test.d.ts +1 -0
  29. package/dist/cli/validate.test.js +40 -0
  30. package/dist/cli.js +138 -140
  31. package/dist/contrast/apca.d.ts +2 -2
  32. package/dist/contrast/apca.js +14 -4
  33. package/dist/contrast/apca.test.d.ts +1 -0
  34. package/dist/contrast/apca.test.js +16 -0
  35. package/dist/contrast/index.d.ts +4 -0
  36. package/dist/contrast/index.js +4 -0
  37. package/dist/contrast/scoring.d.ts +4 -0
  38. package/dist/contrast/scoring.js +31 -0
  39. package/dist/contrast/scoring.test.d.ts +1 -0
  40. package/dist/contrast/scoring.test.js +148 -0
  41. package/dist/contrast/solver.d.ts +13 -0
  42. package/dist/contrast/solver.js +170 -0
  43. package/dist/contrast/solver.test.d.ts +1 -0
  44. package/dist/contrast/solver.test.js +75 -0
  45. package/dist/contrast/types.d.ts +17 -0
  46. package/dist/contrast/types.js +1 -0
  47. package/dist/contrast/utils.d.ts +4 -0
  48. package/dist/contrast/utils.js +18 -0
  49. package/dist/contrast/wcag2.d.ts +3 -0
  50. package/dist/contrast/wcag2.js +19 -0
  51. package/dist/contrast/wcag2.test.d.ts +1 -0
  52. package/dist/contrast/wcag2.test.js +17 -0
  53. package/dist/core/createTheme.d.ts +35 -0
  54. package/dist/core/createTheme.js +24 -0
  55. package/dist/core/dx-helpers.test.d.ts +1 -0
  56. package/dist/core/dx-helpers.test.js +61 -0
  57. package/dist/core/index.d.ts +2 -0
  58. package/dist/core/index.js +2 -0
  59. package/dist/core/onSolid.test.d.ts +1 -0
  60. package/dist/core/onSolid.test.js +118 -0
  61. package/dist/core/qa.v1.test.d.ts +1 -0
  62. package/dist/core/qa.v1.test.js +112 -0
  63. package/dist/core/resolve.d.ts +3 -0
  64. package/dist/core/resolve.js +8 -0
  65. package/dist/core/resolve.test.d.ts +1 -0
  66. package/dist/core/resolve.test.js +89 -0
  67. package/dist/core/resolveMany.d.ts +8 -0
  68. package/dist/core/resolveMany.js +17 -0
  69. package/dist/core/tokenRegistry.d.ts +23 -0
  70. package/dist/core/tokenRegistry.js +83 -0
  71. package/dist/core/tokenRegistry.test.d.ts +1 -0
  72. package/dist/core/tokenRegistry.test.js +133 -0
  73. package/dist/engine/applyOperators.d.ts +3 -0
  74. package/dist/engine/applyOperators.js +23 -0
  75. package/dist/engine/context.d.ts +4 -0
  76. package/dist/engine/context.js +1 -0
  77. package/dist/engine/gamut.d.ts +13 -0
  78. package/dist/engine/gamut.js +101 -0
  79. package/dist/engine/gamut.test.d.ts +1 -0
  80. package/dist/engine/gamut.test.js +23 -0
  81. package/dist/engine/generateScale.d.ts +15 -0
  82. package/dist/engine/generateScale.js +29 -0
  83. package/dist/engine/generateScale.test.d.ts +1 -0
  84. package/dist/engine/generateScale.test.js +32 -0
  85. package/dist/engine/index.d.ts +8 -0
  86. package/dist/engine/index.js +4 -0
  87. package/dist/engine/normalize.d.ts +43 -0
  88. package/dist/engine/normalize.js +403 -0
  89. package/dist/engine/normalize.test.d.ts +1 -0
  90. package/dist/engine/normalize.test.js +136 -0
  91. package/dist/engine/onSolid.d.ts +3 -0
  92. package/dist/engine/onSolid.js +110 -0
  93. package/dist/engine/resolveBaseColor.d.ts +25 -0
  94. package/dist/engine/resolveBaseColor.js +127 -0
  95. package/dist/engine/resolveBaseColor.test.d.ts +1 -0
  96. package/dist/engine/resolveBaseColor.test.js +97 -0
  97. package/dist/export/__snapshots__/exportTheme.test.js.snap +74 -0
  98. package/dist/export/exportTheme.d.ts +47 -0
  99. package/dist/export/exportTheme.js +170 -0
  100. package/dist/export/exportTheme.test.d.ts +1 -0
  101. package/dist/export/exportTheme.test.js +118 -0
  102. package/dist/export/index.d.ts +1 -0
  103. package/dist/export/index.js +1 -0
  104. package/dist/export/serializeColor.d.ts +1 -0
  105. package/dist/export/serializeColor.js +1 -0
  106. package/dist/export/serializeColor.test.d.ts +1 -0
  107. package/dist/export/serializeColor.test.js +54 -0
  108. package/dist/export.d.ts +1 -0
  109. package/dist/export.js +1 -0
  110. package/dist/index.d.ts +3 -20
  111. package/dist/index.js +2 -17
  112. package/dist/operators/emphasis.d.ts +3 -0
  113. package/dist/operators/emphasis.js +113 -0
  114. package/dist/operators/emphasis.test.d.ts +1 -0
  115. package/dist/operators/emphasis.test.js +69 -0
  116. package/dist/operators/index.d.ts +3 -0
  117. package/dist/operators/index.js +2 -0
  118. package/dist/operators/state.d.ts +3 -0
  119. package/dist/operators/state.js +102 -0
  120. package/dist/operators/state.test.d.ts +1 -0
  121. package/dist/operators/state.test.js +48 -0
  122. package/dist/operators/types.d.ts +13 -0
  123. package/dist/operators/types.js +1 -0
  124. package/dist/operators/utils.d.ts +16 -0
  125. package/dist/operators/utils.js +23 -0
  126. package/dist/presets/curves.d.ts +28 -0
  127. package/dist/presets/curves.js +145 -0
  128. package/dist/presets/index.d.ts +2 -0
  129. package/dist/presets/index.js +1 -0
  130. package/dist/presets/tokens/index.d.ts +3 -0
  131. package/dist/presets/tokens/index.js +3 -0
  132. package/dist/presets/tokens/minimal-ui.d.ts +6 -0
  133. package/dist/presets/tokens/minimal-ui.js +53 -0
  134. package/dist/presets/tokens/modern-ui.d.ts +5 -0
  135. package/dist/presets/tokens/modern-ui.js +83 -0
  136. package/dist/presets/tokens/presets.test.d.ts +1 -0
  137. package/dist/presets/tokens/presets.test.js +31 -0
  138. package/dist/presets/tokens/radixLike-ui.d.ts +6 -0
  139. package/dist/presets/tokens/radixLike-ui.js +77 -0
  140. package/dist/serialize/index.d.ts +1 -0
  141. package/dist/serialize/index.js +1 -0
  142. package/dist/serialize/normalizeOutput.d.ts +6 -0
  143. package/dist/serialize/normalizeOutput.js +45 -0
  144. package/dist/serialize/serializeColor.d.ts +21 -0
  145. package/dist/serialize/serializeColor.js +178 -0
  146. package/dist/serialize/serializeResolved.test.d.ts +1 -0
  147. package/dist/serialize/serializeResolved.test.js +45 -0
  148. package/dist/serialize.d.ts +1 -0
  149. package/dist/serialize.js +1 -0
  150. package/dist/types/index.d.ts +187 -0
  151. package/dist/types/index.js +1 -0
  152. package/dist/utils/clamp.d.ts +1 -0
  153. package/dist/utils/clamp.js +1 -0
  154. package/dist/utils/index.d.ts +1 -0
  155. package/dist/utils/index.js +1 -0
  156. package/dist/utils/lerp.d.ts +1 -0
  157. package/dist/utils/lerp.js +1 -0
  158. package/dist/utils/parseColor.d.ts +6 -0
  159. package/dist/utils/parseColor.js +67 -0
  160. package/dist/utils/parseColor.test.d.ts +1 -0
  161. package/dist/utils/parseColor.test.js +51 -0
  162. package/dist/utils/smoothstep.d.ts +1 -0
  163. package/dist/utils/smoothstep.js +5 -0
  164. package/package.json +19 -12
  165. package/planning/phase-10-review.md +550 -0
  166. package/planning/phase-7-review.md +411 -0
  167. package/planning/phase-8-review.md +669 -0
  168. package/planning/phase-9-review.md +564 -0
  169. package/planning/roadmap-v0.3.md +284 -0
  170. package/planning/spec-serializer-v0.3.md +324 -0
  171. package/planning/spec-v0.3.md +305 -0
  172. package/src/cli/args.test.ts +28 -0
  173. package/src/cli/args.ts +66 -0
  174. package/src/cli/codegen/__snapshots__/tokens.test.ts.snap +87 -0
  175. package/src/cli/codegen/tokens.test.ts +61 -0
  176. package/src/cli/codegen/tokens.ts +191 -0
  177. package/src/cli/config.ts +71 -0
  178. package/src/cli/validate.test.ts +49 -0
  179. package/src/cli/validate.ts +38 -0
  180. package/src/cli.ts +183 -0
  181. package/src/contrast/apca.test.ts +20 -0
  182. package/src/contrast/apca.ts +26 -0
  183. package/src/contrast/index.ts +4 -0
  184. package/src/contrast/scoring.test.ts +188 -0
  185. package/src/contrast/scoring.ts +48 -0
  186. package/src/contrast/solver.test.ts +147 -0
  187. package/src/contrast/solver.ts +235 -0
  188. package/src/contrast/types.ts +20 -0
  189. package/src/contrast/utils.ts +28 -0
  190. package/src/contrast/wcag2.test.ts +21 -0
  191. package/src/contrast/wcag2.ts +24 -0
  192. package/src/core/createTheme.ts +78 -0
  193. package/src/core/dx-helpers.test.ts +82 -0
  194. package/src/core/index.ts +7 -0
  195. package/src/core/onSolid.test.ts +146 -0
  196. package/src/core/qa.v1.test.ts +149 -0
  197. package/src/core/resolve.test.ts +99 -0
  198. package/src/core/resolve.ts +11 -0
  199. package/src/core/resolveMany.ts +22 -0
  200. package/src/core/tokenRegistry.test.ts +153 -0
  201. package/src/core/tokenRegistry.ts +114 -0
  202. package/src/engine/applyOperators.ts +32 -0
  203. package/src/engine/context.ts +8 -0
  204. package/src/engine/gamut.test.ts +30 -0
  205. package/src/engine/gamut.ts +144 -0
  206. package/src/engine/generateScale.test.ts +46 -0
  207. package/src/engine/generateScale.ts +48 -0
  208. package/src/engine/index.ts +8 -0
  209. package/src/engine/normalize.test.ts +222 -0
  210. package/src/engine/normalize.ts +550 -0
  211. package/src/engine/onSolid.ts +178 -0
  212. package/src/engine/resolveBaseColor.test.ts +117 -0
  213. package/src/engine/resolveBaseColor.ts +203 -0
  214. package/src/export/__snapshots__/exportTheme.test.ts.snap +74 -0
  215. package/src/export/exportTheme.test.ts +144 -0
  216. package/src/export/exportTheme.ts +251 -0
  217. package/src/export/index.ts +1 -0
  218. package/src/export/serializeColor.test.ts +73 -0
  219. package/src/export/serializeColor.ts +1 -0
  220. package/src/export.ts +1 -0
  221. package/src/index.ts +3 -0
  222. package/src/operators/emphasis.test.ts +85 -0
  223. package/src/operators/emphasis.ts +132 -0
  224. package/src/operators/index.ts +3 -0
  225. package/src/operators/state.test.ts +66 -0
  226. package/src/operators/state.ts +122 -0
  227. package/src/operators/types.ts +14 -0
  228. package/src/operators/utils.ts +44 -0
  229. package/src/presets/curves.ts +168 -0
  230. package/src/presets/index.ts +2 -0
  231. package/src/presets/tokens/index.ts +3 -0
  232. package/src/presets/tokens/minimal-ui.ts +55 -0
  233. package/src/presets/tokens/modern-ui.ts +85 -0
  234. package/src/presets/tokens/presets.test.ts +46 -0
  235. package/src/presets/tokens/radixLike-ui.ts +79 -0
  236. package/src/serialize/index.ts +1 -0
  237. package/src/serialize/normalizeOutput.ts +63 -0
  238. package/src/serialize/serializeColor.ts +260 -0
  239. package/src/serialize/serializeResolved.test.ts +57 -0
  240. package/src/serialize.ts +1 -0
  241. package/src/types/index.ts +207 -0
  242. package/src/utils/clamp.ts +2 -0
  243. package/src/utils/index.ts +1 -0
  244. package/src/utils/lerp.ts +1 -0
  245. package/src/utils/parseColor.test.ts +66 -0
  246. package/src/utils/parseColor.ts +87 -0
  247. package/src/utils/smoothstep.ts +6 -0
  248. package/tsconfig.build.json +11 -0
  249. package/tsconfig.json +15 -0
  250. package/dist/alpha/generateAlphaScale.d.ts +0 -5
  251. package/dist/alpha/generateAlphaScale.js +0 -34
  252. package/dist/contrast/onSolid.d.ts +0 -6
  253. package/dist/contrast/onSolid.js +0 -28
  254. package/dist/contrast/solveText.d.ts +0 -2
  255. package/dist/contrast/solveText.js +0 -31
  256. package/dist/createTheme.d.ts +0 -38
  257. package/dist/createTheme.js +0 -137
  258. package/dist/data/radixSeeds.d.ts +0 -3
  259. package/dist/data/radixSeeds.js +0 -34
  260. package/dist/diagnostics/analyzeScale.d.ts +0 -2
  261. package/dist/diagnostics/analyzeScale.js +0 -7
  262. package/dist/diagnostics/analyzeTheme.d.ts +0 -2
  263. package/dist/diagnostics/analyzeTheme.js +0 -35
  264. package/dist/diagnostics/warnings.d.ts +0 -2
  265. package/dist/diagnostics/warnings.js +0 -20
  266. package/dist/engine/curves.d.ts +0 -9
  267. package/dist/engine/curves.js +0 -48
  268. package/dist/engine/oklch.d.ts +0 -8
  269. package/dist/engine/oklch.js +0 -40
  270. package/dist/engine/templates.d.ts +0 -14
  271. package/dist/engine/templates.js +0 -45
  272. package/dist/exporters/selectColorMode.d.ts +0 -2
  273. package/dist/exporters/selectColorMode.js +0 -19
  274. package/dist/exporters/toCssVars.d.ts +0 -13
  275. package/dist/exporters/toCssVars.js +0 -108
  276. package/dist/exporters/toJson.d.ts +0 -3
  277. package/dist/exporters/toJson.js +0 -25
  278. package/dist/exporters/toReactNative.d.ts +0 -54
  279. package/dist/exporters/toReactNative.js +0 -33
  280. package/dist/exporters/toTailwind.d.ts +0 -17
  281. package/dist/exporters/toTailwind.js +0 -111
  282. package/dist/exporters/toTs.d.ts +0 -3
  283. package/dist/exporters/toTs.js +0 -43
  284. package/dist/generateScale.d.ts +0 -48
  285. package/dist/generateScale.js +0 -274
  286. package/dist/overlays/generateOverlayScale.d.ts +0 -2
  287. package/dist/overlays/generateOverlayScale.js +0 -34
  288. package/dist/text/generateTextScale.d.ts +0 -8
  289. package/dist/text/generateTextScale.js +0 -18
  290. package/dist/tokens/presetRadixLikeUi.d.ts +0 -5
  291. package/dist/tokens/presetRadixLikeUi.js +0 -55
  292. package/dist/types.d.ts +0 -69
  293. /package/dist/{types.js → cli/args.test.d.ts} +0 -0
package/.codex/skills/color-pipeline-implementer/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: color-pipeline-implementer
3
+ description: Implement or adjust the core color pipeline (parse, normalize, scale, resolve) guided by src/planning/spec-v0.3.md and src/planning/roadmap-v0.3.md.
4
+ ---
5
+
6
+ # Color Pipeline Implementer
7
+
8
+ Use this skill when implementing or adjusting the color pipeline stages. Use the v0.3 docs as the source of truth.
9
+
10
+ ## Workflow
11
+
12
+ 1. Read `src/planning/spec-v0.3.md` and the relevant phase in `src/planning/roadmap-v0.3.md`.
13
+ 2. Implement parsing in `src/utils/parseColor.ts` (hex/rgb to OKLCH, preserve alpha).
14
+ 3. Implement normalization in `src/engine/normalize.ts` (clamp L/C/H, defaults, basic validation).
15
+ 4. Implement base scales and semantic resolution in `src/engine/` as per spec ordering.
16
+ 5. Add focused tests for each stage before moving to the next change.
17
+
18
+ ## Guardrails
19
+
20
+ - Keep logic incremental; avoid skipping phase boundaries.
21
+ - Preserve output contracts (`ResolvedColor`, `ColorMeta`) as defined in `src/types`.
22
+ - Keep BaseResolvedColor runtime shape stable.
23
+ - Prefer small PR-sized changes with clear acceptance criteria.
package/.codex/skills/commit-message-crafter/SKILL.md ADDED
@@ -0,0 +1,63 @@
1
+ ---
2
+ name: commit-message-crafter
3
+ description: Generate best-practice git commit messages (Conventional Commits) by inspecting changes, choosing type/scope, and producing concise, high-signal summaries in English.
4
+ ---
5
+
6
+ # Commit Message Crafter
7
+
8
+ Use this skill when the user wants help writing commit messages or asks for best commit messages. When the change set spans distinct concerns (features, fixes, docs, tests), prefer multiple focused commits instead of one large commit.
9
+
10
+ ## Quick workflow
11
+
12
+ 1) **Inspect context and split when needed**
13
+
14
+ - Prefer `git status -sb` and `git diff` (or PR summary if provided).
15
+ - Identify: what changed, why, and impact.
16
+ - Detect breaking change risk and migrations.
17
+ - Group changes by concern (e.g., fix vs test vs docs). If there is more than one clear concern, plan multiple commits.
18
+
19
+ 1) **Use Conventional Commits only**
20
+
21
+ - Always use Conventional Commits; do not ask about other styles.
22
+
23
+ 1) **Craft the message(s)**
24
+
25
+ - Subject is **imperative**, **short**, and **specific**.
26
+ - **Avoid**: “WIP”, “misc”, “stuff”, “update”, or long diffs in subject.
27
+ - Keep ASCII unless the repo clearly uses non-ASCII.
28
+ - Always write commit messages in English.
29
+ - If multiple commits are planned, propose a commit plan (ordering + scope) and produce a message for each.
30
+
31
+ 1) **Optional body and footer**
32
+
33
+ - Use a body when the change is non-trivial or has tradeoffs.
34
+ - Wrap body at ~72 chars, use short bullets if helpful.
35
+ - Add `BREAKING CHANGE:` footer when applicable.
36
+ - Add issue refs if provided by the user.
37
+
38
+ ## Conventional Commits template
39
+
40
+ ```txt
41
+ <type>(<scope>): <subject>
42
+
43
+ <body optional>
44
+
45
+ <footer optional>
46
+ ```
47
+
48
+ **Types** (choose the most accurate):
49
+
50
+ - `feat` new user-facing behavior
51
+ - `fix` bug fix
52
+ - `refactor` code change without behavior change
53
+ - `perf` performance improvement
54
+ - `docs` documentation only
55
+ - `test` tests only
56
+ - `chore` maintenance, tooling
57
+ - `build` build system or dependencies
58
+ - `ci` CI-related
59
+ - `style` formatting-only changes
60
+
61
+ ## Reference benchmarks
62
+
63
+ Read `references/benchmarks.md` if you need formal standards or reminders.
package/.codex/skills/commit-message-crafter/references/benchmarks.md ADDED
@@ -0,0 +1,20 @@
1
+ # Benchmarks for Commit Messages
2
+
3
+ ## Conventional Commits 1.0.0 (spec)
4
+
5
+ - Format: `type(scope): subject`
6
+ - Types describe intent, scopes narrow the area.
7
+ - Supports `BREAKING CHANGE:` footer.
8
+
9
+ ## 50/72 rule (community best practice)
10
+
11
+ - Subject is short and imperative (<= 50-72 chars).
12
+ - Blank line before body.
13
+ - Body wrapped at ~72 chars, explains what/why.
14
+
15
+ ## Common guidance (widely used)
16
+
17
+ - Use imperative mood: “Add”, “Fix”, “Refactor”.
18
+ - Be specific about user impact.
19
+ - Avoid low-signal words: “update”, “changes”, “stuff”.
20
+ - Prefer one commit per logical change.
package/.codex/skills/contrast-solver-helper/SKILL.md ADDED
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: contrast-solver-helper
3
+ description: Implement APCA/WCAG2 contrast requirements and solver behavior per src/planning/spec-v0.3.md and src/planning/roadmap-v0.3.md, with minimal tests.
4
+ ---
5
+
6
+ # Contrast Solver Helper
7
+
8
+ Use this skill when implementing or validating contrast logic, APCA/WCAG2 targets, or solver behavior in `src/contrast`.
9
+
10
+ ## Workflow
11
+
12
+ 1. Read `src/planning/spec-v0.3.md` and the relevant phase in `src/planning/roadmap-v0.3.md`.
13
+ 2. Implement contrast evaluation for APCA and WCAG2.
14
+ 3. Implement solver behavior for targets and failure modes (best-effort vs strict).
15
+ 4. Add minimal tests for target attainment and failure handling.
16
+
17
+ ## Guardrails
18
+
19
+ - Respect `ContrastRequirement` and `OutputOptions.strict` behavior.
20
+ - Prefer deterministic solver paths; document edge-case behavior.
package/.codex/skills/exporters-builder/SKILL.md ADDED
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: exporters-builder
3
+ description: Build CSS/JSON exporters per src/planning/spec-v0.3.md and src/planning/roadmap-v0.3.md, including output options and gamut handling.
4
+ ---
5
+
6
+ # Exporters Builder
7
+
8
+ Use this skill when implementing export functions (CSS variables and JSON) and output formatting per v0.3 spec.
9
+
10
+ ## Workflow
11
+
12
+ 1. Read `src/planning/spec-v0.3.md` and the relevant phase in `src/planning/roadmap-v0.3.md`.
13
+ 2. Implement exporters in `src/export` with `OutputOptions` (precision, formats).
14
+ 3. Ensure optional `meta` data is included only when requested.
15
+ 4. Add minimal snapshot-like tests for CSS vars and JSON output.
16
+
17
+ ## Guardrails
18
+
19
+ - Preserve the public API surface for v0.3 (`exportThemeCss`, `exportThemeJson`).
20
+ - Keep output stable and deterministic (ordering, precision).
package/.codex/skills/markdownlint-writer/SKILL.md ADDED
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: markdownlint-writer
3
+ description: Write or edit Markdown files while conforming to markdownlint rules used in this repo.
4
+ ---
5
+
6
+ # Markdownlint Writer
7
+
8
+ Use this skill whenever creating or editing `.md` files. It enforces markdownlint formatting rules so changes pass `npm run lint:md`.
9
+
10
+ ## Core rules to follow
11
+
12
+ - Surround headings with a blank line above and below.
13
+ - Surround lists with a blank line above and below.
14
+ - Do not use emphasis as a heading; use actual headings.
15
+ - Provide a language for fenced code blocks (e.g., `ts`, `json`, `css`).
16
+ - Surround fenced code blocks with blank lines.
17
+ - Use consistent table spacing: add spaces around pipe separators.
18
+ - Avoid multiple consecutive blank lines.
19
+
20
+ ## Editing checklist (before save)
21
+
22
+ 1. Check headings have blank lines around them.
23
+ 2. Ensure every list has blank lines before and after.
24
+ 3. Ensure fenced code blocks include a language.
25
+ 4. Ensure fenced code blocks have blank lines before and after.
26
+ 5. Confirm tables use spaced pipes: `| Col | Col |`.
27
+ 6. Remove accidental double blank lines.
28
+
29
+ ## Validation
30
+
31
+ - Run `npm run lint:md -- <path>` when asked to fix markdownlint issues.
32
+ - If markdownlint still fails, scan for missing blank lines around headings/lists.
package/.codex/skills/phase-implementation-runbook/SKILL.md ADDED
@@ -0,0 +1,92 @@
1
+ ---
2
+ name: phase-implementation-runbook
3
+ description: Enforce the phase implementation workflow for Palette Kit v0.3 phases. Use when implementing a roadmap phase, creating a phase branch, validating the lint/typecheck/test/build pipeline, generating a patch for review, or preparing commit/push/PR steps.
4
+ ---
5
+
6
+ # Phase Implementation Runbook
7
+
8
+ Use this skill whenever implementing a roadmap phase. It enforces the agreed step-by-step process and adds guardrails for clean reviews.
9
+
10
+ ## Workflow (must follow in order)
11
+
12
+ 1) Preflight and scope
13
+
14
+ - Read the target phase from `src/planning/roadmap-v0.3.md` and any referenced specs.
15
+ - Confirm branch name format: `phase-<number>-<short-slug>`.
16
+ - Check `git status -sb` and call out unrelated changes before proceeding.
17
+ - If unrelated changes are present, stop and ask how to proceed.
18
+
19
+ 2) Create branch
20
+
21
+ - Create the branch from `v0.3` (or current branch if already on `v0.3`).
22
+ - Prefer `git switch -c phase-<number>-<short-slug>` for branch creation.
23
+ - Verify with `git status -sb`.
24
+
25
+ 3) Implement the phase
26
+
27
+ - Make only changes required for the phase.
28
+ - Keep docs updated when required by the phase (e.g., spec references).
29
+ - Do not add unrelated refactors.
30
+ - If editing `.md` files, follow the markdownlint rules (use the markdownlint-writer skill).
31
+ - Do not expand scope beyond what is explicitly listed in the phase.
32
+ - If an improvement is identified but out of scope, document it and stop.
33
+ - Prefer adding new files over modifying existing ones unless explicitly required.
34
+ - Avoid moving files or renaming symbols without spec justification.
35
+
36
+ 4) Validate in order
37
+
38
+ - Run these commands in an order that surfaces fast failures first:
39
+ 1. `npm run lint:md` (if docs touched)
40
+ 2. `npm run lint`
41
+ 3. `npm run typecheck`
42
+ 4. `npm run test`
43
+ 5. `npm run build`
44
+ - If any step fails, fix and rerun from the failing step onward.
45
+ - If a command is not applicable, note it explicitly as "not run" in the report.
46
+
47
+ 5) Summarize changes and produce diff patch for review
48
+
49
+ - Capture a quick summary with `git diff --stat`.
50
+ - Generate a patch file for external review, e.g.:
51
+ - `git diff > /tmp/phase-<number>-<short-slug>.patch`
52
+ - Report the patch path and wait for explicit confirmation to commit and push.
53
+
54
+ 6) After confirmation: commit, push, PR
55
+
56
+ - Craft Conventional Commit message(s) in English.
57
+ - Commit only the phase-related changes.
58
+ - Push the branch.
59
+ - Open a PR with base `v0.3` and a clear summary.
60
+
61
+ ## DX Quality Gate (mandatory)
62
+
63
+ Before producing the patch:
64
+
65
+ - All new public APIs MUST:
66
+ - have complete TypeScript autocomplete
67
+ - include clear JSDoc explaining:
68
+ - intent
69
+ - defaults
70
+ - inferred vs explicit behavior
71
+ - If an API is correct but awkward to discover or use, stop and revise.
72
+ - DX regressions are considered phase failures, even if tests pass.
73
+
74
+ ## Guardrails
75
+
76
+ - If you notice unexpected changes you did not make, stop and ask how to proceed.
77
+ - Never amend commits unless explicitly requested.
78
+ - Do not run destructive git commands.
79
+ - Do not reinterpret or redesign specs.
80
+ - All architectural and API decisions are considered frozen for the phase.
81
+ - If the spec is ambiguous or incomplete, stop and ask before implementing.
82
+
83
+ ## Output checklist
84
+
85
+ Always end the phase work (pre-confirmation) with:
86
+
87
+ - Tests/validation results summary.
88
+ - Patch path.
89
+ - A prompt asking for confirmation to commit/push/PR.
90
+ - Confirmation that all phase goals are satisfied and no extra features were added.
91
+ - Confirmation that no architectural or API decisions were changed.
92
+ - Short note explaining how the implementation maps to the spec requirements.
package/.codex/skills/type-contract-auditor/SKILL.md ADDED
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: type-contract-auditor
3
+ description: Audit public TypeScript types against src/planning/spec-v0.3.md, flag mismatches, and enforce acceptance criteria (build, no circular imports).
4
+ ---
5
+
6
+ # Type Contract Auditor
7
+
8
+ Use this skill when asked to validate the public type contracts against `src/planning/spec-v0.3.md` or to report discrepancies.
9
+
10
+ ## Workflow
11
+
12
+ 1. Review the type list in `src/planning/spec-v0.3.md` and compare with `src/types`.
13
+ 2. Check for missing types, duplicate union members, or mismatched optionals.
14
+ 3. Verify supporting types like `RawColor` and `OutputOptions` align with spec notes.
15
+ 4. Flag acceptance criteria issues: build failure risk or circular imports.
16
+
17
+ ## Common checks
18
+
19
+ - Duplicated union members (e.g., `ColorState`).
20
+ - Optional fields that spec marks required (or vice versa).
21
+ - Extra types are acceptable if non-breaking; call them out as deltas.
package/.github/skills/review-guide/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: review-guide
3
+ description: Review Palette Kit v0.3 changes using the official checklist and feedback template. Use when performing Copilot-assisted code reviews across phases 0-10 to verify contracts, DX, determinism, and phase-specific requirements.
4
+ ---
5
+
6
+ # Copilot Review Guide
7
+
8
+ ## Overview
9
+
10
+ Apply the v0.3 review checklist to code reviews and return actionable feedback with clear priorities.
11
+
12
+ ## Workflow
13
+
14
+ 1. Load the checklist reference: `references/review-guide-v0.3.md`.
15
+ 2. Always run the "Criterios gerais" first, then the current phase checklist.
16
+ 3. Flag any "O que NAO deve acontecer" violations as blockers.
17
+ 4. Use the provided feedback template to structure the review.
18
+
19
+ ## Notes
20
+
21
+ - Keep comments specific (file + line when possible).
22
+ - Prefer concise, actionable corrections.
23
+ - Do not approve if checklist blockers remain.