# PaletteSense

> Free color toolkit: a WCAG color contrast checker and a CSS gradient generator with OKLCH blending, live contrast analysis, and shareable URLs — built to be usable by both humans and AI agents.

PaletteSense runs in the browser, and tool state is encoded in the URL so views are shareable and reproducible. Gradients use `/gradients/<slug>?editor=1` for catalog entries or `/gradients/custom?editor=1&g=...` for arbitrary encoded gradients; the contrast page uses `?cs=`, and saved favorites use `?cart=`. `/` is the marketing landing page, not a tool. Colors are hex (3- or 6-digit). A non-JS fetch of a stateful share URL returns the base page — read supported legacy state headlessly with `/api/share/decode`. The same color math is available through the public JSON API and Model Context Protocol (MCP) server, which agents should prefer over scraping the UI.

## Tools
- [Color contrast checker](https://palettesense.com/app): WCAG AA/AAA pass-fail for text and UI colors. Backgrounds can be a solid color or a CSS gradient (linear/radial/conic, sRGB/OKLCH/HSL) with live min-contrast analysis and scrim suggestions. In the API the conic type is named `angular` (it renders as `conic-gradient`).
- [CSS gradient editor](https://palettesense.com/gradients/custom?editor=1): the current focused gradient editor — design a gradient and copy its CSS, custom property, or Tailwind theme block.
- [Color palette generator](https://palettesense.com/palette-generator): harmonious palettes (complementary/analogous/triadic/tetradic/monochromatic) in OKLCH with WCAG contrast scores; deep-linkable via `?base=&scheme=&count=&bg=`.
- [Color scale generator](https://palettesense.com/color-scales): Radix-style 12-step accent + gray scales (light and dark) from one accent color, with alpha variants, WCAG-checked text steps, and a CSS variables export; deep-linkable via `?accent=&mode=`.

## Reference pages
- [Color library](https://palettesense.com/colors): 31,000+ named colors indexed by hue family (`/colors/blue`); each color has a static page at `/color/<slug>` (e.g. `/color/coral`) with hex/RGB/HSL/OKLCH codes, WCAG contrast data, and palettes.
- [Gradient gallery](https://palettesense.com/gradients): curated named gradients; each `/gradients/<slug>` page (e.g. `/gradients/sunset`) has copy-ready CSS, a Tailwind theme block, and a text-contrast verdict.
- [Contrast examples](https://palettesense.com/contrast): precomputed WCAG verdicts for common color pairs at `/contrast/<fg>-on-<bg>` (e.g. `/contrast/white-on-navy`), with AA/AAA matrices and accessible fixes.
- [Guides](https://palettesense.com/guides): articles on contrast ratios, WCAG AA vs AAA, fixing failing contrast in OKLCH, OKLCH vs HSL, text over gradients, and building accessible palettes.

## API (JSON, no auth, permissive CORS)
- [OpenAPI 3.1 spec](https://palettesense.com/api/openapi.json): the full machine-readable contract.
- [Check contrast](https://palettesense.com/api/contrast?fg=%231a1a1a&bg=%23ffffff): GET /api/contrast?fg=&bg=&context=&level= — ratio plus full WCAG matrix.
- [Batch contrast](https://palettesense.com/api/contrast/batch): POST { pairs: [{ fg, bg, context?, level? }] } — up to 50 pairs in one request; validate a whole palette at once.
- [Search colors](https://palettesense.com/api/colors/search?q=teal): GET /api/colors/search?q=&limit= — by name, hex, or nearest match; limit caps every search mode.
- [Optimize contrast](https://palettesense.com/api/optimize-contrast?fg=%237a7a7a&bg=%23ffffff&level=AA): GET /api/optimize-contrast?fg=&bg=&level= — nudge a color in OKLCH until the pair passes WCAG, keeping its hue.
- [Suggest palette](https://palettesense.com/api/palette/suggest?base=%231392e6&scheme=analogous): GET /api/palette/suggest?base=&scheme= — harmonious scheme (complementary/analogous/triadic/tetradic/monochromatic), each scored for contrast.
- [Generate scales](https://palettesense.com/api/scales?accent=%231392e6): GET /api/scales?accent= — Radix-style 12-step accent + gray scales for light and dark modes, with alpha variants, WCAG checks, and CSS variables.
- [Text color](https://palettesense.com/api/text-color?bg=%231392e6): GET /api/text-color?bg= — best readable text color (black or white) for a background.
- [Analyze gradient contrast](https://palettesense.com/api/gradient/contrast): POST a gradient + text color, get the minimum ratio and a scrim suggestion.
- [Generate gradient CSS](https://palettesense.com/api/gradient/css): POST a gradient, get CSS, a custom property, and a Tailwind v4 theme block.
- [Decode share URL](https://palettesense.com/api/share/decode): GET /api/share/decode?url= — turn a share URL into structured state.
- [Encode share URL](https://palettesense.com/api/share/encode): POST a gradient and/or favorites, get shareable deep links.

## For AI agents
- [MCP server](https://palettesense.com/api/mcp): Streamable HTTP. Tools: check_contrast, check_contrast_batch, search_colors, analyze_gradient_contrast, generate_gradient_css, decode_share_url, encode_share_url, optimize_contrast, suggest_palette, generate_scales, accessible_text.
- [AI agent guide](https://palettesense.com/ai-agent-guide): quickstart, curl examples, recipes, stable UI data-testid hooks, and how to add the MCP connector.
- [AI agent guide (Markdown)](https://palettesense.com/ai-agent-guide.md): the full guide as plain Markdown — fetch the whole thing in one request.

## Optional
- [Site](https://palettesense.com): the marketing landing page, which links out to the tools above.