# Contributing

Thank you for improving Colour Tools. Contributions should preserve its three
core properties: local-first processing, explicit colour semantics and a
relocatable static build.

## Set up

Use Node.js 22 or newer and npm 11 or newer.

```sh
npm ci
npm run check
npm run test:browser
```

Run `npm run dev` for the development server. Do not commit `dist/`, `release/`,
local images, browser traces or editor secrets.

## Expectations

- Keep calculations pure and serialisable where practical. Add unit tests for
  numeric boundaries, invalid input, alpha and out-of-gamut behaviour.
- Never add telemetry, remote image processing, remote fonts or implicit
  network lookups. A feature that needs network access requires prior design
  discussion and a plainly visible, opt-in boundary.
- Preserve values outside a target gamut until mapping is explicitly requested.
  Name the transfer curve or working light for operations where it changes the
  result.
- Bound file bytes, decoded dimensions, worker jobs, list sizes and generated
  output. Release object URLs, workers and large buffers after use.
- Keep all application URLs relative. Test from the nested path used by the
  Playwright server, not only `/`.
- Ensure every pointer interaction has a keyboard route and every colour-only
  signal has a textual or structural equivalent. Use semantic controls before
  custom roles.
- Document third-party runtime code in `THIRD_PARTY_NOTICES.md`, retain its
  exact licence in `LICENSES/`, and confirm compatibility with GPLv3 or later.

## Changes and review

Keep a change focused and update `CHANGELOG.md` for user-visible behaviour.
Include the reasoning behind colour-math choices and cite a primary standard
where the choice is normative. Screenshots can help explain UI changes but do
not replace browser tests.

Before proposing a change, run `npm run check` and `npm run test:browser`.
Tests must not contact external hosts. Security-sensitive reports should follow
[SECURITY.md](SECURITY.md) instead of a public issue.

Contributions are accepted under the repository's
`GPL-3.0-or-later` licence.