Make Agent Design Taste installable, routable and internally consistent

.github/workflows/validate.yml

@@ -0,0 +1,49 @@
+name: validate
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Structure, links and generated files
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Validate repository structure
+        run: python3 scripts/validate.py
+
+      - name: Verify generated files are committed
+        run: |
+          python3 scripts/gen_tokens.py
+          python3 scripts/gen_manifest.py
+          if ! git diff --quiet; then
+            echo "::error::Generated files are out of date. Run:"
+            echo "  python3 scripts/gen_tokens.py && python3 scripts/gen_manifest.py"
+            git --no-pager diff --stat
+            exit 1
+          fi
+
+      - name: Context budget
+        run: python3 scripts/validate.py --budget
+
+      - name: Installer smoke test
+        run: |
+          tmp="$(mktemp -d)"
+          bash scripts/install.sh --agent all --target "$tmp"
+          test -f "$tmp/AGENTS.md"
+          test -f "$tmp/CLAUDE.md"
+          test -f "$tmp/GEMINI.md"
+          test -f "$tmp/.cursor/rules/agent-design-taste.mdc"
+          test -f "$tmp/.windsurf/rules/agent-design-taste.md"
+          test -f "$tmp/.github/copilot-instructions.md"

.gitignore

@@ -0,0 +1,5 @@
+screenshots/
+node_modules
+node_modules/
+__pycache__/
+.DS_Store

AGENT-BOOTSTRAP.md

@@ -0,0 +1,77 @@
+# AGENT BOOTSTRAP
+
+> The shortest possible entry point. If you are an AI agent and you read only
+> one file in this repository, read this one, then read `SKILL.md`.
+
+**You are about to build or change a user interface. Do not write UI code yet.**
+
+---
+
+## The 10 steps
+
+```
+1.  READ        SKILL.md (the full workflow + hard rules)
+2.  MODE        pick LIGHT / STANDARD / FULL   → docs/CONTEXT-PROFILES.md
+3.  UNDERSTAND  product · audience · personality · density · action · emotion
+4.  CHOOSE      1 dominant style (+ max 1 supporting) → DECISION-MATRIX.md
+5.  LOAD        only styles/<chosen>/README.md + tokens.css   (never all 15)
+6.  TOKENS      resolve conflicts via PRECEDENCE  → docs/PRECEDENCE.md
+7.  BUILD       constraint-first: tokens, grid, type scale, component specs
+8.  RENDER      real browser at 1440 / 768 / 390 → evaluation/RENDERED-VERIFICATION.md
+9.  AUDIT       score + anti-slop → evaluation/DESIGN-TASTE-SCORE.md · ANTI-SLOP.md
+10. FIX         repair the two weakest areas, render again, then deliver
+```
+
+Steps 3, 4, 8 and 9 are not optional. A design delivered without them is a
+failure even when it looks good.
+
+---
+
+## What NOT to load
+
+| Do not load | Why |
+|---|---|
+| All 15 style folders | ~60k tokens of context for a decision you make once |
+| Every `example.html` | They are reference output, not input. Open one, at most |
+| `styles/*/prompts.md` | Only when you are *writing a prompt for another tool* |
+| `evaluation/TASTE-LOOP.md` | Only for multi-session projects that keep a `taste/` folder |
+| `docs/INTEGRATIONS.md` | Only when installing the skill, never when designing |
+| `README.pl.md` | Polish translation of the README — same content |
+
+Loading more than one style's DNA is the single most common context mistake.
+The decision matrix exists so you *don't* have to read them all.
+
+---
+
+## Reading order by task
+
+| Task | Read, in order |
+|---|---|
+| "make this button/section better" | `ANTI-SLOP.md` → the project's own tokens |
+| "build a landing page" | `SKILL.md` → `DECISION-MATRIX.md` → 1 style → `LAYOUT-PATTERNS.md` |
+| "redesign the whole product" | Everything in FULL profile — see `docs/CONTEXT-PROFILES.md` |
+| "review this UI" | `evaluation/DESIGN-TASTE-SCORE.md` → `ANTI-SLOP.md` → style Do/Don't |
+| "the project already has a design system" | `docs/PRECEDENCE.md` first, before anything else |
+
+---
+
+## Three rules that override your instincts
+
+1. **Analyze before you choose.** A style is a consequence of audience and
+   content density, never of what looks good in isolation.
+2. **The existing brand wins.** Style tokens are *defaults for greenfield work*,
+   not permission to repaint someone's product. See `docs/PRECEDENCE.md`.
+3. **Code review is not visual review.** You have not verified anything until
+   you have looked at a rendered screenshot.
+   `node scripts/screenshot.mjs <url-or-file>` renders all four viewports and
+   fails on mobile overflow — then open the images and actually look.
+
+---
+
+## Machine-readable index
+
+Routing without reading prose: `design-taste.manifest.json` (repo + skill
+version, file map, context profiles) and `styles/index.json` (all 15 styles
+with ids, aliases, paths, scoring weights, incompatibilities).
+
+Next file: **[`SKILL.md`](SKILL.md)**.

AGENTS.md

@@ -0,0 +1,70 @@
+# AGENTS.md
+
+You are in **Agent Design Taste** — a design decision system for AI coding
+agents. Two things you might be here to do:
+
+---
+
+## A · You want to USE this system to design something
+
+Read [`AGENT-BOOTSTRAP.md`](AGENT-BOOTSTRAP.md) first. It is 75 lines and it
+tells you everything: the 10-step workflow, what to load, and what not to.
+
+Short version:
+
+```
+UNDERSTAND → CHOOSE STYLE → TYPOGRAPHY → LAYOUT → TOKENS
+    → BUILD → RENDER → AUDIT → REMOVE SLOP → POLISH
+```
+
+- Answer audience / product / personality / density / action / emotion **in
+  writing** before generating anything.
+- Choose **one** dominant style via [`DECISION-MATRIX.md`](DECISION-MATRIX.md).
+  Load only that style's `README.md` + `tokens.css`. **Never all 15.**
+- Precedence: `brand & legal ▸ accessibility ▸ product needs ▸ style DNA ▸
+  repo tokens ▸ your taste` — [`docs/PRECEDENCE.md`](docs/PRECEDENCE.md).
+- Render at **1440 / 768 / 390** and look at it before claiming it works.
+- Audit with [`ANTI-SLOP.md`](ANTI-SLOP.md) (zero 🔴 blockers) and
+  [`evaluation/DESIGN-TASTE-SCORE.md`](evaluation/DESIGN-TASTE-SCORE.md) (≥ 75).
+
+To install it into a project, see [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).
+
+---
+
+## B · You are working ON this repository
+
+### Layout
+
+```
+AGENT-BOOTSTRAP.md   entry point        SKILL.md            the workflow
+DECISION-MATRIX.md   style scoring      ANTI-SLOP.md        quality gate
+LAYOUT-PATTERNS.md   43 patterns        STYLE-COMBINATIONS.md
+docs/                precedence, context profiles, integrations, templates
+styles/NN-slug/      the 15 style DNAs + tokens + prompts + example
+accessibility/ responsive/ typography/ visual-language/ motion/
+component-patterns/ layout-patterns/ design-tokens/   cross-style foundations
+evaluation/          score, rendered verification, mode routing, taste loop
+adapters/            copy-paste instruction files for each coding agent
+scripts/             gen_tokens.py · gen_manifest.py · validate.py · install.sh
+```
+
+### Rules for changes
+
+1. **`tokens.css` is the source of truth.** `tokens.json` and
+   `tokens.tailwind.css` are generated — never hand-edit them. After changing
+   any `tokens.css`, run `python3 scripts/gen_tokens.py`.
+2. **`styles/index.json` and `design-taste.manifest.json` are generated.** Edit
+   the data in `scripts/gen_manifest.py`, then run it.
+3. **All 15 style READMEs share one 24-section architecture.** Adding or
+   renaming a section means doing it in all 15. See
+   [`docs/STYLE-TEMPLATE.md`](docs/STYLE-TEMPLATE.md).
+4. **Run `python3 scripts/validate.py` before committing.** It is what CI runs.
+5. **Do not make unsupported claims.** No invented citations, no integration
+   mechanisms that were not checked against the tool's own documentation, no
+   statistics without a source.
+6. **Do not rename core directories.** External installations reference these
+   paths by name.
+7. **390px is the canonical mobile viewport** throughout. Do not reintroduce
+   375 or any other number.
+
+Full contribution guide: [`CONTRIBUTING.md`](CONTRIBUTING.md).

ANTI-SLOP.md

@@ -1,54 +1,145 @@
 # Anti AI-Slop Rules
 
-Universal rules that kill generic AI-generated UI. Run this checklist on every
-design before delivery. **Any hit = fix before shipping.**
+Universal rules that kill generic AI-generated UI. Run this before delivery,
+every time.
 
-## The slop patterns
+## Severity
+
+| Level | Meaning | Action |
+|---|---|---|
+| 🔴 **BLOCKER** | Breaks trust, accessibility, or honesty. Not a taste issue. | **Must be zero.** Fix before delivering. No exceptions, no justification. |
+| 🟠 **STRONG SMELL** | The recognizable fingerprint of unconsidered AI output. | Fix, or justify in one line naming the design reason. |
+| 🟡 **MINOR SMELL** | Sloppiness that accumulates. | Fix if cheap; note it if not. |
+
+Three or more STRONG hits means the interface was generated, not designed.
+Return to `SKILL.md` step 1.
+
+---
+
+## 🔴 BLOCKERS
+
+Every one of these is a hard fail. They are not opinions.
+
+- [ ] **Fake statistics.** "99.9% uptime", "10× faster", "Trusted by 50,000+
+      teams" with no real number behind it. Fabricated precision is the fastest
+      way to destroy credibility — and it is a lie you put in someone's product.
+- [ ] **Fake testimonials.** "Sarah J., CEO" with no company, no person, no
+      permission. Same for invented case-study results.
+- [ ] **Fake logo walls.** Real companies' marks on a page they never agreed to.
+- [ ] **Lorem ipsum or placeholder copy shipped as final.** Every heading must
+      be real, specific and benefit-led.
+- [ ] **Body text below 4.5:1 contrast.** Gray-on-gray is not "subtle."
+- [ ] **Horizontal scroll on mobile at 390px.** The layout is broken, not tight.
+- [ ] **Missing or invisible `:focus-visible` on interactive elements.**
+      Keyboard users cannot use the interface at all.
+- [ ] **Animation with no `prefers-reduced-motion` fallback.** A vestibular
+      accessibility failure, not a polish item.
+- [ ] **Touch targets below 44×44px** on a mobile-reachable control.
+- [ ] **Information conveyed by color alone** (error states, chart series,
+      status dots without labels or icons).
+- [ ] **Inconsistent design tokens** — the same semantic role rendered with
+      three different hex values or radii across the page.
+- [ ] **Screenshots of a product that does not exist**, presented as real UI.
+      Mock UI must be labeled as mock.
+
+---
+
+## 🟠 STRONG SMELLS
 
 ### Color & gradient
-- [ ] **No gradient blobs without purpose.** Purple-to-blue mesh gradient behind a hero "because it looks AI-premium" = slop. A gradient must encode meaning (state, depth, brand).
-- [ ] **No default neon purple (#8B5CF6-family) as the primary brand color.** It is the most statistically over-used AI color. If purple is genuinely on-brand, use a specific, chosen shade — not the default Tailwind violet.
-- [ ] **No low-contrast gray-on-gray text.** All body text ≥ 4.5:1 contrast.
-- [ ] **No more than 2 accent colors** on one screen.
+- [ ] **Purple gradient by default.** Purple-to-blue mesh behind a hero because
+      it "looks AI-premium." A gradient must encode something: state, depth,
+      brand. Decoration is not a reason.
+- [ ] **Default neon violet (`#8B5CF6` family) as primary brand color.** The most
+      statistically over-used color in AI output. If purple is genuinely on-brand,
+      choose a specific shade — not the framework default.
+- [ ] **Gradient text on headings** with no semantic purpose.
+- [ ] **More than 2 accent colors** on one screen.
 
 ### Cards & surfaces
-- [ ] **Not every card has the same border-radius.** Uniform 24px radius on everything is a fingerprint of AI output. Radius should vary by hierarchy (or be consistently sharp).
-- [ ] **No more than 2 glass/translucent surfaces per view.** Glassmorphism ≠ 30 frosted cards.
-- [ ] **No floating cards with large soft shadows for no reason.** Shadow = elevation semantics, not decoration.
-- [ ] **No identical 3-column feature card rows.** Vary composition: bento, alternating, editorial split, numbered list.
+- [ ] **Uniform 24px radius on everything.** One radius for every element, from
+      a badge to a full-width section, is a fingerprint. Radius should follow
+      hierarchy — or be consistently sharp.
+- [ ] **Every section wrapped in a card.** When everything is elevated, nothing
+      is. Sections are sections; cards are for grouped, comparable objects.
+- [ ] **More than 2 glass/translucent surfaces per view.** Glassmorphism is not
+      thirty frosted panels.
+- [ ] **Floating cards with large soft shadows for no reason.** Shadow encodes
+      elevation, not "premium."
+- [ ] **Three identical feature cards in a row.** Vary composition: bento,
+      alternating, editorial split, numbered list.
+- [ ] **Meaningless metric cards** — a dashboard-style KPI grid on a marketing
+      page where the numbers are decorative.
+- [ ] **Excessive pills.** Every label, tag, badge and button as a 999px pill.
 
 ### Layout & composition
-- [ ] **Not everything is centered.** Left-aligned layouts with strong ragged-right text are a design decision; universal centering is a default.
-- [ ] **No same hero every time.** Check LAYOUT-PATTERNS.md — rotate split hero, editorial hero, product screenshot hero, etc.
-- [ ] **No dead whitespace rhythm.** Spacing must follow one scale (4/8/12/16/24/32/48/64/96...), not random 18px/37px gaps.
-- [ ] **No fake "app store" 5-column footer** on a product that has 5 links total.
+- [ ] **Everything centered.** Universal centering is a default, not a decision.
+      Left-aligned text with a strong ragged right is a choice.
+- [ ] **The same hero every time.** Rotate patterns — `LAYOUT-PATTERNS.md`.
+- [ ] **Desktop layout merely stacked for mobile.** Responsive means
+      recomposition: different hierarchy, different crop, different nav.
+- [ ] **No content hierarchy** — no obvious first thing to look at.
+- [ ] **Random spacing.** 18px here, 37px there. One scale, everywhere.
+- [ ] **Five-column "app store" footer** on a product with five links total.
 
 ### Typography
-- [ ] **No Inter/Roboto as an unconsidered default.** If a grotesk is right for the style, fine — but it must be a decision from the style DNA.
-- [ ] **No single-size body text everywhere.** Hierarchy needs ≥ 3 distinct type roles per screen.
-- [ ] **No ALL-CAPS paragraphs.** Uppercase is for labels/eyebrows only, never body.
-- [ ] **No fake letter-spacing on serif display faces** (unless the style demands it).
-
-### Content honesty
-- [ ] **No invented fake statistics** ("99.9% uptime", "10x faster", "Trusted by 50,000+ teams") unless real numbers exist. Fake precision reads as slop instantly.
-- [ ] **No random testimonials with stock-photo names.** "Sarah J., CEO" with no company = slop.
-- [ ] **No logo walls of companies that never agreed to it.**
-- [ ] **No lorem ipsum or filler copy.** Every heading should be real, specific, and benefit-led.
+- [ ] **Inter/Roboto as an unconsidered default.** A grotesk can be right — but
+      it must come from the style DNA, not from muscle memory.
+- [ ] **One size for all body text.** Hierarchy needs ≥3 distinct type roles.
+- [ ] **ALL-CAPS paragraphs.** Uppercase is for labels and eyebrows only.
+- [ ] **Generic marketing copy**: "Built for modern teams", "Transform your
+      workflow", "Supercharge your productivity", "The future of X". If the
+      sentence works for any product, it works for none.
 
 ### Icons & imagery
-- [ ] **No mismatched icon families** (mixing filled, outlined, and 3D icons on one screen).
-- [ ] **No random emoji as feature icons** in a professional context.
-- [ ] **No AI-generated abstract 3D shapes floating in the hero** unless the style is explicitly 3D/Spatial.
-- [ ] **No screenshots of a product that doesn't exist** dressed up as "real UI" — label mock UI as such.
+- [ ] **Generic icon grid** — twelve outline icons in a 4×3 grid, each one
+      loosely related to its label, none of them necessary.
+- [ ] **Mismatched icon families** (filled + outlined + 3D on one screen).
+- [ ] **Random emoji as feature icons** in a professional context.
+- [ ] **Abstract 3D blobs floating in the hero** when the style is not 3D/Spatial.
+- [ ] **Stock photography of people pointing at laptops.**
 
 ### Motion
-- [ ] **No animations without reduced-motion fallback** (`prefers-reduced-motion`).
-- [ ] **No 900ms ease transitions on hover.** Hover feedback: 150-250ms.
-- [ ] **No parallax on dense content pages** — motion belongs in heroes and storytelling sections.
+- [ ] **900ms hover transitions.** Reads as lag, not luxury. Hover: 150–250ms.
+- [ ] **Everything floats or pulses infinitely.**
+- [ ] **Parallax on dense content.** Motion belongs to heroes and storytelling.
+- [ ] **Scroll-jacking.** The scrollbar belongs to the reader.
+
+---
+
+## 🟡 MINOR SMELLS
+
+- [ ] Section padding that never varies (every section exactly 96px).
+- [ ] A "most popular" pricing badge with no visual anchoring behind it.
+- [ ] Decorative dividers between every section.
+- [ ] Marquees of logos or words that pause for nobody.
+- [ ] Icon-only buttons without `aria-label`.
+- [ ] Fake letter-spacing on serif display faces.
+- [ ] `border-radius` on images that are already inside a rounded card.
+- [ ] A dark-mode toggle that only inverts the background.
+
+---
+
+## The two questions that catch what checklists miss
+
+1. **"Could this exact page belong to a different product?"** If yes, you built
+   a template, not an interface. Find the one element only *this* product could
+   have shown.
+2. **"What did I remove?"** A design with nothing removed was not edited. Name
+   one element you deleted and why the page is better without it.
+
+---
+
+## Output format
 
-## Scoring the checklist
+```
+ANTI-SLOP AUDIT
+BLOCKERS       0
+STRONG         2 — uniform 20px radius on all surfaces · centered every section
+MINOR          1 — icon-only share button missing aria-label
+FIXED          radius now 4/8/16 by hierarchy · features left-aligned, hero centered
+JUSTIFIED      none
+VERDICT        clear to deliver
+```
 
-- 0 hits → ship.
-- 1-2 hits on decoration patterns → fix and ship.
-- Any hit on fake statistics / fake testimonials / lorem ipsum → mandatory fix, these destroy trust.
-- 3+ hits → the design has not been designed. Return to SKILL.md step 1.
+Any BLOCKER, or any unjustified STRONG hit, means **not clear to deliver**.