diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..df3d64d --- /dev/null +++ b/.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" diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..029a49a --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +screenshots/ +node_modules +node_modules/ +__pycache__/ +.DS_Store diff --git a/AGENT-BOOTSTRAP.md b/AGENT-BOOTSTRAP.md new file mode 100644 index 0000000..0e7a405 --- /dev/null +++ b/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//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 ` 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)**. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e1e23e7 --- /dev/null +++ b/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). diff --git a/ANTI-SLOP.md b/ANTI-SLOP.md index f432e8b..3d0df91 100644 --- a/ANTI-SLOP.md +++ b/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**. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..7b070b1 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,105 @@ +# Changelog + +All notable changes to this project are documented here. The **skill** follows +[semantic versioning](https://semver.org/): the current version is in the +`SKILL.md` frontmatter and in `design-taste.manifest.json`. + +For a skill, "breaking" means: a renamed or moved file that installations +reference, a changed workflow contract, or a removed rule an agent may be +relying on. + +## [2.0.0] — 2026-09-04 + +The onboarding and routing release. The design knowledge was already here; this +release makes it installable, routable and internally consistent. + +### Added +- `AGENT-BOOTSTRAP.md` — a 75-line universal entry point for any agent. +- `docs/PRECEDENCE.md` — the explicit precedence chain + (`brand ▸ accessibility ▸ product ▸ style DNA ▸ tokens ▸ agent taste`) + and the ANALYZE → MAP → ADAPT process for existing design systems. +- `docs/CONTEXT-PROFILES.md` — LIGHT / STANDARD / FULL loading profiles with + measured per-file token costs. +- `docs/INTEGRATIONS.md` — per-agent installation for Claude Code, Codex, + Cursor, Windsurf, GitHub Copilot, Gemini CLI, Lovable and v0, written against + each tool's own documented conventions. +- `docs/EXAMPLE-WORKFLOW.md` — one brief followed end to end, with the actual + context cost at the bottom. +- `docs/STYLE-TEMPLATE.md` — the required structure for a new style. +- `adapters/` — copy-paste instruction files (`AGENTS.md`, `CLAUDE.md`, + `GEMINI.md`, Cursor `.mdc`, Windsurf rule, Copilot instructions). +- `scripts/install.sh` — installs the right adapter into a project. +- `scripts/gen_manifest.py`, `design-taste.manifest.json`, `styles/index.json` — + machine-readable routing: ids, aliases, paths, scoring weights, veto + conditions, incompatible and supporting styles. +- `scripts/validate.py` + GitHub Actions workflow — structural validation of + every style folder, link, generated file and required README section. +- `accessibility/ACCESSIBILITY.md` — accessibility as a quality gate, with a + per-style failure table. +- `responsive/RESPONSIVE-FOUNDATIONS.md` — recomposition, not stacking. +- `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `LICENSE`. +- `README.pl.md` — Polish translation, with a language switch in both files. +- Each style DNA gained: design philosophy, responsive behaviour, style + combinations, a real signature move, and pointers to prompts, tokens and + example. + +### Changed +- **BREAKING — canonical mobile viewport is now 390px** (with 360 as the narrow + floor). The repository previously said `390px first` in one place and `375px` + in another. Anything pinned to 375 should move to 390. +- **BREAKING — `SKILL.md` hard rule 3 rewritten.** "Never invent colors/fonts + outside the chosen tokens" conflicted with "preserve existing brand + colors/fonts". It now reads: *every value resolves to a token; tokens come + from the precedence chain, brand first, style DNA as the greenfield default.* +- **BREAKING — all 15 style READMEs restructured** into one 24-section + architecture. Content preserved; heading names and order changed. Anything + that deep-links to a style README anchor needs updating. +- `DECISION-MATRIX.md` — added 11 brief signals, absolute veto gates, and a + weighted scoring card per style. The agent must now be able to say why the + runner-up loses. +- `ANTI-SLOP.md` — added BLOCKER / STRONG SMELL / MINOR SMELL severity, and + new detections (every section in a card, generic icon grids, meaningless + metric cards, generic marketing copy, desktop stacked onto mobile). +- `evaluation/DESIGN-TASTE-SCORE.md` — 13 weighted categories summing to 100, + with 8 hard blockers that fail a design regardless of total. Accessibility + now carries the highest single weight. +- `LAYOUT-PATTERNS.md` — 43 patterns became a decision library: when to use, + density, fitting and 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, language support, font-loading + performance; per-style image direction; 19 components with a required state + matrix). +- `evaluation/RENDERED-VERIFICATION.md` — explicit protocol, and an honest + fallback for agents without browser access. +- `evaluation/MODE-ROUTING.md` — modes mapped to context profiles; removed an + unverifiable research citation. + +### Fixed +- `scripts/gen_tokens.py` produced invalid Tailwind v4 output: doubled prefixes + (`--color--bg`), a truncated namespace (`--radiu--sm`), and camelCase keys + (`--fontSize--h1`). Now emits correct `--color-*`, `--text-*`, `--radius-*`, + `--shadow-*`, `--ease-*`, `--container-*` namespaces. +- `tokens.json` keys had leading dashes (`"-bg"`). Now clean (`"bg"`). +- 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. +- The README structure diagram omitted `tokens.json` and `tokens.tailwind.css` + and referenced an `assets/decision-tree.png` that does not exist. +- `07-neumorphism` had a duplicated "When NOT to use" section and a vague + citation. + +## [1.1.0] — 2026 + +### Added +- Taste loop, mode routing, the `DESIGN.md` contract, rendered verification, + per-style accessibility notes and design-decision reasoning, live preview + gallery. + +## [1.0.0] — 2026 + +### Added +- Initial release: `SKILL.md`, `DECISION-MATRIX.md`, `ANTI-SLOP.md`, + `LAYOUT-PATTERNS.md`, `STYLE-COMBINATIONS.md`, 15 design styles with tokens, + prompts and working example pages, and the cross-style foundations. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e99ac0b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,13 @@ +@AGENTS.md + +## Claude Code specifics + +- `SKILL.md` at the repository root is a valid Agent Skill. Its frontmatter + (`name`, `description`, `version`) is load-bearing — keep `name` matching the + repository directory name if the skill is installed by symlink. +- Before committing: `python3 scripts/validate.py`. It is what CI runs, and it + catches broken links, missing files, stale generated output and drift in the + 24-section style architecture. +- Generated files — `styles/*/tokens.json`, `styles/*/tokens.tailwind.css`, + `styles/index.json`, `design-taste.manifest.json` — are never hand-edited. + Change the source, then run `scripts/gen_tokens.py` / `scripts/gen_manifest.py`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..378fea8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,155 @@ +# Contributing + +Thanks for wanting to make this better. This repository is knowledge, not code, +so the bar is different: **a change is good if it makes an agent's output +measurably better, and bad if it only makes the documentation longer.** + +--- + +## Before you open a PR + +```bash +python3 scripts/validate.py # what CI runs +node scripts/screenshot.mjs # render all 15 examples, catch overflow +``` + +The first is what CI runs. It checks every style folder, every required file, every +internal link, every generated file's freshness, and the 24-section structure +of the style DNAs. + +--- + +## Principles + +1. **Observable rules only.** Encode guidance as checkable predicates, not + adjectives. + - ✅ "Body text ≥ 16px, contrast ≥ 4.5:1, one `

` per page" + - ❌ "Buttons should feel clear and modern" +2. **Negative constraints do more work than positive ones.** "Not like this" + removes a region of the solution space; "like this" gestures at a point. + Keep the Do lists short and let the Don't lists carry the weight. +3. **Never make an unsupported claim.** No invented citations. No integration + mechanism that has not been checked against the tool's own documentation. + No statistics without a source. If you are not sure, write what you *do* + know and say what is unverified. +4. **Do not flatten individuality.** The 15 styles share a structure, not a + voice. Neumorphism warns about itself; Maximalism does not apologise. That + is correct. +5. **Every addition costs context.** Before adding a paragraph, ask which + context profile pays for it. If the answer is "all of them", it belongs in + `AGENT-BOOTSTRAP.md` and needs to be one line. + +--- + +## Generated files — never edit by hand + +| Generated | Source | Regenerate with | +|---|---|---| +| `styles/*/tokens.json` | `styles/*/tokens.css` | `python3 scripts/gen_tokens.py` | +| `styles/*/tokens.tailwind.css` | `styles/*/tokens.css` | `python3 scripts/gen_tokens.py` | +| `styles/index.json` | data in `scripts/gen_manifest.py` | `python3 scripts/gen_manifest.py` | +| `design-taste.manifest.json` | data in `scripts/gen_manifest.py` | `python3 scripts/gen_manifest.py` | + +CI fails if a generated file is out of date with its source. + +--- + +## Adding style #16 + +Every style folder must contain exactly these six files: + +``` +styles/16-your-style/ +├── README.md the 24-section Design DNA +├── tokens.css canonical tokens (source of truth) +├── tokens.json generated +├── tokens.tailwind.css generated +├── prompts.md ready prompts for Codex / Claude / Lovable / v0 +└── example.html single-file, zero-dependency working page +``` + +### Checklist + +- [ ] Directory named `NN-kebab-case-slug`, with `NN` the next free number. +- [ ] `README.md` follows [`docs/STYLE-TEMPLATE.md`](docs/STYLE-TEMPLATE.md) + exactly — all 24 sections, in order, with the same headings. +- [ ] **§ 15 "When NOT to use" is filled in properly.** A style with no honest + failure mode has not been thought about. This is the section reviewers + read first. +- [ ] **§ 13 Accessibility names this style's specific failure**, not generic + WCAG advice. What does *this* style get wrong that others do not? +- [ ] **§ 20 Signature move is concrete.** "One accent color used only for + actions" is a signature move. "Bold and modern" is not. +- [ ] `tokens.css` defines every required category: colors, fonts, font-sizes, + spacing, radius, shadows, borders, container, motion, motion-ease — + including `--shadow-focus`. +- [ ] Light theme in `:root`, dark theme in `[data-theme="dark"]`. +- [ ] Contrast verified: every text/background pair used together passes + 4.5:1 (body) or 3:1 (large text and UI boundaries). +- [ ] `example.html` opens in a browser with no build step and no network + dependency beyond webfonts, and holds at **1440 / 768 / 390 / 360** — + verify with `node scripts/screenshot.mjs `. +- [ ] Routing data added to `STYLES` in `scripts/gen_manifest.py`: aliases, + density fit, recommended product types, supporting styles, incompatible + styles, veto conditions and scoring weights. +- [ ] `DECISION-MATRIX.md` gains a scoring card, and `STYLE-COMBINATIONS.md` + gains its safe and dangerous pairings. +- [ ] `visual-language/VISUAL-LANGUAGE-FOUNDATIONS.md § 10` gains an image + direction row. +- [ ] `accessibility/ACCESSIBILITY.md § 10` gains a characteristic-failure row. +- [ ] `README.md` and `README.pl.md` style tables gain a row. +- [ ] `python3 scripts/gen_tokens.py && python3 scripts/gen_manifest.py && python3 scripts/validate.py` + all pass. + +### What gets a style rejected + +- It is a variant of an existing style rather than a distinct design language. + (A darker Minimalism is not style #16.) +- "When NOT to use" is empty, hedged, or says "any project where it doesn't fit". +- The tokens cannot pass contrast without abandoning the style's own premise — + unless, like Neumorphism, the entry says so explicitly and scopes itself to + decorative use. +- The example page only works at 1440px. + +--- + +## Changing an existing style + +Style DNAs are referenced by installed agents. Treat them like an API: + +- **Adding** to a section: fine. +- **Changing** a token value: note it in `CHANGELOG.md` — someone has copied it. +- **Renaming or removing** a section: it must happen in all 15, and it is a + breaking change. + +--- + +## Improving the core documents + +`SKILL.md`, `DECISION-MATRIX.md`, `ANTI-SLOP.md` and +`evaluation/DESIGN-TASTE-SCORE.md` are the system's contract. Changes there +need a reason expressed as a failure: *"an agent did X, and the rules allowed +it."* Include the failing case in the PR. + +--- + +## Versioning + +Semantic versioning on the skill version in `SKILL.md` frontmatter and +`design-taste.manifest.json` — keep both in step. + +| Change | Bump | +|---|---| +| New style, new document, new rule | minor | +| Renamed or moved file, changed workflow contract, removed rule | **major** | +| Wording, examples, typos, expanded guidance | patch | + +--- + +## Commit and PR + +- Conventional-ish commit subjects (`feat:`, `fix:`, `docs:`, `style:`) are + appreciated but not enforced. +- Describe **what an agent will do differently** after your change. That is the + only reliable measure here. +- If you changed a style DNA, say whether you re-rendered its `example.html`. diff --git a/DECISION-MATRIX.md b/DECISION-MATRIX.md index 7d1aa4f..0880332 100644 --- a/DECISION-MATRIX.md +++ b/DECISION-MATRIX.md @@ -1,72 +1,217 @@ # Product → Style Decision Engine -Do not pick a style because it "looks cool". Pick it because the product, -audience, and brand personality demand it. Work top-down: +A style is a **consequence**, not a preference. It falls out of who uses the +product, how much information is on screen, and what the user must feel in the +first three seconds. Never choose a style because it looks cool. ``` -Product type → Audience → Brand personality → Content density -→ Emotion → Dominant style → (optional) Supporting style → Visual direction +Product type → Audience → Personality → Density → Trust → Emotion + → veto gates → weighted score → dominant style (+ optional supporting) ``` -## 1. Decision table +Two paths. Take the **fast path** when the brief is unambiguous; take the +**scored path** when two styles are plausible, when a stakeholder will ask +"why," or when the brief pulls in different directions. -| Product type | Audience | Personality | Density | Recommended dominant | Supporting | Avoid | +--- + +## Part 1 — The brief (answer before scoring) + +Eleven signals. Answer them from `SKILL.md` step 1. Anything you cannot answer +is a question for the user, not a blank to fill with a guess. + +| # | Signal | Values | +|---|---|---| +| S1 | **Content density** | low · medium · high | +| S2 | **Audience** | technical · professional · consumer · creative · child/family · mixed-public | +| S3 | **Brand personality** | precise · bold · warm · premium · playful · nostalgic · futuristic · literary | +| S4 | **Trust requirement** | low · medium · **critical** (money, health, legal, identity) | +| S5 | **Accessibility sensitivity** | standard · **elevated** (public sector, health, wide age range, regulated) | +| S6 | **Conversion priority** | browse · consider · convert-now | +| S7 | **Information complexity** | simple · layered · dense-relational (tables, graphs, hierarchies) | +| S8 | **Device context** | desktop-first · mobile-first · mixed | +| S9 | **Session duration** | glance (<1 min) · task (1–10 min) · dwell (daily use, long-form) | +| S10 | **Emotional target** | trust · competence · calm · excitement · status · safety · curiosity | +| S11 | **Existing brand system** | none (greenfield) · partial · complete | + +**S11 = complete or partial short-circuits everything below.** Go to +`docs/PRECEDENCE.md` and run ANALYZE → MAP → ADAPT. You are choosing a style to +*accommodate* an existing system, not to replace it. + +--- + +## Part 2 — Veto gates (run first, they are absolute) + +A veto removes a style from consideration no matter how well it scores. +This is where most bad AI style choices die. + +| Condition | Vetoed styles | Why | +|---|---|---| +| S4 = **critical** (money/health/legal) | Y2K (13) · Maximalism (12) · Neumorphism (07) · Anti-Grid (06) | Visual instability reads as institutional instability | +| S5 = **elevated** | Neumorphism (07) · Glassmorphism (02) as dominant · Maximalism (12) | Soft-shadow and translucent surfaces cannot reliably hold 3:1 non-text contrast | +| S1 = **high** or S7 = **dense-relational** | Neumorphism (07) · Claymorphism (08) · Anti-Grid (06) · Kinetic Type (15) | Each pays a legibility tax per element; density multiplies it | +| S2 = **child/family** | Neo-Brutalism (05) · Anti-Grid (06) · Skeuomorphism (09) | Aggressive or complex surfaces, wrong affordances for the audience | +| S8 = **mobile-first** | 3D/Spatial (14) as dominant · Anti-Grid (06) | Both depend on viewport area and pointer precision | +| S9 = **dwell** (hours per day) | Maximalism (12) · Y2K (13) · Kinetic Type (15) | High-stimulus surfaces exhaust on repeat exposure | + +If vetoes eliminate everything, the brief is contradictory. Say so, name the +contradiction, and propose the trade-off — do not silently pick a survivor. + +--- + +## Part 3 — Scoring cards + +Score every surviving style. Add the modifiers whose condition the brief meets. +Highest total wins; ties go to Part 5. + +**01 · Minimalism** — *the neutral default* +`+3` trust:critical · `+3` personality:premium · `+2` audience:professional +`+2` emotion:calm · `+2` S5 elevated · `+1` density:medium · `+1` mobile-first +`−2` emotion:excitement · `−2` personality:playful · `−3` audience:child/family + +**02 · Glassmorphism** +`+3` personality:futuristic · `+2` audience:technical · `+2` device:desktop-first +`+1` density:medium · `+1` emotion:curiosity +`−2` S5 elevated · `−3` trust:critical · `−3` density:high + +**03 · Liquid Glass** +`+3` audience:consumer · `+3` personality:futuristic · `+2` emotion:excitement +`+2` mobile-first · `+1` session:glance +`−2` density:high · `−3` S7 dense-relational · `−2` trust:critical + +**04 · Bento Grid** +`+3` density:high · `+3` S7 layered · `+2` conversion:consider +`+2` audience:consumer · `+2` personality:precise · `+1` mixed device +`−2` personality:literary · `−2` session:dwell (as a whole-app layout) + +**05 · Neo-Brutalism** +`+3` personality:bold · `+3` emotion:excitement · `+2` audience:creative +`+2` conversion:convert-now · `+1` session:glance +`−2` trust:critical · `−3` audience:child/family · `−2` S5 elevated + +**06 · Brutalist / Anti-Grid** +`+3` audience:creative · `+3` personality:bold · `+2` emotion:curiosity +`+2` density:low · `+1` desktop-first +`−3` density:high · `−3` trust:critical · `−3` S5 elevated · `−2` mobile-first + +**07 · Neumorphism** — *use sparingly, never for critical controls* +`+2` personality:calm/premium · `+1` density:low · `+1` audience:consumer +`−3` S5 elevated · `−3` density:high · `−3` trust:critical · `−2` mobile-first + +**08 · Claymorphism** +`+3` audience:child/family · `+3` personality:playful · `+3` emotion:safety +`+2` audience:consumer · `+1` conversion:browse +`−3` density:high · `−3` audience:technical · `−2` trust:critical + +**09 · Skeuomorphism / Tactile** +`+3` S7 dense-relational *in instrument UI* · `+2` personality:premium +`+2` emotion:competence · `+2` desktop-first · `+1` session:dwell +`−2` mobile-first · `−2` audience:child/family · `−1` conversion:convert-now + +**10 · Swiss / International** +`+3` density:high · `+3` personality:precise · `+3` S7 dense-relational +`+2` audience:technical · `+2` trust:critical · `+2` emotion:competence +`+1` session:dwell +`−2` personality:playful · `−2` emotion:excitement · `−2` audience:child/family + +**11 · Editorial / Magazine** +`+3` personality:literary · `+3` session:dwell · `+3` S7 layered +`+2` personality:premium · `+2` emotion:trust · `+1` conversion:browse +`−2` S7 dense-relational · `−2` conversion:convert-now · `−1` audience:technical + +**12 · Maximalism** +`+3` personality:bold · `+3` emotion:excitement · `+2` audience:creative +`+2` session:glance · `+1` conversion:browse +`−3` trust:critical · `−3` S5 elevated · `−3` session:dwell · `−2` density:high + +**13 · Y2K / Retrofuturism** +`+3` personality:nostalgic · `+3` emotion:excitement · `+2` audience:consumer +`+2` session:glance · `+1` conversion:convert-now +`−3` trust:critical · `−3` audience:professional · `−2` S5 elevated + +**14 · 3D / Spatial UI** +`+3` personality:futuristic · `+3` emotion:curiosity · `+2` audience:creative +`+2` desktop-first · `+1` session:glance +`−3` mobile-first · `−3` density:high · `−2` S5 elevated + +**15 · Expressive / Kinetic Typography** +`+3` audience:creative · `+3` personality:bold · `+2` emotion:curiosity +`+2` density:low · `+2` session:glance +`−3` S7 dense-relational · `−3` S5 elevated · `−2` session:dwell + +--- + +## Part 4 — Fast path (unambiguous briefs) + +Skip scoring when the brief lands cleanly in a row here. This table is a +shortcut through Part 3, not a replacement for the veto gates. + +| Product type | Audience | Personality | Density | Dominant | Supporting | Avoid | |---|---|---|---|---|---|---| | B2B SaaS | managers, teams | trustworthy, clear | medium | Minimalism (01) | Swiss (10) | Maximalism, Y2K | | Dev tool / AI platform | developers | technical, fast, precise | medium-high | Swiss (10) | subtle Brutalism (06) | Claymorphism, pastel gradients | | Fintech / banking | professionals | secure, precise | medium-high | Minimalism (01) | Swiss (10) | Neo-Brutalism, Y2K | | E-commerce (mass) | everyone | friendly, clear | high | Bento Grid (04) | Minimalism (01) | Anti-Grid, Skeuomorphism | | Luxury / fashion | high-income | exclusive, refined | low | Editorial (11) | Minimalism (01) | Neon anything, gradients | -| Agency / studio | creative clients | bold, original | low-medium | Brutalist/Anti-Grid (06) | Kinetic Typography (15) | Neumorphism, Bento | -| Portfolio (designer) | art directors | expressive, memorable | low | Kinetic Typography (15) | Anti-Grid (06) | Dashboard layouts | +| Agency / studio | creative clients | bold, original | low-medium | Anti-Grid (06) | Kinetic Type (15) | Neumorphism, Bento | +| Portfolio (designer) | art directors | expressive, memorable | low | Kinetic Type (15) | Anti-Grid (06) | Dashboard layouts | | Media / magazine | readers | intelligent, literary | high | Editorial (11) | Swiss (10) | Glassmorphism overload | -| Consumer app (social/lifestyle) | 18-35 | modern, fluid | medium | Liquid Glass (03) | Bento (04) | Skeuomorphism (heavy) | +| Consumer app | 18–35 | modern, fluid | medium | Liquid Glass (03) | Bento (04) | Heavy skeuomorphism | | Kids / education | children, parents | playful, safe | medium | Claymorphism (08) | Maximalism (12) | Brutalism, dark modes | -| Web3 / metaverse | early adopters | futuristic, immersive | medium | 3D/Spatial (14) | Glassmorphism (02) | Editorial serif | +| Web3 / immersive | early adopters | futuristic | medium | 3D/Spatial (14) | Glassmorphism (02) | Editorial serif | | Music / events / gaming | fans | loud, nostalgic | high | Y2K (13) | Maximalism (12) | Minimalism | -| Health / wellness | broad | calm, human | low-medium | Minimalism (01) | Claymorphism (08) | Neon, harsh contrast | +| Health / wellness | broad public | calm, human | low-medium | Minimalism (01) | Claymorphism (08) | Neon, harsh contrast | | Restaurant / local biz | locals | appetizing, warm | medium | Editorial (11) | Neo-Brutalism (05) | 3D spatial, dark SaaS | | Corporate / enterprise | executives | serious, stable | high | Swiss (10) | Minimalism (01) | Y2K, Maximalism | +| Developer docs | developers | clear, scannable | high | Swiss (10) | Minimalism (01) | Glass, 3D, Kinetic | +| Data / analytics product | analysts | precise, dense | high | Swiss (10) | Bento (04) | Clay, Neumorphism, Y2K | -## 2. Personality → style shortcuts +--- -- "technical / fast / precise" → Swiss + mono accents -- "bold / rebellious" → Neo-Brutalism or Anti-Grid -- "premium / exclusive" → Editorial with generous whitespace -- "friendly / approachable" → Claymorphism or rounded Bento -- "futuristic / immersive" → Spatial 3D or Liquid Glass -- "nostalgic / fun" → Y2K -- "human / literary" → Editorial -- "organized / structured" → Bento or Swiss +## Part 5 — Tie-breakers, in order -## 3. Content density override +1. **Accessibility.** The style that clears WCAG AA with less effort wins. +2. **Density durability.** The style that survives the product's *next* screen — + the settings page, the empty state, the 40-row table — wins. +3. **Brand accommodation.** If a brand system exists, the style that adopts its + colors and fonts without distortion wins (`docs/PRECEDENCE.md`). +4. **Mobile survivability.** If mobile is >50% of traffic, the style that + recomposes rather than stacks wins. +5. **Still tied → Minimalism (01).** The neutral default. Say that you defaulted + and why nothing else earned it. -- **Low density + few screens** → allow expressive styles (15, 06, 12, 13). -- **High density (dashboards, tables)** → structural styles only (01, 04, 10); - expressiveness goes into micro-interactions, not layout. -- If a client demands an expressive style for a dense product → keep layout - structural, apply the expressive style to hero and marketing pages only. +--- -## 4. Worked example +## Part 6 — Required output -Input: *"AI coding platform for developers"* +Choosing a style produces a **brief**, not a stylesheet. Print it: ``` -Audience: developers -Brand personality: technical / fast / precise -Content density: medium-high -Primary action: start free trial -Recommended style: Swiss (10) + subtle Brutalist accents (06) -Typography: Inter (UI) + JetBrains Mono (code, labels) -Visual direction: real product UI, terminal windows, technical diagrams -Avoid: clay characters, pastel gradients, excessive glass, neon purple -``` +DESIGN BRIEF +Audience developers evaluating a tool in under 90 seconds +Product AI coding platform · dev tool +Personality technical / fast / precise +Density medium-high (S1) · dense-relational (S7) +Trust medium · A11y: standard · Device: desktop-first · Session: task + +Vetoes applied none triggered -Notice: the answer is a **brief**, not a stylesheet. That's the point. +Scores Swiss (10) +3 density-high +3 precise +3 dense-relational + +2 technical +2 competence = 13 + Minimalism (01) +2 professional +1 medium-density = 3 + Bento (04) +3 density-high +2 precise = 5 + Claymorphism (08) −3 technical −3 density-high = −6 -## 5. Tie-breakers +Dominant Swiss / International (10) +Supporting Neo-Brutalism (05) — owns display type weight only +Why not Bento modular tiles imply feature parity; this product has one hero + capability and a long tail, which a numbered list expresses better +Why not Clay friendly softness contradicts an audience that buys on precision + +Typography Archivo (display) + Inter (UI) + JetBrains Mono (code, labels) +Layout Product Screenshot Hero → Numbered Feature List → Comparison Table +Visual real product UI, terminal frames, technical diagrams +Avoid pastel gradients, clay characters, excessive glass, fake stats +``` -1. If two styles score equally → pick the one with better accessibility. -2. If the brand already has colors/fonts → keep them, choose the style that - accommodates them. -3. If still unsure → Minimalism. It is the neutral default that rarely fails. +A brief you cannot defend against its runner-up is a brief you did not write. diff --git a/LAYOUT-PATTERNS.md b/LAYOUT-PATTERNS.md index 7bd994e..97b85fe 100644 --- a/LAYOUT-PATTERNS.md +++ b/LAYOUT-PATTERNS.md @@ -1,71 +1,429 @@ -# Layout Pattern Library - -40+ ways to compose a page. The #1 AI layout problem is not colors — it's -generating the same "centered hero → 3 cards → CTA" every time. Rotate patterns. - -Legend: 🖥 desktop-first · 📱 needs mobile adaptation care - -## Hero patterns - -1. **Split Hero** — text left, visual right (50/50 or 60/40). Best for products with a strong screenshot. 🖥 -2. **Centered Hero** — headline + sub + CTA stacked center. Use when the visual comes below, not beside. 📱 -3. **Editorial Hero** — oversized headline spanning full width, magazine-style dek, image below. For Editorial/Brutalist styles. -4. **Product Screenshot Hero** — real UI floats large above/behind a short headline. For dev tools & SaaS. -5. **Dashboard Hero** — the product's dashboard IS the hero, slightly tilted or in a browser frame. -6. **Full-bleed Visual Hero** — image/video fills viewport, text overlaid at bottom-left. Luxury, hospitality. -7. **Terminal Hero** — a live-looking terminal/REPL typing the product's value. Dev tools. -8. **Typographic Hero** — type is the visual (kinetic, oversized, variable font). Kinetic Typography style. -9. **3D Object Hero** — a hero product/spatial object center stage, orbiting or scroll-reactive. -10. **Video Background Hero** — muted looped video, high-contrast text overlay. Hotels, events. -11. **Split Diagonal Hero** — diagonal divider between text and visual. Energy without chaos. -12. **Card Stack Hero** — key value props as overlapping stacked cards; scroll fans them out. - -## Feature/content patterns - -13. **Bento Feature Grid** — asymmetric modular tiles, one hero tile. Bento style. -14. **Alternating Feature Sections** — text/image zig-zag down the page. -15. **Numbered Feature List** — 01/02/03 vertical list with large numerals. Swiss/Brutalist. -16. **Sticky Storytelling** — left column sticky (headline/visual), right scrolls through steps. -17. **Horizontal Showcase** — horizontal scroll gallery of use cases/products. -18. **Comparison Table Section** — you vs alternatives; honest, specific rows. -19. **Tabbed Use-Cases** — switch between personas/industries, each with its own mini-hero. -20. **Metrics Strip** — one horizontal band of 3-4 real KPIs. (Only with REAL numbers.) -21. **Logo Wall** — customer logos, grayscale, single row or grid. -22. **Case Study Grid** — 2-3 deep case cards with image + result metric. -23. **Magazine Grid** — mixed-size article cards like a newspaper front page. -24. **Annotated Screenshot** — product UI with callout lines to features. -25. **Before/After Slider** — draggable comparison. Very high engagement. -26. **FAQ Accordion (two-column)** — sticky heading left, accordion right. -27. **Integration Marquee** — infinite scrolling logo strip (pause on hover, reduced-motion safe). -28. **Testimonial Masonry** — varied-size quote cards, NOT identical rows. -29. **Video Testimonial Feature** — one strong talking-head clip, not a wall of thumbnails. -30. **Interactive Demo Embed** — the actual product, sandboxed, on the page. -31. **Timeline Section** — company journey / how-it-works horizontally or vertically. -32. **Pricing Toggle Cards** — monthly/annual toggle, recommended plan visually anchored (size/color), never just "most popular" badge sameness. -33. **Pricing Comparison Slider** — drag between tiers; feature list updates. - -## Conversion patterns - -34. **CTA Banner** — full-width band, single message + button, near page end. -35. **Final Split CTA** — last section splits: recap left, big CTA right. -36. **Sticky Mini-CTA** — slim bar appears after 50% scroll. Mobile especially. -37. **Inline CTA in Editorial Flow** — CTA appears mid-article, styled as part of the text flow. -38. **Email Capture with Value Promise** — input + button + one specific benefit line (not "Subscribe to newsletter"). - -## Structural patterns - -39. **Sidebar App Layout** — persistent nav sidebar + content area. Dashboards. -40. **Top-Bar Marketing Layout** — slim sticky navbar, full-width sections. Landing pages. -41. **Overlay Navigation** — fullscreen/panel menu triggered by burger. Editorial/portfolio. -42. **Footer as Sitemap Grid** — organized columns + one human element (real contact, real address). -43. **Breadcrumb + Filter Bar** — for e-commerce/listing pages above the grid. +# Layout Pattern Library — a decision library, not a menu + +43 ways to compose a page. The #1 AI layout failure is not color — it is +generating **centered hero → three cards → CTA → footer** every single time. + +Each pattern carries the information needed to *choose* it: when it works, the +density it wants, which styles it fits, how it recomposes on mobile, where the +CTA goes, and the mistake agents keep making with it. + +**Legend** · `D` density fit · `✓` fits these styles · `✗` fights these styles +· `📱` mobile recomposition · `→` CTA + hierarchy · `⚠` common AI mistake + +Sections are separable — load `§ Hero` and `§ Feature` for a landing page; you +do not need all 43 in context. + +--- + +## § Hero patterns + +### 1 · Split Hero +Text one side, visual the other (50/50 or 60/40). +**Use when** a real screenshot or photograph carries meaning and the value +proposition fits two lines. `D` medium +`✓` Swiss, Minimalism, Bento, Glassmorphism `✗` Anti-Grid, Kinetic Type +`📱` Decide which half leads: if the image *explains*, image first; if it +decorates, text first. Never squeeze 50/50 into two thin columns. +`→` CTA under the sub-headline, left-aligned to the text column. H1 → sub → CTA. +`⚠` A floating browser mockup at 40% scale where no UI text is readable. + +### 2 · Centered Hero +Headline, sub, CTA stacked centre. +**Use when** the visual comes *below* the fold, not beside it — and the message +is short enough to centre without a ragged block. `D` low +`✓` Minimalism, Claymorphism, Y2K `✗` Editorial, Swiss (as a whole page) +`📱` Already vertical; reduce H1 by ~35% and tighten the CTA gap. +`→` One CTA, optionally one ghost secondary. Never three equal buttons. +`⚠` Used by default. If you did not consider a split or editorial hero first, +this is not a choice. + +### 3 · Editorial Hero +Oversized headline across the full width, magazine dek, image below. +**Use when** the words are the product: manifestos, campaigns, publications. +`D` low `✓` Editorial, Brutalist, Kinetic, Maximalism `✗` Dashboards, Bento +`📱` Headline stays oversized (that is the point); the dek drops to 2 lines. +`→` CTA is often a link, not a button. Hierarchy: headline dominates absolutely. +`⚠` Setting the huge headline in the body font at 700 weight and calling it +editorial. + +### 4 · Product Screenshot Hero +Real UI, large, above or behind a short headline. +**Use when** the interface *is* the argument — dev tools, SaaS, design software. +`D` medium `✓` Swiss, Minimalism, Bento, Glass `✗` Claymorphism, Y2K +`📱` Crop to the single most meaningful region at 2× scale. Never shrink the +whole screenshot until nothing is legible. +`→` CTA above the screenshot; the image is proof, not the action. +`⚠` A mocked-up dashboard with invented numbers. That is a 🔴 anti-slop blocker. + +### 5 · Dashboard Hero +The product's dashboard is the hero, slightly tilted or in a browser frame. +**Use when** density itself is the selling point (analytics, observability). +`D` high `✓` Swiss, Bento, Glass `✗` Editorial, Clay +`📱` Replace the full dashboard with one widget, real size, real data. +`→` CTA above; a caption naming what the user is looking at. +`⚠` 3D perspective tilt so aggressive the UI becomes texture. + +### 6 · Full-bleed Visual Hero +Image or video fills the viewport, text overlaid bottom-left. +**Use when** atmosphere sells: hospitality, travel, fashion, food. `D` low +`✓` Editorial, Maximalism, Minimalism `✗` Dev tools, dense SaaS +`📱` Change the crop, not the scale — a 16:9 landscape becomes a 4:5 portrait +focused on the subject. +`→` CTA in the text block. Overlay must be a scrim, not opacity on the text. +`⚠` White text straight onto a bright photo: a contrast blocker every time. +Use a gradient scrim and measure the actual ratio. + +### 7 · Terminal Hero +A live-looking terminal or REPL types the product's value. +**Use when** the audience lives in a terminal. `D` medium +`✓` Swiss, Brutalist, Minimalism `✗` Clay, Liquid Glass +`📱` Reduce to 4–6 lines, monospace at 13–14px minimum, horizontal scroll inside +the terminal frame only — never the page. +`→` CTA is the install command, copyable, with a real copy button. +`⚠` Fake command output that would not actually be produced by that command. + +### 8 · Typographic Hero +Type *is* the visual: oversized, variable, kinetic. +**Use when** the brand is expressive and the page is short. `D` low +`✓` Kinetic Type, Brutalist, Maximalism, Editorial `✗` Fintech, health, enterprise +`📱` Reflow the line breaks deliberately at each breakpoint — never let a +display headline wrap by accident. +`→` CTA must survive the type: a plain, high-contrast button. +`⚠` Animated headline carrying information that exists nowhere else on the page. + +### 9 · 3D Object Hero +A hero object centre stage, orbiting or scroll-reactive. +**Use when** the product is physical, spatial, or genuinely three-dimensional. +`D` low `✓` 3D/Spatial, Glass, Y2K `✗` Editorial, Swiss, dense products +`📱` Ship a static high-quality render. A 3D canvas on mobile costs battery and +usually drops frames. +`→` CTA below the object, never overlapping it. +`⚠` An abstract 3D blob that represents nothing. 🟠 anti-slop. + +### 10 · Video Background Hero +Muted looped video, high-contrast text overlay. +**Use when** motion communicates something a still cannot. `D` low +`✓` Editorial, Maximalism, 3D `✗` Anything data-heavy +`📱` Replace with a poster image. Do not autoplay video on cellular. +`→` Same as full-bleed: scrim behind the text block. +`⚠` No `prefers-reduced-motion` fallback. 🔴 blocker. + +### 11 · Split Diagonal Hero +A diagonal divides text and visual. +**Use when** you want energy without disorder. `D` medium +`✓` Neo-Brutalism, Y2K, Maximalism `✗` Swiss, Minimalism, Editorial +`📱` The diagonal becomes a horizontal band; a diagonal at 390px just clips text. +`→` CTA inside the text field, well clear of the diagonal edge. +`⚠` Text placed under the diagonal so the first and last words are cut off. + +### 12 · Card Stack Hero +Overlapping stacked cards fan out on scroll. +**Use when** you have 3–5 parallel value props of equal weight. `D` medium +`✓` Bento, Glass, Liquid Glass `✗` Editorial, Swiss +`📱` Become a vertical list, not a tiny stack. Fanning needs width. +`→` CTA after the stack resolves. +`⚠` Scroll-driven animation with no reduced-motion static state. 🔴 blocker. + +--- + +## § Feature and content patterns + +### 13 · Bento Feature Grid +Asymmetric modular tiles, one hero tile. +**Use when** the product has one headline capability and several supporting +ones. `D` high `✓` Bento, Glass, Swiss, Neo-Brutalism `✗` Editorial, Anti-Grid +`📱` Ordered stack, **hero tile first**. Never let CSS grid auto-flow decide the +narrative order. +`→` CTA in the hero tile or after the grid, not repeated per tile. +`⚠` Twelve equal tiles. Equal tiles are a table, not a bento. +**a11y** Reading order must match visual order; check DOM order after any +`grid-area` reordering. + +### 14 · Alternating Feature Sections +Text/image zig-zag down the page. +**Use when** there are 3–5 features each needing a sentence and a picture. +`D` medium `✓` Minimalism, Swiss, Editorial, Clay `✗` Anti-Grid +`📱` All become text-then-image. Do **not** preserve the alternation — on mobile +it just looks like inconsistent ordering. +`→` One CTA at the end, not one per section. +`⚠` Six alternating sections. After the third, the rhythm is a lullaby. + +### 15 · Numbered Feature List +01 / 02 / 03 vertical list with large numerals. +**Use when** the features are sequential, or one clearly matters most. +`D` medium-high `✓` Swiss, Brutalist, Editorial, Minimalism `✗` Clay, Y2K +`📱` Numerals shrink but stay dominant; the list stays a list. +`→` CTA after the last item. Hierarchy: numeral → title → description. +`⚠` Numbers styled as decoration with no ordinal meaning. +**a11y** Use `
    `. Do not fake numbering with pseudo-elements on a `
    `. + +### 16 · Sticky Storytelling +Left column sticky, right column scrolls through steps. +**Use when** explaining a process where the visual updates per step. +`D` medium `✓` Swiss, Minimalism, Glass, 3D `✗` Editorial long-form +`📱` Collapse to a linear sequence: visual, then step, repeated. Sticky +positioning at 390px steals the whole viewport. +`→` CTA after the last step. +`⚠` Sticky element taller than the viewport, so it can never fully show. +**a11y** Ensure scroll position is not the *only* way to reach later content. + +### 17 · Horizontal Showcase +Horizontally scrolling gallery. +**Use when** items are peers and the set is browsable, not readable. `D` medium +`✓` Editorial, Maximalism, Bento, Y2K `✗` Swiss (as a primary section) +`📱` Native touch scroll with visible affordance (a peeking next card). +`→` No CTA inside cards; one after the rail. +`⚠` Horizontal scroll with no visual hint that more exists. +**a11y** Keyboard-reachable: arrow keys or focusable items that scroll into view. + +### 18 · Comparison Table +You vs alternatives, honest and specific. +**Use when** the audience is actively comparing. `D` high +`✓` Swiss, Minimalism, Bento `✗` Maximalism, Kinetic +`📱` Do **not** shrink the table. Transform: one card per competitor, or a +sticky first column with horizontal scroll inside the table container. +`→` CTA in your own column, once. +`⚠` Every competitor row marked ✗ and yours ✓. Nobody believes it. +**a11y** Real `` with `
    `; a caption; never a grid of divs. + +### 19 · Tabbed Use-Cases +Switch between personas or industries. +**Use when** one product genuinely serves distinct audiences. `D` medium +`✓` Swiss, Bento, Minimalism `✗` Editorial +`📱` Tabs become a horizontal scroller or a select; content stacks below. +`→` A CTA per tab is legitimate — each persona converts differently. +`⚠` Four tabs whose content differs only in the noun. +**a11y** Full tab pattern: `role="tablist"`, arrow-key navigation, `aria-selected`. + +### 20 · Metrics Strip +One band of 3–4 real KPIs. +**Use when** the numbers are real, sourced, and impressive. `D` low +`✓` Swiss, Minimalism, Bento, Editorial `✗` — +`📱` 2×2 grid, not a single row of tiny numbers. +`→` No CTA. This is proof, not action. +`⚠` Invented numbers. 🔴 blocker. If you do not have real figures, delete +the section — an honest page beats a decorated lie. + +### 21 · Logo Wall +Customer logos, usually grayscale. +**Use when** you have permission and the names mean something to the audience. +`D` low `✓` most styles `✗` Anti-Grid +`📱` Two columns, or a paused marquee. Never eight logos at 40px wide. +`→` None. +`⚠` Logos of companies that never agreed. 🔴 blocker. +**a11y** Real `alt` text with the company name; not `alt="logo"`. + +### 22 · Case Study Grid +2–3 deep cards, image + result. +**Use when** the work is the argument. `D` medium +`✓` Editorial, Swiss, Minimalism, Anti-Grid `✗` Clay +`📱` One per row, full-bleed image, result metric prominent. +`→` CTA per card ("Read the case"), plus one section CTA. +`⚠` Three cards with identical crops and identical made-up percentages. + +### 23 · Magazine Grid +Mixed-size article cards, newspaper-front-page logic. +**Use when** content volume is real and items have genuinely different weight. +`D` high `✓` Editorial, Swiss, Maximalism `✗` Clay, Neumorphism +`📱` Priority-ordered single column. The lead story stays the lead. +`→` None; the cards are the actions. +`⚠` A magazine grid where every item has the same importance — that is a list. + +### 24 · Annotated Screenshot +Product UI with callout lines. +**Use when** the UI needs interpretation. `D` medium +`✓` Swiss, Minimalism, Bento `✗` Maximalism +`📱` Callouts become a numbered list beneath a croppable image. Lines and dots +at 390px are unreadable. +`→` CTA after. +`⚠` Nine callouts. Three to five, maximum. +**a11y** Callout text must exist in the DOM, not only inside the image. + +### 25 · Before / After Slider +Draggable comparison. +**Use when** the change is visual and obvious. `D` low +`✓` most styles `✗` Swiss (rarely earns it) +`📱` Works well; ensure the handle is ≥44px and drag does not fight page scroll. +`→` CTA after. +`⚠` Drag-only with no keyboard control. +**a11y** Back the handle with an `` so it is keyboard-operable. + +### 26 · FAQ Accordion (two-column) +Sticky heading left, accordion right. +**Use when** there are ≥5 real questions people actually ask. `D` medium +`✓` Minimalism, Swiss, Editorial `✗` Maximalism +`📱` Single column, heading above. +`→` A support link, not a purchase CTA. +`⚠` Marketing copy disguised as questions ("Why is X so great?"). +**a11y** `