Aesthete Agent README

English | 简体中文 | Online demo

aesthete-agent

Mechanically validated frontend aesthetics for AI agents. An agent skill (and MCP server) that plans, validates, and exports color systems — so your agent stops shipping purple-gradient AI slop and starts shipping palettes that pass WCAG, survive color-blindness, and read as designed.

npx skills add docsor1212/aesthete-agent   # 30 seconds; also: skillhub / clawhub / MCP uvx — see Install

Other tools give your agent taste advice. This one gives it gates: nothing ships until it passes four mechanical checks (WCAG contrast, three color-blindness simulations, AI-slop detection, scorecard) — backed by a 119-palette evidence library, five full-page layout recipes, and a render-verified review loop.

Why

LLMs choose colors badly for measurable reasons: they treat hex codes as text, they regress to the median of their training data (the frontend-tutorial median is purple/indigo), and they cannot see the colors they emit. aesthete-agent fixes this the engineering way — outsource taste to process:

• an evidence library of 119 curated palettes filtered by objective quality gates (flat lightness → rejected; no readable text pair → rejected; color-blind collisions / slop signatures → flagged),
• mechanical gates on every decision: a 5-dimension scorecard, exact WCAG 2.2 boundaries (APCA optional), three color-blindness simulations, AI-slop signature detection, a gradient ban (any gradient = P0), and an HTML delivery linter,
• a six-step method (manifesto → register check → source → roles → validate → five-lens review) that turns "make it pretty" into a reproducible pipeline,
• a preference profile (profile.json) that learns from every accept/reject verdict and mechanically down-ranks what the user rejects.

What it renders

Every image below is a real deliverable produced by the engine — roles derived in OKLCH, contrast gated, color-blind simulated, slop checked, then rendered into a full scene. No hand-picked colors. Live versions: visual showcase (30 scenes across curated palettes).

Mobile app — Bees & Honey · text/bg 5.6:1 AA	SaaS landing — same palette, browser chrome, 3:1 accents
Dashboard — KPI cards, chart bars, status pills	E-commerce — Deep Space Blue · 60-30-10 enforced
Editorial — Lavender · print-grade restraint	The showcase itself — 30 scenes, one engine

Install

Agent skill — one line in any skills-compatible agent (Claude Code, ZCode, Codex, Cursor, Gemini CLI):

npx skills add docsor1212/aesthete-agent

SkillHub (中文站, fastest in China — primary release channel):

skillhub install aesthete-agent --dir <your-skills-dir>   # e.g. ~/.claude/skills

or open skillhub.cn/skills/aesthete-agent and click 安装到本地 Agent.

DeepSeek Harness native plugin (DSH desktop / web / TUI) — 11 native tools over the bundled engine:

dsh plugin --profile web add github:docsor1212/dsh-aesthete-agent

ClawHub (international registry):

ClawHub (international registry):

npx clawhub install aesthete-agent

MCP server (Claude Desktop, Cursor, any MCP client) — the engine as 21 callable tools:

uvx aesthete-agent-mcp            # from PyPI, zero keys
# or: npx -y @smithery/cli install docsor1212/aesthete-agent-mcp --client claude

Pure Python stdlib in the core engine (offline, zero keys, zero telemetry); Pillow optional for image extraction; FastMCP optional for the MCP server.

30-second agent quickstart

S="scripts/palette_forge.py"   # inside the installed skill directory
python "$S" match --brief "pediatric clinical teaching page" --limit 6   # rank the evidence library by register
python "$S" score --palette 264653,2A9D8F,E9C46A,F4A261,E76F51           # 5-dim scorecard /20
python "$S" matrix --palette ... --method apca --recommend               # full contrast matrix (APCA = WCAG 3 draft)
python "$S" semantic --count 8 --base 2A9D8F                             # color-blind-safe categorical colors
python "$S" visualize --palette ... --variants 3                         # 10 real UI scenes + variants
python "$S" report --palette ...                                         # all gates → one PASS/FAIL verdict
python "$S" theme "Golden Window Suya" --format css                      # named theme pack → CSS tokens
python "$S" export --palette ... --format w3c                            # W3C Design Tokens JSON
python "$S" export --palette ... --format prompt                         # image-generation prompt block
python "$S" doctor                                                       # environment health check

Full method (manifesto → register → source → roles → validate → five-lens review) lives in SKILL.md. References carry a 30-second routing table per task.

What's inside

The evidence library

Nobody can know "beautiful" a priori — so the library is built from three filters, each doing only what it can: crowd signal (community-endorsed charts, like tiers, cross-page recurrence), objective gates (reject only objectively broken architecture: flat lightness, no readable pair; flag CB collisions and slop), and in-context review (the final verdict happens in real layouts, with the user). Every rejection is recorded with a measured cause.

MCP server

mcp/ wraps the engine as MCP tools (JSON-RPC over stdio). Zero keys, zero telemetry; ships as a self-contained wheel — server_data/ carries the engine, so uvx aesthete-agent-mcp works standalone. A pure-stdlib stdio fallback (--stdio) runs even without FastMCP.

Platform availability

License

MIT