# Colour Tools Colour Tools is a standalone, local-first browser workbench for converting, compositing, interpolating, sampling, comparing and organising colours. It is part of the [add·ideas Toolbox](https://git.add-ideas.de/lotobo/toolbox-portal), but every release also runs independently from a static HTTPS host or local preview. No colour, image, palette or usage event is sent to a server. Image decoding, pixel sampling and palette extraction happen in the browser; the application has no analytics, accounts, advertisements or remote lookup feature. ## Workspaces - **Convert** parses CSS colours and presents copy-ready hex, RGB, HSL, HSV, HWB, CMYK, Lab, LCH, OKLab, OKLCH, Display P3, Adobe RGB, ProPhoto RGB, Rec. 2020 and XYZ representations. Wide-gamut coordinates remain intact until an explicit display or gamut-mapping step. A batch converter isolates invalid lines instead of silently dropping them. - **Composite** calculates Porter–Duff source-over for an arbitrary ordered stack of translucent colours. Each layer has its own alpha, opacity and blend mode. The working-light choice makes encoded-sRGB and linear-light results explicit, and an optional matte produces an opaque RGB result. - **Steps** builds multi-stop colour ramps in perceptual, RGB or cylindrical colour spaces. It supports positioned stops, five hue routes, easing, premultiplied-alpha interpolation by default with a straight-alpha option, and a linear/radial/conic/repeating gradient editor with copy/download CSS and a versioned JSON recipe. - **Pick** provides a large keyboard- and pointer-operable HSV picker, alpha control, exact CSS entry, browser-native colour input, recent picks and the system EyeDropper API where the browser exposes it. - **Image** accepts one bounded local PNG, JPEG, WebP, GIF or AVIF. It samples an exact coordinate or a configurable average/median neighbourhood and extracts two to twelve perceptual palette colours in a worker when available. - **Contrast** flattens transparency against a stated canvas, reports WCAG 2 contrast thresholds, finds a nearby passing foreground, compares colours by six Delta E methods, checks colour gamuts and previews four approximate colour-vision deficiencies. - **Palette** creates OKLCH harmonies, tints, shades and tones; keeps a named palette in local browser storage; imports common text/JSON token forms; and imports/exports DTCG 2025.10 structured colour tokens and local aliases; displays a bounded directional WCAG contrast matrix; and exports CSS, SCSS, JSON, Design Tokens JSON, JavaScript or CSV. Adding a generated or sampled colour to the palette is always explicit. The saved palette is device-local and can be cleared from the Palette workspace or by clearing site storage. ## Colour behaviour Colour Tools keeps source coordinates outside display gamuts so conversions do not destructively clip them. Browser previews and hex exports are mapped to sRGB with an explicit indicator when mapping was needed. Compositing is carried out in the selected sRGB working light, while interpolation defaults to OKLCH for perceptual spacing. See [docs/COLOUR-MATH.md](docs/COLOUR-MATH.md) for the formulas, bounds and terminology. Contrast pass/fail indicators follow WCAG 2 ratios: 3:1 for non-text UI and large text, 4.5:1 for normal AA text and 7:1 for normal AAA text. They are an engineering aid, not a complete accessibility audit; typography, state, context and non-colour cues still need human review. DTCG import requires an explicit, inherited or reference-resolved `$type` and does not guess token types. Supported colour-space components are validated against the 2025.10 ranges; `none` components are reported as unsupported because the current internal colour model is numeric. Imports are bounded to 2 MiB, 10,000 tokens and 32 group levels. Exact duplicate saved values are reported and not added twice. ## Local image handling Selecting an image decodes a bounded raster locally with `createImageBitmap` where available. The image-element fallback uses a temporary in-memory object URL. Decoded resources and any fallback URL are released when the image is replaced, removed or the workspace is closed. Palette extraction uses a deterministic OKLab clustering implementation and bounded sampling rather than uploading the image or retaining a copy. Metadata outside the decoded raster is not exposed or stored by the application. ## Browser support Current evergreen Firefox, Chromium and Safari are the deployment target. JavaScript modules, CSS custom properties, Canvas 2D and Web Workers are used. The EyeDropper API is progressive enhancement and only appears where a browser supports it. Clipboard writes, service workers and EyeDropper access may require HTTPS and browser permission; all core calculations work without them. The UI supports system, light and dark themes through the shared Toolbox shell. Tabs, picker controls and image sampling are keyboard operable, status changes use live regions, and swatches are accompanied by machine-readable colour values rather than relying on colour alone. ## Offline application shell Production builds include a relative-scope web app manifest and a subpath-aware service worker. After one successful load, the worker caches the application shell and same-origin built assets, uses network-first navigation with a cached fallback, serves cached static resources where possible and removes obsolete cache versions. Service-worker support is optional; colour operations never depend on a network connection. ## Development Requirements: Node.js 22 or newer and npm 11 or newer. ```sh npm ci npm run check npm run test:browser npm run dev ``` Vite uses `base: './'`, so `dist/` is relocatable to `/` or a nested Toolbox path. `toolbox-check` validates standalone and contextual operation. The main implementation layers are described in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). Contributions should follow [CONTRIBUTING.md](CONTRIBUTING.md); please report security concerns according to [SECURITY.md](SECURITY.md). ## Release ```sh npm run release:artifact ``` This command checks the manifest, types, lint, formatting, unit tests, production build, Toolbox contract and browser workflows, then creates a deterministic `release/colour-tools-0.2.0.zip` and matching SHA-256 sidecar. The archive is a ready-to-host static application and contains project and third-party licence notices. ## Licence Colour Tools is free software under `GPL-3.0-or-later`. See [LICENSE](LICENSE). Runtime dependencies retain their respective licences; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).