colour-tools/public/README.md

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, 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 copy-ready CSS and JSON output.
• 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 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 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.

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.

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. Contributions should follow CONTRIBUTING.md; please report security concerns according to SECURITY.md.

Release

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.1.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. Runtime dependencies retain their respective licences; see THIRD_PARTY_NOTICES.md.