# IDEA.md – a program that works out color mixes This is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build an implementation of your own. It draws on what was learned building Color Paint, a desktop program for Windows and macOS written in Rust with Claude Code. ## 1. What to build A desktop program that works out **how to mix colors to hit a target color**, using the colors the user actually owns. The problem: anyone tinting epoxy, polyurethane, paint or another material sometimes needs to match an existing color as closely as possible. Guessing proportions from a handful of base colors rarely works. Web services that do it often require a subscription and cap the number of mixes per day. The program should do the same thing locally, offline, with no cap. The program must be able to: - **Take a target color** as hex (`#7A9668`, `7a9668`, `#abc`), `rgb(…)`, `hsl(…)`, HSV, CMYK, CIELAB or LCh, from a color picker, with an eyedropper on an image, or as a code or name from a color chart (`RAL 3020`, `ral3020`, `3020`). All fields stay in sync. Ctrl+V anywhere in the window pastes a target color. - **List the best recipes** from the selected palette, best first. Each recipe has the colors in whole parts and percent, the predicted color, ΔE (CIEDE2000) to the target and a verdict. - **Convert parts into amounts** for a batch: grams, millilitres or drops. - **Show a lightness ladder**: the mix with ¼, ½ and 1 part black or white per part of mix. Clicking a step makes it the target. - **Mixing board**: add parts of colors with + and − and see the predicted mix and ΔE to the target immediately. A recipe can be opened on the board to adjust it, and the mix can become the new target. - **Palettes**: a built-in default palette (15 artist colors) that cannot be changed but can be duplicated. User palettes with name, color, pigment code, tinting strength and an active/inactive checkbox per color. Import and export as a file. - **Color charts**: RAL and paint manufacturers' colors (about 23,000) built into the program. A tab shows them book by book as swatches, with search. A swatch can become the target, be added to a palette or be saved as a recipe. Below the target, the three nearest chart colors are shown with ΔE. - **Saved recipes**: a saved entry is a **target color** with name, note, date and project – not parts. When opened, the recipe is solved against the selected palette as it is at that moment. A searchable list grouped and filterable by project, export as CSV and JSON. The same color is only saved once. - **Eyedropper on an image**: open a PNG or JPEG, click, average over 1×1, 5×5 or 11×11 pixels. Show the image's eight dominant colors (k-means) as swatches. **Not** included: an eyedropper on the screen itself, spectrophotometers, printing, Pantone/NCS (licensing and trademarks), a two-constant model with measured spectra, importing a whole color book as a palette (the solver becomes too slow, see section 5). ## 2. Stack and architecture Color Paint chose the following. What **matters** is marked; the rest can be swapped. - **Rust** (edition 2024), a Cargo workspace with two crates. Chosen for a small, fast, self-contained binary with no runtime, and because the sibling projects use the same setup. Can be swapped, but the solver must be compiled code or equally fast. - **Important: a UI-free core** (`core`) and a separate window program (`app`). The core holds color spaces, the mixing model, the solver, palettes, color charts, the library and the eyedropper maths. It is tested without a window. Everything that can be computed must be testable without starting the program. - **eframe/egui** (0.36) for the interface: immediate mode, the same code on Windows and macOS. Can be swapped for another framework. - **The solver runs on its own thread**, so the color picker doesn't stutter with large palettes. The answer carries which palette it was solved in (see Pitfalls). - **The menu is described once, as data.** On Windows it's drawn in the window; on macOS the same model is synced to the system menu bar (e.g. with `muda`). Keyboard shortcuts live in a single place, and the menu formats its shortcut text from the same constant that triggers the command. Menu, keyboard and buttons all produce the same `Action` values, which go through a single `apply` function. - **The color charts are compiled in** (`include_str!` of a text file, about 590 kB). No download at run time. - **Per-user data**: palettes and recipes in one JSON file, written atomically (write to a temporary file, rename). `%APPDATA%\\data` on Windows, `~/Library/Application Support/` on macOS. - **Third-party data**: the spectral tables from spectral.js (MIT, Ronald van Wijnen) and the color charts from colornerd (MIT). The licenses ship in `third_party/` and in the packages' README. - **Packaging**: the Windows exe cross-compiled with `cargo xwin` to `x86_64-pc-windows-msvc`, an NSIS installer and a portable zip. macOS `aarch64-apple-darwin`, `.app` and dmg. Version number `major.minor.build`, where the build scripts bump the third number. ## 3. Decisions that turned out to matter **Don't mix in RGB.** Paint mixes subtractively: each pigment absorbs part of the spectrum. Averaging RGB mixes light, and yellow + blue becomes grey instead of green. That's wrong exactly where the user needs help. **Spectral Kubelka-Munk, single constant, 38 bands (380–750 nm).** The same model as spectral.js: 1. *Spectrum from sRGB.* Linearize the color and split it into white, cyan, magenta, yellow, red, green and blue (Smits 1999). The spectrum is the sum of seven base curves weighted by those shares. It gives back the same color (ΔE < 1, test it), but it is only *one* of many spectra that produce that color. 2. *K/S per band:* `K/S = (1 − R)² / 2R`. 3. *Mix:* average K/S weighted by the concentration `c = parts² × tinting strength² × luminance`. Convert back to reflectance with `R = 1 + K/S − √((K/S)² + 2·K/S)`, then to XYZ, Lab and sRGB. Squaring the parts and the luminance weight are spectral.js's empirical choices, not physics. Without them, white drowns everything it's mixed with. Mixbox was judged to give better results but is licensed CC BY-NC and therefore can't be used. **Tinting strength per color.** The same RGB says nothing about how strong a color is: phthalo blue and ultramarine can look alike in a thin layer, but phthalo blue completely takes over a mix with white. Each color therefore has a tinting strength that is multiplied into the concentration. The default palette's values are **calibrated**, not guessed: for each color, pick a typical lightness L* for a 1:1 tint with titanium white, and search for the tinting strength that produces it. Put the calibration in a test that runs on demand and prints the new values. Reference values (L* for 1:1 with white → tinting strength): Ivory Black 40 → 2.71; Cadmium Yellow Light 92 → 0.84; Cadmium Yellow Medium 85 → 1.20; Cadmium Red Light 64 → 1.08; Cadmium Red Medium 57 → 1.25; Quinacridone Magenta 55 → 1.57; Alizarin Crimson 55 → 1.31; Dioxazine Purple 40 → 2.78; Ultramarine Blue 50 → 1.87; Phthalo Blue 45 → 2.47; Phthalo Green 50 → 2.58; Yellow Ochre 80 → 0.93; Burnt Sienna 60 → 1.28; Burnt Umber 50 → 1.94. Titanium White 1.0. These are estimates, and they're the first thing to adjust when recipes miss. **The solver.** 1. Try every combination of 1, 2 and 3 active colors. Try 4 colors only as extensions of the 30 best three-color combinations – otherwise the search grows too fast. 2. For each combination: lay a coarse grid over the proportions (the simplex; 24 steps for two colors, 12 for three, 6 for four), each color at least 0.5 %. Refine the best point with coordinate search: move share between two colors at a time, halve the step when nothing improves, stop below 1e-4. The objective is CIEDE2000 to the target. 3. Round the ~80 best combinations to whole parts: try every total up to *Max parts* (default 20), divide by the greatest common divisor, and **pick the smallest total within 0.5 ΔE of the best**. That way 3 : 1 wins over 14 : 5. Judge the recipe on the rounded parts, so the color shown is the color you actually get. 4. Rank with a penalty of 0.35 ΔE per color beyond the first. Remove duplicates (same set of colors). 5. Verdict from ΔE: < 1 Exact ("No visible difference"), < 2 Excellent ("Visible only side by side"), < 5 Good, < 10 Approximate, otherwise Out of reach ("This palette cannot mix the color. Add a paint closer to it."). Say it plainly when the palette isn't enough. Settings: colors per recipe 1–4, *Avoid black*, *Max parts*, batch size and unit. **A saved recipe is a target color, not parts.** Palettes change – colors run out, new ones arrive. Save the target color with name, note, date and project, and solve the recipe against the current palette when it's opened. From the mixing board, the mix's color is saved; with the same palette, the solver finds the same mix again. The name is suggested from the color chart when the target is a chart color. **Chart colors are ordinary colors.** The model derives a spectrum from sRGB for *every* color, including the default palette's. A chart color can therefore go into a palette and be mixed like any other, with tinting strength 1.0. State clearly in the interface that the values are the manufacturers' screen colors, not measured samples. **One source of truth for shortcuts and menu**, see section 2. A new command is added in one place and shows up in the menu, on the keyboard and on both platforms. **Developer hooks from day one.** Environment variables that let an agent review the interface with no one at the screen: - `_DATA_DIR=dir` – a separate data directory, so a test run doesn't touch the user's data - `_WINDOW=1240x800@X,Y` – window size and position - `_SCREENSHOT=file.ppm` – save an image of the window and exit; `_SCREENSHOT_DELAY=N` frames to wait first - `_DEBUG_STATE=…` – comma-separated steps that set up state at start: `tab=…`, `target=#hex|RAL 3020`, `type=text`, `chart=…`, `book=…`, `palette=…`, `board=Name:2;Name:1`, `recipe=N`, `project=…`, `dialog=save|rename`, `do=save:Name|duplicate|new|add` - `_DEBUG_MENU=Recipe` – open a menu so it shows in the image Every debug step must take **the same path** as the menu item or button it stands for, or the screenshot proves nothing. ## 4. Pitfalls - **Show recipes with the palette they were solved in, not the selected one.** Otherwise the recipes point at colors by index in the previous palette when the user switches palette, creates a new empty palette or deletes a color – and the program crashes (`index out of bounds: the len is 0 but the index is 12`). Let the solver's answer carry its palette, and disable "Load Best Recipe" until the answer is for the selected palette. Write a test that asks about an empty palette while the answer for the default palette is shown. - **Expect a panic to be invisible on Windows.** A release build without a console shows no error dialog – the window just disappears. Reproduce with the debug steps and check the exit code (101 on panic, 0 normally). - **Don't assume a color without a measured spectrum can't be mixed.** No color in the model has a measured spectrum; all are derived from sRGB. The wrong premise cost an extra round. - **Clean third-party data before building it in.** colornerd has `rgb(…)` instead of hex for one manufacturer, a space before `#` for two, mixed formats for one, and duplicate codes (Behr 43, Benjamin Moore 12, Kilz 41, MPC 3). Some names are just the code again, and some are truncated ("HC-154 Hale" instead of "Hale Navy"). Write an import script that parses every value with the same color parser as the program, removes duplicates, prefixes the codes (`RAL 3020`, `SW 0001`) and can be re-run. - **Leave out printing-ink books** (DIC, HKS, TOYO, Trumatch), paper and film: they're commercial systems or irrelevant for mixing. Take the paint manufacturers and RAL. - **Don't turn a whole color book into a palette.** The solver handles about 30 colors per palette; 4,000 makes it unusably slow. - **Don't store parts in recipes.** See section 3. Still read old files with parts, keeping their target, name and note. - **Don't build in a `target/` on a Windows drive from WSL.** On `/mnt/…`, rustc fails with `Invalid cross-device link (os error 18)` when renaming its files. Put `target/` on the Linux file system (`CARGO_TARGET_DIR` or a symlink). - **Don't put the system Cut/Copy/Paste in the macOS menu.** The native menu takes the ⌘ keys before egui sees them, and ⌘C/⌘V stop working in text fields. - **A screenshot of the window doesn't reach the macOS menu bar.** Draw the menu in the window with `_DEBUG_MENU` when it needs reviewing. - **A fully covered window isn't drawn on macOS**, and then no screenshot is taken. Place the window visibly with `_WINDOW=…@X,Y`. - **Don't bump the version twice for the same release.** A failed build bumped the number; let an environment variable (`_KEEP_BUILD=1`) hold it still. ## 5. Requirements and measurements Benchmarks from Color Paint (release, Apple Silicon unless stated): - The solver: 15 colors, at most 3 per recipe: **13–19 ms** per search. The requirement was under 500 ms. At most 4 per recipe: **34 ms**. Add a test with a time limit that only applies in release. - The color charts: 22,960 colors in 16 books. Loading 9.5 ms once, search 0.10 ms, nearest color 0.05 ms – no cache needed. The grid draws only the visible rows. - The binary grew from 14.06 to 14.69 MB when the charts were built in. Windows installer 6.3 MB, portable zip 6.0 MB. - The spectrum derived from sRGB must give back the same color with ΔE < 1. - Examples from the default palette to test against: - `#7A9668` sage → 4 Yellow Ochre + 3 Titanium White + 2 Ultramarine Blue, ΔE 0.99 - `#E8C4B8` pastel pink → 12 Titanium White + 3 Cadmium Red Light + 1 Ultramarine Blue, ΔE 0.73 - `#8B5A2B` saddle brown → 6 Burnt Umber + 5 Cadmium Yellow Medium + 2 Quinacridone Magenta, ΔE 0.18 - `#00FF00` neon green → ΔE 9.7, and the program says the color is outside the palette - The solver can be run from the terminal: an example program that takes a target color and a maximum number of colors and prints the recipes. ## 6. How it's verified - **Unit tests in the core** for: color parsing (every notation and tolerant variants), that every color space round-trips through RGB, CIEDE2000 against Sharma's reference pairs, that the spectrum from sRGB gives back the color, that yellow and blue make green and not grey, that a color mixed with itself is unchanged, that white lightens without shifting the hue much, that a known mix is found again with ΔE < 1, that *max colors*, *Avoid black* and unticked colors are respected, that whole parts mix back to exactly the color shown, that recipes keep their palette, that every color chart line is read, code variants in search, that the nearest lookup agrees with a full search, that old library files are read, that a broken file is moved aside rather than overwritten, and that atomic writes leave no temporary files. - **Lint and cross-check**: `cargo clippy --workspace --all-targets` with no warnings, `cargo test --workspace --release`, and `cargo check --target` for the platform you're not on. - **The interface is reviewed with screenshots** taken with the developer hooks from the real binary – not assumed. A task is done when the image shows it. - **Smoke test of the package**: start the packaged binary with its own data directory, save a palette and a recipe, restart and check they're still there. - **Against real paint**: mix three recipes for real – a green from yellow and blue, a pastel with white, a brown – and compare with the prediction, ideally with a colorimeter or a photo in even light. This has *not* yet been done for Color Paint, and it's where the model most needs testing: the squared parts and the tinting strengths. "Done" means: tests green, clippy quiet, both platforms checked, and every interface change shown in a screenshot. ## 7. Way of working - **Plan first.** Start with research on similar programs (Trycolors, Mixbox, spectral.js, Golden mixers, "Paint Mixer" apps) and write a plan: mixing model, solver, limitations. Split the work into small tasks, each with a clear line for what's not included. - **Ask about real decisions, not everything.** Examples: should chart colors be targets or mixing colors? Which books go in? Must old saved recipes be preserved? Comment on the interpretation before building when a premise chafes – and correct the premise openly when it turns out wrong. - **One task at a time**, with the measurement in the closing comment: times, number of tests, file sizes. - **Test in a real environment.** Build the Windows package and run the real exe with the developer hooks; take screenshots from there. What needs a human – the installer, the icon in Explorer, real key presses, mixing real paint – becomes separate verification tasks. ## 8. The prompt > Build a desktop program for [Windows and macOS] in [Rust with eframe/egui] that works out how to mix colors to hit a target color, using the colors the user owns. I tint [epoxy and polyurethane / paint / …] and sometimes need to match an existing color as closely as possible. > > Read all of IDEA.md below first. It describes the features, the mixing model (spectral Kubelka-Munk as in spectral.js, not RGB), the solver, the decisions that turned out to matter and the pitfalls to avoid. > > Work like this: > 1. Research similar programs and write a plan. Split the work into small parts and say what's not included. > 2. Put all computation in a library without an interface, with tests, before building the window. > 3. Build the developer hooks (separate data directory, window size, screenshot, debug steps) early, and review every interface change with a screenshot from the real binary. > 4. Only ask me about real decisions, for example [which color charts to include, the default palette's colors, units for the batch]. > 5. Measure the solver's time and report it. The requirement is under 500 ms with [15] colors and at most 3 per recipe. > > My palette: [list your colors, ideally with pigment codes, or use the default palette in IDEA.md]. > > [paste IDEA.md here]