colorsbymax 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 What changed in each colorsbymax release. Update with `npm install colorsbymax@latest`.
 
+## 0.2.1 (2026-09-25)
+
+- **Smarter colours when re-colouring a site.** After swapping, text and icons are only adjusted to undo harm the swap did: a pair that reads as well as the site's original design did is left alone (so deliberately soft icons stay soft), and a fix keeps the design's intent, so white icons on a coloured pill stay white, using the nearest theme colour that works. Icon-only buttons are judged as icons (3:1), not text (4.5:1). Across 59 themes on a test site, nothing reads worse than the original design.
+- **Audit.** A new Audit button in the panel header checks the page in the chosen colours and pins numbered notes to what won't look right: a logo that's hard to see (offering "Colour the logo", or, for picture logos colorsbymax can't re-colour, advice and a "Preview inverted" look), pictures whose solid background shows as a box against the theme, and text or icons below readable contrast. A bar by the colour button shows the count and the theme's own contrast issues, with Re-check and Close; it re-checks by itself when the colours or settings change.
+- **"I'm done": finish without the switcher popping up in production.** A new button at the bottom of the panel shows your chosen colours and three ways to finish, each with code to copy and a prompt for Claude, Cursor or Copilot: keep the colours as the site's default and hide the switcher in production (it still shows in development), hide it on this device only (Alt+Shift+C or `?colorsbymax` brings it back), or remove colorsbymax and keep the colours in your CSS. Cancel goes back.
+- **`hidden` config option:** hides the colour button while the theme still applies, e.g. `hidden: import.meta.env.PROD`.
+- A `defaultTheme` in the config is now applied on re-coloured sites too (it used to be treated as the page's original look), and the page's own colours stay available as "… original".
+- **"Colour the logo too" setting**, off by default: the site's logo keeps its own colours whatever the theme. It works on re-coloured sites and on sites using the colour variables. colorsbymax finds logos by `data-colorsbymax-logo`, or "logo" in a class, id or label, or common brand classes.
+- Fixed: content that appeared while a theme was showing could be re-coloured from the theme's colours instead of the site's, giving the wrong colour (for example buttons turning blue).
+- Fixed: decorative gradient strips, like animated underlines, were treated as the background behind text and icons.
+- When an element changes class (a nav item becoming active), its contents are re-checked too.
+
 ## 0.2.0 (2026-09-25)
 
 **Upgrading from 0.1.x:** the colour button moves to the bottom-right corner; add `position: 'top-right'` to keep it where it was. If your site doesn't use colorsbymax's `--color-*` variables, themes now re-colour it automatically; to keep the old behaviour (themes set only the variables), pass `recolour: false` in the config.

package/README.md

@@ -28,6 +28,7 @@ A floating theme switcher for websites. Visitors (or the site's owner) can re-co
 - **Light and dark mode.** Every built-in theme is designed light; dark mode lists a generated dark twin of each (dark surfaces, light text, brand colours lifted to read on dark, then contrast-fixed) and switches the current theme to its twin. The panel turns dark with it. Custom palettes stay as they were made.
 - **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.
 - **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.
+- **Audit the page.** The **Audit** button in the panel header 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 (it also re-checks when the colours change) and close it from its bar.
 - **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.
 - **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`.
 - **Accessible panel.** A labelled dialog with focus trap, Escape, the colour button or an outside click to close, keyboard operable, and reduced-motion support.
@@ -69,6 +70,7 @@ That's all. The colour button appears in the bottom-right corner once the page h
   autoMount({ siteName: 'My site', storageKey: 'my-site-theme' })
   ```
 
+- **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).
 - **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.
 
 Already installed it? Get the newest version with `npm install colorsbymax@latest` (see [Updating](#updating)).
@@ -133,6 +135,7 @@ Without a `siteName`, the site group is named from the page's `og:site_name`, it
                                     // no --color-* variables, the default), true or false
   position: 'bottom-right',         // where the button starts: bottom-right (default), bottom-left,
                                     // top-left, or top-right (just under a floating nav bar)
+  hidden: import.meta.env.PROD,     // hide the button (the theme still applies), e.g. in production
 }
 ```
 
@@ -154,6 +157,42 @@ PDF.js still downloads only when a visitor picks a PDF. Sites that don't opt in
 
 `examples/tsungi.config.js` is a complete example for tsungi.online, the first site to use colorsbymax.
 
+## Finished? Keep your colours and hide the switcher
+
+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.
+
+### Keep the colours and hide it in production (recommended)
+
+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:
+
+```js
+// With the one-line setup, replace `import 'colorsbymax/auto'` with:
+import { autoMount } from 'colorsbymax/auto'
+
+autoMount({
+  defaultTheme: { name: 'Ocean', tokens: { primary: '#0d6b84', /* …every colour… */ } },
+  hidden: import.meta.env.PROD,
+})
+```
+
+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).
+
+**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."*
+
+### Hide it on this device only
+
+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.
+
+### Remove colorsbymax
+
+1. `npm uninstall colorsbymax`
+2. Delete its import (`import 'colorsbymax/auto'`, `autoMount`, or `ThemeProvider` and `ThemeSwitcher`) and any colorsbymax pre-paint script.
+3. Keep your colours:
+   - If your site uses the `--color-*` variables, paste the CSS the panel gives you (`:root { --color-primary: …; … }`) into your global stylesheet.
+   - 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.
+
+To bring it back later, install it again and follow the [Quick start](#quick-start).
+
 ## Updating
 
 ```bash
@@ -162,6 +201,12 @@ npm install colorsbymax@latest
 
 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`.
 
+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:
+
+```bash
+npm install colorsbymax@latest --prefer-online
+```
+
 What changed in each release, and anything you need to do when upgrading, is in [CHANGELOG.md](CHANGELOG.md).
 
 ## Building the package