aesthete-agent — Frontend Aesthetics Engine

Why LLM color output is bad, with evidence: models treat hex codes as text, regress to the median of training data (the frontend-tutorial median is purple/indigo), and cannot actually see color. The fix is not a better model — it is outsourcing taste to process: manifesto first, role mapping, mechanical validation, in-context self-review.

⛔ Iron rules:

1. No bare palette writing. Every color task goes through the six-step method; step 6 (five-lens review) is not skippable.
2. No runtime access to the source site — no public API, direct connections hit Cloudflare 403; all data ships offline.
3. The brief is law: colors and aesthetics pinned by the user are binding constraints. Already-shipped brand systems are out of scope for re-paletteing.
4. Bounded verification: build fully → one batched review → one batched fix round → at most one more confirmation → stop polishing.
5. Candidate discipline: user verdicts require ≥2 full-page candidates (make_variants.py builds the comparison sheet); a single proposal is not sent for review.
6. Verdict write-back: every accept/reject lands in profile.json (machine-read) and critique.md necropsies (failure modes) — no write-back, no growth.

Capability × Boundary Quick Reference

Non-goals: layout systems, image asset generation, print CMYK gamut, typeface selection — this skill only decides and validates color.

Six-Step Method

Command variables (set once): SDIR="<absolute path to this skill dir>", S="$SDIR/scripts/palette_forge.py".

Step 1: Name the aesthetic manifesto

Pick a 1-2 word movement name + a one-line manifesto: "Herb garden ledger — pot brown, dried-herb green, mulberry-paper cream, all low saturation, sun-bleached". The manifesto includes:

• Register check (lens 0): who reads it / in what setting / what they take away in 3 seconds; visual register must match the content domain. The user's existing aesthetic profile (e.g. light/understated/whitespace/ghost numerals) is the highest-priority constraint — check before writing; a fitting metaphor cannot rescue a register mismatch;
• Reference aesthetics: "1970s ski lodge: burnt orange, avocado green, warm brown";
• Lightness architecture: light or dark ground; text is always the extreme;
• Color dosage: accent ≤10% of the page — "scarcity is force";
• Negation list: pick applicable items from references/anti-slop.md into the prompt (inference-time negation works);
• 60-30-10 is a default scaffold, not law — proportions follow the brief.

Step 2: Source (four routes)

python "$S" match --brief "pediatric clinical teaching page" --limit 6   # A' brief match: auto register + profile down-rank (preferred)
python "$S" search --style warm,pastel --no-flags --limit 6   # A manual filter
python "$S" harmony --base 780000 --mode complementary --theme light  # B OKLCH harmony
python "$S" extract reference.png --n 6                  # C image extraction (needs Pillow)
python "$S" ramp --base 2A9D8F --steps 7                 # D luminance ramp (charts/heatmaps)

A' = natural-language brief → register detection + profile down-rank + tier ranking, the preferred entry for new tasks. The spacebar-iteration equivalent: re-roll seeds/modes/style words; generate ≥2 candidates before moving on. Many candidates → showcase renders named picks.

Step 3: Roles, not a bag of swatches

python "$S" roles --palette 606C38,283618,FEFAE0,DDA15E,BC6C25 --semantic --css

Outputs bg/text/accent/primary/surface + derived semantic colors (success/warning/error/info), with three contrast checks — non-zero exit on failure. Key point: the strongest color owns one deliberate region, not scattered accents.

Step 4: Mechanical validation (measurement vs taste, separated)

python "$S" score --palette ...     # 5-dim scorecard /20, P0-P3 findings, <10 exits non-zero
python "$S" contrast --fg ... --bg ... [--large]   # single-pair check with fix suggestions
python "$S" blind --palette ...     # three color-blind simulations; mandatory for charts/status colors
python "$S" slop --palette ...      # AI-slop signatures; non-zero exit on hit

Charts additionally: distinguish data by luminance ramps only (ramp), redundant encoding via shape/labels, never red+green as the sole distinction.

Step 5: Export tokens

python "$S" export --palette ... --format css|tailwind|json|svg|w3c|context   # w3c=设计令牌标准;context=LLM 上下文块
python "$S" mutate --palette ... --shade -20 --sat +5 --hue 15 --temp +30

Step 6: Five-lens self-review (mandatory gate)

python "$S" card --palette ... --name "Project" --out card.html   # palette card + mockup
python "$S" visualize --palette ... --name "Project" --out viz.html   # 10-scene visualizer; --variants N = same scenes under N palette orders
python "$S" visualize --palette ... --svg design.svg --shuffle 3      # slot-inventory recolor: 3 permutations + comparison grid
python "$S" critique --palette ... [--evidence evidence.json] --out report.md   # 五镜报告生成器(机械发现预填)
python "$S" report --palette ...   # 一键验收: 四闸聚合 PASS/FAIL JSON, 退出码=裁决
python "$S" export --palette ... --format prompt   # 色板→图像生成提示词块(封面/插画管线)
python "$S" doctor                                 # 环境体检
python "$SDIR/scripts/lint_page.py" page.html --palette <declared palette> --floor 12   # delivery audit

Always screenshot into the conversation and adjudicate with the five lenses from references/critique.md (intent/register → composition → information → color → type): every PASS/FAIL points at a concrete element + cites a principle + evidence; FAIL unfixed = not delivered; fixes are bounded. Before HTML delivery run lint_page.

Gate chain:

Render-probe fallback: without browser tooling skip step 4, keep five-lens screenshots as the floor, and note "render evidence not run" in the delivery.

On user rejection, run a necropsy first (write the transferable failure mode back to critique.md), then redesign. Formal deliverables follow the host environment's acceptance flow.

Verdict write-back & customization

• Accepted-design intake: python "$S" house --name "Project final" --hexes ... --from-proj project — joins the library and gets match-boosted.
• Custom registers: edit registers in profile.json (key = register name, value with theme/style_tags/accent_max_area); match --register picks it up. A new domain = a new entry, not new code.
• Self-test: python "$S" selftest — WCAG boundaries/OKLCH round-trip/slop signatures; non-zero exit = engine untrustworthy.

Reference docs (30-second routing)

Selection methodology

Three filters: ① crowd signal (source-site official charts + likes tiers + cross-page recurrence) ② objective gates (reject only objectively broken: flat lightness / no readable pair; flag CB collisions / slop / narrow lightness) ③ in-context self-review (the final verdict). Nobody can know "beautiful" a priori — the library sets the starting line, the context decides. Details in references/curation.md.