Make Agent Design Taste installable, routable and internally consistent

[aievolutionpl]

The design knowledge was already strong. The gaps were onboarding, context routing, and a handful of rules that contradicted each other. This addresses all three without replacing any existing system.

98 files changed · +10,632 / −1,797

---

1. Onboarding — the README as a mental installer

A human should know what to do in 30 seconds; an agent reading the same file should know too.

• AGENT-BOOTSTRAP.md — a 75-line universal entry point: 10 steps, reading order by task, and an explicit what NOT to load table.
• README.md rewritten — three concrete install modes (one-shot / project / global), a copy-paste one-shot prompt, a FOR AI AGENTS section, the workflow diagram, measured context costs, and a verification question to confirm the install worked.
• README.pl.md — full Polish translation, language switch at the top of both. No more mixed languages in one file.
• docs/INTEGRATIONS.md — per-agent setup for Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Lovable and v0. Every mechanism was checked against that tool's own documentation before being written down — file paths, precedence order, size caps, frontmatter fields. Nothing guessed.
• adapters/ + scripts/install.sh — copy-paste instruction files per agent, installed with one command (--dry-run and no-overwrite-without---force).

2. Context routing — never load all 15 styles

• docs/CONTEXT-PROFILES.md — LIGHT (~3k) / STANDARD (~8k) / FULL (~25k), with per-file token costs measured by validate.py --budget, not estimated.
• design-taste.manifest.json + styles/index.json — machine-readable routing: ids, aliases, paths, scoring weights, veto conditions, supporting and incompatible styles. Another agent can route without parsing prose.
• All 15 style DNAs together cost ~41k tokens. One costs ~2.7k and is already a complete brief. That argument is now stated in the README, the bootstrap, the skill and the manifest.

3. Contradictions resolved

Was	Now
SKILL.md said "390px first"; step 8 and three other files said 375px	390 × 844 is canonical, 360 is the narrow floor. One ladder: 1440 / 768 / 390 / 360. Enforced by a validator check.
SKILL.md: "never invent colors/fonts outside the chosen tokens" vs DECISION-MATRIX: "keep existing brand colors/fonts"	One precedence chain in docs/PRECEDENCE.md: brand & legal ▸ accessibility ▸ product ▸ style DNA ▸ repo tokens ▸ agent taste, plus ANALYZE → MAP → ADAPT for projects that already have a design system, and an explicit rule for the brand-vs-contrast collision (keep the brand, derive an accessible variant in the same hue family).
README showed a style folder with 4 files and linked a non-existent assets/decision-tree.png	Real structure including tokens.json and tokens.tailwind.css — the strongest argument for developers.

4. Deepened, not replaced

• DECISION-MATRIX.md — 11 brief signals, absolute veto gates, and a weighted scoring card per style. The agent must now output why the runner-up loses.
• ANTI-SLOP.md — BLOCKER / STRONG SMELL / MINOR SMELL severity, plus new detections (every section in a card, generic icon grids, meaningless metric cards, generic marketing copy, desktop merely stacked for mobile).
• evaluation/DESIGN-TASTE-SCORE.md — 13 weighted categories summing to 100, 8 hard blockers that fail a design regardless of total, accessibility carrying the highest single weight (12).
• LAYOUT-PATTERNS.md — the 43 patterns became a decision library: when to use, density fit, fitting/conflicting styles, mobile recomposition, CTA placement, accessibility notes, and the common AI mistake for each.
• typography/, visual-language/, component-patterns/ substantially expanded (typeface signals and metrics, Polish/CE diacritics, font-loading cost; per-style image direction table; 19 components × 8 interaction states).
• New accessibility/ACCESSIBILITY.md (a quality gate with a per-style failure table) and responsive/RESPONSIVE-FOUNDATIONS.md (recomposition, not stacking).
• All 15 style DNAs restructured into one 24-section architecture. Each gained a design philosophy, responsive behaviour, style combinations, and a real signature move — the generic placeholder is gone. Individuality preserved: Neumorphism still warns about itself, Maximalism still doesn't apologise.

5. Bugs fixed

• gen_tokens.py emitted invalid Tailwind v4: --color--bg (doubled prefix), --radiu--sm (rstrip('s') ate the namespace), --fontSize--h1 (camelCase). Now correct --color-* / --text-* / --radius-* / --shadow-* / --ease-* / --container-* namespaces.
• tokens.json keys had leading dashes ("-bg").
• Both scripts had a hard-coded absolute path from the author's machine.
• Five styles were missing token categories they were documented as having; 15-expressive-kinetic-typography had no --shadow-focus at all, which is an accessibility requirement.
• 07-neumorphism had a duplicated "When NOT to use" section and a vague citation; an unverifiable research citation in MODE-ROUTING.md was removed.

6. Verification

python3 scripts/validate.py            # 943 checks — all passing
python3 scripts/validate.py --budget   # measured context cost per file
node    scripts/screenshot.mjs 10      # render at 1440/768/390/360

scripts/validate.py checks style folders, required files, token categories, generated-file freshness, the 24-section architecture, every internal link, every example.html parse, manifest path resolution, duplicate ids and aliases, and stale viewport references.

scripts/screenshot.mjs renders any page or example at all four canonical viewports and exits non-zero on horizontal overflow at mobile — it makes rendered verification a step you can run, not an instruction you can skip. Screenshots go to a gitignored directory; no binaries added.

A GitHub Actions workflow runs the validator, verifies generated files are committed, prints the context budget, and smoke-tests the installer.

Also added: CONTRIBUTING.md (with a full checklist for style #16), CHANGELOG.md, LICENSE, docs/STYLE-TEMPLATE.md, docs/EXAMPLE-WORKFLOW.md (one brief followed end to end, with the actual context cost at the bottom).

Compatibility notes

Three changes are breaking for anyone who pinned to the old structure, and are listed in CHANGELOG.md:

1. Style README headings changed (24-section architecture) — deep links to anchors need updating.
2. 375px → 390px as the canonical mobile viewport.
3. SKILL.md hard rule 3 was rewritten.

Core directory names were deliberately not renamed — external installations reference them by path.

Not done

• No screenshot binaries committed (script provided instead, per "do not add giant binary assets unnecessarily").
• The preview gallery links to docs/index.html with instructions for enabling GitHub Pages, rather than claiming a live URL I could not verify from this environment.
• Per-style hero / dashboard / mobile example variants were not added — each style still ships one example.html. Worth a follow-up.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MSG5kjLk3ZvmZy2C4B17kP

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.