colorsense 0.3.0

Extract the rendered color palette from any website as a typed result.

colorsense

Extract the rendered color palette of any website as a structured, typed Python object.

colorsense renders a page in a headless browser, harvests its design tokens and computed element colors, and classifies them into a 60/30/10 palette — primary, secondary, accent, and neutrals, each with ranked, scored candidates. The result is a frozen Pydantic model, ready for downstream consumers (including AI models) that need to understand a site's color identity.

import asyncio
from colorsense import PaletteRole, Theme, analyze

result = asyncio.run(analyze("https://example.com"))
primary = result.themes[Theme.light].roles.mapping[PaletteRole.primary]
print(primary[0].color.hex)  # ranked candidates; empty tuple when none detected

Installation

pip install colorsense
playwright install chromium

Requires Python 3.12+. Rendering uses headless Chromium via Playwright; the browser binary is not a pip dependency, so run playwright install chromium once after installing (on Linux, also playwright install-deps chromium for the OS libraries).

Quick start

analyze is async — await it from an event loop, or wrap it with asyncio.run:

import asyncio
from colorsense import analyze, PaletteRole

result = asyncio.run(analyze("https://example.com"))

for theme, palette in result.themes.items():
    candidates = palette.roles.mapping[PaletteRole.primary]
    if candidates:  # every role is present; empty tuple when none detected
        best = candidates[0]
        print(theme, best.color.hex, best.probability)

Each role — primary, secondary, accent, neutral_light, neutral_dark — maps to a probability-ranked tuple of candidates; take [0] for the best pick. Inside an async application (e.g. a FastAPI endpoint), just result = await analyze(url).

See the usage guide for the full result schema, options, and fetch policy.

Command line

pip install colorsense also ships a colorsense command, so a first look needs no code:

colorsense https://example.com
colorsense https://example.com --dark --json > palette.json

The default output is a human-readable palette summary; --json emits the full AnalysisResult schema. All flags are documented in the usage guide.

Features

• 60/30/10 palette classification — five roles, each with ranked candidates carrying a confidence (probability) and page-area dominance (area).
• Typed, serializable results — analyze returns a frozen Pydantic AnalysisResult; result.model_dump_json() round-trips.
• OKLCH out of the box — every Color carries an sRGB hex plus cached OKLCH coordinates, so you can derive theme-matched tints, shades, and contrast without re-parsing hex strings.
• Light and dark themes — opt into dark mode rendering; near-identical light/dark renders collapse to a single reported theme.
• Declared vs. rendered reconciliation — reports the site's CSS custom properties and discrepancies between what is declared and what is actually used.
• Status-color filtering — success/error/warning colors are detected and kept out of the palette, so an error banner never masquerades as a brand accent.
• Polite, controllable fetching — configurable User-Agent, robots.txt gate with Crawl-delay support, per-host rate limiting, render caching, and a per-request egress filter that gates every browser request and the policy's own robots.txt fetch.
• Server-grade guard rails — a built-in private-network egress filter (block_private_networks) covering browser requests and the robots fetch alike, plus opt-in bounds on render concurrency (max_concurrent_renders) and total call time (max_total_seconds), and a browser launch-arg pass-through (browser_args) for e.g. capping the V8 heap per renderer.
• Async-native and concurrent — themes render concurrently in one shared browser; CPU work is offloaded so the event loop stays responsive.

How it compares

Most palette tools quantize the pixels of an image or screenshot and return dominant colors with no semantics. colorsense renders the live page, reads computed styles and declared design tokens, and classifies colors into 60/30/10 roles with confidence scores — you get "this is the brand accent", not "this orange is common". If you just need dominant colors from an image, an image-quantization tool is simpler and the right choice.

Security

colorsense fetches and fully renders third-party pages. If untrusted or user-supplied URLs can reach analyze from a server, treat it as an SSRF surface: validate hosts before calling, and use PolitenessPolicy(request_filter=block_private_networks()) to gate every request the rendered page makes — and the policy's own robots.txt fetch, including its redirect hops; bound abuse with max_concurrent_renders and max_total_seconds. The threat model and required controls are documented in SECURITY.md — read it before exposing analyze to untrusted input.

Examples

The examples/ directory has two runnable starting points: quickstart.py for trusted, hardcoded URLs, and webservice/ — a FastAPI service that is a reference implementation of the SECURITY.md controls for untrusted, user-supplied URLs.

Documentation

• Usage guide — options, the result schema, errors, and fetch policy.
• Advanced guide — design-token auditing and custom tuning.
• SECURITY.md — threat model and consumer responsibilities.
• CONTRIBUTING.md — development setup and contribution workflow.
• CHANGELOG.md — release history.

Support & license

Bug reports and feature requests: GitHub Issues. Want to contribute? Start with CONTRIBUTING.md. Licensed under the MIT License.