{"id":50341503,"url":"https://github.com/tiagojct/pequod","last_synced_at":"2026-05-29T17:30:44.406Z","repository":{"id":353386955,"uuid":"1219193496","full_name":"tiagojct/pequod","owner":"tiagojct","description":"A pigment-inspired colour palette for reading and code, rooted in Moby-Dick. Warm paper, deep ink, eight accent hues named after the crew of the Pequod.","archived":false,"fork":false,"pushed_at":"2026-04-30T09:58:43.000Z","size":7766,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T19:11:59.233Z","etag":null,"topics":["accessibility","alacritty","color-palette","colorblindness","design-tokens","ghostty","iterm2","kitty","moby-dick","python","r","tailwindcss","tmux","typography","vscode-theme","wezterm","zed-theme"],"latest_commit_sha":null,"homepage":"https://tiagojct.eu/projects/pequod/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiagojct.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-CC-BY-4.0","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-23T16:15:18.000Z","updated_at":"2026-04-30T09:58:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tiagojct/pequod","commit_stats":null,"previous_names":["tiagojct/pequod"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tiagojct/pequod","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagojct%2Fpequod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagojct%2Fpequod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagojct%2Fpequod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagojct%2Fpequod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiagojct","download_url":"https://codeload.github.com/tiagojct/pequod/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagojct%2Fpequod/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33664259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","alacritty","color-palette","colorblindness","design-tokens","ghostty","iterm2","kitty","moby-dick","python","r","tailwindcss","tmux","typography","vscode-theme","wezterm","zed-theme"],"created_at":"2026-05-29T17:30:43.469Z","updated_at":"2026-05-29T17:30:44.401Z","avatar_url":"https://github.com/tiagojct.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pequod\n\nA pigment-inspired colour palette for reading and code, rooted in *Moby-Dick*.\nWarm paper on one end, deep ink on the other, with eight accent hues named\nafter the crew of the Pequod.\n\n[![PyPI](https://img.shields.io/pypi/v/pequod?label=PyPI\u0026color=2C3E50)](https://pypi.org/project/pequod/)\n[![npm](https://img.shields.io/npm/v/pequod-tailwind?label=npm\u0026color=2C3E50)](https://www.npmjs.com/package/pequod-tailwind)\n[![VS Code](https://vsmarketplacebadges.dev/version-short/tiagojct.pequod-color-theme.svg)](https://marketplace.visualstudio.com/items?itemName=tiagojct.pequod-color-theme)\n[![Open VSX](https://img.shields.io/open-vsx/v/tiagojct/pequod-color-theme?label=Open%20VSX\u0026color=2C3E50)](https://open-vsx.org/extension/tiagojct/pequod-color-theme)\n[![CRAN](https://www.r-pkg.org/badges/version/pequod)](https://CRAN.R-project.org/package=pequod)\n[![Licence](https://img.shields.io/badge/licence-MIT%20%2B%20CC--BY--4.0-C4A57B)](#licence)\n\n![Pequod swatches](./cover.jpg)\n\n- **Base scale:** twelve steps from Log 50 (warm paper) to Log 950 (night sky).\n- **Accents:** eight crew members — Ahab, Starbuck, Queequeg, Pip, Ishmael,\n  Stubb, Tashtego, Daggoo — each with a light and a dark variant and a\n  recommended syntax role.\n- **Read-first:** designed for long-form reading and code at length, not\n  for glance-ability. Saturation stays low, backgrounds stay warm, accents\n  stay in the same pigment register.\n- **Accessibility:** every body-text pair clears WCAG-AA (4.5:1) on the\n  reference surface; dark-mode accents clear 4.5:1 comfortably. Colour-\n  vision-deficiency collapses are documented, not hidden — see below.\n- **Semantics, not decoration:** each accent has a role. Using the palette\n  should feel earned; the colour choice should tell you something.\n\nThe full narrative and design rationale live at\n\u003chttps://tiagojct.eu/projects/pequod/\u003e. This repository is the canonical\nsource of truth for the tokens and the built themes.\n\n## Status\n\n**Alpha (0.1.0).** Tokens are stable enough to run a website on them and\nto publish across every ecosystem the palette ships into:\n\n| Surface | Where | Status |\n|---|---|---|\n| VS Code extension | [Marketplace](https://marketplace.visualstudio.com/items?itemName=tiagojct.pequod-color-theme), [Open VSX](https://open-vsx.org/extension/tiagojct/pequod-color-theme) | live |\n| Zed theme | `themes/Pequod.zed.json` | drop-in |\n| Terminal presets | `themes/terminals/` | Ghostty, Alacritty, kitty, WezTerm, tmux, Windows Terminal, iTerm2 |\n| Python package | [PyPI](https://pypi.org/project/pequod/) | `pip install pequod` |\n| Tailwind plugin | [npm](https://www.npmjs.com/package/pequod-tailwind) | `npm install pequod-tailwind` |\n| R package | [CRAN](https://CRAN.R-project.org/package=pequod) | `install.packages(\"pequod\")` |\n| Specimen PDF | `specimen/specimen.pdf` | regenerated from tokens |\n\nHex values may still shift by a point or two during the alpha — palette\ntesting continues against more code and long-form prose. Breaking\nchanges before 1.0 will be called out in `CHANGELOG.md`.\n\n## Showcase\n\nEight hero plots in matplotlib — sequential heatmaps, grouped and\nhorizontal bars, scatter, box plots, distributions, time series,\nand a specimen-style swatch grid. Four on dark, four on light:\n\n![Log heatmap on dark](examples/02_log_heatmap.png)\n![Horizontal bars on light](examples/07_hbars_light.png)\n\nTitles in Atkinson Hyperlegible Next SemiBold, ticks in JetBrains Mono, surfaces and series\ncolours pulled directly from `pequod.LOG`, `pequod.CREW_LIGHT`, and\n`pequod.CREW_DARK`. Full gallery, code patterns, and reproduction\ninstructions live in [`examples/`](examples/). Generate them\nyourself with:\n\n```bash\npip install \"pequod[plot]\" numpy\npython examples/plots.py\n```\n\n## Contents\n\n```\npequod/\n├── pequod.json                  # the canonical palette tokens\n├── themes/\n│   ├── Pequod.itermcolors                 # iTerm2 (dark)\n│   ├── Pequod-color-theme.json            # VS Code (dark) — canonical\n│   ├── Pequod-light-color-theme.json      # VS Code (light) — canonical\n│   ├── Pequod.zed.json                    # Zed (dark + light in one file)\n│   └── terminals/                         # Ghostty, Alacritty, kitty,\n│                                          # WezTerm, tmux, Windows Terminal\n├── tailwind/                    # npm package — `npm install pequod-tailwind`\n├── vscode/                      # VS Code extension — `make vsix` builds\n│   │                            # the .vsix; published to the Marketplace\n│   │                            # as \"tiagojct.pequod-color-theme\"\n│   ├── package.json\n│   ├── icon.png\n│   └── themes/                  # copies of the canonical themes\n├── python/                      # Python package — install with\n│   │                            #   pip install pequod\n│   ├── pyproject.toml           # see python/README.md for full Python docs\n│   ├── src/pequod/              # palette + matplotlib helpers\n│   ├── tests/\n│   └── data-raw/                # generator: re-reads ../pequod.json\n├── r/                           # R package — install with\n│   │                            #   remotes::install_github(\n│   │                            #     \"tiagojct/pequod\", subdir = \"r\")\n│   ├── DESCRIPTION              # see r/README.md for full R docs\n│   ├── R/                       # palette constants, ggplot2 scales\n│   ├── tests/\n│   └── data-raw/                # generator: re-reads ../pequod.json\n├── specimen/\n│   ├── specimen.typ             # single-page specimen source (Typst)\n│   └── specimen.pdf             # rendered output — swatches + samples\n├── scripts/\n│   └── cvd_check.py             # Viénot–Brettel–Mollon CVD simulation + ΔE\n├── Makefile                     # ~13 targets — see `make help`\n├── README.md\n├── CHANGELOG.md\n├── LICENSE-CC-BY-4.0            # palette tokens and docs\n└── LICENSE-MIT                  # theme files, scripts, R package\n```\n\n## Install\n\n### VS Code\n\nThe themes ship as a marketplace extension under [`vscode/`](vscode/),\npublished as `tiagojct.pequod-color-theme` on both surfaces. Install\nin any of three ways:\n\n1. **Marketplace** — open *Extensions* (⌘⇧X), search **Pequod\n   Palette**, install. Or use [the listing page](https://marketplace.visualstudio.com/items?itemName=tiagojct.pequod-color-theme).\n   For VSCodium / Cursor / Gitpod, use the [Open VSX listing](https://open-vsx.org/extension/tiagojct/pequod-color-theme) instead.\n2. **`.vsix` file** — build with `make vsix`, then\n   `code --install-extension vscode/pequod-color-theme-0.1.0.vsix`.\n3. **From source (no marketplace)** — copy the [`vscode/`](vscode/)\n   folder to `~/.vscode/extensions/pequod-color-theme/`. VS Code will\n   pick it up on next launch.\n\nThen *Preferences: Color Theme* → pick **Pequod** or **Pequod Light**.\n\n### Zed\n\nZed reads user themes directly from disk:\n\n1. Copy `themes/Pequod.zed.json` to `~/.config/zed/themes/Pequod.zed.json`\n   (create the folder if it does not exist).\n2. Restart Zed → *theme selector: toggle* → pick **Pequod Dark** or **Pequod Light**.\n\n### iTerm2\n\n1. Open *Settings → Profiles → Colors → Color Presets → Import…*\n2. Select `themes/Pequod.itermcolors`.\n3. Apply the *Pequod* preset.\n\nAn iTerm2 light preset is on the roadmap.\n\n### Other terminals\n\nDrop-in dark presets for the most common terminals live in\n[`themes/terminals/`](themes/terminals/):\n\n| Terminal | File |\n|---|---|\n| Ghostty | `Pequod.ghostty` |\n| Alacritty | `Pequod.alacritty.toml` |\n| kitty | `Pequod.kitty.conf` |\n| WezTerm | `Pequod.wezterm.lua` |\n| tmux | `Pequod.tmux.conf` |\n| Windows Terminal | `Pequod.windowsterminal.json` |\n\nSee [`themes/terminals/README.md`](themes/terminals/README.md) for the\ninstall path each terminal expects.\n\n### Tailwind CSS\n\n```bash\nnpm install pequod-tailwind\n```\n\n```js\n// tailwind.config.js\nconst pequod = require(\"pequod-tailwind\");\n\nmodule.exports = {\n  theme: {\n    extend: {\n      colors: pequod.colors,    // log + all eight crew accents\n    },\n  },\n};\n```\n\n```html\n\u003cbody class=\"bg-log-50 text-log-800 dark:bg-log-950 dark:text-log-100\"\u003e\n  \u003ch1 class=\"text-queequeg dark:text-queequeg-dark\"\u003ePequod\u003c/h1\u003e\n\u003c/body\u003e\n```\n\nFull usage in [`tailwind/README.md`](tailwind/README.md).\n\n### Python\n\n```bash\npip install pequod              # palette + helpers\npip install \"pequod[plot]\"      # adds matplotlib glue\n```\n\n```python\nfrom pequod import LOG, CREW_LIGHT, palette\n\npalette(\"log\")                  # 12-step Log scale, list of hex\npalette(\"crew\", n=5)            # first five crew accents\n\n# matplotlib (with the [plot] extra)\nimport matplotlib.pyplot as plt\nimport pequod\npequod.register_cmaps()\nplt.imshow(data, cmap=\"pequod_log\")\n```\n\nFull usage in [`python/README.md`](python/README.md).\n\n### R\n\nThe R package is on [CRAN](https://CRAN.R-project.org/package=pequod):\n\n```r\ninstall.packages(\"pequod\")\n\nlibrary(pequod)\npalette_pequod(\"log\")              # 12-step Log scale\npalette_pequod(\"crew\", n = 5)      # first five crew accents\npequod_preview(\"crew\")             # quick base-R preview\n```\n\nSource lives in [`r/`](r/); to follow the development version,\n`remotes::install_github(\"tiagojct/pequod\", subdir = \"r\")`.\n\nggplot2 scales are provided too:\n\n```r\nlibrary(ggplot2)\nggplot(iris, aes(Sepal.Length, Sepal.Width, colour = Species)) +\n  geom_point(size = 3) +\n  scale_color_pequod_d(palette = \"crew\")\n```\n\nFull usage in [`r/README.md`](r/README.md).\n\n## The tokens\n\n`pequod.json` is the single source of truth. The file contains:\n\n- `log` — the twelve-step base scale (Log 50 → Log 950).\n- `accents` — the eight crew accents, each with `light`, `dark`, `role`,\n  and a short `note` explaining the character and the syntax role.\n- `roles` — semantic role → token mappings for light and dark modes\n  (`bg`, `text`, `text-muted`, `link`, `accent-primary`, etc.).\n- `syntax` — default mappings from syntax role to accent (keyword,\n  string, comment, function, type, constant, variable, operator).\n\nThe R package, the Python package, the Typst specimen, and the CVD\ntest script all regenerate from `pequod.json` (see each one's\n`data-raw/` or generator). The terminal presets and the editor themes\nare still produced by hand; bringing them under the same generator\ncontract is the next priority — see `What comes next` below.\n\n## Accessibility\n\nBody-text contrast on the reference surfaces:\n\n| Pair | Use | Ratio |\n|---|---|---|\n| Log 800 on Log 100 | light body | 10.8 : 1 |\n| Log 700 on Log 50 | light link | 8.5 : 1 |\n| Log 400 on Log 50 | muted / large text | 3.9 : 1 |\n| Log 100 on Log 950 | dark body | 14.0 : 1 |\n| Accent-light on Log 100 | UI accents | 3.0 – 9.5 : 1 |\n| Accent-dark on Log 950 | dark-mode accents | 3.6 – 13.6 : 1 |\n\nIn v0.2.0-alpha every accent clears the AA-large (3 : 1) bar on its target\nsurface — none of the bright-on-light \"fill-only\" cases from v0.1 remain.\nLight-mode body-text candidates (≥ 4.5 : 1 on Log 100): **Daggoo**,\n**Queequeg**, **Pip**, **Ahab**. Dark-mode body-text candidates (≥ 4.5 : 1\non Log 950): every accent except **Daggoo** (3.6, AA-large only).\n\n### Colour vision deficiency\n\n`scripts/cvd_check.py` simulates each accent at 100 % severity for\nprotanopia, deuteranopia, and tritanopia using the Viénot–Brettel–Mollon\n(1999) model, and reports pairwise ΔE*~ab~ (CIE76, Lab D65) between\nsimulated accents.\n\nIn v0.2.0-alpha the worst-case pair under each simulation:\n\n| | light variants | dark variants |\n|---|---|---|\n| protanopia    | Ishmael ↔ Tashtego, ΔE 15.1 | Stubb ↔ Tashtego, ΔE 11.8 |\n| deuteranopia  | Ishmael ↔ Tashtego, ΔE 8.0  | Ishmael ↔ Tashtego, ΔE 6.8 |\n| tritanopia    | Pip ↔ Daggoo, ΔE 13.3       | Ahab ↔ Pip, ΔE 10.2       |\n\nThe deuteranopia floor is set by **Ishmael ↔ Tashtego** because green\ncollapses to neutral grey under deutan and the two accents sit at similar\nL\\*. This is unavoidable for an 8-hue palette that includes both a green\nand a low-chroma grey, so it is documented rather than designed away —\nin practice, comments (Ishmael) and strings (Tashtego) are rarely\nadjacent and rarely encode meaning by colour alone.\n\n**Usage guidance:** do not rely on colour alone to distinguish *Ishmael*\nfrom *Tashtego* under deuteranopia. Pair with icon, weight, or italics\n(the default theme already italicises comments). Every other pair clears\nΔE ≥ 10 across all three simulations.\n\nRun the check yourself:\n\n```bash\npython3 scripts/cvd_check.py\n```\n\nThe script has no dependencies beyond NumPy.\n\n## Specimen\n\nA one-page A4 specimen — the full Log scale, the eight crew accents\nwith light and dark variants, a body-text sample, and a dark code\nsample with every token coloured by its crew role — lives at\n[`specimen/specimen.pdf`](specimen/specimen.pdf). Use it as a quick\nreference when choosing which accent a new UI element should take,\nor print it and pin it somewhere.\n\nThe PDF is generated from [`specimen/specimen.typ`](specimen/specimen.typ)\nwith [Typst](https://typst.app/). To regenerate after a token change:\n\n```bash\nmake specimen\n# equivalent to: typst compile specimen/specimen.typ specimen/specimen.pdf\n```\n\nTypst uses the system-installed Atkinson Hyperlegible Next and\nJetBrains Mono. Install them from\n[Google Fonts](https://fonts.google.com/specimen/Atkinson+Hyperlegible+Next)\nif they are not already present.\n\n## What comes next\n\n- **Generators for the editor and terminal themes**, so the\n  hand-maintained files in `themes/` and `themes/terminals/`\n  regenerate from `pequod.json` the same way the R, Python, and\n  specimen targets already do.\n- **Light presets** for the terminals (currently dark only) and for\n  iTerm2 specifically.\n- **Vim / Neovim colourscheme** using [Lush](https://github.com/rktjmp/lush.nvim).\n- **Tailwind v4 plugin** as a first-class plugin once Tailwind v4's\n  plugin API stabilises (the current package works in v4 via\n  `@theme` but isn't formally a v4 plugin yet).\n- **Sublime Text, Helix, Emacs** — lower priority.\n\nContributions to any of these are welcome.\n\n## Inspirations and credits\n\n- [Flexoki](https://stephango.com/flexoki) by Steph Ango is the most\n  direct inspiration. Pequod owes its philosophy — warm paper, cool\n  ink, muted accents, published tokens — to Flexoki. Where Flexoki\n  draws on earth pigments broadly, Pequod narrows the story to a\n  ship, a century, and a text.\n- [Solarized](https://ethanschoonover.com/solarized/) by Ethan\n  Schoonover established the modern practice of designing palettes\n  for reading first.\n- [Tokyo Night](https://github.com/enkia/tokyo-night-vscode-theme)\n  and [Nord](https://www.nordtheme.com/) are two other palettes with\n  a disciplined colour story worth studying.\n- Herman Melville, *Moby-Dick; or, The Whale* (1851), for the names.\n\n## Licence\n\n- **Palette tokens (`pequod.json`) and documentation** — [Creative Commons\n  Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).\n  Use, adapt, ship; credit required. See `LICENSE-CC-BY-4.0`.\n- **Theme files, scripts, and packages** (`themes/*`, `scripts/*`,\n  `tailwind/*`, `vscode/*`, `python/*`, `r/*`, `specimen/*`) —\n  [MIT](https://opensource.org/licenses/MIT). See `LICENSE-MIT`.\n\n## Contact\n\nIf you use Pequod in a project or have a suggestion, I would love to\nhear about it: [tiagojacinto@med.up.pt](mailto:tiagojacinto@med.up.pt),\nor open an issue here.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiagojct%2Fpequod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiagojct%2Fpequod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiagojct%2Fpequod/lists"}