feat: release Colour Tools 0.1.0
This commit is contained in:
@@ -0,0 +1,128 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user