Metadata-Version: 2.4
Name: albers
Version: 0.2.6
Summary: Color theory tools: harmony, contrast, perceptual metrics, brand token I/O
Project-URL: Homepage, https://github.com/lmarkmann/albers
Project-URL: Repository, https://github.com/lmarkmann/albers
Project-URL: Issues, https://github.com/lmarkmann/albers/issues
Author-email: Luis Markmann <110569833+lmarkmann@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: accessibility,color,contrast,harmony,palette,theme,wcag
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: rich>=14.3.3
Requires-Dist: typer>=0.24.1
Description-Content-Type: text/markdown

# albers

[![PyPI](https://img.shields.io/pypi/v/albers)](https://pypi.org/project/albers/)
[![Python](https://img.shields.io/pypi/pyversions/albers)](https://pypi.org/project/albers/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

![albers banner](./banner.svg)

Color theory tools: harmony, contrast, perceptual metrics, brand token I/O.

## Install

```sh
uv add albers
# or
pip install albers
```

## Usage

Works standalone with hex colors:

```sh
albers compare #4d9375 #2d7a5f
albers suggest #4d9375
albers suggest #4d9375 --harmony complementary
albers replace #ff5555 #ff6666
```

Load and analyze an existing brand palette:

```sh
albers from-css brand/tokens.css
albers from-tokens brand/tokens.json
```

Export colors to standard formats:

```sh
albers export primary:#4d9375 bg:#1a1a1a accent:#ff5555
albers export primary:#4d9375 bg:#1a1a1a --format css
```

## Commands

| Command | What it does |
|---|---|
| `compare #hex1 #hex2` | Side-by-side perceptual comparison of two colors |
| `suggest #hex` | Harmony-based color alternatives |
| `replace #old #new` | Perceptual impact of swapping one color for another |
| `from-css <file>` | Load and analyze color tokens from CSS custom properties |
| `from-tokens <file>` | Load and analyze colors from a W3C DTCG token file |
| `export name:hex ...` | Export a palette as DTCG JSON or CSS custom properties |

## Python API

```python
from albers import (
    hex_to_rgb, contrast_ratio, analyze_harmony,
    name_color, from_css, to_dtcg,
)

rgb = hex_to_rgb("#4d9375")
cr = contrast_ratio(rgb, (18, 18, 18))

print(name_color("#4d9375"))   # ('seagreen', 16.3)

colors = from_css(open("brand.css").read())
print(to_dtcg(colors))
```

## License

MIT
