@kidthales/tol-palettes 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,36 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, kidthales
+All rights reserved.
+
+Note: Colour values derived from Paul Tol's `tol_colors.py` (version 2022.10)
+are Copyright (c) 2022, Paul Tol, under the 3-Clause BSD License reproduced in
+NOTICE. This project is independent and is not affiliated with or endorsed by
+Paul Tol.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer, as well as the third-party
+   notices in NOTICE.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution, as well as the
+   third-party notices in NOTICE.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE

@@ -0,0 +1,58 @@
+tol-palettes: third-party notices
+================================
+
+This project is independent. It is not affiliated with or endorsed by Paul Tol.
+The name "Paul Tol" is used only to describe the source of the colour values.
+
+Policy: this project stores colour VALUES only, with attribution. It does not
+copy the notes' prose, figures, the PDF or the LaTeX template.
+
+Sources
+-------
+1. Paul Tol's notes, "Colour schemes and templates"
+   https://sronpersonalpages.nl/~pault/
+2. tol_colors.py (version 2022.10)
+   https://sronpersonalpages.nl/~pault/data/tol_colors.py
+   Its header reads: "Copyright (c) 2022, Paul Tol. All rights reserved.
+   License: Standard 3-clause BSD". The header names the licence but does not
+   reproduce its text, so the standard 3-clause BSD text is reproduced below.
+3. Colour schemes and templates (PDF)
+   https://sronpersonalpages.nl/~pault/data/colourschemes.pdf
+
+Which values come from where is recorded per scheme in data/schemes/*.json
+(the "source" field). Values that also appear in tol_colors.py are covered by
+the notice below. Values that appear only on the notes page (for example dark,
+pale, incandescent, banded and groundcover) are published as plain colour
+values with attribution to the notes page; their terms have not been
+confirmed with the author.
+
+BSD 3-Clause License (applies to values derived from tol_colors.py)
+-------------------------------------------------------------------
+
+Copyright (c) 2022, Paul Tol
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# @kidthales/tol-palettes
+
+[![CI](https://github.com/kidthales/tol-palettes/actions/workflows/ci.yml/badge.svg)](https://github.com/kidthales/tol-palettes/actions/workflows/ci.yml)
+[![Pages](https://github.com/kidthales/tol-palettes/actions/workflows/pages.yml/badge.svg)](https://tol-palettes.kidthales.com)
+[![npm version](https://img.shields.io/npm/v/@kidthales/tol-palettes.svg)](https://www.npmjs.com/package/@kidthales/tol-palettes)
+[![PyPI version](https://img.shields.io/pypi/v/tol-palettes.svg)](https://pypi.org/project/tol-palettes/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](LICENSE)
+[![Node.js >= 22](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
+[![DOI](https://img.shields.io/badge/citation-CITATION.cff-informational.svg)](CITATION.cff)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
+
+Colour scheme data inspired by and sourced from [Paul Tol's notes](https://sronpersonalpages.nl/~pault/), with multi-environment generators for **CSS**, **JavaScript / TypeScript**, **Python (`matplotlib`)**, **Godot 4.x**, and **GIMP / Aseprite**.
+
+> *Independent project: not affiliated with or endorsed by Paul Tol.*
+
+---
+
+## Scope & Policy
+
+- **Values only, with attribution.** The project stores colour values and structural lookup rules (`data/schemes/*.json`); it does not copy the notes' prose, figures, the PDF, or the LaTeX template.
+- **No invented names.** A colour name appears only when the official `tol_colors.py` module provides one (the 6 qualitative schemes: `bright`, `high-contrast`, `vibrant`, `muted`, `medium-contrast`, `light`).
+- **Single source of truth.** One hand-verified JSON file per scheme (22 schemes total) is the only canonical data layer; every environment output in `dist/` is deterministically generated from it.
+
+---
+
+## Installation & Quickstart
+
+### Installation
+
+#### npm (Public Registry — Zero Config)
+
+Install directly from the npm public registry:
+
+```bash
+npm install @kidthales/tol-palettes
+```
+
+#### GitHub Packages (Alternative)
+
+To install from GitHub Packages instead, configure the scope in your `.npmrc`:
+
+```ini
+@kidthales:registry=https://npm.pkg.github.com
+```
+
+Then install:
+
+```bash
+npm install @kidthales/tol-palettes
+```
+
+
+#### PyPI (Python Package)
+
+Install directly from PyPI into your virtualenv or project:
+
+```bash
+pip install tol-palettes
+```
+
+With optional `matplotlib` colormap integration:
+
+```bash
+pip install "tol-palettes[matplotlib]"
+```
+
+#### CDN Delivery (jsDelivr / unpkg)
+
+You can load CSS stylesheets, JavaScript modules, or JSON data directly in the browser via CDN without a build step:
+
+**CSS Stylesheets:**
+```html
+<!-- Full 22-scheme bundle (jsDelivr) -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kidthales/tol-palettes/dist/css/tol.css">
+
+<!-- Individual scheme (e.g. bright palette via unpkg) -->
+<link rel="stylesheet" href="https://unpkg.com/@kidthales/tol-palettes/dist/css/bright.css">
+```
+
+**JavaScript / ESM:**
+```html
+<script type="module">
+  import { bright, interpolate } from "https://cdn.jsdelivr.net/npm/@kidthales/tol-palettes/+esm";
+  console.log(bright.colors);
+</script>
+```
+
+**Raw JSON Data:**
+```text
+https://cdn.jsdelivr.net/npm/@kidthales/tol-palettes/dist/json/schemes.json
+https://unpkg.com/@kidthales/tol-palettes/dist/json/schemes.json
+```
+
+> [!NOTE]
+> **SemVer 2.0.0 Pre-release**: Per SemVer 2.0.0 §4, versions in the `0.y.z` range denote initial development releases with evolving APIs. True stable releases begin at `v1.0.0`.
+
+### JavaScript / TypeScript (ESM)
+```ts
+import { bright, muted, interpolate, discreteRainbow } from '@kidthales/tol-palettes';
+
+console.log(bright.colors); // [{ hex: '#4477AA', name: 'blue' }, ...]
+console.log(interpolate('sunset', 0.5)); // '#EAECCC'
+console.log(discreteRainbow(5)); // ['#1965B0', '#7BAFDE', '#4EB265', '#F7F056', '#DC050C']
+```
+
+### CSS Custom Properties (`--tol-*`)
+```css
+/* Import an individual scheme or the full 22-scheme bundle */
+@import '@kidthales/tol-palettes/css/bright.css';
+@import '@kidthales/tol-palettes/css/tol.css';
+
+.callout {
+  background-color: var(--tol-pale-0);
+  color: var(--tol-dark-3);
+  border-left: 4px solid var(--tol-bright-blue);
+}
+```
+
+### Python (`tol_palettes.py`)
+```python
+from tol_palettes import tol_cset, tol_cmap
+
+bright = tol_cset("bright")
+cmap = tol_cmap("sunset")  # Returns matplotlib colormap when matplotlib is installed
+```
+
+### Godot 4.x & Pixel Art (`dist/godot/`, `dist/aseprite/`, `dist/gpl/`, `dist/assets/`)
+- **Godot 4.x Addon**: Extract `dist/assets/tol-palettes-godot.zip` into your project root to install `addons/tol_palettes/` with `plugin.cfg`, `tol_palettes.gd` (`TolPalettes`), and 22 `ColorPalette` `.tres` resources. See [`docs/game.md`](docs/game.md).
+- **Aseprite & GPL Bundles**: Download `dist/assets/tol-palettes-aseprite.zip` or `tol-palettes-gpl.zip` for instant drag-and-drop palette loading in Aseprite, GIMP, Inkscape, or Krita.
+- Download zip bundles directly from the [latest GitHub Release](https://github.com/kidthales/tol-palettes/releases).
+
+---
+
+## Layout & Generated Outputs
+
+| Path | Command | Description |
+|---|---|---|
+| `data/schemes/*.json` | `npm run validate` | 22 verified scheme JSON files validated against `schema/scheme.schema.json` |
+| `dist/css/` | `npm run generate:css` | Per-scheme CSS custom properties (`<id>.css`) and bundle (`tol.css`) — see [`docs/css.md`](docs/css.md) |
+| `dist/js/` & `dist/json/` | `npm run generate:js` | Tree-shakeable ESM module (`index.js` + `index.d.ts`) and flat `schemes.json` — see [`docs/js.md`](docs/js.md) |
+| `dist/py/` | `npm run generate:py` | Python module (`tol_palettes.py`) with optional `matplotlib` support — see [`docs/python.md`](docs/python.md) |
+| `dist/gpl/`, `dist/aseprite/`, `dist/godot/` | `npm run generate:game` | GIMP/Aseprite `.gpl` palettes, Godot 4.x `tol_palettes.gd` and `ColorPalette` `.tres` resources — see [`docs/game.md`](docs/game.md) |
+| `dist/assets/` | `npm run package:assets` | Downloadable `.zip` archives for Godot (`tol-palettes-godot.zip`), Aseprite, and GPL |
+| `dist/gallery/` | `npm run generate:gallery` | Self-contained offline HTML reference gallery (`index.html`) with copyable hex codes and WCAG contrast ratios |
+
+---
+
+## Regenerating, Linting & Testing
+
+```bash
+npm run lint       # Validate schemas, JS syntax, attribution headers, and export resolution
+npm run validate   # Validate all 22 scheme JSON files against schema + invariants
+npm run generate   # Regenerate all outputs in dist/
+npm test           # Run full linter, schema, CSS, JS/TS, Python, Game/Godot/GPL, Gallery, and packaging test suite
+```
+
+---
+
+## Community & Citation
+
+- **Code of Conduct**: This project is governed by the [Contributor Covenant v2.1](CODE_OF_CONDUCT.md). Please report issues or violations to `admin@agogpixel.com`.
+- **Contributing**: Please review [CONTRIBUTING.md](CONTRIBUTING.md) for local development workflows and code generation rules.
+- **Academic Citation**: If you use `tol-palettes` or Paul Tol's colour schemes in academic publications, research software, or educational material, please cite this project via [`CITATION.cff`](CITATION.cff) and Paul Tol's technical report:
+
+```bibtex
+@techreport{tol2021colourschemes,
+  author      = {Paul Tol},
+  title       = {Colour Schemes},
+  institution = {SRON Netherlands Institute for Space Research},
+  year        = {2021},
+  number      = {SRON/EPS/TN/09-002},
+  type        = {Technical report issue 3.2},
+  url         = {https://sronpersonalpages.nl/~pault/data/colourschemes.pdf}
+}
+```
+
+---
+
+## License & Attribution
+
+- **Project Code & Generators**: [BSD 3-Clause License](LICENSE) (`Copyright (c) 2026, kidthales`).
+- **Colour Scheme Data**: Sourced from [Paul Tol's Notes](https://sronpersonalpages.nl/~pault/) and `tol_colors.py` (version 2022.10, `Copyright (c) 2022, Paul Tol`, 3-Clause BSD). See [`NOTICE`](NOTICE) for full attribution and the BSD licence notice, and [`docs/cvd-and-greyscale-scope.md`](docs/cvd-and-greyscale-scope.md) for the scope decision on colour-blindness and greyscale reference material.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/data/schemes/banded-12.json

@@ -0,0 +1,49 @@
+{
+  "id": "banded-12",
+  "kind": "sequential",
+  "colors": [
+    {
+      "hex": "#D2D1E2"
+    },
+    {
+      "hex": "#C1A7C4"
+    },
+    {
+      "hex": "#AD7BA4"
+    },
+    {
+      "hex": "#93C7EC"
+    },
+    {
+      "hex": "#6DA1D6"
+    },
+    {
+      "hex": "#3E79BD"
+    },
+    {
+      "hex": "#B8D29E"
+    },
+    {
+      "hex": "#7BB47D"
+    },
+    {
+      "hex": "#2C925B"
+    },
+    {
+      "hex": "#F4A937"
+    },
+    {
+      "hex": "#EB7121"
+    },
+    {
+      "hex": "#D9070D"
+    }
+  ],
+  "bad": "#FFFFFF",
+  "interpolation": "none",
+  "source": {
+    "retrieved": "2026-10-18",
+    "siteFigure": "fig:scheme_banded",
+    "siteUrl": "https://sronpersonalpages.nl/~pault/#fig:scheme_banded"
+  }
+}

package/data/schemes/banded-16.json

@@ -0,0 +1,61 @@
+{
+  "id": "banded-16",
+  "kind": "sequential",
+  "colors": [
+    {
+      "hex": "#D2D1E2"
+    },
+    {
+      "hex": "#C5B3CC"
+    },
+    {
+      "hex": "#B893B5"
+    },
+    {
+      "hex": "#A8719D"
+    },
+    {
+      "hex": "#97CDEF"
+    },
+    {
+      "hex": "#7DB1DF"
+    },
+    {
+      "hex": "#5F94CE"
+    },
+    {
+      "hex": "#3976BB"
+    },
+    {
+      "hex": "#BCD4A0"
+    },
+    {
+      "hex": "#90BE88"
+    },
+    {
+      "hex": "#60A770"
+    },
+    {
+      "hex": "#198D56"
+    },
+    {
+      "hex": "#F5B43B"
+    },
+    {
+      "hex": "#F08C2B"
+    },
+    {
+      "hex": "#E85E1B"
+    },
+    {
+      "hex": "#D9070D"
+    }
+  ],
+  "bad": "#FFFFFF",
+  "interpolation": "none",
+  "source": {
+    "retrieved": "2026-10-18",
+    "siteFigure": "fig:scheme_banded",
+    "siteUrl": "https://sronpersonalpages.nl/~pault/#fig:scheme_banded"
+  }
+}

package/data/schemes/banded-20.json

@@ -0,0 +1,73 @@
+{
+  "id": "banded-20",
+  "kind": "sequential",
+  "colors": [
+    {
+      "hex": "#D2D1E2"
+    },
+    {
+      "hex": "#C8B9D1"
+    },
+    {
+      "hex": "#BEA0BF"
+    },
+    {
+      "hex": "#B287AD"
+    },
+    {
+      "hex": "#A56B99"
+    },
+    {
+      "hex": "#9ACFF1"
+    },
+    {
+      "hex": "#85BAE4"
+    },
+    {
+      "hex": "#6FA3D7"
+    },
+    {
+      "hex": "#578DC9"
+    },
+    {
+      "hex": "#3774BA"
+    },
+    {
+      "hex": "#BFD6A1"
+    },
+    {
+      "hex": "#9CC48E"
+    },
+    {
+      "hex": "#78B27B"
+    },
+    {
+      "hex": "#4F9F68"
+    },
+    {
+      "hex": "#058A53"
+    },
+    {
+      "hex": "#F6B93D"
+    },
+    {
+      "hex": "#F29B31"
+    },
+    {
+      "hex": "#ED7A24"
+    },
+    {
+      "hex": "#E65318"
+    },
+    {
+      "hex": "#D9070D"
+    }
+  ],
+  "bad": "#FFFFFF",
+  "interpolation": "none",
+  "source": {
+    "retrieved": "2026-10-18",
+    "siteFigure": "fig:scheme_banded",
+    "siteUrl": "https://sronpersonalpages.nl/~pault/#fig:scheme_banded"
+  }
+}

package/data/schemes/bright.json

@@ -0,0 +1,48 @@
+{
+  "id": "bright",
+  "kind": "qualitative",
+  "colors": [
+    {
+      "hex": "#4477AA",
+      "name": "blue"
+    },
+    {
+      "hex": "#EE6677",
+      "name": "red"
+    },
+    {
+      "hex": "#228833",
+      "name": "green"
+    },
+    {
+      "hex": "#CCBB44",
+      "name": "yellow"
+    },
+    {
+      "hex": "#66CCEE",
+      "name": "cyan"
+    },
+    {
+      "hex": "#AA3377",
+      "name": "purple"
+    },
+    {
+      "hex": "#BBBBBB",
+      "name": "grey"
+    }
+  ],
+  "extras": [
+    {
+      "hex": "#000000",
+      "name": "black"
+    }
+  ],
+  "interpolation": "none",
+  "source": {
+    "retrieved": "2026-10-18",
+    "siteFigure": "fig:scheme_bright",
+    "siteUrl": "https://sronpersonalpages.nl/~pault/#fig:scheme_bright",
+    "module": "tol_cset('bright')",
+    "moduleVersion": "2022.10"
+  }
+}

package/data/schemes/burd.json

@@ -0,0 +1,43 @@
+{
+  "id": "burd",
+  "kind": "diverging",
+  "colors": [
+    {
+      "hex": "#2166AC"
+    },
+    {
+      "hex": "#4393C3"
+    },
+    {
+      "hex": "#92C5DE"
+    },
+    {
+      "hex": "#D1E5F0"
+    },
+    {
+      "hex": "#F7F7F7"
+    },
+    {
+      "hex": "#FDDBC7"
+    },
+    {
+      "hex": "#F4A582"
+    },
+    {
+      "hex": "#D6604D"
+    },
+    {
+      "hex": "#B2182B"
+    }
+  ],
+  "bad": "#FFEE99",
+  "interpolation": "either",
+  "source": {
+    "retrieved": "2026-10-18",
+    "siteFigure": "fig:scheme_burd",
+    "siteUrl": "https://sronpersonalpages.nl/~pault/#fig:scheme_burd",
+    "module": "tol_cmap('BuRd')",
+    "moduleName": "BuRd",
+    "moduleVersion": "2022.10"
+  }
+}

package/data/schemes/dark.json

@@ -0,0 +1,45 @@
+{
+  "id": "dark",
+  "kind": "qualitative",
+  "colors": [
+    {
+      "hex": "#4477BB"
+    },
+    {
+      "hex": "#CC4466"
+    },
+    {
+      "hex": "#228833"
+    },
+    {
+      "hex": "#2255AA"
+    },
+    {
+      "hex": "#993366"
+    },
+    {
+      "hex": "#006644"
+    },
+    {
+      "hex": "#117788"
+    },
+    {
+      "hex": "#882288"
+    },
+    {
+      "hex": "#BB4488"
+    },
+    {
+      "hex": "#775500"
+    },
+    {
+      "hex": "#444444"
+    }
+  ],
+  "interpolation": "none",
+  "source": {
+    "retrieved": "2026-10-18",
+    "siteFigure": "fig:scheme_dark",
+    "siteUrl": "https://sronpersonalpages.nl/~pault/#fig:scheme_dark"
+  }
+}

package/data/schemes/groundcover.json

@@ -0,0 +1,54 @@
+{
+  "id": "groundcover",
+  "kind": "special",
+  "colors": [
+    {
+      "hex": "#5566AA"
+    },
+    {
+      "hex": "#117733"
+    },
+    {
+      "hex": "#44AA66"
+    },
+    {
+      "hex": "#55AA22"
+    },
+    {
+      "hex": "#668822"
+    },
+    {
+      "hex": "#99BB55"
+    },
+    {
+      "hex": "#558877"
+    },
+    {
+      "hex": "#88BBAA"
+    },
+    {
+      "hex": "#AADDCC"
+    },
+    {
+      "hex": "#44AA88"
+    },
+    {
+      "hex": "#DDCC66"
+    },
+    {
+      "hex": "#FFDD44"
+    },
+    {
+      "hex": "#FFEE88"
+    },
+    {
+      "hex": "#BB0011"
+    }
+  ],
+  "interpolation": "none",
+  "source": {
+    "retrieved": "2026-10-18",
+    "siteFigure": "fig:scheme_groundcover",
+    "siteUrl": "https://sronpersonalpages.nl/~pault/#fig:scheme_groundcover"
+  }
+}

package/data/schemes/high-contrast.json

@@ -0,0 +1,32 @@
+{
+  "id": "high-contrast",
+  "kind": "qualitative",
+  "colors": [
+    {
+      "hex": "#004488",
+      "name": "blue"
+    },
+    {
+      "hex": "#DDAA33",
+      "name": "yellow"
+    },
+    {
+      "hex": "#BB5566",
+      "name": "red"
+    }
+  ],
+  "extras": [
+    {
+      "hex": "#000000",
+      "name": "black"
+    }
+  ],
+  "interpolation": "none",
+  "source": {
+    "retrieved": "2026-10-18",
+    "siteFigure": "fig:scheme_highcontrast",
+    "siteUrl": "https://sronpersonalpages.nl/~pault/#fig:scheme_highcontrast",
+    "module": "tol_cset('high-contrast')",
+    "moduleVersion": "2022.10"
+  }
+}