poikilos 1.0.0__tar.gz

poikilos-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Oldest and newest Python. The lowest job also runs 3.11, but with an old numpy.
+        python-version: ["3.11", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      # setup-uv publishes no major tags since v8, only immutable release tags.
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run pytest
+      # The editable install reads files from src/, so only the wheel shows missing package data.
+      - run: uv build --wheel
+      - run: |
+          files=$(unzip -Z1 dist/*.whl)
+          for f in poikilos/base.mplstyle poikilos/looks/ poikilos/palettes/; do
+            grep -q "^$f" <<< "$files" || { echo "wheel lacks $f"; exit 1; }
+          done
+
+  lowest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: "3.11"
+      - run: uv run --resolution lowest-direct pytest -m "not images"

poikilos-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # PyPI's trusted publisher for poikilos names this environment.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      # PyPI never accepts a version twice, so a tag that disagrees with pyproject.toml must not publish.
+      - run: test "${GITHUB_REF_NAME#v}" = "$(uv version --short)"
+      - run: uv build
+      - run: uv publish --trusted-publishing always

poikilos-1.0.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

poikilos-1.0.0/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+Versions follow [Semantic Versioning](https://semver.org). The public API is
+every name in `poikilos.__all__`, every theme name and each theme's look.
+
+- Renaming or removing a theme, or any public name, is a major release. Each
+  such change goes under "Breaking".
+- A new theme, palette, look or helper is a minor release.
+- A visual change to an existing theme is a minor release. It comes with new
+  image baselines and a line here.
+- A bug fix that leaves the API and the looks alone is a patch release.
+
+## 1.0.0 (2026-10-17)
+
+`matplotlib-rosepine` 0.2.0 is now `poikilos` 1.0.0. The distribution and the
+import package are both `poikilos`. The rename breaks code written for 0.2.0,
+so the major version goes up.
+
+### Breaking
+
+| `matplotlib_rosepine` 0.2.0 | `poikilos` 1.0.0 |
+| --- | --- |
+| `import matplotlib_rosepine as rp` | `import poikilos as pk` |
+| `rp.apply_style(v)` before importing pyplot | `pk.use(v)`, before or after importing pyplot |
+| `rp.style_path(v)` | `pk.rc_params(v)` returns the settings as a dict |
+| `rp.VARIANTS` | `pk.THEMES` (now 8 themes) |
+| `rp.register()`, `plt.style.use("rose-pine")` | removed; use `pk.use("rose-pine")` |
+| Rosé Pine hex values copied by hand | `pk.PALETTES["rose-pine-dawn"].colors["love"]` |
+
+- `use()` never sets the backend. `apply_style()` forced Agg.
+- Importing the package no longer registers styles or changes rcParams.
+- The themes set `savefig.dpi: 300` instead of `figure.dpi: 300`. Saved files
+  keep their resolution. Figures on screen and in notebooks use matplotlib's
+  100 dpi, and `fig.dpi` reads 100 unless you pass `dpi=`.
+- A figure's own dpi no longer sets the saved resolution. `plt.figure(dpi=150)`
+  used to save at 150 dpi and now saves at 300. Pass `dpi=` to `save_figure`
+  to change it.
+- `save_figure` keeps dots in the stem: `x.curve` gives `x.curve.svg` and
+  `x.curve.png`. It used to write `x.svg` and `x.png`.
+- Removed `template.mplstyle`, the generated `.mplstyle` files and the
+  rose-pine-bloom step. Palettes are TOML files now.
+- Needs Python 3.11 and matplotlib 3.11.
+
+### Added
+
+- Themes `plain`, `plain-dark`, `lilaq`, `lilaq-moon` and `pgl`, next to the
+  three Rosé Pine themes.
+- `use(theme, *, palette=None, rc=None)`, `context(...)` and `rc_params(...)`.
+  Any look takes any palette, and `rc` overrides any rcParam.
+- `PALETTES`, with each palette's colors as hex, and `THEMES`.
+- `zero_line(ax, axis="y")` draws a bold line at zero, for values that change
+  sign.
+- `fit_legend(fig)` grows the figure so legends outside the axes keep the
+  axes at their size without the legends.
+- `label_points(..., offsets=[(dx, dy), ...])` places labels at fixed offsets
+  in points, without adjustText. `leader=False` drops the leader lines.
+- `save_figure(..., formats=("pdf", "png"))` picks the formats to write.
+- `save_figure` writes SVG and PDF files without a creation date. The themes
+  fix `svg.hashsalt`. Reruns write the same bytes.
+
+### Changed
+
+- As before, no theme sets `pdf.fonttype`, so PDFs use matplotlib's Type 3 fonts.
+  `rc={"pdf.fonttype": 42}` gives TrueType. The default fonts are CFF, and with
+  them it writes a PDF that breaks the spec.
+- `despine` hides top and right tick marks, so it works on looks that mirror
+  ticks. On a categorical axis it hides minor ticks too.
+- `despine` leaves lines without data clipped, such as the flier line of a
+  boxplot with no outliers. Unclipped, it pulled constrained layout to the
+  figure corner.
+- `label_points` runs a fixed 1000 adjustText iterations instead of adjustText's
+  1 s time limit. The same figure with the same fonts now gets the same labels
+  on any machine. Markers push labels away twice as hard as adjustText's
+  default.
+- `label_points` draws each label in a rounded box with the legend frame's
+  face. The box outline and the leader line to the marker share one stroke
+  in the axes edge color. adjustText keeps the boxes apart and off the
+  markers. `bbox=None` gives bare labels.
+- `label_points` keeps labels off the axes edge by the legend's gap to it,
+  `legend.borderaxespad`. adjustText alone let boxes touch the frame.
+- Title, legend label, legend face and `savefig` face colors now inherit from
+  the palette's root colors instead of repeating them. 2D Rosé Pine figures
+  render pixel-identical at the same save dpi.
+- 3D panes take the background color instead of matplotlib's translucent grey.
+
+### Fixed
+
+- `despine` raised `TypeError` on Python 3.11 with numpy 2.3 or later.
+- `despine` keeps clipping on when a log axis leaves out values at or below 0,
+  such as the base of each bar. Unclipped, log bar charts collapsed constrained
+  layout and lost tick labels.
+- `despine` unclips every panel of shared axes, such as seaborn facets. Only
+  the first panel used to draw edge markers whole. Explicit limits that hold
+  all the data now unclip too.
+- `despine` picks ticks for the axes size after layout. It picked them before
+  layout, so an axes that layout shrank, such as one beside long category
+  names, kept too many ticks and their labels overlapped. Axes that layout
+  resizes can get a different tick step.
+- `despine` fixes the limits of a categorical axis. A twin drawn after
+  `despine` refitted them with its own margins and moved the bars off the
+  spine.
+- `despine` no longer offsets a categorical axis. Its labels sat 10 pt farther
+  from the bars or cells than the tick padding.
+- `despine` keeps styling set on tick labels, such as rotation. Moving the
+  spines used to reset rotated labels to horizontal. Long category names then
+  overlapped.

poikilos-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Samuel Ramirez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

poikilos-1.0.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.5
+Name: poikilos
+Version: 1.0.0
+Summary: Matplotlib themes and figure helpers
+Author-email: Christian Samuel Ramirez <chrisram0403@proton.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: lilaq,matplotlib,plotting,rose-pine,style,theme
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.11
+Provides-Extra: labels
+Requires-Dist: adjusttext>=1.4.0; extra == 'labels'
+Description-Content-Type: text/markdown
+
+# poikilos
+
+Matplotlib themes, plus five helpers for publication figures. *Poikilos* is
+Greek for many-colored.
+
+A theme is a look (fonts, spines, ticks, sizes) plus a palette (colors). Any
+look takes any palette.
+
+| Theme | Look | Palette |
+| --- | --- | --- |
+| `plain`, `plain-dark` | plain | matplotlib's tab10 on white or `#242424` |
+| `rose-pine`, `rose-pine-moon`, `rose-pine-dawn` | plain | [Rosé Pine](https://rosepinetheme.com) |
+| `lilaq`, `lilaq-moon` | lilaq | [lilaq](https://lilaq.org) 0.6.0, default and moon |
+| `pgl` | pgl | seaborn's whitegrid greys, tab10 |
+
+| Light | Dark |
+| --- | --- |
+| ![plain](https://raw.githubusercontent.com/ramirc0/poikilos/main/assets/gallery/plain.png) | ![plain-dark](https://raw.githubusercontent.com/ramirc0/poikilos/main/assets/gallery/plain-dark.png) |
+| ![rose-pine-dawn](https://raw.githubusercontent.com/ramirc0/poikilos/main/assets/gallery/rose-pine-dawn.png) | ![rose-pine](https://raw.githubusercontent.com/ramirc0/poikilos/main/assets/gallery/rose-pine.png) |
+| ![lilaq](https://raw.githubusercontent.com/ramirc0/poikilos/main/assets/gallery/lilaq.png) | ![lilaq-moon](https://raw.githubusercontent.com/ramirc0/poikilos/main/assets/gallery/lilaq-moon.png) |
+| ![pgl](https://raw.githubusercontent.com/ramirc0/poikilos/main/assets/gallery/pgl.png) | |
+
+[`rose-pine-moon`](https://github.com/ramirc0/poikilos/blob/main/assets/gallery/rose-pine-moon.png)
+has its own gallery image.
+
+## Install
+
+```bash
+uv add "poikilos @ git+https://github.com/ramirc0/poikilos"
+uv add "poikilos[labels] @ git+https://github.com/ramirc0/poikilos"  # adds adjustText for label_points
+```
+
+Needs Python 3.11 and matplotlib 3.11 or later.
+
+## Usage
+
+```python
+import matplotlib.pyplot as plt
+
+import poikilos as pk
+
+pk.use("rose-pine")
+
+fig, ax = plt.subplots()
+ax.plot([0, 1, 2], [0, 1, 0])
+pk.despine(ax)
+pk.save_figure(fig, "results/plot")  # writes plot.svg and plot.png
+```
+
+`use()` resets every style rcParam to matplotlib's default, then applies the
+theme. It leaves the backend alone, so it works before or after importing
+pyplot. Importing `poikilos` changes nothing.
+
+For one figure in another theme, use `context()`. It restores the previous
+rcParams on exit. Save inside the block, because matplotlib reads
+`savefig.dpi` at save time.
+
+```python
+with pk.context("lilaq"):
+    fig, ax = plt.subplots()
+    ax.plot(x, y)
+    pk.save_figure(fig, "results/lilaq")
+```
+
+### Mixing and overrides
+
+`palette=` puts another palette on a theme's look. `rc=` sets any rcParams on
+top. `use()`, `context()` and `rc_params()` all take both.
+
+```python
+pk.use("lilaq", palette="rose-pine-dawn")  # lilaq look, Rosé Pine Dawn colors
+pk.use("plain", rc={"axes.grid": True})
+```
+
+`use()` validates everything before it touches matplotlib. A misspelled key in
+`rc` raises `KeyError` and a bad value raises `ValueError`. Either way the
+current rcParams stay as they were. The next `use()` resets any rcParam you set
+by hand, so set them after `use()` or pass them in `rc`.
+
+seaborn's `set_theme()` also resets rcParams. Call it before `pk.use()`.
+
+`pk.rc_params(theme, palette=None)` returns a theme's rcParams as a dict
+without applying them.
+
+### Palettes as data
+
+Palettes are TOML files in `src/poikilos/palettes/`. `pk.PALETTES` holds them
+with every color resolved to hex:
+
+```python
+dawn = pk.PALETTES["rose-pine-dawn"]
+dawn.background  # '#faf4ed'
+dawn.cycle  # ('#b4637a', '#ea9d34', ...)
+dawn.colors["love"]  # '#b4637a', by the palette's own name
+```
+
+`pk.THEMES` maps each theme name to its `(look, palette)` pair.
+
+A palette sets root colors only: background, foreground, frame, ticks, grid,
+legend edge, boxplot median and mean, and the cycle. Legend face, title,
+`savefig` and hatch colors inherit from those. An `rc=` override of a root
+color therefore carries through to them.
+
+## Helpers
+
+- `despine(ax, categorical_x=False, categorical_y=False)` fits each continuous
+  axis to its data and widens it to the enclosing ticks. It then offsets the
+  left and bottom spines by 10 pt and trims them to the end ticks. The top and
+  right spines and their ticks go. Pass `categorical_x=True` for bar charts,
+  `categorical_y=True` for horizontal bars, and both for heatmaps. A categorical
+  axis has no spine or offset, so its labels sit by the data. Call it after
+  everything on the figure is drawn. It picks ticks for the axes size after
+  layout.
+- `fit_legend(fig)` grows the figure by the room legends outside the axes
+  take. Constrained layout otherwise keeps `figsize` and shrinks the axes, so
+  a square plot turns into a rectangle. The figure ends up larger than
+  `figsize`. Call it after adding every legend, before `despine`.
+- `label_points(ax, points, labels, offsets=None, leader=True, **text_kwargs)`
+  labels the collection
+  `ax.scatter` returns. Each label sits in a box outlined like its leader
+  line, or stays bare with `bbox=None`. It moves labels off each other and off
+  the markers, but a label can still touch a marker. That happens most near
+  the edge of the axes, since labels stay inside them. Call it last, after
+  `despine` and every title and legend. Needs the `labels` extra.
+  `offsets=[(dx, dy), ...]`, in points, fixes each label's place instead and
+  needs no extra. `leader=False` drops the leader lines.
+- `save_figure(fig, path, formats=("svg", "png"), **savefig_kwargs)` writes
+  `path.svg` and `path.png`, or one file per entry in `formats`. It drops a
+  suffix that names a format, such as `.svg` or `.pdf`, and keeps any other
+  dots, so `x.curve` gives `x.curve.svg` and `x.curve.png`.
+- `zero_line(ax, axis="y", **line_kwargs)` draws a bold line at zero, for
+  values that change sign. It uses the frame color at twice the grid width.
+  `axis="x"` draws x = 0 and `"both"` draws both. The limits widen to include
+  zero.
+
+## Recipes per look
+
+Looks only set rcParams. Anything that needs code per axes is a recipe.
+
+**plain.** Call `despine` on every axes. Without it you get matplotlib's
+default frame minus the top and right spines. `despine` styles the left and
+bottom spines only, so style a twin axes by hand:
+
+```python
+ax2 = ax.twinx()
+ax2.plot(x, y2, clip_on=False)  # despine never sees the twin
+ax2.set_ylim(0, 100)  # limits on ticks, so the spine ends on one
+ax2.spines[["left", "bottom"]].set_visible(False)
+ax2.spines["right"].set_visible(True)  # the look hides right spines
+ax2.spines["right"].set_position(("outward", 10))
+pk.despine(ax)  # last, once the twin is drawn
+```
+
+**lilaq.** lilaq's tick steps and dotted lines take a few lines of code:
+
+```python
+from matplotlib.ticker import MaxNLocator, NullLocator
+
+ax.plot(x, y, marker="o")  # lilaq draws a dot at every data point
+for axis in (ax.xaxis, ax.yaxis):
+    axis.set_major_locator(MaxNLocator(7, steps=[1, 2, 5, 10]))
+ax.xaxis.set_minor_locator(NullLocator())  # instead, on a categorical axis
+```
+
+lilaq rounds the step to 1, 2 or 5 and scales the tick count with the axis
+length. That gives about five ticks on its default 6 × 4 cm plot, where
+`nbins=7` switches steps at nearly the same data ranges. On axes of another
+size, lilaq picks a different count. The dots stay out of the look
+on purpose. A `marker` in `axes.prop_cycle` makes `plot(color="k")` use up a
+cycle slot and beads dense lines. seaborn would also apply it unevenly.
+`scatterplot` and `pointplot` drop it. `lineplot` keeps it but leaves it out of
+the legend, and without `hue` takes the marker from the wrong cycle slot.
+
+**pgl.** The Programmable Genomics Laboratory's papers use seaborn's
+`whitegrid` without spines, with a dashed grid in place of tick marks. This look
+follows them. Never call `despine` on it, because that brings the spines back.
+
+```python
+ax.xaxis.grid(False)  # categorical x; seaborn's categorical plots already do this
+pk.zero_line(ax)  # values change sign; axis="x" for x = 0
+```
+
+Heatmaps need `ax.grid(False)`. To sign positive tick labels on a scale that
+runs from − to +:
+
+```python
+from matplotlib.ticker import ScalarFormatter
+
+
+class SignedFormatter(ScalarFormatter):
+    def __call__(self, x, pos=None):
+        text = super().__call__(x, pos)
+        return f"+{text}" if x > 0 and text.strip("0.") else text
+
+
+ax.xaxis.set_major_formatter(SignedFormatter())
+```
+
+It keeps matplotlib's formatting, so `+1.50` sits next to `−0.50`.
+
+**PDF text as TrueType.** `rc={"pdf.fonttype": 42}` embeds fonts as TrueType.
+Use it only with a TrueType font. Anthropic Sans Text and New Computer Modern
+are CFF (`.otf`) fonts. So is Overpass from Debian's `fonts-overpass` package.
+With them, matplotlib writes CFF outlines into a TrueType font stream. Common
+viewers still render that PDF, but it breaks the PDF spec and strict checkers
+flag it.
+
+## Fonts
+
+No fonts ship with poikilos. Each look names a fallback chain that ends in a
+DejaVu family bundled with matplotlib, so a missing font falls back silently.
+
+- plain: Anthropic Sans Text, Google Sans Flex, Arimo, Arial, DejaVu Sans.
+- lilaq: New Computer Modern, Palatino Linotype, P052, DejaVu Serif. Math uses
+  matplotlib's bundled Computer Modern.
+- pgl: Overpass, Arial, Arimo, DejaVu Sans.
+
+matplotlib knows New Computer Modern as `NewComputerModern`. From
+[CTAN](https://ctan.org/pkg/newcomputermodern), install only the 10 pt cuts
+Typst uses: `NewCM10-Regular.otf`, `NewCM10-Italic.otf`, `NewCM10-Bold.otf`,
+`NewCM10-BoldItalic.otf` and `NewCMMath-Regular.otf`. The 8 pt and Book cuts
+register under the same family and weight, and matplotlib may pick any of them.
+
+After installing a font, delete matplotlib's font cache so it rescans:
+
+```bash
+rm "$(python -c 'import matplotlib; print(matplotlib.get_cachedir())')"/fontlist-*.json
+```
+
+Check that a family resolves without falling back:
+
+```python
+from matplotlib.font_manager import FontProperties, findfont
+
+findfont(FontProperties(family="NewComputerModern"), fallback_to_default=False)
+```
+
+The themes set `svg.fonttype: none`, so an SVG names its font instead of
+embedding it. A viewer without the font shows a substitute. PNGs look the same
+everywhere.
+
+## Limits
+
+- matplotlib hard-codes the colors of `table` cells, `quiver`, `barbs` and
+  `spy`. Palettes do not reach them.
+- rcParams cannot fix the size of the data area. The lilaq look's figure size
+  gives about lilaq's 6 × 4 cm for a plot with a title and both axis labels.
+- matplotlib's `scatter` draws from its own color cycle, separate from `plot`.
+- Some cycle colors have under 3:1 contrast with their background, such as two
+  petroff10 colors on `lilaq-moon`. `scripts/gallery.py` prints the ratios.
+  Text has at least 4.5:1 in every palette, and a test checks it.
+
+## Development
+
+```bash
+uv sync
+uv run pytest                          # includes image tests against tests/baseline/3.11
+uv run ruff check && uv run ruff format --check
+uv run python scripts/gallery.py       # regenerate assets/gallery
+uv run python scripts/lilaq_parity.py  # compare with lilaq 0.6.0 in build/parity
+```
+
+[CHANGELOG.md](https://github.com/ramirc0/poikilos/blob/main/CHANGELOG.md) has
+the version history and the versioning rules.
+
+## License
+
+MIT (see `LICENSE`).