129 lines
5.9 KiB
Markdown
129 lines
5.9 KiB
Markdown
# 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 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](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.
|
||
|
||
```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.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](LICENSE). Runtime dependencies retain their respective licences; see
|
||
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|