@damiangilgonzalez/harness 1.3.7

package/skills/tastemaker/references/component-patterns.md

@@ -0,0 +1,148 @@
+# Layout patterns by screen type
+
+Pick the pattern that fits the PRD's actual goal for the screen, not the first one on the list. These are structural starting points — the locked style tokens (palette/type/shape) from `.tastemaker/style-lock.md` determine how they're skinned.
+
+## Show, don't tell — the default that overrides all the patterns below
+
+Before picking any pattern, apply the visual-over-text default from SKILL.md Step 4. The failure mode every layout below can collapse into is "heading + two sentences of prose," repeated down the page. Each pattern has a *show* version that carries the same meaning with a visual and a caption instead of a paragraph — reach for that version first:
+
+| Instead of telling (text) | Show it (visual) |
+|---|---|
+| A feature card: heading + 2-sentence description | A small mockup of the feature's actual UI, with a one-line caption |
+| "Fast / powerful / real-time analytics" | An actual chart or dashboard fragment rendered in the locked palette |
+| "Simple 3-step setup" as a bulleted list | Three side-by-side visual panels, each a screen state, numbered |
+| "See the difference" prose | A literal before/after split or slider |
+| A stat buried in a sentence | A big number + one-word label, as its own tile |
+| "Works with your stack" paragraph | A logo/icon grid of the integrations |
+| "Trusted by teams" claim | The actual logo strip, or a real testimonial with a face |
+| An abstract benefit (calm, focus, security) | The project's `ideagram` illustration for that concept |
+
+The point isn't to delete all copy — a headline, a short subhead, captions, and CTA labels are text doing real work. The point is that the *primary content of each section is something to look at*, and text captions it. A section that's mostly words with a decorative icon on top is the thing to catch and rebuild.
+
+**A chart is not exempt from this table's own requirement — a chart with axis labels but no title or caption is close to meaningless on its own.** Every chart/graph card needs a one-line heading or caption stating what it shows, the same requirement as a mockup ("with a one-line caption") or a stat tile (its label). If the chart sits next to related numbers or claims elsewhere in the section (a stat list, a headline promise), tie them together explicitly — either visually (the chart and the stats share a caption or a connecting element) or in copy (the caption names what the numbers next to it represent) — don't leave a chart and a stat list floating next to each other with no stated connection.
+
+**A label + one-line description + small icon in a bordered box is the *minimum* bar for a feature card — it is not sufficient for a proof or evidence section.** Real output has shown this exact failure: a page's proof/evidence beat (per `references/narrative-arc.md`) built as a handful of small text-in-card clusters floating in mostly-empty background, technically satisfying "this is a card, not a paragraph" while still reading as sparse and unfinished. Proof is the one beat on the page that most needs to *show*, not describe, so it gets a higher floor than a generic feature card:
+
+- A proof/evidence card needs a *real* supporting visual doing the work — an annotated capture of the actual evidence output, a constructed diagram, a real chart with data, a before/after comparison — not a decorative icon standing in for one. If the section has nothing to show but a claim and a small icon, that's a signal the section needs a different archetype (a `P#` archetype built around one real artifact, not a card grid) or a genuine visual to source, not a smaller version of the feature-card pattern.
+- **Check visual surface area, not just visual presence.** A `P#`/`F#` archetype that's inherently light on surface area for the content (three small cards in a wide viewport) needs to either compensate with one larger real visual carrying the section's weight, or be swapped for an archetype with more natural surface area (a `P4` stat strip with a real chart behind it, an `F5` annotated capture) — don't leave the extra space as empty background around undersized cards.
+- This is the proof beat's version of gate 1 (show-don't-tell) and gate 4 (narrative arc) working together: a technically-varied, technically-visual section can still fail in spirit if its one visual element is too small and too generic to carry the argument the beat exists to make.
+
+## Column balance — a default that applies across every two-column pattern below
+
+Two-column sections show up constantly: a pricing headline next to a stack of tier cards, a feature row of short labels next to a headline-and-CTA block, an About page's alternating text/image rows. Their columns are rarely the same natural height — a headline-and-paragraph column commonly runs taller than a short card stack or a handful of labels next to it.
+
+Left alone, the default failure mode is: each column renders at its own natural height, the shorter one stops short, and the section reads unbalanced — a cluster of content near the top with a block of unclaimed space below it. This isn't a padding problem (see `references/style-tokens.md`'s Spacing scale for that); it's a layout decision nothing was making by default.
+
+When a two-column section's columns differ noticeably in natural height, pick one deliberate treatment instead of leaving it to chance:
+
+1. **Vertically center the shorter column** against the taller column's height (`align-items: center` on the row). Best when the shorter column reads fine as a self-contained block wherever it lands — three pricing cards centered next to a tall headline column, rather than pinned to the top with dead space below.
+2. **Add a real filler element that intentionally uses the remaining height.** A stat callout, a short testimonial, a small supporting illustration, a secondary CTA note. This fills the gap with actual content instead of blank space — the "show, don't tell" default above applies here too, so reach for a visual filler over another paragraph.
+3. **Cap the taller column** so both sides land closer to the same length — tighten the headline, shorten the paragraph, or cap the column's max-width/line count. Best when the taller column's extra length is prose creep rather than content that has to be there.
+
+Pick whichever treatment fits the specific section; the failure to catch is leaving the shorter column to trail into empty space by default because nothing decided otherwise.
+
+## Section-to-section separation
+
+For a page with several stacked sections to read as distinct, intentional beats rather than one long scroll of similar-looking blocks, pick **one** separation mechanism for the whole project and apply it consistently at every section boundary — don't decide it per section:
+
+- **Alternating surface tint** (Background/Surface alternating section by section) — a solid default for a content-dense marketing page with many stacked sections; the tint alone marks the boundary without adding a visible line.
+- **Hairline divider** (a 1px border at the section boundary) — fits a project already using hairline borders elsewhere instead of shadows (the semi-brutalist treatment in `references/anti-slop-checklist.md`); mixing a divider into a project that otherwise uses soft shadows reads as inconsistent.
+- **Fixed minimum section padding**, applied regardless of content, with no tint or divider — works when the mood already commits to generous whitespace (an "editorial/generous" project per `references/style-tokens.md`) and additional visual noise would undercut that. This is the mechanism real, well-separated landing pages reach for most often, and it only works if the padding itself is actually generous — see `references/style-tokens.md`'s Section-level padding section for the weight-tiered range (`space-16` through `space-48`) this depends on. Fixed padding at a cramped value (everything capped near `space-16`) doesn't separate anything; it just looks like a page that forgot to add a divider.
+
+Record the chosen mechanism once in `.tastemaker/style-lock.md` the same way other per-project decisions are recorded, and reuse it — a page that alternates tint on some boundaries and adds dividers on others reads as unplanned, the same failure mode inconsistent spacing produces.
+
+## Landing / marketing page
+
+For a marketing page, the whole-page *shape* is now picked upstream at Step 2.5 as a named macrostructure (`references/macrostructures.md`) and filled with named archetypes (`references/component-catalog.md`) — that's the layer that makes two landing pages structurally different instead of two color-swaps of one template. This section stays useful as the finer-grained guidance *inside* whatever macrostructure you picked: the fold discipline, the show-don't-tell conversions, the common failures. Read it alongside the macrostructure, not instead of it. The three bullets below are lightweight shape hints; the macrostructure catalog is the real menu.
+
+- **Hero-centric**: one sharp promise + one short explanation + one primary CTA (optionally one secondary) + one supporting visual. This is the default for most products. Read `references/hero-guidelines.md` before building it; the hero is an attention hierarchy, not a compressed feature tour.
+- **Social-proof-first**: logos/testimonials above the fold, hero secondary. Use when credibility is the biggest conversion blocker (enterprise, higher price point).
+- **Problem/solution narrative**: scroll-driven sections walking through a pain point then the fix. Use for products solving a non-obvious problem that needs explaining before the pitch lands.
+- **Default fold boundary**: keep workflow steps, metrics, integration grids, detailed proof, and secondary product states below the hero. If the pitch needs them to make sense, simplify the pitch rather than attaching more modules above the fold.
+- **Give each section room to be its own moment, not just a stop on the way to the next one.** Cramped section rhythm (every section padded to the same tight value, sections blurring into one long scroll) is as recognizable a tell as the generic template — a real, checkable failure, not a vague "needs more polish" feeling. See `references/style-tokens.md`'s Section-level padding section for the weight-tiered range (a pivotal section deserves `space-32`–`space-48`, not the same padding as a connective one) and the target boundary gap (~120–250px on desktop) between adjacent sections.
+- Common failure: stacking 6+ generic feature cards with icon + heading + one line, identical structure repeated — the text-wall tell. Apply the show-don't-tell table above: convert feature cards into feature *mockups*, vary rhythm (a full-width visual, an alternating two-column showing the feature in use, a comparison table, a real chart) so the page is a sequence of things to look at, not a stack of paragraphs.
+
+## App shell (dashboards, internal tools, anything behind a sidebar)
+
+This is a first-class pattern, not a footnote under "Dashboard." A meaningful share of what gets built with a coding agent is internal tooling, not a marketing site, and it has a genuinely different shape: a persistent navigation frame the user works *inside*, not a page they scroll through once. Don't reach for `references/hero-guidelines.md` here — there is no hero, the shell is the whole first impression, every session.
+
+### The shape
+
+The default shell for anything with more than a handful of screens is sidebar plus topbar, content in between:
+
+```
+┌─────────┬──────────────────────────────┐
+│         │  topbar: breadcrumb / search / account   │
+│ sidebar │──────────────────────────────│
+│  nav    │                              │
+│         │        content area          │
+│         │   (the one thing this        │
+│         │    screen is actually for)   │
+└─────────┴──────────────────────────────┘
+```
+
+- **Sidebar**: primary navigation, persistent across every screen. Sections/groups if the product has more than ~7 top-level destinations; a flat list otherwise. Collapsible to icon-only on narrow viewports, not hidden entirely — internal tool users live in this thing for hours, don't make them reopen it constantly.
+- **Topbar**: contextual, not navigational. Breadcrumb or current-section label, search, account/notifications. It should never duplicate what the sidebar already tells the user.
+- **Content area**: exactly one job per screen. See the existing dashboard guidance below for how to lead with it.
+
+### Map the locked palette onto persistent chrome, not just one-off sections
+
+A marketing page skins each section once. A shell skins the *frame* once and reuses it on every screen, so get this mapping right at Step 2, record it in `.tastemaker/style-lock.md`, and don't re-derive it per screen:
+
+- **Sidebar background**: usually `Surface`, one step off `Background`, so the content area reads as the "canvas" and the sidebar reads as structural chrome around it. In a dark-mode-native project (e.g. the Technical/builder mood), this can invert — a near-black sidebar against a very slightly lighter content area — either direction is fine as long as it's deliberate and consistent.
+- **Content area background**: `Background`. This is where the user's actual work/data lives; it should be the quietest surface in the shell.
+- **Topbar**: usually shares the content area's `Background` with a `Border` hairline underneath, not its own distinct fill — it's contextual chrome, not a second nav surface competing with the sidebar.
+- **Active nav item**: the one place `Primary` earns a dedicated treatment outside a button — a filled pill/row, or a `Primary`-colored left-border accent on an otherwise-transparent row. Pick one treatment and use it for every active state in the shell, not a different one per section.
+- **Hover state on inactive nav items**: a subtle `Surface`-on-`Surface` shift (or `Background`-on-`Surface`, whichever is lighter in context) — never the same visual weight as the active state, or users lose track of where they actually are.
+- **Breadcrumbs**: `Text muted` for all but the current segment, which gets `Text primary`. Don't spend `Primary` or `Accent` on breadcrumb links; they're wayfinding, not calls to action.
+
+Run every pairing this introduces (active-row text on its fill, hover-state text on its background) through `scripts/check_contrast.py --matrix` the same as any other new pairing — Step 4's color-contract non-negotiable applies to shell chrome exactly like it applies to a marketing hero.
+
+### Density is correct here, not a mistake to fix
+
+A "premium/confident" marketing page wants generous whitespace. An app shell showing the same mood should still be *denser* than its own marketing page — more rows visible without scrolling, tighter row height, smaller default type size in data-heavy areas. This is not a contradiction of the locked mood; it is what that mood looks like applied to a tool instead of a pitch. Don't inherit the marketing page's spacing scale wholesale into the shell; use `references/style-tokens.md`'s "dense/information-heavy" spacing guidance instead, per project.
+
+### Motion in the shell
+
+Covered in full in `references/animation-guidelines.md`'s "App shell motion" section — panel/tab-switch transitions, staggered list/table entrances on data-load, animated state changes, skeleton loading. The scroll-storytelling track from that same file does not apply to a shell; there is no scroll narrative to tell.
+
+### The screen content itself
+
+Once the shell and its chrome are locked, individual screens follow:
+- Lead with the one number/status the user opens the app to check — don't bury it below navigation chrome.
+- Group related metrics; don't scatter unrelated KPIs in one uniform grid just because a grid is easy to build.
+- Empty and loading states matter as much as the populated state — design them explicitly, don't leave them as an afterthought default.
+- Build the action path: what the user checks, what they can change, what happens after the change, and how they recover from a mistake.
+- Provide keyboard focus, hover, pressed, disabled, loading, empty, error, and success states for every primary control.
+
+## Data table / collection view
+- Put filtering, sorting, bulk actions, and visible selection state in the first pass.
+- Avoid bare grids of identical cards when the job is comparison. Tables, compact rows, and split views can be more humane than cards.
+- Show empty, no-results, and error states separately. "No data" and "your filter hid everything" are different messages.
+- If rows can exceed a few hundred, use virtualization. If columns matter, preserve header context with sticky headers or a summary rail.
+- Do not animate rows during normal scanning. Animate row insert/remove only when the list changes occasionally and the motion clarifies what changed.
+
+## Pricing
+- 3 tiers is the safe default (2 feels thin, 4+ causes decision paralysis) unless the product genuinely needs more.
+- Highlight one tier visually (border, subtle background shift) — don't rely on a "Most Popular" ribbon alone to do that work.
+- Put the annual/monthly toggle and the actual price close together; don't make users hunt for what a plan costs.
+- If the section pairs a headline column with the tier cards side by side, that's the Column balance case above — a headline column running the full section height next to cards clustered near the top is the concrete failure that rule exists to catch. Center the cards against the headline's height, or add a real element (a short FAQ note, a guarantee callout) below them rather than leaving the gap.
+
+## Onboarding
+- Map directly to the PRD's step list — don't invent extra steps or collapse necessary ones for the sake of a "clean 3-step flow" if the product actually needs 5.
+- Show progress (steps remaining, not just a generic spinner) — abandonment correlates with uncertainty about how much is left.
+- First-run empty states should teach by example (a pre-filled sample, not a blank field with placeholder text) wherever the product allows it.
+
+## Empty states
+- Explain what will appear here and how to make it appear (one clear action), not just "No data yet."
+- This is a legitimate place for the project's anchor illustration/asset — empty states are low-stakes, high-visibility real estate for personality.
+
+## About / company / mission page
+- Structure that reads as intentional rather than a template dump: hero statement → a small row of illustrated concept icons (not literal feature icons) → credibility stats → logo strip (social proof) → a values grid (2x2 or 3-column, icon + heading + one line) → team grid → physical presence (real office photography, not illustration).
+- **This is the page type most likely to mix asset kinds on purpose**: illustrations for abstract concepts (mission, values, team personality) but real photography for anything claiming physical/factual presence (offices, sometimes real team headshots instead of illustrated avatars). Don't illustrate everything by default — ask which sections are meant to feel "real" (offices, actual team photos) vs. "conceptual" (mission, values) before generating assets, since guessing wrong here is a common way this page type ends up feeling like a template.
+- Stats and logo-strip rows work best restrained — 3-4 stats, 5-6 logos, plenty of whitespace. Cramming more in reads as filler rather than credibility.
+
+## Settings / forms
+- Group by relatedness, not alphabetically or by database schema order.
+- Destructive actions (delete account, remove data) visually separated and never styled identically to safe actions.
+- Save state should be obvious (either autosave with a clear confirmation, or an explicit save action that's unambiguous about what it commits).

package/skills/tastemaker/references/component-sourcing.md

@@ -0,0 +1,150 @@
+# Component sourcing — Tastemaker as director, not fabricator
+
+Tastemaker's job is **art direction and coherence**, not reinventing a date picker. Hand-rolling a bento grid, a pricing table, an animated accordion, or a chart from scratch reliably produces something that works but looks half-finished — the exact "AI-built" tell this skill exists to kill.
+
+There is a large ecosystem of production-grade, free, copy-pasteable components. **Use them.** Then spend the design effort on what only a director can do: choosing which parts, enforcing one visual system across them, and cutting what doesn't serve the page.
+
+Read this file at Step 1.5, alongside `references/library-selection.md`. That file covers **behavioral primitives** (dialogs, toasts, drag, virtualization — things that are hard to get *right*). This file covers **visual components and blocks** (heroes, pricing tables, bento grids, charts, marketing sections — things that are hard to make *look finished*). They are complementary; read both.
+
+---
+
+## Step 0 — Detect the stack first. Everything below depends on it.
+
+**This is not optional and it is the most common way this step goes wrong.** Most registries below are React + Tailwind + shadcn/ui. If the target project is static HTML/CSS, a Rails app, SwiftUI, or anything else, `npx shadcn add …` is meaningless and running it (or telling the user to) is a real failure, not a small mismatch.
+
+Check, in this order:
+
+1. `package.json` — is React present? Next.js? Tailwind? What version of Tailwind (v3 vs v4 matters for several registries below)?
+2. `components.json` — does shadcn/ui already exist in this project? If yes, its `registries` field is where new namespaces get added.
+3. The actual files — `.tsx`/`.jsx` vs `.html`. Existing component conventions.
+
+Then branch:
+
+| Stack detected | What applies |
+|---|---|
+| **React + Tailwind + shadcn** | Everything in this file. Full registry access. This is the happy path. |
+| **React + Tailwind, no shadcn** | Run `npx shadcn@latest init` first (it's additive, not a framework lock-in), then full access. Confirm with the user before adding it to an established repo. |
+| **React, no Tailwind** | Registries below mostly won't drop in cleanly (they ship Tailwind classes). Port the *pattern* by reading the component source, not the file. Motion still applies fully. |
+| **Static HTML / CSS (no build step)** | **Registries do not apply.** Do not emit `npx shadcn add` commands. What still applies: Motion via CDN, the interface-quality rules, and reading registry components as *reference* for visual treatment you then write in plain CSS. Say plainly that you're porting a pattern rather than installing a component. |
+| **Vue / Svelte / React Native** | shadcn-ui-mcp-server supports these (`--framework svelte\|vue\|react-native`). The Tailwind-based registries generally do not. |
+| **SwiftUI / Flutter / native** | None of the registries apply. Direction, motion principles, and interface rules still do. |
+
+**Never emit an install command for a stack that can't consume it.** If the project is static HTML and a bento layout is needed, write the CSS grid yourself — informed by how the good registries structure theirs — and say that's what happened.
+
+---
+
+## The registry map (verified, with exact commands)
+
+All of these were checked directly, not recalled. Free/open-source unless marked.
+
+### shadcn-compatible registries (React + Tailwind)
+
+These install real component source into the project (copy-in, not a dependency you can't edit). That's the point: you own and can restyle the code to match the project's locked palette.
+
+| Registry | Namespace / URL | Best for | Notes |
+|---|---|---|---|
+| **shadcn/ui** (the base) | `npx shadcn@latest add <name>` | The foundation layer: button, input, dialog, table, form, sidebar, chart. Also official **blocks** (dashboards, login, sidebar layouts). | Set this up first. Everything else layers on top. |
+| **Watermelon UI** | `@watermelon` → `https://registry.watermelon.sh/r/{name}.json`<br>`npx shadcn@latest add @watermelon/<name>` | 260+ components **and full blocks** — dashboards, login forms, page sections. Broadest single source. | Open source. Categories: inputs, data display, feedback, navigation, layout, charts (Recharts), blocks. **Note the `/r/` path** — Watermelon's own docs print the URL without it, which returns the site's HTML instead of JSON and fails with `Unexpected token '<'`. Verified working path is `/r/{name}.json`. |
+| **KokonutUI** | `@kokonutui` → `https://kokonutui.com/r/{name}.json`<br>`npx shadcn@latest add @kokonutui/<name>` | Higher-polish, more *designed* components — the ones with real motion and visual character (e.g. `particle-button`). | **Tailwind v4** + lucide-icons. Verify the project's Tailwind major version before pulling. Utils: `https://kokonutui.com/r/utils.json`. |
+| **bklit UI** | `@bklit` → `https://ui.bklit.com/r/{name}.json`<br>`npx shadcn@latest add @bklit/<name>` | **Charts, specifically.** 17+ types: area, bar, line, pie, scatter, candlestick, sankey, heatmap. Plus legends, grids, tooltips, axes, brushes. | Free/open source. Reach for this over hand-rolling any chart. Some components auto-pull `@bklit/shimmering-text`. |
+
+To register a namespace once in an existing project, add to `components.json`:
+
+```json
+{
+  "registries": {
+    "@kokonutui": "https://kokonutui.com/r/{name}.json",
+    "@bklit": "https://ui.bklit.com/r/{name}.json",
+    "@watermelon": "https://registry.watermelon.sh/r/{name}.json"
+  }
+}
+```
+
+Two things that bite in practice, both hit while wiring this up for real:
+
+- **`shadcn init` overwrites the palette.** It writes its own neutral oklch defaults into the CSS token block, silently replacing a locked palette that was already there. Re-apply the lock's values *after* init, not before — and keep the `--chart-*` and `--sidebar-*` token names it adds, since pulled components reference them. Point them at the locked palette so charts and sidebars land on-brand without per-component overrides.
+- **Some registry items prompt interactively** (`utils.ts already exists, overwrite?`). In a non-interactive agent context that hangs. Pass `--yes`, and pipe `y` when a component legitimately needs to overwrite a shared file.
+
+### MCP servers (live component search/retrieval, if configured)
+
+These give the agent *searchable* access rather than a fixed catalog. Check whether they're actually connected in the current session before planning around them — if they aren't, fall back to the registry URLs above, which need no setup beyond the shadcn CLI.
+
+| Server | Install | What it gives |
+|---|---|---|
+| **shadcn-ui-mcp-server** | `npx @jpisnice/shadcn-ui-mcp-server` (optionally `--github-api-key <token>`, `--framework svelte\|vue\|react-native`) | Source, demos, blocks, and metadata for shadcn/ui v4. Rate limit is 60 req/hr without a GitHub token, 5,000 with one (token needs no scopes). |
+| **21st.dev** (`magic-mcp` → now `21st`) | `npx @21st-dev/cli@latest init --client <cursor\|claude-code\|windsurf>`, or HTTP MCP at `https://21st.dev/api/mcp` with an `x-api-key` header | Search 10,000+ React/Tailwind components; tools: `generate`, `get_inspiration`, `search_logo`. | **Requires an API key from 21st.dev/mcp** (old Magic keys are dead). Treat as optional — never make a build depend on it. `search_logo` is genuinely useful alongside `references/logo-sourcing.md`. |
+
+### Motion — the animation engine for *components*
+
+`motion` (motion.dev, formerly Framer Motion) — verified install and usage:
+
+```bash
+npm install motion
+```
+
+Vanilla JS with **no build step** (this is the important one — it means Motion works on static HTML sites too, where the registries above don't):
+
+```html
+<script type="module">
+  import { animate, scroll, inView, stagger } from "https://cdn.jsdelivr.net/npm/motion@12/+esm"
+</script>
+```
+
+Pin a major version rather than `@latest` in anything shipped — the docs say this explicitly.
+
+Real API, verified:
+
+```js
+animate(".box", { rotate: 360 }, { ease: "circInOut", duration: 1.2 })
+animate(el, { rotate: 90 }, { type: "spring", stiffness: 300 })
+animate("li", { y: 0, opacity: 1 }, { delay: stagger(0.1) })
+
+inView("section", () => { animate("section", { opacity: [0, 1] }) })
+
+// scroll-linked (scrubbed): pass an animation into scroll()
+const a = animate("div", { transform: ["none", "rotate(90deg)"] }, { ease: "linear" })
+scroll(a, { target: document.getElementById("item"), offset: ["start end", "end start"] })
+```
+
+**Motion does not replace GSAP as this skill's default** (see `references/animation-guidelines.md` — GSAP + ScrollTrigger stays the default engine, with a real tested investment behind it). Use Motion when:
+- The project is **React** and components need springs, layout animation, exit animation, or gesture values (this is already `library-selection.md`'s standing recommendation).
+- A pulled component **already ships with Motion** as its animation dependency — don't rip it out to re-do it in GSAP. Let the component keep its own engine and match its timing to the project's locked motion values instead.
+
+Never load both GSAP and Motion just to get one effect. One engine per project unless a pulled component forces the second, and if it does, say so.
+
+### Not agent-consumable (documented so it isn't attempted)
+
+- **GrayBlocks** (grayblocks.net) — 5,600+ blocks, but it is **Figma / Framer / Webflow only, and paid**. Its delivery model is one-click copy *inside those design tools*; there is no npm package, registry URL, or API a coding agent can pull from. It's a genuine resource **for the user working in Figma/Framer**, and worth recommending to them for that. It is not something this skill can install. Don't imply otherwise.
+
+---
+
+## Precedence — what to reach for, in order
+
+1. **What's already in the repo.** A healthy existing component beats a new dependency every time. Extend it.
+2. **shadcn/ui base** for foundational primitives.
+3. **Watermelon** for breadth, including whole blocks/sections.
+4. **KokonutUI** for a component that needs visual character and motion out of the box.
+5. **bklit** for anything chart-shaped. Always. Hand-rolled charts are a reliable slop tell.
+6. **MCP search** (shadcn-ui-mcp / 21st) when you need to *discover* rather than pick from the known list.
+7. **Hand-roll** only when: the stack can't consume any of the above, the interaction is genuinely simple (a static section, a plain card), or the project forbids dependencies.
+
+---
+
+## The director's actual job — the part that matters most
+
+**Pulling six components from six registries and stacking them produces worse slop than hand-rolling.** Mixed radii, three icon families, four shadow depths, competing motion feels, five type scales. It reads as assembled, because it was.
+
+Sourcing is the cheap part. These are the rules that make it design work:
+
+1. **Restyle every pulled component to the locked palette and tokens.** Registry components ship with their own defaults (`bg-zinc-900`, `rounded-xl`, their own shadows). Rewrite those to `.tastemaker/style-lock.md`'s tokens as part of the same pass. A pulled component still carrying its origin registry's colors is an unfinished component, and it's visible instantly. This is non-negotiable and it's where most of the work goes.
+2. **One icon family across the whole project.** shadcn and KokonutUI both lean lucide; if the project's mood-matched set from `scripts/fetch_icons.py` is different, pick one and convert. Never ship two icon families — `anti-slop-checklist.md` gates this.
+3. **One radius scale, one shadow scale, one spacing scale.** Take them from the lock, not from whichever component happened to arrive first.
+4. **One motion feel.** Match every pulled component's durations/easings to the lock's Motion section. A component that springs at 300 stiffness next to one that eases at 200ms linear reads as broken.
+5. **Delete what the page doesn't need.** A registry block often ships with a stat row, a logo wall, and a testimonial slot. If the brief has no real numbers and no real testimonials, **cut those slots** — do not fill them with invented content. That's `anti-slop-checklist.md` item 47 (no invented metrics) and it's the most common way pulled blocks introduce fabrication.
+6. **Structure still comes from Step 2.5.** Registries supply parts; the macrostructure, narrative arc, and rotation decisions in `references/macrostructures.md` / `references/narrative-arc.md` still govern the page shape. Don't let a block's built-in section order silently become the page's architecture.
+
+## Honesty requirement
+
+Say what was pulled and from where — in the handoff, and where it matters, in a code comment. "Pricing table from Watermelon, restyled to the locked palette; chart from bklit" is useful, verifiable information for whoever maintains this next. Implying that pulled components were designed from scratch is the same failure as implying a fallback asset was custom-generated (SKILL.md's honesty rule).
+
+Also state it plainly when a registry **didn't** apply — a static-HTML project where you ported a pattern by hand should say that, not quietly present it as a library install.

package/skills/tastemaker/references/diversification.md

@@ -0,0 +1,68 @@
+# Diversification engine — enforced structural variety across builds
+
+Picking a named macrostructure and named archetypes (per `references/macrostructures.md` and `references/component-catalog.md`) only produces variety if the picks actually *change* build to build. Left to instinct, the model reaches for the same default shape every time — the generic hero → 3-feature-cards → CTA → footer — because that's the on-distribution attractor. This file is the mechanism that forces the pick to differ: a small project-memory file, a rotation rule, and a build stamp the next run reads.
+
+**What this axis does and doesn't cover.** tastemaker already prevents *color* monoculture at the source: `scripts/generate_palette.py` produces a fresh, contrast-verified palette per project, so two projects never share a palette by construction. This engine is the complement — it prevents *structural* monoculture. Both axes moving together is what makes two tastemaker sites feel like different sites rather than two color-swaps of one template. (This is also why tastemaker doesn't need a Hallmark-style multi-axis *theme* rotation: our color axis varies by generation, so diversification here is purely structural.)
+
+## The memory file — `.tastemaker/log.json`
+
+Lives alongside `.tastemaker/style-lock.md` in the project root. A JSON array, newest entry first, one entry per build:
+
+```json
+[
+  { "date": "2026-07-23", "page": "landing", "macrostructure": "Feature Stack", "nav": "N2", "hero": "H2", "footer": "Ft1", "knobs": "hero=split/left-bias/mockup; features=F1/irregular", "brief": "Tracejam · SaaS observability" },
+  { "date": "2026-07-20", "page": "landing", "macrostructure": "Editorial Index", "nav": "N4", "hero": "H1", "footer": "Ft4", "knobs": "hero=statement/xxl/centered", "brief": "Meridian · design studio" }
+]
+```
+
+- **Read it before picking** the macrostructure or any archetype (this is part of Step 0's memory check).
+- **Append a new entry at the front** after each build, in the same pass that writes the CSS stamp.
+- **Trim to the last ~20 entries.** Create `.tastemaker/` and the file if absent; respect the project's `.gitignore` (the user may or may not want it committed).
+- If a build's CSS carries a stamp but there's no `log.json`, infer one entry from the stamp and proceed.
+
+## The rotation rule (mandatory)
+
+Using the **last 3-5 entries**:
+
+1. **Macrostructure** must differ from the last build's (and ideally from all of the last three). Marketing pages only — an App shell page is governed by `component-patterns.md`'s App shell section and doesn't rotate against marketing macrostructures.
+2. **Nav archetype** and **footer archetype** must each differ from the last build's. These are the single most-violated rule in practice: the failure mode is reaching for the mood's *default* nav/footer on every build, so four builds ship two navs. A mood with four builds should show four different navs — rotate deliberately through the "also OK" column in the catalog's routing tables.
+3. **Hero archetype** must differ from the last build's.
+4. **If you must reuse an archetype** (small catalog, genuine best-fit), change **at least one variation knob** — two heroes built `split/left-bias/mockup` are the same hero. State the knob delta.
+
+**Palette is exempt** — it's regenerated per project and already differs by construction; don't try to "rotate" it.
+
+## State the rotation out loud (the accountability step)
+
+Before writing any code, say the rotation in plain text — picking on the page, not in your head, is what actually breaks the default-attractor. Format:
+
+> *"Last 3 builds: Feature Stack (Tracejam) · Editorial Index (Meridian) · Bento Showcase (Cobalt). Picking from {Long-Scroll Narrative, Stat-Led, Gallery Grid, Product Demo} — going with Long-Scroll Narrative; the brief is a non-obvious product that needs explaining.*
+> *Nav: last was N2, this build N3 floating pill. Footer: last was Ft1, this build Ft4 statement. Hero: last was H2, this build H6 letter."*
+
+Three shapes to imitate:
+
+- **First build** (no `log.json`): no rotation block — just the pick. *"First build for this project. Picking Feature Stack — fits the observability brief."*
+- **Mature project** (5+ entries): the full frequency-count + exclusion + pick block above.
+- **User asked for the same shape again** (*"use the same layout"*): honor it, but change knobs. *"You asked for Feature Stack again — same shape, different fingerprint: features go F2 bento this time (was F1 bands), hero right-bias (was left)."*
+
+## The build stamp
+
+The first non-empty line of the built CSS (or the top of an inline `<style>`) records what was chosen, so the next run can read and rotate against it:
+
+```css
+/* tastemaker · macrostructure: Long-Scroll Narrative · mood: warm · page: landing
+ * arc: hook(H6) -> problem(prose) -> solution(F1) -> how(F4) -> proof(P4) -> close(C2)
+ * nav: N3 · hero: H6 · footer: Ft4 · knobs: hero=letter/1-para/typed-signoff
+ * palette: seed 4 (warm/light) · contrast: pass (matrix)
+ * critique: ShowTell 5 · Phil 4 · Hier 5 · Spec 4 · Restr 5 · Var 5 */
+```
+
+The stamp is the durable record. It carries the structural picks (for diversification), the narrative arc's beat sequence (see `references/narrative-arc.md` — so a later `audit` pass can check the arc held together, not just that structure varied), the mood + palette seed (so the exact palette is reproducible), the contrast result (so a later run knows the color contract was actually verified, not assumed), and the pre-emit self-critique scores (see `references/anti-slop-checklist.md`). Keep it in sync with the `log.json` entry — they record the same build from two angles.
+
+## Recording in the style lock
+
+`.tastemaker/style-lock.md` gets a **Structure** section (see `references/style-lock-format.md`) recording the macrostructure and archetype family this project's pages use. Note the intent difference from the log:
+
+- **Across projects** — structure *varies* (that's this engine; the log enforces it).
+- **Within one project** — structure stays *coherent*: a multi-page site should feel like one site, so its pages share a nav/footer/type system even as each page's body can use a different macrostructure. The style lock records the shared frame; the log records what each build did so builds don't repeat.
+
+Don't over-rotate inside a single project to the point that its own pages feel unrelated — the rotation rule is about not repeating *the same page build*, not about making every page of one site look foreign to the others.

package/skills/tastemaker/references/hero-guidelines.md

@@ -0,0 +1,108 @@
+# Clean hero guidelines
+
+Use this reference whenever building or revising the first viewport of a landing page, marketing site, or public front door for an application. The goal is not minimalism for its own sake. The goal is a decisive attention hierarchy: the visitor should understand the product before noticing the composition.
+
+## Start with the five-second answer
+
+Before writing markup, complete this sentence in plain language:
+
+> This product helps [specific user] achieve [valuable outcome] by [distinct mechanism].
+
+Turn the valuable outcome into the headline. Let the subhead clarify the mechanism. If the hero needs a workflow diagram, four metrics, or a paragraph to explain the product, the message is not yet sharp enough.
+
+## Default attention budget
+
+Treat this as the starting limit, not a quota to fill:
+
+- One optional eyebrow, only when it adds context the headline cannot.
+- One headline: one promise, usually 6-12 words. Tighten display line-height and allow the strongest phrase to carry the accent — but tightening has a floor: at the weight and size actually used, descenders (g/y/p/j/q) and punctuation (apostrophes, commas) on one line must clear the line below without touching or overlapping it. Check this visually, not just by the line-height number — the same value that's safe at 400-weight/3rem can clip at 800-weight/6rem+. `line-height: 0.87` or lower on a bold, large-clamp display headline is a known way to cause this; see `references/anti-slop-checklist.md`'s line-height item for the numeric floor.
+  - **Word count and display size move together — they are not independent rules.** A headline within the 6-12 word budget can still render oversized if the type size doesn't scale down as the word count climbs toward the long end. Split the range: **6-8 words** gets the full display size (the top of whatever `clamp()` range the project's type scale defines). **9-12 words** steps down to a visibly smaller size — roughly one clamp tier down, about 15-20% smaller across the whole `clamp()` range, not just the same size left to wrap across more lines. If a headline needs the long end of the word budget *and* the full display size to say what it needs to say, that's a signal to cut the headline, not to let the type carry the overflow.
+  - **Under 6 words still has a ceiling — a shorter headline is not a license to go bigger.** The instinct to size inversely with word count (fewer words, so make each one huge) is exactly the failure real output has shown: a 4-word headline like "Block blind agent releases." rendering one word per line at near-viewport scale. **3-5 words caps at the same full display size the 6-8 word band uses — never above it.** Real premium product heroes (Linear, Stripe, Vercel) run short headlines at that same top-tier size, not a scaled-up outlier; punchiness comes from word choice and whitespace, not from exceeding the scale's own ceiling. A 1-2 word headline is rare enough it should be treated as a deliberate art-directed statement piece (mood note in the acceptance checks below), not the default case.
+  - **A short headline must not be forced into one-word-per-line stacking.** At the display size in use, a headline under 6 words should read on 1-2 lines. If it's breaking into 3+ lines — especially one word per line — the type size is too large for the container at that word count; step it down rather than letting the layout stretch vertically to accommodate it. This is the same failure as the long-headline wrapping check below, just triggered from the opposite direction (oversized type forcing a short line count to fragment, instead of a long headline overflowing a fixed size).
+- One subhead: one sentence, ideally 16-28 words and no more than two lines on desktop.
+- One primary CTA. Add one secondary CTA only when it serves a distinct lower-commitment path such as proof, demo, or documentation.
+- One focused visual that proves the outcome.
+- Navigation stays quiet. Do not let its controls compete with the hero CTA.
+
+Do not add trust rows, feature chips, workflow rails, contract/metric sidebars, floating badges, decorative stamps, orbit lines, file/status footers, or multiple mockups merely because there is room. Move them into the next section where they can become real proof instead of hero clutter.
+
+## Choose one proof visual
+
+Show the product's desirable result, not the machinery used to produce it.
+
+- For a builder or generation tool, show one excellent finished output.
+- For a dashboard, crop to the one decision or result users care about instead of reproducing the entire app shell.
+- For a workflow product, show the completed state in the hero and explain the steps below the fold.
+- For a physical product, use one strong product-in-context image rather than a collage of supporting assets.
+- For an abstract service, use one clear illustration or before/after moment tied directly to the promise.
+
+Use at most one outer presentation frame around the visual. Avoid a dashboard inside a dashboard. Small chrome may establish context, but every label inside it must earn its place.
+
+## Compose for hierarchy
+
+- Give the headline and visual clear, separate territories with generous negative space.
+- Let one side dominate slightly; equal-weight columns can feel mechanically templated.
+- Use one intentional rule-break at most: a controlled bleed, an off-grid edge, or a restrained accent bar. Do not stack several decorative gestures.
+- Keep the hero palette quieter than the sections below it. Accent color should identify the key phrase, action, or visual detail—not all three at maximum intensity.
+- When an established logo does not match the new theme, preserve the logo and solve the mismatch through its surrounding space, scale, or container.
+
+## Optional: a floating metric chip as annotation, not a second hero group
+
+A small chip (a real number + a one-to-three-word label, e.g. "6.60:1 contrast" or "5.2K active users") laid directly on top of the single proof visual — not beside it — reads as an annotation of that one visual, not a competing hero group, and premium references (motionsites.ai's higher-end hero examples among them) use this well. It is still governed by the same restraint budget, not exempt from it:
+
+- **Cap at one, or at most two** chips per hero, and they must sit ON the proof visual (overlapping its edge/corner), never floating independently in empty hero space — that reads as a fourth hero group, exactly what line 27 above forbids.
+- **The number must be real** — pulled from the product's own verified output (a contrast ratio actually computed for this build, a real usage count), never invented to fill the space.
+- Keep them small and quiet: this is a caption-scale detail noticed on a second look, not a headline-scale claim competing with the actual headline.
+- This does not relax the "one focused visual" rule — the chip is part of that one visual's presentation, not a second one.
+
+## Turn a static proof visual into a real animated comparison
+
+When the product's proof is fundamentally a *comparison* (before/after, with-skill/without-skill, old-way/new-way) and you have both real states as separate assets, don't compose them into one flat static image. Build an animated wipe/reveal instead: layer the two real screenshots absolutely, clip the top layer with `clip-path: inset()` driven by a CSS custom property (e.g. `--wipe`), and animate that property back and forth on a slow loop (GSAP supports tweening CSS custom properties directly: `gsap.to(el, { "--wipe": "80%", duration: 4, ease: "sine.inOut", yoyo: true, repeat: -1 })`).
+
+This is the single highest-leverage move for a hero that otherwise reads as "just a screenshot" — it turns real, honest content into something that visually reads as continuous motion (the "it looks like a video plays in the background" reaction premium references get), without fabricating a video asset or a synthetic 3D render. Both layers must be genuinely real captures of the actual product/comparison — never stage one side to look worse than it actually is.
+
+Constraints: this replaces the single proof visual, it doesn't add to it — still one visual, one frame, one job. Cap the wipe range so it never fully hides either state for long (e.g. 15%-85%, not 0%-100%) so a viewer glancing at any moment still sees both sides represented. Always respect `prefers-reduced-motion`: freeze at a fixed midpoint (e.g. 50%) rather than animating.
+
+## Optional: ambient depth behind the proof visual
+
+A soft radial glow (using the project's existing accent color at low opacity, positioned behind the proof visual) or a subtle idle drift/pulse on the visual itself (a few px of float, GSAP `yoyo: true, repeat: -1`, several-second duration) can make a static screenshot or product shot feel alive without adding a new competing element.
+
+**A stronger option when the brief calls for real production value**: an animated generative background — two or three soft radial-gradient "blobs" in the project's locked accent colors, drawn on a `<canvas>` and slowly drifted with `Math.sin`/`Math.cos` on a `requestAnimationFrame` loop — sitting behind the entire hero section (not just the proof visual). This is the honest substitute for a licensed stock-video background loop: genuinely continuous motion, zero licensing/sourcing cost, and it never competes with content because it's decorative and kept to low opacity. Draw one static frame and stop under `prefers-reduced-motion` instead of starting the loop.
+
+Either technique: keep the motion slow and low-amplitude enough that it reads as ambient texture, not attention-grabbing animation — and always gate it behind `prefers-reduced-motion` like any other motion in the hero.
+
+## A real reference check before calling a hero "done"
+
+Before finishing a hero pass, look at one current, genuinely award-caliber site in the same category as the product (not just a general inspiration gallery) and name what it's actually doing. A concrete finding from doing this against Linear.app while building this exact section: its hero is almost entirely restraint — huge type, a real (not glamorized) product screenshot at full width fading into the background via a top vignette, and *one* tiny text-link secondary action instead of a second button. No floating badges, no chips, no glow. That's a legitimate answer to "make it award-winning" that looks nothing like a maximalist agency-showcase hero — restraint, at sufficient scale and fidelity, reads as premium on its own. Don't assume "award-winning" means "add more decoration"; check a real reference in the product's own category before deciding which direction it means here.
+
+## Motion should reveal, not multiply
+
+Use a short GSAP sequence with at most four coherent beats:
+
+1. navigation or context,
+2. headline,
+3. subhead and actions,
+4. the single proof visual.
+
+Animate the visual as one composition. Do not stagger every label, tile, metric, or decorative shape separately. Avoid decorative parallax/orbits in the first viewport unless they communicate product behavior. Respect `prefers-reduced-motion`.
+
+## Responsive acceptance checks
+
+- At 390px, no horizontal overflow.
+- The headline remains readable in roughly 3-5 lines; no orphaned one-word line caused by an avoidable width constraint.
+- **At the top of the display size range, the headline fits comfortably in 2-3 lines.** If it's wrapping into 5+ lines at full size, that's not a responsive-width problem to accept — it's a signal the headline is too long for the size in use. Step the display size down a tier (see the word-count/size rule above) or shorten the headline; don't let a long headline dominate the hero by taking up more vertical space at full size instead of stepping down.
+- The subhead remains one compact paragraph.
+- CTAs either fit cleanly side by side or stack as full-width actions; they never squeeze into awkward labels.
+- The proof visual remains legible when stacked. Crop or simplify its internals rather than shrinking a dense desktop composition until it becomes unreadable.
+- On a short desktop viewport, the primary promise and action remain visible without scrolling. The visual may continue below the fold if necessary.
+
+## Subtraction pass
+
+Before delivery, list every distinct hero group and ask what user question it answers. Keep only groups that answer one of these:
+
+1. What is this?
+2. Why should I care?
+3. What should I do next?
+4. What does a good result look like?
+
+Move everything else below the fold. If two groups answer the same question, keep the stronger one.

package/skills/tastemaker/references/illustration-sources.md

@@ -0,0 +1,51 @@
+# Asset sourcing — attribution-free by design
+
+The governing rule: **every default source here requires zero attribution on the finished site.** A visible photo credit or "icons by X" line on a real marketing site is a visual hindrance no shipped product tolerates — so this skill sources only from places whose license lets the asset be used cleanly, with nothing for the end user to see. Sources that *require* on-site attribution (notably Unsplash's API) are deliberately not used as defaults, even though the imagery is good, because that requirement fights the end-user experience.
+
+## Photos — Openverse (default, keyless), Pixabay (optional upgrade)
+
+- **Openverse** — `scripts/fetch_photos.py`, **no API key at all**. Searches 800M+ openly-licensed images and filters by default to CC0 + Public-Domain-Mark, licenses that legally require **zero attribution** anywhere. This is the default specifically because it's keyless — combined with keyless Iconify icons, photos and icons need no accounts, no setup. (Illustrations, below, are the one asset type that may need a single one-time manual step — see that section.) Anonymous rate limits (20/min, 200/day) are ample for build-time fetching. The script tries the full-res source URL first and falls back to Openverse's own image proxy when a source blocks hotlinking, so a download rarely fails.
+- **Pixabay** — `--source pixabay` (needs a free `PIXABAY_API_KEY`). More stock-polished, higher-curation, full-resolution imagery; also attribution-free. Use it only when Openverse's more eclectic pool (which mixes in museum/wiki/rawpixel content) doesn't have a clean match for a section. It's an upgrade for a specific need, not the default, precisely because it reintroduces a key.
+- **Why not Unsplash** — its imagery is excellent, but its API Guidelines require *visible* photographer + Unsplash attribution wherever a photo appears, enforced as a condition of API access. That's an on-site hindrance with no compliant way around it, so it's off the path entirely.
+
+## Crediting sources in the code, never on the page
+
+CC0/PDM require no attribution — but crediting the creators anyway, as a voluntary thank-you, is a decent thing to do, and it costs the end user nothing if it lives in the source rather than on the page. `fetch_photos.py` writes a `CREDITS` comment block (per-photo creator + source + license + link) into the photos folder for exactly this. Paste it into a code comment at the top of the HTML/CSS. Two rules: (1) it's a comment, never rendered text — a viewer of the live site should never see it; (2) it's genuinely optional for CC0/PDM, so never let it become a reason to add *visible* credit. If a source ever actually requires visible attribution (e.g. Unsplash, or Streamline's free tier), that source simply isn't used here — the code-comment courtesy is for attribution-free assets only, not a loophole for attribution-required ones.
+
+## Illustrations — the vendored `ideagram/` (default)
+
+`ideagram/` is bundled directly inside this skill (not a sibling skill that may or may not be installed — see `ideagram/SKILL.md`) and is the default for every concept-driven section, and for any request that uses the word "illustration"/"illustrate" explicitly. Its current approach: **match a real unDraw illustration from a local library, then recolor it to the project's locked accent** — real illustrator path data, reused and rebranded, rather than an LLM hand-drawing SVG paths from scratch (which reliably produces crude pictograms, per `ideagram/references/undraw-anatomy.md`).
+
+This means illustrations have a genuine **one-time setup step, unlike photos/icons**: the local library (`~/.ideagram/undraw/`) needs 20-30 unDraw SVGs in it before matching works. unDraw's own license permits free, no-attribution personal use and download, but bars *redistributing a compiled collection* of their files — so this library lives on the user's machine, downloaded once from undraw.co, never bundled into this skill or any repo it produces. If the library doesn't exist yet when this step runs, say so plainly and either prompt the user to populate it (fast, one-time, reused across every future project) or fall back to `ideagram/assets/primitives` — a real quality drop, and say so rather than presenting the fallback as equivalent.
+
+Once matched: `ideagram/scripts/recolor_undraw.py` → `ideagram/scripts/validate_assets.py` → save to `design/assets/illustrations/` → reference the actual file in the page markup. See `ideagram/SKILL.md` for the full step-by-step and the Step 4 "compose a custom scene from real components" escape hatch for when no single library illustration fits.
+
+## Icons — Iconify (default)
+
+`scripts/fetch_icons.py` hits Iconify's public API (`api.iconify.design`) — **no API key required**. It draws from permissively-licensed open sets (Lucide ISC, Tabler MIT, Phosphor MIT, Heroicons MIT, Material Symbols Apache-2.0, …) that need **no attribution** in a finished product, and returns SVGs already tinted to the accent color server-side. Pick one set per project and stay in it so every icon shares a stroke weight and corner style — mixing sets is a fast way to look unintentional.
+
+That does not mean the same set every project, though. Pass `--mood <the project's locked mood>` and the script picks a set matched to that mood (premium → heroicons, warm → tabler, technical → lucide, playful → ph, elegant → material-symbols) instead of silently defaulting to lucide regardless of what's being built — that default-to-one-set habit is exactly the icon half of the sameness complaint this file's "through-line" section already warns against for photos and illustrations. Discover names with `--search --mood <mood>`, then fetch with `--icons --mood <mood>`. Name `--set` directly only when the mood mapping is a genuine mismatch for a specific project.
+
+> One nuance to respect: Iconify/its sets are for using icons *in* your design. Don't build a product feature that re-exposes these icons as a *pickable library to your own end users* (an "insert icon" picker in a builder app) — that's a different use some sets restrict. Using an icon directly in a client's UI, which is all this skill does, is fine.
+
+## Manual exception — Streamline
+
+unDraw is no longer a fallback here — it's the primary illustration source via `ideagram/` above. The remaining manual exception is for when even a populated unDraw library has no real fit for a concept (per `ideagram/SKILL.md` Step 2's "don't force a bad match" rule):
+
+- **Streamline** (streamlinehq.com) — larger, more detailed library. Free tier requires visible attribution for open-source sets (premium removes it); their Fair Use Policy also prohibits scripted bulk downloading. Because the free tier *does* carry an attribution string, prefer the unDraw/`ideagram` path when the goal is a clean, credit-free site — reach for Streamline only if the user has a premium license (attribution-free) or explicitly accepts the credit. If the user has Streamline's own official MCP connected, that's the sanctioned automated channel; otherwise it's a manual step.
+
+After any manual download: validate with `scripts/validate_assets.py`, recolor to the locked accent with `scripts/recolor_svg.py` if needed, then reuse across screens.
+
+## Logos — constructed, not sourced
+
+The project's logo mark is its own sourcing step, not an illustration — see `references/logo-sourcing.md`. It is **constructed** from primitives in the locked palette (or an existing brand asset is preserved), so there is no third-party license or domain involved at all.
+
+## The through-line
+
+Photos (Openverse) and icons (Iconify) are fully automatic, **keyless**, and attribution-free — no setup, every session. Illustrations (`ideagram/`) need a one-time manual step (populating the unDraw library), but are otherwise attribution-free and reused across every future project. Logos are constructed locally, so they need no external source at all. Streamline and the keyed upgrade (Pixabay) exist for fit, not because the defaults are lacking. If you ever find yourself about to add an on-site credit line to satisfy a source's license, stop: that means the wrong source was chosen for this skill's goal. Switch to an attribution-free one instead.
+
+## On sameness across projects
+
+Color and icon set both now vary by project on purpose: the palette is generated fresh per project (`scripts/generate_palette.py`, see `references/style-tokens.md`), and the icon set is chosen by mood instead of always defaulting to one (`--mood` on `fetch_icons.py`, above). Illustrations are recolored to that same generated accent every time, so the color half of an illustration's identity varies with the project too, even though the underlying artwork is matched from a shared local library.
+
+Being honest about what is not solved: the underlying unDraw scene an illustration is matched from can still recur, since the matching in `ideagram/SKILL.md` picks the closest scene from whatever is in `~/.ideagram/undraw/`, and that library is finite. Two projects that both need a "team collaborating" illustration and draw from a similarly-populated library can land on the same base scene, just recolored differently. This is a real, known limitation, not a solved one — populating a broader personal library reduces it, but does not remove it. A genuinely different fix (generating original illustration artwork instead of matching an existing library) is a larger change than fits here.