calmplots

If calmplots is useful in your work, consider starring and watching the repo to follow updates.

calmplots is a cohesive visualization theme package for:

• Matplotlib
• Seaborn
• Plotnine
• Plotly
• Altair

It is inspired by the spirit of the blueycolors palette family and aims to provide attractive, consistent defaults across notebooks, reports, and dashboards.

Palette compatibility

• Exact blueycolors palettes: bluey, chilli, heeler, socks
• calmplots extensions: bluey10, colorblind, and continuous ramps (bluey_seq, sunset_seq, bluey_div)
• In dark themes, colorblind is automatically mapped to a dark-safe variant for contrast.
• Public API stability: names exported in calmplots.__all__ are considered stable

Palette quick guide

• Use bluey, chilli, heeler, or socks when you want strict blueycolors compatibility.
• Use colorblind when category distinction and accessibility are the top priority.
• Use accessible_palette(theme="light"|"dark") for CVD-optimized defaults.
• Use bluey10 for larger categorical charts (up to 10 categories).
• For very high category counts, group categories and highlight only key series.
• Use continuous ramps (bluey_seq, bluey_div) for heatmaps and gradients.

Accessibility note:

• calmplots uses Color Vision Deficiency (CVD) simulation checks, perceptual distance checks, and contrast checks for accessibility-focused palettes.
• This evidence supports real-world usage. It does not claim universal suitability for all CVD types, severities, or chart designs.

Attribution

The base palette set is derived from blueycolors by Eric Ekholm.

Install

For most users:

pip install calmplots

To install all optional backend integrations:

pip install "calmplots[all]"

For local development with uv:

uv sync --extra all

Install the latest unreleased code from GitHub:

pip install "calmplots @ git+https://github.com/techwizrd/calmplots.git"
pip install "calmplots[all] @ git+https://github.com/techwizrd/calmplots.git"
uv add "calmplots @ git+https://github.com/techwizrd/calmplots.git"
uv add "calmplots[all] @ git+https://github.com/techwizrd/calmplots.git"

For reproducible Git installs, pin to a commit:

pip install "calmplots @ git+https://github.com/techwizrd/calmplots.git@<commit_sha>"
uv add "calmplots @ git+https://github.com/techwizrd/calmplots.git@<commit_sha>"

Note: Git installs may include unreleased changes; use PyPI releases for production.

For docs and test tooling only:

uv sync --extra docs --extra test

For full development (all backends + docs + checks):

uv sync --extra dev

Quickstart

import calmplots

# Matplotlib + Seaborn
calmplots.apply_matplotlib_theme()
calmplots.set_seaborn_theme(context="notebook")

# Plotly
calmplots.register_plotly_template(set_default=True)

# Altair
calmplots.enable_altair_theme()

Core design

• Clarity first: readable labels, lines, and grid hierarchy
• Consistent tokens: one semantic token source reused across backends
• Sensible defaults: subtle grid, softened spines, accessible emphasis
• Accessible by design: includes a colorblind-considerate categorical palette

Documentation

• Website: techwizrd.github.io/calmplots
• Quickstart: Quickstart
• Do/Don't guide: Do/Don't
• Compatibility notes: Compatibility
• Colorblindness approach: Colorblindness
• Gallery page: Gallery
• Matrix index: examples/gallery/matrix/README.md

Gallery Preview

Palette Gallery (all palettes)

Light background

Dark background

Before vs After (Matplotlib)

See the full comparison matrix in the docs-linked index above.

Matplotlib/Seaborn

Plotnine

Plotly

Altair

Contributing

See CONTRIBUTING.md for development setup, checks, and release process.

Get involved

• Ask usage and design questions in GitHub Discussions.
• Report bugs and request features via Issues.
• Look for issues labeled good first issue or help wanted to jump in quickly.

Roadmap

• Publish to PyPI and add release automation checks.
• Expand gallery coverage with more chart types and dashboards.
• Add backend parity checks for theming behavior.
• Improve accessibility guidance with practical chart design examples.