colorsbymax 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 What changed in each colorsbymax release. Update with `npm install colorsbymax@latest`.
 
+## 0.3.0 (2026-09-25)
+
+- **Dark mode for every site, on every load.** The mode now lives in the theme provider: a saved Dark (or Auto on a dark device) turns the whole site dark as soon as it loads, not only when the mode is changed, and it keeps working when the switcher is hidden. Before, the panel could go dark while the site stayed light. Sites without a dark mode of their own get one: every theme's dark twin re-colours the page, contrast-checked.
+- **A light and dark switch for your site:** mark any element with `data-colorsbymax-mode="toggle"` (or `light`, `dark`, `system`) and colorsbymax wires it up and remembers the choice. `<html>` gets `data-colorsbymax-scheme` with the current mode, and `useTheme()` has `mode`, `modeSetting` and `setMode`.
+- **Light, Dark and Auto in the panel's header**, next to Audit, so they're one click away.
+- **"Add to site": a light and dark switch for your site.** Next to the mode buttons, it previews a working switch in your page's top bar (until reload) and gives the code (HTML or React, plus styles) and a prompt for Claude, Cursor or Copilot to add it for good.
+- **Plain sites show off a theme.** On a site with no brand colour of its own (greys and text), grey icons and plain text links now take the theme's brand colour, contrast-checked, so a theme visibly changes the page.
+- **A burst of colour on every click** of the colour button, not only when it first appears.
+- **The panel stays open while you drag the button**, and moves with it.
+- **Picking a library category scrolls to its themes**, so the colours are in view straight away.
+- **Feedback on the colorsbymax site:** a Feedback button in the top bar (and the menu and footer) opens a form for bug reports, suggestions, praise and questions, with the areas it's about, a rating, steps to reproduce, expected and actual results, severity, several screenshots (pasted, dropped, chosen or captured from the page) and technical details attached automatically. The coffee and bakery demo pages are gone: the colorsbymax site is the demo. The site also asks for feedback in its own section, and has a support page (buy Max a coffee, coming soon).
+- **The colour button makes an entrance.** A moment after the page loads, it pops in with a burst of squiggles, dots and dashes in the theme's colours, so visitors notice it arrive. With reduced motion it simply fades in. Turn it off with `intro: false`.
+- **A new colorsbymax site** at [mrmaxdesigns.com/colorsbymax](https://mrmaxdesigns.com/colorsbymax): what colorsbymax does and why, every colour role explained with a live preview, the rules of good colour (with a little history), setup guides, coding-agent setup, and a way back to mrmaxdesigns.com. Every colour on it follows the theme you pick.
+- **Set-up steps for many more coding agents,** in the README, the MCP README and the site: GitHub Copilot CLI, Codex, Google Antigravity, Gemini CLI, Grok Build, Windsurf, Kiro, Zed, JetBrains, Cline and Roo, and opencode, alongside Claude Code, Cursor, VS Code and Claude Desktop. The MCP server's docs tool has a new `agents` topic with all of them (colorsbymax-mcp 0.1.3).
+- **Dark themes always read.** A dark twin's brand, data and status colours are now lifted until they measurably pass against the dark background, and buttons get whichever text colour (dark or white) reads best. Before, a few vivid blues and violets stayed too dark to read (7 of the 720 built-in themes, and some sites' own colours); now every built-in theme passes every check in both light and dark.
+- The colorsbymax site's own colours now pass every contrast check in light and dark.
+- Fixed: when the colour button was hidden on a device, the next page load could stop the switcher with an error.
+- The demo is live at [mrmaxdesigns.com/colorsbymax](https://mrmaxdesigns.com/colorsbymax), now the package's homepage.
+
+## 0.2.3 (2026-09-25)
+
+- **Paste an image to build a palette.** Took a screenshot of something whose colours you like? Open the panel and press Ctrl+V (⌘V on a Mac), or use the new **Paste image** button in Import / export. Import / export opens by itself and shows a thumbnail of the image, marked "Image pasted", with its size and a button to remove it (dropped and chosen images get the same preview). Pasting text into a field still works as usual.
+- The README and the MCP README now explain the steps after adding the MCP server: start a new session, ask your agent to add colorsbymax, and run your site.
+
 ## 0.2.2 (2026-09-25)
 
 - **MCP server for AI agents.** [colorsbymax-mcp](mcp/) lets Claude Code, Cursor, VS Code Copilot and other agents set colorsbymax up in a project (with the right edits for Vite, Next.js, Remix, Astro, Nuxt, SvelteKit, plain HTML and more), find themes, build one from brand colours, check contrast and finish. Add it with `claude mcp add colorsbymax -- npx -y colorsbymax-mcp`.

package/README.md

@@ -10,6 +10,8 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/licence-MIT-c2410c?style=flat-square" alt="MIT licence"></a>
 </p>
 
+<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>
+
 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.
 
 <p align="center">
@@ -64,12 +66,14 @@ Already installed it? Get the newest version with `npm install colorsbymax@lates
 
 ## Try the demo
 
+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:
+
 ```bash
 npm install
 npm run dev
 ```
 
-This serves `demo/`: colorsbymax's own landing page, built with Tailwind, where every colour is a token (it uses every token group, and a strip shows the live values); `/plain.html`, a plain-CSS bakery site with deliberately careless global styles to show they don't reach the panel; and `/unwired.html`, a coffee shop with only hard-coded colours whose whole setup is `import 'colorsbymax/auto'`.
+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/`.
 
 <br>
 
@@ -77,7 +81,7 @@ This serves `demo/`: colorsbymax's own landing page, built with Tailwind, where
 
 ## Coding agents (MCP)
 
-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, VS Code Copilot, Claude Desktop, Windsurf, Codex and other agents colorsbymax's own tools:
+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:
 
 | The agent can… | Tool |
 | --- | --- |
@@ -90,6 +94,13 @@ Your coding agent can set colorsbymax up and use it for you. [colorsbymax-mcp](m
 
 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).
 
+**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:
+
+1. **Add the server** once, with the steps for your editor below.
+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.
+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).
+4. **Run your site** (for example `npm run dev`). The colour button appears in the bottom-right corner.
+
 ### Claude Code
 
 ```bash
@@ -98,6 +109,8 @@ claude mcp add colorsbymax -- npx -y colorsbymax-mcp
 
 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.
 
+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`."*
+
 ### Cursor
 
 Add this to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:
@@ -128,9 +141,21 @@ Add this to `.vscode/mcp.json`, then use it from Copilot Chat in **Agent** mode:
 
 Open **Settings → Developer → Edit Config**, add the same `mcpServers` entry as Cursor to `claude_desktop_config.json`, and restart Claude Desktop.
 
-### Windsurf, Cline, Codex and others
+### GitHub Copilot CLI
+
+```bash
+copilot mcp add colorsbymax -- npx -y colorsbymax-mcp
+```
+
+Or type `/mcp add` inside `copilot`. It's saved to `~/.copilot/mcp-config.json`.
 
-Most agents take the same `mcpServers` entry as Cursor: Windsurf in `~/.codeium/windsurf/mcp_config.json`, and Cline under **MCP Servers → Configure**. For the Codex CLI, add this to `~/.codex/config.toml`:
+### Codex (OpenAI)
+
+```bash
+codex mcp add colorsbymax -- npx -y colorsbymax-mcp
+```
+
+It's saved to `~/.codex/config.toml`, which the Codex IDE extension shares. To write it by hand:
 
 ```toml
 [mcp_servers.colorsbymax]
@@ -138,6 +163,57 @@ command = "npx"
 args = ["-y", "colorsbymax-mcp"]
 ```
 
+### Google Antigravity
+
+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.
+
+### Gemini CLI
+
+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`.
+
+### Grok Build (xAI)
+
+```bash
+grok mcp add colorsbymax -- npx -y colorsbymax-mcp
+```
+
+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.
+
+### Windsurf, Kiro, JetBrains, Cline and Roo
+
+They take the same `mcpServers` entry as Cursor:
+
+- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`
+- **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.
+- **JetBrains:** AI Assistant under **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**; Junie under **Settings → Tools → Junie → MCP Settings**.
+- **Cline and Roo Code:** in the extension's **MCP Servers** view, choose **Configure** (or **Edit MCP Settings**).
+
+### Zed and opencode
+
+Zed calls them context servers. In `settings.json`, or through **Settings → AI → MCP Servers → Add Server**:
+
+```json
+{
+  "context_servers": {
+    "colorsbymax": { "command": "npx", "args": ["-y", "colorsbymax-mcp"] }
+  }
+}
+```
+
+opencode, in `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "colorsbymax": { "type": "local", "command": ["npx", "-y", "colorsbymax-mcp"] }
+  }
+}
+```
+
+### Any other MCP client
+
+Most take the same `mcpServers` entry as Cursor: the command is `npx`, with `-y colorsbymax-mcp` as its arguments.
+
 On Windows, if an editor can't start `npx`, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "colorsbymax-mcp"]`.
 
 ### What to ask
@@ -166,12 +242,12 @@ When you're done choosing colours, the panel's **I'm done** button gives you rea
 - **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.
 - **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.
 - **Custom palettes, single-colour overrides, JSON import/export.**
-- **Palettes from images and PDFs.** In Import / export, upload or drop a mood board, screenshot or photo. 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.
+- **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.
 - **Contrast checks.** Problems show as a badge on the theme; the breakdown offers per-item fixes or "Fix all automatically", which changes lightness only.
 - **No flash on reload.** An inline pre-paint script applies the saved theme before the page draws.
 - **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.
-- **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 the panel closes while it moves) 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.
-- **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.
+- **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.
+- **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.
 - **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.
@@ -206,7 +282,7 @@ This is the full setup, for sites that want exact control over which colour goes
    }
    ```
 
-   With plain CSS, or Tailwind before v4, define the variables yourself (`demo/plain.html` shows this):
+   With plain CSS, or Tailwind before v4, define the variables yourself:
 
    ```css
    :root {
@@ -228,7 +304,7 @@ This is the full setup, for sites that want exact control over which colour goes
    </ThemeProvider>
    ```
 
-   The switcher needs React but not a React site: `demo/plain.jsx` mounts it on its own next to a static page.
+   The switcher needs React but not a React site: `autoMount` from `colorsbymax/auto` mounts it on its own next to any page.
 
 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.
 
@@ -250,9 +326,31 @@ Without a `siteName`, the site group is named from the page's `og:site_name`, it
   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
+  intro: true,                      // the button pops in with a burst of the theme's colours a moment
+                                    // after the page loads (default); reduced motion fades it in
 }
 ```
 
+### Dark mode
+
+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.
+
+Give visitors a light and dark switch anywhere, styled your way, by marking an element with `data-colorsbymax-mode`:
+
+```html
+<button data-colorsbymax-mode="toggle">Light / dark</button>
+```
+
+The panel's **Add to site** button (next to Light, Dark and Auto) 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:
+
+```css
+html[data-colorsbymax-scheme="dark"] .hero-photo {
+  filter: brightness(0.9);
+}
+```
+
+With `ThemeProvider`, `useTheme()` gives `mode` ('light' or 'dark'), `modeSetting` (including 'system') and `setMode(mode)`, for building your own switch.
+
 ### PDF uploads
 
 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`.