colorsbymax 0.4.1 → 0.5.1
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/CHANGELOG.md +24 -0
- package/README.md +593 -488
- package/THIRD_PARTY_NOTICES.md +1 -1
- package/dist/{ThemeSwitcher-BFOWqFUZ.js → ThemeSwitcher-B5FVmhGp.js} +4904 -1863
- package/dist/auto.js +1 -1
- package/dist/index.js +1 -1
- package/package.json +1 -1
- package/types/index.d.ts +27 -8
package/README.md
CHANGED
|
@@ -1,488 +1,593 @@
|
|
|
1
|
-
<p align="center">
|
|
2
|
-
<img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/hero.svg" alt="colorsbymax by mrmaxdesigns: re-colour any website, live." width="880">
|
|
3
|
-
</p>
|
|
4
|
-
|
|
5
|
-
<p align="center">
|
|
6
|
-
<a href="https://www.npmjs.com/package/colorsbymax"><img src="https://img.shields.io/npm/v/colorsbymax?style=flat-square&color=0d6b84&label=colorsbymax" alt="colorsbymax on npm"></a>
|
|
7
|
-
<a href="https://www.npmjs.com/package/colorsbymax-mcp"><img src="https://img.shields.io/npm/v/colorsbymax-mcp?style=flat-square&color=7c3aed&label=colorsbymax-mcp" alt="colorsbymax-mcp on npm"></a>
|
|
8
|
-
<img src="https://img.shields.io/badge/React-18%20%7C%2019-be185d?style=flat-square" alt="React 18 or 19">
|
|
9
|
-
<img src="https://img.shields.io/badge/types-included-15803d?style=flat-square" alt="TypeScript types included">
|
|
10
|
-
<a href="LICENSE"><img src="https://img.shields.io/badge/licence-MIT-c2410c?style=flat-square" alt="MIT licence"></a>
|
|
11
|
-
</p>
|
|
12
|
-
|
|
13
|
-
<p align="center"><strong><a href="https://mrmaxdesigns.com/colorsbymax">See it live at mrmaxdesigns.com/colorsbymax →</a></strong><br>Open the colour button on the page and re-colour the whole site.</p>
|
|
14
|
-
|
|
15
|
-
A floating theme switcher for websites. Visitors (or the site's owner) can re-colour the whole site instantly: pick one of the site's own themes, a hand-tuned pick, or one of 715 library themes in 14 categories; build and share custom palettes; or override single colours. Every theme is checked against the Web Content Accessibility Guidelines (WCAG) contrast rules, with one-click fixes.
|
|
16
|
-
|
|
17
|
-
<p align="center">
|
|
18
|
-
<a href="#at-a-glance"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-start.svg" alt="1. Get started" height="36"></a>
|
|
19
|
-
<a href="#coding-agents-mcp"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-agents.svg" alt="2. Coding agents" height="36"></a>
|
|
20
|
-
<a href="#features"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-inside.svg" alt="3. Features" height="36"></a>
|
|
21
|
-
<a href="#add-it-to-a-site"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-control.svg" alt="4. Full control" height="36"></a>
|
|
22
|
-
<a href="#finished-keep-your-colours-and-hide-the-switcher"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-ship.svg" alt="5. Ship it" height="36"></a>
|
|
23
|
-
<a href="#building-the-package"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-hood.svg" alt="6. Under the hood" height="36"></a>
|
|
24
|
-
</p>
|
|
25
|
-
|
|
26
|
-
<br>
|
|
27
|
-
|
|
28
|
-
<img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/section-start.svg" alt="01 · Get started: two steps to a live colour switcher" width="100%">
|
|
29
|
-
|
|
30
|
-
## At a glance
|
|
31
|
-
|
|
32
|
-
- **Two steps.** `npm install colorsbymax`, then `import 'colorsbymax/auto'` once. The colour button appears and visitors can re-colour the site, even if its colours are hard-coded (see [Quick start](#quick-start)).
|
|
33
|
-
- **
|
|
34
|
-
- **
|
|
35
|
-
- **
|
|
36
|
-
- **
|
|
37
|
-
- **
|
|
38
|
-
- **
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
- **
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
- **
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
npm
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
|
88
|
-
|
|
|
89
|
-
|
|
|
90
|
-
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
}
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
}
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
- **
|
|
188
|
-
- **
|
|
189
|
-
- **
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
}
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
}
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
- *"
|
|
223
|
-
- *"
|
|
224
|
-
- *"
|
|
225
|
-
- *"
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
- **
|
|
243
|
-
- **
|
|
244
|
-
- **
|
|
245
|
-
- **
|
|
246
|
-
- **
|
|
247
|
-
- **
|
|
248
|
-
- **
|
|
249
|
-
- **
|
|
250
|
-
- **
|
|
251
|
-
- **
|
|
252
|
-
- **
|
|
253
|
-
- **
|
|
254
|
-
- **
|
|
255
|
-
- **
|
|
256
|
-
- **
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
With
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/hero.svg" alt="colorsbymax by mrmaxdesigns: re-colour any website, live." width="880">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<a href="https://www.npmjs.com/package/colorsbymax"><img src="https://img.shields.io/npm/v/colorsbymax?style=flat-square&color=0d6b84&label=colorsbymax" alt="colorsbymax on npm"></a>
|
|
7
|
+
<a href="https://www.npmjs.com/package/colorsbymax-mcp"><img src="https://img.shields.io/npm/v/colorsbymax-mcp?style=flat-square&color=7c3aed&label=colorsbymax-mcp" alt="colorsbymax-mcp on npm"></a>
|
|
8
|
+
<img src="https://img.shields.io/badge/React-18%20%7C%2019-be185d?style=flat-square" alt="React 18 or 19">
|
|
9
|
+
<img src="https://img.shields.io/badge/types-included-15803d?style=flat-square" alt="TypeScript types included">
|
|
10
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/licence-MIT-c2410c?style=flat-square" alt="MIT licence"></a>
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
<p align="center"><strong><a href="https://mrmaxdesigns.com/colorsbymax">See it live at mrmaxdesigns.com/colorsbymax →</a></strong><br>Open the colour button on the page and re-colour the whole site.</p>
|
|
14
|
+
|
|
15
|
+
A floating theme switcher for websites. Visitors (or the site's owner) can re-colour the whole site instantly: pick one of the site's own themes, a hand-tuned pick, or one of 715 library themes in 14 categories; build and share custom palettes; or override single colours. Every theme is checked against the Web Content Accessibility Guidelines (WCAG) contrast rules, with one-click fixes.
|
|
16
|
+
|
|
17
|
+
<p align="center">
|
|
18
|
+
<a href="#at-a-glance"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-start.svg" alt="1. Get started" height="36"></a>
|
|
19
|
+
<a href="#coding-agents-mcp"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-agents.svg" alt="2. Coding agents" height="36"></a>
|
|
20
|
+
<a href="#features"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-inside.svg" alt="3. Features" height="36"></a>
|
|
21
|
+
<a href="#add-it-to-a-site"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-control.svg" alt="4. Full control" height="36"></a>
|
|
22
|
+
<a href="#finished-keep-your-colours-and-hide-the-switcher"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-ship.svg" alt="5. Ship it" height="36"></a>
|
|
23
|
+
<a href="#building-the-package"><img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/nav-hood.svg" alt="6. Under the hood" height="36"></a>
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
<br>
|
|
27
|
+
|
|
28
|
+
<img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/section-start.svg" alt="01 · Get started: two steps to a live colour switcher" width="100%">
|
|
29
|
+
|
|
30
|
+
## At a glance
|
|
31
|
+
|
|
32
|
+
- **Two steps.** `npm install colorsbymax`, then `import 'colorsbymax/auto'` once. The colour button appears and visitors can re-colour the site, even if its colours are hard-coded (see [Quick start](#quick-start)).
|
|
33
|
+
- **Go as deep as you like.** One click recolours the whole site; [Studio](#studio) colours it part by part; [Subtle, Balanced or Colourful](#colour-styles) sets how bold it is; and a [contrast guard](#the-contrast-guard) keeps every piece of text readable.
|
|
34
|
+
- **React 18 or 19.**
|
|
35
|
+
- **Tailwind optional.** The panel carries its own styles, so it works with Tailwind v4, older Tailwind or plain CSS. Your site only needs to paint its colours with `var(--color-…)` variables. The optional `colorsbymax/tokens.css` helper is for Tailwind v4 (`@theme` syntax); without Tailwind v4, define the variables yourself.
|
|
36
|
+
- **TypeScript types included.**
|
|
37
|
+
- **No runtime dependencies** besides React. PDF uploads are opt-in and need `pdfjs-dist` (see [PDF uploads](#pdf-uploads)).
|
|
38
|
+
- **ESM only.** Import it from a bundler or `import()`; `require('colorsbymax')` from CommonJS isn't supported.
|
|
39
|
+
- **The colour tools work on their own too.** `contrastRatio`, `checkTheme`, `suggestFix`, `fixAll`, `themeFromPalette`, `darkTokens` and the rest are plain functions with no UI.
|
|
40
|
+
|
|
41
|
+
## Quick start
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npm install colorsbymax
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Then add one line anywhere in your site's code, for example `main.jsx`:
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
import 'colorsbymax/auto'
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
That's all. The colour button appears in the bottom-right corner once the page has loaded, and visitors can start swapping the site's colours. (npm doesn't let a package change your site on install, so this one line is the only step.)
|
|
54
|
+
|
|
55
|
+
- **Any site's colours.** If your site doesn't use colorsbymax's colour variables, colorsbymax reads the colours actually on the page (backgrounds, text, borders, gradients and icons) and swaps each for its counterpart in the chosen theme: greys follow the theme's background and text, brand shades follow its brand colour, and success and error colours keep their meaning. Content added later is re-coloured too, and picking the site's own theme brings back the exact original.
|
|
56
|
+
- **Settings.** Use `autoMount` instead of the plain import:
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
import { autoMount } from 'colorsbymax/auto'
|
|
60
|
+
autoMount({ siteName: 'My site', storageKey: 'my-site-theme' })
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
- **Logos keep their own colours** unless a visitor turns on "Colour the logo too" in settings. Mark your logo with `data-colorsbymax-logo` if colorsbymax doesn't find it (it looks for "logo" in a class, id or label).
|
|
64
|
+
- **Where automatic re-colouring falls short:** images keep their colours, hover and focus colours keep the site's own, and colours drawn by `::before`/`::after` aren't swapped. For full control, use the colour variables below; colorsbymax then applies themes to them directly, with no page reading at all.
|
|
65
|
+
|
|
66
|
+
Already installed it? Get the newest version with `npm install colorsbymax@latest` (see [Updating](#updating)).
|
|
67
|
+
|
|
68
|
+
## Try the demo
|
|
69
|
+
|
|
70
|
+
colorsbymax's home, **[mrmaxdesigns.com/colorsbymax](https://mrmaxdesigns.com/colorsbymax)**, is the demo: open the colour button and the whole page re-colours. To run it locally:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
npm install
|
|
74
|
+
npm run dev
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
This serves `demo/`, the same site: built with Tailwind, where every colour is a token, and every token group is used. Its sections are in `demo/site/`.
|
|
78
|
+
|
|
79
|
+
<br>
|
|
80
|
+
|
|
81
|
+
<img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/section-agents.svg" alt="02 · Coding agents: let Claude, Cursor or Copilot do it" width="100%">
|
|
82
|
+
|
|
83
|
+
## Coding agents (MCP)
|
|
84
|
+
|
|
85
|
+
Your coding agent can set colorsbymax up and use it for you. [colorsbymax-mcp](mcp/) is an [MCP](https://modelcontextprotocol.io) server that gives Claude Code, Cursor, GitHub Copilot, Codex, Google Antigravity, Gemini CLI, Grok Build, Claude Desktop, Windsurf, Kiro, Zed, JetBrains, Cline, opencode and other agents colorsbymax's own tools:
|
|
86
|
+
|
|
87
|
+
| The agent can… | Tool |
|
|
88
|
+
| --- | --- |
|
|
89
|
+
| Look at your project and add colorsbymax the right way for its framework: Vite, Next.js, Remix, Gatsby, Astro, Nuxt, SvelteKit, Vue, Svelte or plain HTML | `setup_plan` |
|
|
90
|
+
| Find themes by mood, category or closeness to your brand colour, in light or dark | `find_themes`, `get_theme` |
|
|
91
|
+
| Build a complete, accessible theme around your brand colours | `theme_from_colours` |
|
|
92
|
+
| Check contrast and suggest the smallest fixes | `check_contrast` |
|
|
93
|
+
| Make your chosen colours the default and hide the switcher in production, or remove colorsbymax and keep them | `finish` |
|
|
94
|
+
| Read these docs and the full TypeScript API | `docs` |
|
|
95
|
+
|
|
96
|
+
It reads your project but never changes it: the agent makes the edits, so you review them as usual. It runs with `npx`, so there's nothing to install first (Node 18 or later).
|
|
97
|
+
|
|
98
|
+
**Adding the server doesn't change your site by itself.** It gives your agent the tools; the agent then sets colorsbymax up when you ask:
|
|
99
|
+
|
|
100
|
+
1. **Add the server** once, with the steps for your editor below.
|
|
101
|
+
2. **Start a new chat or session** in your project. Agents load MCP servers when a session starts, so one that was already open won't see it yet.
|
|
102
|
+
3. **Ask:** *"Add colorsbymax to this project."* The agent installs the package and adds the one line (or the right version of it for your framework).
|
|
103
|
+
4. **Run your site** (for example `npm run dev`). The colour button appears in the bottom-right corner.
|
|
104
|
+
|
|
105
|
+
### Claude Code
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
claude mcp add colorsbymax -- npx -y colorsbymax-mcp
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
That adds it for you in this project. Add `--scope user` to have it in every project, or `--scope project` to share it with your team through a `.mcp.json` file. Check it with `/mcp` inside Claude Code.
|
|
112
|
+
|
|
113
|
+
If your terminal says `claude` isn't found (the desktop app doesn't always put it on your PATH), ask Claude Code itself: *"Add the colorsbymax MCP server: `npx -y colorsbymax-mcp`."*
|
|
114
|
+
|
|
115
|
+
### Cursor
|
|
116
|
+
|
|
117
|
+
Add this to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"mcpServers": {
|
|
122
|
+
"colorsbymax": { "command": "npx", "args": ["-y", "colorsbymax-mcp"] }
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
It then shows under **Settings → MCP**, and Cursor's agent uses it when you ask about colours or themes.
|
|
128
|
+
|
|
129
|
+
### VS Code (GitHub Copilot)
|
|
130
|
+
|
|
131
|
+
Add this to `.vscode/mcp.json`, then use it from Copilot Chat in **Agent** mode:
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
{
|
|
135
|
+
"servers": {
|
|
136
|
+
"colorsbymax": { "command": "npx", "args": ["-y", "colorsbymax-mcp"] }
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Claude Desktop
|
|
142
|
+
|
|
143
|
+
Open **Settings → Developer → Edit Config**, add the same `mcpServers` entry as Cursor to `claude_desktop_config.json`, and restart Claude Desktop.
|
|
144
|
+
|
|
145
|
+
### GitHub Copilot CLI
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
copilot mcp add colorsbymax -- npx -y colorsbymax-mcp
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Or type `/mcp add` inside `copilot`. It's saved to `~/.copilot/mcp-config.json`.
|
|
152
|
+
|
|
153
|
+
### Codex (OpenAI)
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
codex mcp add colorsbymax -- npx -y colorsbymax-mcp
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
It's saved to `~/.codex/config.toml`, which the Codex IDE extension shares. To write it by hand:
|
|
160
|
+
|
|
161
|
+
```toml
|
|
162
|
+
[mcp_servers.colorsbymax]
|
|
163
|
+
command = "npx"
|
|
164
|
+
args = ["-y", "colorsbymax-mcp"]
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Google Antigravity
|
|
168
|
+
|
|
169
|
+
In the agent panel, open **… → MCP Servers → Manage MCP Servers → View raw config**, add the same `mcpServers` entry as Cursor to `~/.gemini/config/mcp_config.json`, and save. Antigravity reloads it by itself. For one project, use `.agents/mcp_config.json`. In the Antigravity CLI, `/mcp` opens the same manager.
|
|
170
|
+
|
|
171
|
+
### Gemini CLI
|
|
172
|
+
|
|
173
|
+
Add the same `mcpServers` entry as Cursor to `~/.gemini/settings.json` (or `.gemini/settings.json` in your project), restart Gemini CLI, and check it with `/mcp`.
|
|
174
|
+
|
|
175
|
+
### Grok Build (xAI)
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
grok mcp add colorsbymax -- npx -y colorsbymax-mcp
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
It's saved to `~/.grok/config.toml`; add `--scope project` for `.grok/config.toml`. The first start downloads the server, so if it times out, raise `startup_timeout_sec` for it in that file.
|
|
182
|
+
|
|
183
|
+
### Windsurf, Kiro, JetBrains, Cline and Roo
|
|
184
|
+
|
|
185
|
+
They take the same `mcpServers` entry as Cursor:
|
|
186
|
+
|
|
187
|
+
- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`
|
|
188
|
+
- **Kiro:** `.kiro/settings/mcp.json` in your project, or `~/.kiro/settings/mcp.json`. Kiro doesn't read your shell's PATH, so use the full path to `npx` if it can't start.
|
|
189
|
+
- **JetBrains:** AI Assistant under **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**; Junie under **Settings → Tools → Junie → MCP Settings**.
|
|
190
|
+
- **Cline and Roo Code:** in the extension's **MCP Servers** view, choose **Configure** (or **Edit MCP Settings**).
|
|
191
|
+
|
|
192
|
+
### Zed and opencode
|
|
193
|
+
|
|
194
|
+
Zed calls them context servers. In `settings.json`, or through **Settings → AI → MCP Servers → Add Server**:
|
|
195
|
+
|
|
196
|
+
```json
|
|
197
|
+
{
|
|
198
|
+
"context_servers": {
|
|
199
|
+
"colorsbymax": { "command": "npx", "args": ["-y", "colorsbymax-mcp"] }
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
opencode, in `opencode.json`:
|
|
205
|
+
|
|
206
|
+
```json
|
|
207
|
+
{
|
|
208
|
+
"mcp": {
|
|
209
|
+
"colorsbymax": { "type": "local", "command": ["npx", "-y", "colorsbymax-mcp"] }
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### Any other MCP client
|
|
215
|
+
|
|
216
|
+
Most take the same `mcpServers` entry as Cursor: the command is `npx`, with `-y colorsbymax-mcp` as its arguments.
|
|
217
|
+
|
|
218
|
+
On Windows, if an editor can't start `npx`, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "colorsbymax-mcp"]`.
|
|
219
|
+
|
|
220
|
+
### What to ask
|
|
221
|
+
|
|
222
|
+
- *"Add colorsbymax to this project."*
|
|
223
|
+
- *"Find me a calm ocean theme that also works in dark mode."*
|
|
224
|
+
- *"Build a theme around our brand colours #e63946 and #1d3557, and check its contrast."*
|
|
225
|
+
- *"Does white text pass on #f59e0b?"*
|
|
226
|
+
- *"I've picked my colours in the panel. Make them the default and hide the switcher in production."* Paste the theme from the panel's **Import / export**, or name the theme.
|
|
227
|
+
|
|
228
|
+
### Without MCP
|
|
229
|
+
|
|
230
|
+
Any coding agent can still do it from a prompt. Paste this into Claude, Cursor, Copilot or another agent:
|
|
231
|
+
|
|
232
|
+
> Install the colorsbymax npm package in this project and add `import 'colorsbymax/auto'` to the app's entry file, so the colorsbymax colour button appears on every page. For Next.js, Remix or other server-rendered apps, load it in the browser only, with `import('colorsbymax/auto')` inside a `useEffect`. Follow https://github.com/MaxMuyalwa/colorsbymax#quick-start and don't change anything else.
|
|
233
|
+
|
|
234
|
+
When you're done choosing colours, the panel's **I'm done** button gives you ready-made prompts for keeping your colours, hiding the switcher or removing it (see [Finished?](#finished-keep-your-colours-and-hide-the-switcher)).
|
|
235
|
+
|
|
236
|
+
<br>
|
|
237
|
+
|
|
238
|
+
<img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/section-inside.svg" alt="03 · What's inside: everything in the panel" width="100%">
|
|
239
|
+
|
|
240
|
+
## Features
|
|
241
|
+
|
|
242
|
+
- **Site themes first.** The panel opens on a group named after the site, holding its own colours. If those fail contrast, an accessible version is generated automatically.
|
|
243
|
+
- **Scan the site.** Press "Scan site" and colorsbymax reads the colours actually painted on the page (ignoring any theme it has applied, and including gradients). It works out the page background, surfaces, text and brand colours, then adds themes named after the site: Scanned (as found), Accessible, Soft, Bold, Complementary, and the closest library matches. Scans run only when asked, and the results are remembered.
|
|
244
|
+
- **Max’s picks and library.** 5 hand-tuned picks, plus 715 library themes (Bright, Fun, Pastel, Earth tones, Summer, Autumn, Winter, Spring, Ocean, Warm, Nature, Moody, Monochrome, Eclectic) with search and "Surprise me". The library loads only when the panel opens.
|
|
245
|
+
- **Custom palettes, single-colour overrides, import and export as JSON or CSS.**
|
|
246
|
+
- **Palettes from images and PDFs.** In Import / export, upload or drop a mood board, screenshot or photo, or paste one straight from the clipboard: take a screenshot, open the panel and press Ctrl+V (⌘V on a Mac), or use **Paste image**. colorsbymax picks out its main colours, lets you leave any out, previews the palette it builds around them and saves it as a custom palette. Nothing leaves the browser. PDFs, such as brand guides, work where the site [turns them on](#pdf-uploads); hex codes written in a PDF take priority.
|
|
247
|
+
- **Contrast checks.** Problems show as a badge on the theme; the breakdown offers per-item fixes or "Fix all automatically", which changes lightness only.
|
|
248
|
+
- **No flash on reload.** An inline pre-paint script applies the saved theme before the page draws.
|
|
249
|
+
- **Works on any site.** The panel carries its own stylesheet inside a shadow root, so it needs no Tailwind or other CSS from the site, and the site's CSS can't restyle it.
|
|
250
|
+
- **Movable colour button.** The floating button starts in the corner; visitors can drag it anywhere (mouse or touch; a tooltip says so on hover, and an open panel moves with it) and it stays there, remembered across reloads. The panel then opens beside it, on whichever side has room. Its dot cycles through the current theme's colours.
|
|
251
|
+
- **Three colour styles.** Subtle, Balanced or Colourful: as quiet or as bold as you like, with a strength slider and tints from your own pictures. See [Colour styles](#colour-styles).
|
|
252
|
+
- **A contrast guard, on every site and in every style.** Every piece of text and every icon is checked against what it really sits on, and anything hard to read is fixed, keeping its hue. See [The contrast guard](#the-contrast-guard).
|
|
253
|
+
- **Know when there's an update.** A bell in the panel, only where you work on your site, says when a newer colorsbymax is out and how to update, with news from mrmaxdesigns. See [The bell](#the-bell-updates-and-news).
|
|
254
|
+
- **Light and dark mode, for any site.** Every built-in theme is designed light and has a generated dark twin (dark surfaces, light text, brand colours lifted until they read on dark, then contrast-checked). Switching to Dark, one click in the panel's header, turns the whole site dark, even one that never had a dark mode. Auto follows the visitor's device, and a light and dark switch can go anywhere on the site (see [Dark mode](#dark-mode)). Custom palettes stay as they were made.
|
|
255
|
+
- **Visitor settings.** The gear in the panel header opens settings: theme mode (Light, Dark, Auto), panel size (Compact, Standard, Large), which groups and sections to show, whether the button can be dragged or its dot animates, and moving the button back to its corner. Saved per site.
|
|
256
|
+
- **Resizable panel.** Drag the panel's free edges or corner (the ones away from the colour button) to any size, or pick a size in settings; double-click an edge to reset it. The layout follows the panel's width, so a large panel shows three theme cards a row.
|
|
257
|
+
- **Studio: go deeper.** Point and click any part of the page to give it its own colours (one part, every part like it, or every part on every page), with a readability check from the first click; choose which pages get the colours; audit the page; and keep it all as a prompt for your AI editor or as CSS. See [Studio](#studio).
|
|
258
|
+
- **Audit the page.** **Audit this page**, in Studio, pins notes to what won't look right in the chosen colours: a logo that disappears, a picture whose background shows as a box, text too faint to read. See [Check the page](#check-the-page).
|
|
259
|
+
- **Clear groups and feedback.** The site's own group (globe), Max’s picks (paintbrush) and Yours (person) sit in their own row, apart from the library's categories. Toasts confirm what just happened; saving, importing or building a palette says it went to Yours and offers "Show" to jump straight to it. Tooltips are drawn in the panel's colours.
|
|
260
|
+
- **Themed scrollbars.** The page's scrollbars and the panel's slim one take the selected theme's primary colour. Turn the page's off with `scrollbars: false`.
|
|
261
|
+
- **Accessible panel.** A labelled dialog with focus trap, Escape, the colour button or an outside click to close, keyboard operable, and reduced-motion support.
|
|
262
|
+
|
|
263
|
+
## Studio
|
|
264
|
+
|
|
265
|
+
Studio is the panel's deeper way of working. The quick switcher colours the whole site with one theme; Studio colours it part by part, exactly the way you want it. Open it with **Studio** in the panel's header; **Back to the switcher** returns to the quick one.
|
|
266
|
+
|
|
267
|
+
### Point and click
|
|
268
|
+
|
|
269
|
+
Press **Point and click**. The panel steps aside and a bar at the bottom of the page says what to do. Hovering outlines each part of the page and names it (Button, Link, Heading, Card, Section, Header, Footer, Text…); a click picks it instead of following a link or pressing a button. **Done** in the bar, or Escape, goes back to Studio.
|
|
270
|
+
|
|
271
|
+
A card opens beside what you picked, with:
|
|
272
|
+
|
|
273
|
+
- **What it is and where:** "Card “Pricing”, in the “Plans” section".
|
|
274
|
+
- **The part around it / The part inside it:** step out from a heading to its card, or from a card to its section, and back in again, down to the text itself. When you've reached the text, the card says so and points you to **Text colour**.
|
|
275
|
+
- **Just this one / All N here / On every page:** change only that part, every part like it on the page (the same element with the same classes), or every part like it on every page of the site.
|
|
276
|
+
- **Background · Text colour · Border:** the current theme's colours as swatches, or any colour from the colour picker. **Its own** puts the part's own colour back. A Border on a part that has none adds a thin outline.
|
|
277
|
+
|
|
278
|
+
Colours picked from the swatches follow the theme: pick a new theme and they take its colours. Colours from the colour picker stay exactly as they are.
|
|
279
|
+
|
|
280
|
+
### Readable from the first click
|
|
281
|
+
|
|
282
|
+
As soon as you pick something, Studio checks every piece of text in it (and in every part like it, when they change together) against what it really sits on, see-through backgrounds included, and says whether it's **easy** or **hard to read**, with its contrast ratio. **Fix** finds the text colour that reads on all of it, preferring the theme's own colours, else black or white, and only offers one that passes. Swatches that would make the text hard to read carry a small "!" before you choose them; hover one for its ratio.
|
|
283
|
+
|
|
284
|
+
### Where the colours go
|
|
285
|
+
|
|
286
|
+
**Where the colours go** chooses the whole site, or only some pages: colour the landing page, say, and leave the app inside as it is. Studio offers the site's own pages (the ones the current page links to, and the ones you've opened), you can type a path, and a path ending in `/*` covers a whole section (`/blog/*` is `/blog` and every page under it). Pages left out keep their own colours exactly, dark mode included, and the quick switcher says so when you open it there, with **Colour this page too**.
|
|
287
|
+
|
|
288
|
+
To make it the same for every visitor, set the [`pages`](#config) option; Studio gives you the line, and a prompt for your AI editor.
|
|
289
|
+
|
|
290
|
+
### Check the page
|
|
291
|
+
|
|
292
|
+
**Audit this page** looks at the page in the chosen colours and pins notes to what won't look right: a logo that disappears against its background (with a one-click "Colour the logo", or tips when it's a picture colorsbymax can't re-colour, plus "Preview inverted"), pictures whose solid background shows as a box, and text or icons too faint to read. The notes stay on the page as you scroll; **Re-check** after a fix, and close it from its bar.
|
|
293
|
+
|
|
294
|
+
### Keep it for good
|
|
295
|
+
|
|
296
|
+
Your changes are listed page by page (and "On every page"), each with an undo, and saved on your device; they're drawn before the page first shows, like the theme, so they never flash. **Keep them for good** turns them into:
|
|
297
|
+
|
|
298
|
+
- **A prompt** (recommended) for Claude, Cursor or Copilot: each change in plain words (the page, what the part says, where it is, the old and new colours), asking your editor to find the part in your code and use your own colour settings where you have them. Changes on every page are marked as a shared component, to change where it's defined.
|
|
299
|
+
- **CSS** with the same changes. Its selectors come from the page as it is now, so the prompt holds up better if the layout changes.
|
|
300
|
+
|
|
301
|
+
Picking another theme while you have Studio changes asks first: keep them on the new theme, or clear them.
|
|
302
|
+
|
|
303
|
+
## Colour styles
|
|
304
|
+
|
|
305
|
+
Every theme comes three ways. Choose in the panel's **Colour style** section, above Preset themes:
|
|
306
|
+
|
|
307
|
+
| | What changes | Best for |
|
|
308
|
+
|---|---|---|
|
|
309
|
+
| **Subtle** | Your site keeps its own backgrounds, cards and text. The theme's colour goes on buttons, links and highlights, with only a quiet, greyed hint of it on badges and tints. | Trying a new brand colour without changing the feel of the site. |
|
|
310
|
+
| **Balanced** | The theme in every role, with a soft wash of it across the page, cards and borders, so it shows even where a theme's own backgrounds are nearly white. Your site's own colours stay exactly as designed. | Seeing the theme as it's meant to be. The default on a site that paints with the colour variables. |
|
|
311
|
+
| **Colourful** | An overhaul: the page, cards and borders take a clear tint of the brand (soft in light mode, deeper in dark), and text and headings a hint of it. | A whole new look. The default on a site colorsbymax re-colours. |
|
|
312
|
+
|
|
313
|
+
**Strength.** With Colourful on, a slider runs from **Light wash** through Soft and Lively to **Bold**: how much the page, sections and cards are tinted, whether headings take the brand colour, and how deep the footer goes. Set where first-time visitors start with `colourStrength` (0 to 100).
|
|
314
|
+
|
|
315
|
+
**Tints from your pictures.** **Tint with my pictures' colours** (on by default) takes Colourful's washes from the site's logo and biggest photos, so they feel made for the site, while buttons and links keep the theme's colours. The panel shows the colours it found, with the one it uses outlined. Pictures from another site that doesn't allow reading them are skipped.
|
|
316
|
+
|
|
317
|
+
**On a site colorsbymax re-colours,** Colourful also paints the page by role, as a designer would: the header, the hero, sections taking turns, headings, cards, badges, buttons, links and the footer. It reads what each section is and gives it its own treatment: pricing tables (the most popular plan ringed in the brand colour), testimonials (on their own wash, with a brand bar on each), forms (a tinted band and a raised form box), image-led sections (kept on the plain page colour so pictures show true) and the current page in the menu. On a site that paints with the colour variables, Colourful works through those variables alone, so the site's own design still decides where each colour goes.
|
|
318
|
+
|
|
319
|
+
Choose the style first-time visitors start in with [`colourStyle`](#config).
|
|
320
|
+
|
|
321
|
+
## The contrast guard
|
|
322
|
+
|
|
323
|
+
Whatever the theme and style, colorsbymax has the last word on readability. Once the colours are on the page, it checks every piece of text and every icon against what it actually sits on: its own background and every see-through one behind it, laid over each other, or each colour of a gradient. Anything under WCAG AA (4.5:1 for text, 3:1 for large text and icons) is fixed:
|
|
324
|
+
|
|
325
|
+
1. Its own colour, made lighter or darker until it reads, so a green "Paid" stays green and a red "Failed" stays red.
|
|
326
|
+
2. Else the theme colour closest to it that reads.
|
|
327
|
+
3. Else black or white.
|
|
328
|
+
|
|
329
|
+
It works on every site and in every style, and in Studio's colours too. It runs when the colours or the page's content change (including a part of the page that sets colour variables of its own, like a theme preview), never while the page scrolls. Hidden, disabled and `aria-hidden` parts are skipped. To keep a deliberate example of poor contrast as it is, mark it:
|
|
330
|
+
|
|
331
|
+
```html
|
|
332
|
+
<div data-colorsbymax-contrast="keep">…</div>
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
## The bell: updates and news
|
|
336
|
+
|
|
337
|
+
When a newer colorsbymax is published, the panel says so: a small red plus appears on the colour button and on the bell in the panel's header. The bell shows:
|
|
338
|
+
|
|
339
|
+
- the version you have and the latest one,
|
|
340
|
+
- the headlines of what changed, from the [changelog](CHANGELOG.md),
|
|
341
|
+
- `npm install colorsbymax@latest` to copy,
|
|
342
|
+
- a prompt for Claude, Cursor or Copilot that updates it and makes any changes the changelog's "Upgrading" notes ask for,
|
|
343
|
+
- a link to the full changelog,
|
|
344
|
+
- and news from mrmaxdesigns: new features to try, and requests for feedback.
|
|
345
|
+
|
|
346
|
+
Opening the bell clears the plus.
|
|
347
|
+
|
|
348
|
+
**Who sees it.** By default only you, where you work on your site: development addresses (`localhost`, `127.0.0.1`, names ending in `.local`, `.localhost` or `.test`, and private networks). Visitors to your live site never see it. `updates: true` shows it everywhere, and `updates: false` turns it off.
|
|
349
|
+
|
|
350
|
+
**What it sends.** Once a day at most, a few seconds after the page has loaded, the switcher asks the npm registry for the latest version, `raw.githubusercontent.com` for the changelog (only when there's an update), and mrmaxdesigns.com for the news. Those requests carry nothing but the usual details of any web request, no cookies, and nothing is stored about you. Offline, it simply skips the check.
|
|
351
|
+
|
|
352
|
+
## How it works
|
|
353
|
+
|
|
354
|
+
Every colour is one of 35 tokens (`primary`, `surface`, `ink`, `data-1`…), exposed as `--color-<token>` CSS variables. Applying a theme just sets those variables on `<html>`, so anything the site paints with `var(--color-primary)` (directly, or through Tailwind CSS v4 utilities like `bg-primary`) changes instantly. There's no rebuild and no re-render.
|
|
355
|
+
|
|
356
|
+
The switcher renders into a `<colorsbymax-root>` element on `<body>` with its own shadow root and stylesheet. Only the `--color-*` variables cross into it. With reduced motion, the colour button's dot holds still on the theme's primary colour.
|
|
357
|
+
|
|
358
|
+
<br>
|
|
359
|
+
|
|
360
|
+
<img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/section-control.svg" alt="04 · Full control: paint with colour tokens" width="100%">
|
|
361
|
+
|
|
362
|
+
## Add it to a site
|
|
363
|
+
|
|
364
|
+
This is the full setup, for sites that want exact control over which colour goes where. colorsbymax needs React 18 or 19, and ships as plain JavaScript with TypeScript types, so Vite, Next.js, webpack and other bundlers use it without extra setup:
|
|
365
|
+
|
|
366
|
+
1. **Paint the site with the token variables.** Use `var(--color-<token>)` wherever the site sets a colour, with your own colours as the starting values.
|
|
367
|
+
|
|
368
|
+
With Tailwind CSS v4, import the defaults (`colorsbymax/tokens.css` is Tailwind v4 syntax), override them, and use the token utilities (`bg-primary`, `text-ink`, …) instead of hard-coded colours:
|
|
369
|
+
|
|
370
|
+
```css
|
|
371
|
+
@import "tailwindcss";
|
|
372
|
+
@import "colorsbymax/tokens.css";
|
|
373
|
+
|
|
374
|
+
@theme static {
|
|
375
|
+
--color-primary: #c67cde; /* your colours */
|
|
376
|
+
}
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
With plain CSS, or Tailwind before v4, define the variables yourself:
|
|
380
|
+
|
|
381
|
+
```css
|
|
382
|
+
:root {
|
|
383
|
+
--color-primary: #c67cde;
|
|
384
|
+
}
|
|
385
|
+
.button {
|
|
386
|
+
background: var(--color-primary);
|
|
387
|
+
}
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
2. **Wrap the app and render the switcher:**
|
|
391
|
+
|
|
392
|
+
```jsx
|
|
393
|
+
import { ThemeProvider, ThemeSwitcher } from 'colorsbymax'
|
|
394
|
+
|
|
395
|
+
<ThemeProvider config={config}>
|
|
396
|
+
<App />
|
|
397
|
+
<ThemeSwitcher />
|
|
398
|
+
</ThemeProvider>
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
The switcher needs React but not a React site: `autoMount` from `colorsbymax/auto` mounts it on its own next to any page.
|
|
402
|
+
|
|
403
|
+
3. **Add the pre-paint script** to `<head>`, as a classic inline `<script>`, using the same storage key. `prePaintScript(storageKey)` returns its source, and `demo/index.html` shows it in place.
|
|
404
|
+
|
|
405
|
+
Without a `siteName`, the site group is named from the page's `og:site_name`, its title or its host name.
|
|
406
|
+
|
|
407
|
+
### Config
|
|
408
|
+
|
|
409
|
+
```js
|
|
410
|
+
{
|
|
411
|
+
siteName: 'Tsungi', // name of the first theme group
|
|
412
|
+
storageKey: 'tsungi-theme', // localStorage key (match the pre-paint script)
|
|
413
|
+
defaultTheme: { name, tokens }, // the site's own colours; missing tokens are filled in
|
|
414
|
+
themes: [{ id, name, tokens }], // optional extra themes made for the site
|
|
415
|
+
usage: { primary: 'Buttons…' }, // optional notes shown in the colour editors
|
|
416
|
+
scrollbars: true, // colour the page's scrollbars from the theme (default)
|
|
417
|
+
pdf: loadPdf, // optional: allow PDF uploads (see below)
|
|
418
|
+
recolour: 'auto', // re-colour hard-coded colours: 'auto' (only if the site has
|
|
419
|
+
// no --color-* variables, the default), true or false
|
|
420
|
+
position: 'bottom-right', // where the button starts: bottom-right (default), bottom-left,
|
|
421
|
+
// top-left, or top-right (just under a floating nav bar)
|
|
422
|
+
hidden: import.meta.env.PROD, // hide the button (the theme still applies), e.g. in production
|
|
423
|
+
defaultMode: 'light', // the mode first-time visitors start in: 'light' (default),
|
|
424
|
+
// 'dark', or 'system' to follow their device
|
|
425
|
+
colourLogo: false, // themes colour the logo too, for first-time visitors (default
|
|
426
|
+
// false: it keeps its own colours); visitors can change it
|
|
427
|
+
features: { scan: false }, // parts of the panel to switch off for everyone (all on by default):
|
|
428
|
+
// picks, library, search, surprise, scan, custom, overrides,
|
|
429
|
+
// importExport, audit, addToSite, colourStyle, colourCount, studio
|
|
430
|
+
pages: ['/', '/pricing'], // only colour these pages; the rest keep their own colours (default:
|
|
431
|
+
// the whole site). '/blog/*' is /blog and every page under it
|
|
432
|
+
updates: 'dev', // the bell (new versions, news): 'dev' only on development
|
|
433
|
+
// addresses (default), true everywhere, false never
|
|
434
|
+
colourStrength: 50, // how strongly Colourful paints for first-time visitors, 0 (a light
|
|
435
|
+
// wash) to 100 (bold); visitors can change it
|
|
436
|
+
colourStyle: 'balanced', // how boldly the site takes a theme, for first-time visitors:
|
|
437
|
+
// 'subtle' keeps the site's own backgrounds and text and brings the
|
|
438
|
+
// theme in on buttons, links and highlights; 'balanced' is the
|
|
439
|
+
// theme with a soft wash (the default on a site that paints with the
|
|
440
|
+
// variables); 'colourful' is an overhaul: tinted backgrounds and the
|
|
441
|
+
// page painted by role (the default on a site colorsbymax re-colours)
|
|
442
|
+
intro: true, // the button pops in with a burst of the theme's colours a moment
|
|
443
|
+
// after the page loads (default); reduced motion fades it in
|
|
444
|
+
}
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
A bar pinned above your nav (an announcement, a cookie notice)? Set its height on `<html>` and the colour button and panel make room for it:
|
|
448
|
+
|
|
449
|
+
```js
|
|
450
|
+
document.documentElement.style.setProperty('--colorsbymax-offset-top', `${bar.offsetHeight}px`)
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
### Dark mode
|
|
454
|
+
|
|
455
|
+
Dark mode works on any site: every theme has a dark twin, so choosing Dark (or Auto, on a device set to dark) re-colours the whole page, and text, buttons and icons are checked for contrast on the dark background. It applies on every page load, and keeps working when the switcher is hidden in production.
|
|
456
|
+
|
|
457
|
+
Give visitors a light and dark switch anywhere, styled your way, by marking an element with `data-colorsbymax-mode`:
|
|
458
|
+
|
|
459
|
+
```html
|
|
460
|
+
<button data-colorsbymax-mode="toggle">Light / dark</button>
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
**Add a light and dark switch to your site**, in the panel's settings (under Theme mode) and on the **I'm done** screen, previews one in your top bar and gives you ready-made code and an AI-editor prompt. `toggle` switches between light and dark; `light`, `dark` and `system` set one mode. colorsbymax wires the click, remembers the choice and sets `aria-pressed`. The page is marked with the current mode, for anything your CSS wants to adjust, like photos:
|
|
464
|
+
|
|
465
|
+
```css
|
|
466
|
+
html[data-colorsbymax-scheme="dark"] .hero-photo {
|
|
467
|
+
filter: brightness(0.9);
|
|
468
|
+
}
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
With `ThemeProvider`, `useTheme()` gives `mode` ('light' or 'dark'), `modeSetting` (including 'system') and `setMode(mode)`, for building your own switch.
|
|
472
|
+
|
|
473
|
+
### PDF uploads
|
|
474
|
+
|
|
475
|
+
Building a palette from an image works out of the box. PDFs, such as brand guides, need [PDF.js](https://mozilla.github.io/pdf.js/), which is large, so it's opt-in: install it and pass the loader from `colorsbymax/pdf`.
|
|
476
|
+
|
|
477
|
+
```bash
|
|
478
|
+
npm install pdfjs-dist
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
```jsx
|
|
482
|
+
import { loadPdf } from 'colorsbymax/pdf'
|
|
483
|
+
|
|
484
|
+
<ThemeProvider config={{ ...config, pdf: loadPdf }}>
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
PDF.js still downloads only when a visitor picks a PDF. Sites that don't opt in never install or bundle it, and the upload offers images only.
|
|
488
|
+
|
|
489
|
+
`examples/tsungi.config.js` is a complete example for tsungi.online, the first site to use colorsbymax.
|
|
490
|
+
|
|
491
|
+
<br>
|
|
492
|
+
|
|
493
|
+
<img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/section-ship.svg" alt="05 · Ship it: keep your colours and go live" width="100%">
|
|
494
|
+
|
|
495
|
+
## Finished? Keep your colours and hide the switcher
|
|
496
|
+
|
|
497
|
+
The colours you pick in the panel are saved only in your own browser. When you're happy with them, press **I'm done** at the bottom of the panel. It shows your colours and three ways to finish, each with code to copy and a prompt you can paste into Claude, Cursor, Copilot or any AI editor. **Cancel, keep using colorsbymax** takes you back without changing anything.
|
|
498
|
+
|
|
499
|
+
### Keep the colours and hide it in production (recommended)
|
|
500
|
+
|
|
501
|
+
Make your pick the site's default for everyone, and keep the button out of production while it still shows when you run the site locally, so you can keep iterating:
|
|
502
|
+
|
|
503
|
+
```js
|
|
504
|
+
// With the one-line setup, replace `import 'colorsbymax/auto'` with:
|
|
505
|
+
import { autoMount } from 'colorsbymax/auto'
|
|
506
|
+
|
|
507
|
+
autoMount({
|
|
508
|
+
defaultTheme: { name: 'Ocean', tokens: { primary: '#0d6b84', /* …every colour… */ } },
|
|
509
|
+
hidden: import.meta.env.PROD,
|
|
510
|
+
})
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
With `ThemeProvider`, add the same `defaultTheme` and `hidden` to its `config`. The panel fills in all your colours for you. Not using Vite? Use `process.env.NODE_ENV === 'production'` in place of `import.meta.env.PROD` (Next.js, webpack).
|
|
514
|
+
|
|
515
|
+
**Bring it back later:** it keeps showing in development. To show it in production again, set `hidden: false` or remove the line, or ask your AI editor: *"Show the colorsbymax colour switcher again in production: in its config, set hidden to false or remove the hidden line."*
|
|
516
|
+
|
|
517
|
+
### Hide it on this device only
|
|
518
|
+
|
|
519
|
+
Hides the button in your browser straight away, with no code change and nothing different for anyone else. **To bring it back**, press **Alt+Shift+C** on the page, or open it with `?colorsbymax` at the end of the address.
|
|
520
|
+
|
|
521
|
+
### Remove colorsbymax
|
|
522
|
+
|
|
523
|
+
1. `npm uninstall colorsbymax`
|
|
524
|
+
2. Delete its import (`import 'colorsbymax/auto'`, `autoMount`, or `ThemeProvider` and `ThemeSwitcher`) and any colorsbymax pre-paint script.
|
|
525
|
+
3. Keep your colours:
|
|
526
|
+
- If your site uses the `--color-*` variables, paste the CSS the panel gives you (`:root { --color-primary: …; … }`) into your global stylesheet.
|
|
527
|
+
- If colorsbymax was re-colouring hard-coded colours for you, the chosen colours only exist while it runs, so your CSS needs updating to them. The panel's prompt asks your AI editor to do that.
|
|
528
|
+
|
|
529
|
+
To bring it back later, install it again and follow the [Quick start](#quick-start).
|
|
530
|
+
|
|
531
|
+
## Updating
|
|
532
|
+
|
|
533
|
+
```bash
|
|
534
|
+
npm install colorsbymax@latest
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
This moves you to the newest release and records it in your `package.json`. `npm update` alone isn't enough while colorsbymax is below 1.0: with the usual `^0.1.0` range, npm treats 0.2.0 as a breaking change and stays on 0.1.x. Check which version you have with `npm ls colorsbymax`.
|
|
538
|
+
|
|
539
|
+
If it still installs the old version right after a release, npm is using its cached list of versions; add `--prefer-online` to check the registry:
|
|
540
|
+
|
|
541
|
+
```bash
|
|
542
|
+
npm install colorsbymax@latest --prefer-online
|
|
543
|
+
```
|
|
544
|
+
|
|
545
|
+
What changed in each release, and anything you need to do when upgrading, is in [CHANGELOG.md](CHANGELOG.md).
|
|
546
|
+
|
|
547
|
+
From 0.5.0, colorsbymax tells you itself: when a newer version is out, the bell in the panel shows it (where you work on your site), with what changed, this command to copy and a prompt for your AI editor. See [The bell](#the-bell-updates-and-news).
|
|
548
|
+
|
|
549
|
+
<br>
|
|
550
|
+
|
|
551
|
+
<img src="https://raw.githubusercontent.com/MaxMuyalwa/colorsbymax/main/docs/readme/section-hood.svg" alt="06 · Under the hood: build, regenerate, contribute" width="100%">
|
|
552
|
+
|
|
553
|
+
## Building the package
|
|
554
|
+
|
|
555
|
+
`src/` is the source; `dist/` is what sites install: plain JavaScript with the JSX compiled away. `types/` holds the hand-written TypeScript declarations; `npm run typecheck` compiles `types/check.tsx` against them and checks they match the built exports. The panel's icons are copied from Lucide into `src/icons.jsx` by `npm run icons`. `dist/` is committed so installs straight from GitHub work even when npm skips install scripts, so rebuild it before committing changes to `src/`. `npm publish` also rebuilds it first:
|
|
556
|
+
|
|
557
|
+
```bash
|
|
558
|
+
npm run build
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
## README artwork
|
|
562
|
+
|
|
563
|
+
The hero, the section banners and the navigation chips are SVGs in `docs/readme/`, drawn by `scripts/make-readme-art.mjs` from colorsbymax's own themes:
|
|
564
|
+
|
|
565
|
+
```bash
|
|
566
|
+
node scripts/make-readme-art.mjs
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
## Panel styles
|
|
570
|
+
|
|
571
|
+
The panel is styled with Tailwind classes in `src/ThemePanel.jsx` and `src/ThemeSwitcher.jsx`. `scripts/build-css.mjs` compiles them, with `src/panel.css`, into `src/panel-css.generated.js`. The demo server does this automatically as you edit; otherwise run:
|
|
572
|
+
|
|
573
|
+
```bash
|
|
574
|
+
npm run css
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
## Regenerating the library
|
|
578
|
+
|
|
579
|
+
```bash
|
|
580
|
+
npm run presets
|
|
581
|
+
```
|
|
582
|
+
|
|
583
|
+
`scripts/generate-presets.mjs` turns each source palette into a full theme, auto-fixes contrast, drops anything that still fails or duplicates another theme, names it and tags its categories. Adjust the category rules at the top of the script.
|
|
584
|
+
|
|
585
|
+
## Notices
|
|
586
|
+
|
|
587
|
+
The library palettes come from [nice-color-palettes](https://github.com/Jam3/nice-color-palettes) (MIT). Its licence notice is in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and must ship with every copy.
|
|
588
|
+
|
|
589
|
+
PDF reading uses [pdfjs-dist](https://github.com/mozilla/pdf.js) (Apache-2.0), installed as a dependency rather than bundled into colorsbymax.
|
|
590
|
+
|
|
591
|
+
## Licence
|
|
592
|
+
|
|
593
|
+
colorsbymax is released under the [MIT Licence](LICENSE). The names colorsbymax and mrmaxdesigns are marks of Max Muyalwa and aren't covered by the code licence.
|