@damiangilgonzalez/harness 1.3.7

package/skills/tastemaker/ideagram/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: ideagram
+description: Turn a concept, feature description, blog post, or pitch into a single beautiful, on-brand illustration by matching it to a real unDraw illustration in a local library and recoloring it to the brand accent — genuine illustrator quality, not an AI-drawn approximation. Use whenever the user asks to "make an illustration," "create a graphic," "visualize this concept," "explain this visually," wants something "unDraw-style" or "Storyset-style," needs a hero/feature/blog illustration, or says an idea needs a picture. Trigger even if they don't name a style — "make something to explain X" or "I need a graphic for this tweet" both qualify.
+---
+
+# Ideagram
+
+## The core idea
+
+Produce **one** beautiful, on-brand illustration for a concept by matching it to a real unDraw illustration and recoloring it to the brand — never by hand-drawing. unDraw's figures are dozens of hand-placed bezier anchors from a professional illustrator; freehand-generating path coordinates produces crude pictograms, not art. The quality lives in the real path data, so this skill reuses it: match → recolor → (compose, if needed) → deliver. The output is genuinely illustrator-grade because it *is* the illustrator's work, just made on-brand.
+
+Read `references/undraw-anatomy.md` once — it's the dissection of how these files are built and why this reuse approach works.
+
+## Setup: a local unDraw library
+
+This skill reads real unDraw SVGs from a **local library folder** — it does not bundle or redistribute unDraw's files (their license bars compiling their assets into a redistributed collection; downloading them for your own use is free and needs no attribution).
+
+- Default library location: `~/.ideagram/undraw/`.
+- Populate it by downloading illustrations from [undraw.co/illustrations](https://undraw.co/illustrations) (free, no attribution, unlimited) — 20-30 illustrations spanning common themes (teams, devices, data, growth, communication, security, travel) covers most requests well.
+- After adding SVGs, (re)build the index: `python3 scripts/build_library_index.py`. This writes `index.md` (human-scannable) and `index.json` (machine-readable) into the library folder — read `index.md` first for matching instead of guessing from filenames cold.
+- If **no library exists yet**, say so plainly and point the user at undraw.co (30 seconds to grab a few). Only fall back to the crude generated-primitive path (`references/style-contract.md`) if they genuinely can't, and be upfront that it's a large quality drop from real unDraw art.
+
+## Workflow
+
+### Step 1 — Distill the concept
+
+Reduce the input to one sentence — "this is fundamentally about ___" — plus a few keywords. If the content genuinely holds two ideas, that's two illustrations, not one crowded brief.
+
+### Step 2 — Match to the best illustration in the library
+
+Read `~/.ideagram/undraw/index.md` (run `scripts/build_library_index.py` first if it doesn't exist or the library changed). Match the concept's keywords against each entry's keyword list — prefer a match on the *scene*, not just a loose word overlap: a dashboard/analytics concept wants an illustration with a screen or chart; a teamwork concept wants one with multiple figures. If several are close, pick the one whose scene most literally embodies the concept (see the worked example below). If nothing in the library is a real fit, say so and either ask the user to grab a closer one from undraw.co or fall back (Step 5) — don't force a bad match.
+
+**Worked example:** "an AI creative director composing a whole design system from one prompt" → not literally "AI" or "design system" in any filename, but `mobile-site-builder` (a person actively laying out screen components) is the closest *scene* match — the visual metaphor matters more than exact keyword overlap.
+
+### Step 3 — Recolor to the brand
+
+```
+python3 scripts/recolor_undraw.py <matched>.svg --accent "#<brand-hex>" --out design/<name>.svg
+```
+
+This swaps only unDraw's `#6c63ff` accent family for the brand color, leaving every skin tone, hair, clothing, and neutral exactly as drawn — verified on real multi-figure scenes. Check the matched illustration's `index.md` row for a flagged secondary accent (green/pink); if present and it should also change, add `--also "#8ed16f:#<hex>"`. If the user gives no brand color, unDraw's default purple is a fine, deliberate choice — don't invent one.
+
+**If you need to redo a color** (the user asks for a different one), re-copy the *original* unDraw source into the output path first, then recolor — `recolor_undraw.py` only remaps `#6c63ff` outward, so recoloring an already-recolored file does nothing (the purple it looks for is gone). Never edit a previously-branded file's colors by hand to "fix" this.
+
+### Step 4 — (Optional) Compose a custom scene from real components
+
+Only when no single library illustration fits and a custom scene is worth the extra effort:
+
+- List a source's components with `scripts/extract_component.py source.svg --list`, then lift one with `--match "translate(...)" --out part.svg`.
+- Assemble whole components into one `<svg>` as a real **scene** — a background element, the concept's midground device, then the figure interacting with it, plus a ground shadow — not a floating figure. This is what separates a designed illustration from a subject stranded on white.
+- Place each with `<g transform="translate() scale()">`; render and read `getBBox()` to size/position accurately rather than guessing coordinates from nested transforms.
+- Reuse *whole* components. Recombining sub-limbs (an arm from one figure onto another's torso) is fragile — different coordinate spaces and shading directions rarely join cleanly.
+- Recolor the finished composition (Step 3).
+
+### Step 5 — Fallback only if there's no usable library
+
+If the user genuinely has no unDraw library and won't create one, `references/style-contract.md` + `assets/primitives/` still exist — but they produce simple flat pictograms, not illustrator-grade art. Use only as a last resort, and say plainly that a couple of real unDraw SVGs would look dramatically better for the same effort.
+
+### Step 6 — Validate and deliver
+
+- `python3 scripts/validate_assets.py <final>.svg` — catches malformed SVG (e.g. a `--` inside a comment) that renders as a broken image in strict browsers, invisible unless actually parsed.
+- Deliver the SVG directly for web use — smallest, crispest, infinitely recolorable. For social/raster: `scripts/export_png.py <final>.svg --out design/export/` (needs `cairosvg` + system cairo; degrades honestly if either is missing, and the SVG stays fully usable regardless).
+
+## Reference files
+
+| File | Read when |
+|---|---|
+| `references/undraw-anatomy.md` | Always, first — the palette, structure, and the reuse technique this skill is built on |
+| `~/.ideagram/undraw/index.md` | Step 2 — matching a concept to the right illustration |
+| `references/style-contract.md`, `references/metaphor-library.md` | Only for the Step 5 fallback (no library, generated primitives) |
+
+## Scripts
+
+| Script | Purpose |
+|---|---|
+| `scripts/build_library_index.py` | Index a local unDraw library into `index.md`/`index.json` for fast, accurate matching. Run after adding new SVGs. |
+| `scripts/recolor_undraw.py` | Recolor a real unDraw illustration's accent to a brand color, preserving skin/ink/clothing/neutrals. The workhorse. |
+| `scripts/extract_component.py` | Lift a whole figure/device/panel out of a source unDraw SVG for composing a new scene. |
+| `scripts/validate_assets.py` | Verify the finished SVG is well-formed before delivering. |
+| `scripts/export_png.py` | Export flattened PNGs at standard social/presentation sizes (needs cairosvg + system cairo). |
+
+## Honesty
+
+Say what actually happened: which illustration was matched and why, whether it was recolored, and if you fell back to generated primitives because there was no library, say that plainly and note the quality gap rather than presenting it as equal. Respect the sourcing model — reuse real unDraw art from the user's local library for their own sites; never redistribute unDraw's files into a public repo.
+
+## A note on image generation
+
+An alternative, higher-ceiling approach exists — *generating* an original illustration with an image model, steered by a rigorous style system (`references/style-dna.md`, `composition-patterns.md`, `prompt-template.md`, `qa-checklist.md`) — for the rare case a session has a genuine image-generation tool available and the library has no good match. Most Claude sessions don't have one, so this isn't part of the default workflow above; only reach for it if such a tool is actually present, and say so.

package/skills/tastemaker/ideagram/assets/primitives/figure-pointing.svg

@@ -0,0 +1,13 @@
+<svg width="400" height="400" viewBox="0 0 400 400" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Figure gesturing toward something, presenting or explaining a concept">
+  <ellipse cx="200" cy="378" rx="70" ry="10" fill="#262631" opacity="0.08"/>
+  <rect x="162" y="285" width="34" height="90" rx="16" fill="#262631"/>
+  <rect x="204" y="285" width="34" height="90" rx="16" fill="#262631"/>
+  <ellipse cx="179" cy="378" rx="24" ry="10" fill="#262631"/>
+  <ellipse cx="221" cy="378" rx="24" ry="10" fill="#262631"/>
+  <rect x="118" y="172" width="30" height="108" rx="15" fill="#262631"/>
+  <g transform="rotate(-58 267 172)">
+    <rect x="252" y="172" width="30" height="108" rx="15" fill="#262631"/>
+  </g>
+  <rect x="150" y="155" width="100" height="145" rx="42" fill="#6C5CE7"/>
+  <circle cx="200" cy="108" r="46" fill="#262631"/>
+</svg>

package/skills/tastemaker/ideagram/assets/primitives/figure-sitting-desk.svg

@@ -0,0 +1,11 @@
+<svg width="400" height="400" viewBox="0 0 400 400" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Figure sitting at a desk with a laptop">
+  <rect x="70" y="290" width="16" height="70" rx="6" fill="#262631"/>
+  <rect x="314" y="290" width="16" height="70" rx="6" fill="#262631"/>
+  <rect x="55" y="270" width="290" height="22" rx="8" fill="#262631"/>
+  <rect x="118" y="140" width="26" height="110" rx="13" fill="#262631"/>
+  <rect x="256" y="140" width="26" height="110" rx="13" fill="#262631"/>
+  <rect x="150" y="118" width="100" height="130" rx="38" fill="#6C5CE7"/>
+  <circle cx="200" cy="78" r="42" fill="#262631"/>
+  <rect x="150" y="248" width="100" height="26" rx="6" fill="#262631"/>
+  <rect x="158" y="178" width="84" height="72" rx="6" fill="#6C5CE7"/>
+</svg>

package/skills/tastemaker/ideagram/assets/primitives/figure-standing.svg

@@ -0,0 +1,11 @@
+<svg width="400" height="400" viewBox="0 0 400 400" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Standing figure">
+  <ellipse cx="200" cy="378" rx="70" ry="10" fill="#262631" opacity="0.08"/>
+  <rect x="162" y="285" width="34" height="90" rx="16" fill="#262631"/>
+  <rect x="204" y="285" width="34" height="90" rx="16" fill="#262631"/>
+  <ellipse cx="179" cy="378" rx="24" ry="10" fill="#262631"/>
+  <ellipse cx="221" cy="378" rx="24" ry="10" fill="#262631"/>
+  <rect x="118" y="172" width="30" height="108" rx="15" fill="#262631"/>
+  <rect x="252" y="172" width="30" height="108" rx="15" fill="#262631"/>
+  <rect x="150" y="155" width="100" height="145" rx="42" fill="#6C5CE7"/>
+  <circle cx="200" cy="108" r="46" fill="#262631"/>
+</svg>

package/skills/tastemaker/ideagram/assets/primitives/prop-chart-bar.svg

@@ -0,0 +1,8 @@
+<svg width="400" height="400" viewBox="0 0 400 400" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Bar chart, growth or data concept">
+  <line x1="70" y1="320" x2="330" y2="320" stroke="#262631" stroke-width="10" stroke-linecap="round"/>
+  <rect x="100" y="240" width="46" height="80" rx="8" fill="#262631"/>
+  <rect x="177" y="180" width="46" height="140" rx="8" fill="#262631"/>
+  <rect x="254" y="110" width="46" height="210" rx="8" fill="#6C5CE7"/>
+  <path d="M100 150 L177 120 L254 70 L300 40" stroke="#262631" stroke-width="10" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+  <circle cx="300" cy="40" r="14" fill="#6C5CE7"/>
+</svg>

package/skills/tastemaker/ideagram/assets/primitives/prop-document.svg

@@ -0,0 +1,10 @@
+<svg width="400" height="400" viewBox="0 0 400 400" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Document, writing or content concept">
+  <ellipse cx="200" cy="358" rx="90" ry="10" fill="#262631" opacity="0.08"/>
+  <rect x="100" y="50" width="200" height="280" rx="16" fill="#262631"/>
+  <rect x="124" y="76" width="152" height="228" rx="8" fill="#6C5CE7"/>
+  <rect x="148" y="112" width="104" height="14" rx="7" fill="#262631"/>
+  <rect x="148" y="142" width="104" height="14" rx="7" fill="#262631"/>
+  <rect x="148" y="172" width="70" height="14" rx="7" fill="#262631"/>
+  <rect x="148" y="212" width="104" height="14" rx="7" fill="#262631"/>
+  <rect x="148" y="242" width="88" height="14" rx="7" fill="#262631"/>
+</svg>

package/skills/tastemaker/ideagram/assets/primitives/prop-envelope.svg

@@ -0,0 +1,7 @@
+<svg width="400" height="400" viewBox="0 0 400 400" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Envelope, email or messaging concept">
+  <rect x="60" y="120" width="280" height="190" rx="16" fill="#262631"/>
+  <rect x="84" y="144" width="232" height="142" rx="8" fill="#6C5CE7"/>
+  <path d="M84 150 L200 235 L316 150" stroke="#262631" stroke-width="12" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+  <circle cx="290" cy="105" r="34" fill="#6C5CE7"/>
+  <path d="M278 105 L288 115 L305 95" stroke="#262631" stroke-width="8" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+</svg>

package/skills/tastemaker/ideagram/assets/primitives/prop-lightbulb.svg

@@ -0,0 +1,14 @@
+<svg width="400" height="400" viewBox="0 0 400 400" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Lightbulb, idea concept">
+  <g stroke="#262631" stroke-width="10" stroke-linecap="round">
+    <line x1="200" y1="40" x2="200" y2="70"/>
+    <line x1="290" y1="80" x2="270" y2="100"/>
+    <line x1="110" y1="80" x2="130" y2="100"/>
+    <line x1="320" y1="170" x2="290" y2="170"/>
+    <line x1="80" y1="170" x2="110" y2="170"/>
+  </g>
+  <circle cx="200" cy="170" r="95" fill="#6C5CE7"/>
+  <rect x="168" y="248" width="64" height="24" fill="#262631"/>
+  <rect x="172" y="278" width="56" height="18" rx="6" fill="#262631"/>
+  <rect x="178" y="302" width="44" height="14" rx="6" fill="#262631"/>
+  <path d="M180 150 L200 190 L175 190 L200 230" stroke="#262631" stroke-width="10" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+</svg>

package/skills/tastemaker/ideagram/assets/primitives/prop-rocket.svg

@@ -0,0 +1,8 @@
+<svg width="400" height="400" viewBox="0 0 400 400" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Rocket, launch or speed concept">
+  <path d="M200 50 C250 100 260 180 260 230 H140 C140 180 150 100 200 50 Z" fill="#262631"/>
+  <path d="M140 230 L100 300 L150 280 Z" fill="#262631"/>
+  <path d="M260 230 L300 300 L250 280 Z" fill="#262631"/>
+  <circle cx="200" cy="165" r="34" fill="#6C5CE7"/>
+  <path d="M170 230 H230 L215 300 H185 Z" fill="#6C5CE7"/>
+  <path d="M188 300 C188 330 175 345 175 345 C205 345 212 330 212 300 Z" fill="#6C5CE7"/>
+</svg>

package/skills/tastemaker/ideagram/assets/primitives/prop-shield.svg

@@ -0,0 +1,5 @@
+<svg width="400" height="400" viewBox="0 0 400 400" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Shield, security concept">
+  <path d="M200 50 L320 95 V190 C320 270 270 320 200 350 C130 320 80 270 80 190 V95 Z" fill="#262631"/>
+  <path d="M200 85 L292 118 V190 C292 254 254 296 200 320 C146 296 108 254 108 190 V118 Z" fill="#6C5CE7"/>
+  <path d="M160 205 L190 240 L245 165" stroke="#262631" stroke-width="16" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+</svg>

package/skills/tastemaker/ideagram/assets/primitives/prop-speech-bubble.svg

@@ -0,0 +1,7 @@
+<svg width="400" height="400" viewBox="0 0 400 400" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Speech bubble, communication concept">
+  <path d="M70 90 H330 C341 90 350 99 350 110 V240 C350 251 341 260 330 260 H190 L130 310 L140 260 H70 C59 260 50 251 50 240 V110 C50 99 59 90 70 90 Z" fill="#262631"/>
+  <path d="M96 116 H304 C309.5 116 314 120.5 314 126 V224 C314 229.5 309.5 234 304 234 H185 L145 270 L152 234 H96 C90.5 234 86 229.5 86 224 V126 C86 120.5 90.5 116 96 116 Z" fill="#6C5CE7"/>
+  <circle cx="140" cy="175" r="14" fill="#262631"/>
+  <circle cx="200" cy="175" r="14" fill="#262631"/>
+  <circle cx="260" cy="175" r="14" fill="#262631"/>
+</svg>

package/skills/tastemaker/ideagram/references/composition-patterns.md

@@ -0,0 +1,49 @@
+# Composition patterns & the metaphor recipe (generation path)
+
+The single biggest lever on quality isn't rendering — it's **what you decide to depict**. A generic prompt ("illustration about analytics") yields generic art. A specific scene built on a fresh metaphor yields something that looks art-directed. This file is how you get there.
+
+## Step 1 — Pick ONE structure
+
+Choose a single structure per image; don't blend. These are the shapes a concept can take:
+
+| Structure | Fits | How it's drawn |
+|---|---|---|
+| **Hero scene** | A product/feature's core promise | One character interacting with the key object (device/dashboard/tool), calm background, accent on the object. The default. |
+| **Before / after** | chaos→order, manual→automatic, scattered→cohesive | Left = messy/tense, right = calm/resolved, a bridge/arrow between. Character's posture shifts across the two. |
+| **Character state** | user pain, "too many tools," stuck→flowing | 2–3 small vignettes, each one posture/expression, one short label each. |
+| **Concept metaphor** | an abstract idea (trust, scale, memory, taste) | ONE memorable object/machine that stands in for the idea, a character operating it. Highest ceiling, needs the recipe below. |
+| **Workflow / flow** | input→process→output, a pipeline | Left input, middle transform (a machine or the character working), right output, accent arrow for the main flow. |
+| **Layers / stack** | a framework, a system with levels | Stacked shapes (not a stiff pyramid), character building or climbing them. |
+| **Journey / path** | idea→launch, onboarding, a roadmap | One curved path, a few nodes, character walking or drawing it. |
+
+## Step 2 — Invent a FRESH metaphor (don't reach for the obvious)
+
+The obvious visual (analytics → bar chart, security → shield, idea → lightbulb) is what makes illustration forgettable. Generate a fresher one with this 3-step recipe (lifted from how the best editorial illustrators work):
+
+1. **Abstract concept → a physical action.** Turn the idea into something a body can *do*: stacking, sorting, pouring, catching, wiring, untangling, bridging, planting, fermenting, folding, filtering, balancing.
+2. **System/structure → a low-key concrete object.** Turn the mechanism into a tangible thing: a control panel, a set of drawers, a funnel, a loom, a conveyor, a garden, a switchboard, a scale, a well, a bridge, a printing press.
+3. **Put the character *in* the action.** The person operates/builds/rides/repairs the object — they perform the core verb, they don't stand beside it.
+
+**Object pool:** control panel, drawers, funnel, loom, conveyor belt, switchboard, scale/balance, bridge, ladder, garden bed, printing press, pipes, valves, dials, a well, a workshop bench, a filing system, a mixing board.
+**Action pool:** stack, sort, pour, catch, wire, untangle, bridge, plant, tune, fold, filter, balance, assemble, channel, weave.
+Use **1–2** objects, never a cluttered pile.
+
+## Step 3 — The scene, not the subject
+
+An amateur illustration is a subject floating on white. A designed one is a **scene** with depth. Build in layers:
+
+1. **Background** — a calm large shape or suggested environment (a soft-tinted panel, a wall, a horizon line, a window). Often the biggest element, lowest contrast.
+2. **Midground** — the metaphor object / device the concept is about. Carries the accent.
+3. **Foreground figure** — the character performing the action, interacting with the midground.
+4. **Grounding + a few decorative beats** — a soft shadow under the subject, one or two small accent details (a plant, floating cards, a couple of dots) to add life. Sparse.
+
+## The "earn its place" test for the character
+
+After composing, ask: *if I removed the person, would the metaphor still fully read?* If yes, the person is decoration — rewrite so they perform the core action. A character watching a chart is decoration; a character *tuning the dials that move the chart* is the idea.
+
+## Restraint rules (what keeps it tasteful)
+
+- One focal point, accent-colored. Everything else is neutral.
+- ≤ 3 short text labels, and only if essential. Prefer zero.
+- One or two objects, not a set. Whitespace over density.
+- Don't explain every element — suggestion reads as confident; over-labeling reads as a diagram.

package/skills/tastemaker/ideagram/references/metaphor-library.md

@@ -0,0 +1,34 @@
+# Concept → visual metaphor library
+
+The single hardest part of this whole skill isn't drawing — it's picking *what to draw*. Given a paragraph of content, the temptation is to try to depict everything in it. Don't. Pick the one concrete object or scene that a viewer would recognize in under a second, even with zero context. This file is a starting lookup for that translation; treat it as scaffolding, not an exhaustive catalog — extend it as new concepts come up.
+
+Every row below defaults to **figure + prop together**, per `style-contract.md`'s "default to including a human figure" rule — `figure-pointing.svg` is the usual choice since its gesture reads naturally as presenting/explaining whatever the prop represents. Treat the "prop alone" variant as the exception, for cases where the output needs to work as a small inline icon rather than a scene.
+
+| Abstract concept | Concrete visual metaphor | Primitives to compose |
+|---|---|---|
+| Idea / innovation / brainstorming | A figure gesturing toward a lit lightbulb | `figure-pointing.svg` + `prop-lightbulb.svg` |
+| Security / privacy / protection | A figure gesturing toward a shield with a checkmark | `figure-pointing.svg` + `prop-shield.svg` |
+| Communication / feedback / conversation | A figure gesturing toward a speech bubble, or two figures facing each other with a bubble between them | `figure-pointing.svg` + `prop-speech-bubble.svg` |
+| Growth / progress / analytics / success metrics | A figure gesturing toward an upward bar chart | `figure-pointing.svg` + `prop-chart-bar.svg` |
+| Email / messaging / notifications | A figure gesturing toward (or a `figure-standing.svg` holding) an envelope | `figure-pointing.svg` + `prop-envelope.svg` |
+| Speed / launch / momentum / going live | A figure gesturing toward a rocket | `figure-pointing.svg` + `prop-rocket.svg` |
+| Remote work / focus / desk work / building something | A figure already sitting at a desk with a laptop — the figure is built into this primitive, no separate pairing needed | `figure-sitting-desk.svg` |
+| A single user / person / individual contributor | A standing figure alone | `figure-standing.svg` |
+| Collaboration / teamwork | Two `figure-standing.svg` instances, mirrored toward each other (see `style-contract.md`'s mirroring note — a plain side-by-side placement doesn't read as "facing"), with a shared object (chart, speech bubble) between them | multiple figures + one shared prop |
+| Real-time co-editing / live presence / multiple people in one document | Two figures flanking a `prop-document.svg`, with two small cursor markers (a simple triangle + a small rounded-rect "nameplate") pointing at different lines of text — use the fill-vs-outline technique from `style-contract.md` to make the two cursors distinguishable without a third color | 2× `figure-standing.svg` (mirrored) + `prop-document.svg` + two small hand-built cursor markers |
+| Writing / content / documents / notes | A figure gesturing toward a document with visible text lines | `figure-pointing.svg` + `prop-document.svg` |
+| Onboarding / getting started | A standing figure + an open envelope or a lit path forward — pick whichever the actual product does (welcome email vs. guided steps) | context-dependent |
+| Data / cloud / storage | Not yet in the primitive kit — until a dedicated primitive exists, compose from simple shapes (rounded rectangle stack) following the style contract rather than skipping the concept, and still pair it with a figure by default |
+
+## How to pick when nothing matches directly
+
+1. Strip the input down to one sentence: "this is fundamentally about ___." If that sentence still has two unrelated nouns in it, the content needs two illustrations, not one overloaded scene.
+2. Ask what a five-year-old would draw for this concept with three crayons. That instinct — the single, obvious, almost-too-simple image — is usually the right one. Sophistication in this style comes from restraint, not from adding detail.
+3. If the concept is genuinely abstract (e.g. "reliability," "scale," "trust") and no object maps to it directly, pick the closest adjacent concrete thing (trust → shield or handshake; scale → upward chart or multiplying figures) rather than inventing a literal abstraction (there's no good visual noun for "trust" itself — the shield stands in for it).
+4. When composing multiple primitives into one scene, keep the same one-focal-point rule from `style-contract.md` — one element (usually the prop, not the figure) should carry the accent color and be the thing the eye lands on first.
+
+## When a new concept doesn't map to anything here
+
+Don't force it into a bad-fit existing primitive. The default move is still to compose a new simple flat shape following `style-contract.md`'s shape language (circles, rounded rects, capsules, flat fill, two colors only) — this keeps the illustration original artwork with zero licensing questions, which is the whole point of this skill existing rather than just pointing people at an existing illustration site. Validate it with `scripts/validate_assets.py`, and add it to `assets/primitives/` if it's likely to recur.
+
+Only if the concept needs a level of detail this flat-primitive system genuinely can't produce well (see `style-contract.md`'s "what this style is not" note), mention to the user that browsing an existing illustration library — unDraw (undraw.co/illustrations) or Streamline (streamlinehq.com/illustrations) — for a closer pre-made match is a reasonable alternative for that one asset. That's a manual, occasional escape hatch, not something this skill automates: both sites explicitly prohibit automated scraping/bulk downloading in their own terms (unDraw's license bans it outright; Streamline's Fair Use Policy states downloading via scripts "does not fall within fair use"), and pulling from either changes the artwork from "generated by this skill" to "sourced from a third party," which the user should make deliberately, not by default.

package/skills/tastemaker/ideagram/references/prompt-template.md

@@ -0,0 +1,50 @@
+# Image-generation prompt template (generation path)
+
+Fill the variables from the brief and the decisions made in `composition-patterns.md`. Generate ONE image per prompt — never ask for a grid or multiple concepts in one call. Keep the whole Style DNA in every prompt; image models forget constraints that aren't restated.
+
+```text
+Generate one standalone modern flat-vector editorial illustration, landscape orientation, on a calm near-white background.
+
+Visual DNA:
+Clean modern flat illustration in the register of unDraw / Storyset / premium SaaS landing pages. Proportioned, natural characters (roughly 7-8 heads tall, relaxed pose, simple face). Flat shapes with at most one subtle shade for depth — no heavy 3D. Restrained neutral palette (off-white, greys, charcoal) plus natural skin tones, and exactly ONE saturated accent color: {BRAND_ACCENT_HEX}. The accent is the loudest thing in the frame and marks the single focal point. Generous whitespace; the subject fills about 50-65% of the frame. Confident, tasteful, a little clever — art-directed, not auto-generated.
+
+Absolutely avoid: rainbow or multi-hue palettes; indigo-to-purple or blue-to-cyan gradients; glossy 3D, bevels, glow, glassmorphism; busy or textured backgrounds; realistic photography; corporate clip-art or generic stock-team scenes; cute children's-book cartoon style; dense infographic / PowerPoint / flowchart look; baked-in paragraphs of text; deformed hands or faces.
+
+Concept:
+{ONE_SENTENCE_CORE_IDEA}
+
+Structure:
+{STRUCTURE from composition-patterns.md: hero scene / before-after / character state / concept metaphor / workflow / layers / journey}
+
+Fresh metaphor:
+{THE_METAPHOR — the physical action + the low-key object, from the 3-step recipe. e.g. "a person tuning the dials of a control panel that raises a set of bars" rather than "a bar chart"}
+
+Scene (build depth, not a floating subject):
+Background: {calm large shape / suggested environment}. Midground: {the metaphor object/device, in the accent}. Foreground: {the character performing the core action, interacting with the midground}. Grounding: soft shadow under the subject; {one or two sparse decorative accents}.
+
+Focal point:
+{the one element the accent lands on}
+
+Optional labels:
+{zero to three very short words, only if essential — else "none"}
+
+Constraints:
+One idea, one focal point. The character must be performing the core action, not standing beside the scene. One or two objects maximum; keep at least 35% of the frame as calm whitespace. Only the accent color is saturated; everything else neutral. No title, no caption, no baked-in body text. Clean but not sterile, simple but not empty, characterful but not busy.
+```
+
+## Iteration prompts (image-edit / regenerate)
+
+**Make the character central to the idea (fixes "figure is decoration"):**
+```text
+Regenerate with the same concept, palette, and simple layout, but make the character clearly perform the core action — operating/building/riding the metaphor object, not standing beside it. Keep it clean, flat, sparse, one accent color, plenty of whitespace.
+```
+
+**Calm it down (fixes "too busy / too many colors"):**
+```text
+Regenerate simpler: remove secondary objects and any extra colors, keep only the focal subject and one accent color, add more whitespace. One clear idea, nothing decorative competing with it.
+```
+
+**Remove unwanted baked-in text:**
+```text
+Edit the provided image: remove the text "{TEXT}" and fill that area with the matching clean background. Preserve everything else exactly — characters, shapes, colors, composition, aspect ratio. Add no new text or objects.
+```

package/skills/tastemaker/ideagram/references/qa-checklist.md

@@ -0,0 +1,19 @@
+# QA checklist (generation path)
+
+Run every generated image against this before delivering. If it fails, regenerate or edit (see the iteration prompts in `prompt-template.md`) rather than shipping it. This is what separates "an AI image" from "a designed illustration."
+
+- [ ] **One idea, one focal point.** The eye lands in one place first, and that place is the accent color. If attention scatters, it's too busy — simplify.
+- [ ] **The character earned its place.** If a person is present, they're *performing the core action*, not standing beside the scene. (Remove-them test: does the metaphor still fully read without them? If yes, rewrite.)
+- [ ] **It's a scene, not a floating object.** There's a background/ground, a subtle shadow, some depth — not a subject stranded on blank white.
+- [ ] **Palette is disciplined.** Neutrals + skin + exactly one saturated accent. No rainbow, no default indigo/purple gradient, no second unrelated hue.
+- [ ] **No anti-slop tells.** No glossy 3D, glow, glassmorphism, busy/textured background, stock clip-art stiffness, cutesy cartoon, or dense-infographic look.
+- [ ] **Whitespace intact.** At least ~35% calm space; subject ~50–65% of the frame. Not cramped.
+- [ ] **People render cleanly.** Proportions natural (~7–8 heads), no deformed hands/faces. If a hand or face broke, regenerate or crop it out of frame.
+- [ ] **Minimal/no baked-in text.** No title, no caption, ≤3 short label words and only if essential. If the model wrote gibberish text, edit it out.
+- [ ] **On-brand.** The accent is actually the requested brand hex (or visually equivalent), and it's on the focal point.
+- [ ] **Fresh, not generic.** The metaphor isn't the first cliché (analytics≠plain bar chart, idea≠plain lightbulb). If it is, try the metaphor recipe again.
+- [ ] **Consistent with siblings.** If this is one of a set, it shares the palette, character style, and level of detail with the others — reads as one system.
+
+## Honesty on delivery
+
+Say which path produced the image (generated vs. recolored real unDraw), how many images, and which are the strongest vs. optional. Don't present a generated image with a broken hand or gibberish text as finished — fix it or say it needs another pass.

package/skills/tastemaker/ideagram/references/style-contract.md

@@ -0,0 +1,29 @@
+# Style contract
+
+Every illustration this skill produces follows the same visual grammar, on purpose — a set of illustrations that all follow one grammar reads as one system (shareable, brandable); a set that each improvise their own style reads as clip art.
+
+## Color: exactly two, always
+
+- **One base/outline color** — near-black, used for figures, outlines, and structural elements. Default: `#262631`.
+- **One accent color** — used for the single "pop" element per illustration (the thing the concept is actually about: the shield's face, the bulb's glass, the chart's highlighted bar). Default: `#6C5CE7`, but this is the one thing a caller should expect to customize per brand.
+- **Never a third color, never a gradient.** If a scene seems to need a third color, that's a sign the composition is trying to depict too much at once — simplify the scene instead of expanding the palette. This constraint is what makes recoloring reliable (`scripts/recolor_svg.py` assumes exactly this two-color convention) and what makes the output actually look like one coherent family rather than assorted clip art.
+
+## Shape language
+
+- Flat fills only. No shadows, no bevels, no gradients, no photorealistic rendering.
+- Rounded corners on human-made objects (devices, furniture, signage) — sharp corners read as colder/more technical than the friendly, approachable register this style targets.
+- Circles and capsule shapes for anything organic (heads, limbs) — this is what keeps figures reading as simple/abstract rather than attempting (and failing at) realistic anatomy.
+- Generous negative space. A cluttered illustration with 6 objects competing for attention explains nothing; a spare one with 2 objects and a clear focal point explains instantly.
+
+## Composition
+
+- **One concept, one scene.** Resist the urge to depict every aspect of the input content — pick the single idea that explains it fastest and build the whole illustration around that (see `references/metaphor-library.md` for how to choose it).
+- **One clear focal point.** The accent color should land on the thing that matters most in the scene, not be spread evenly across several elements — if everything is accented, nothing is.
+- **Default to including a human figure, not a bare object.** This is the single biggest thing that makes unDraw-style illustration read as "explaining an idea to a person" rather than "a stock icon" — almost every unDraw illustration has a character *doing something* with the concept, not just the concept floating alone. So the default composition is a figure (usually `figure-pointing.svg`, gesturing toward the prop as if presenting or explaining it) plus the prop that carries the actual concept — not the prop by itself. Reach for a bare, figure-less prop only when the illustration is meant to work as a small standalone icon (e.g. inline next to a heading) rather than as a scene — that's the exception, not the starting point.
+- Canvas: build on a `400 400` viewBox per primitive; when composing a scene from multiple primitives, lay them out with simple `transform="translate(x y)"` groups rather than editing each primitive's internal coordinates — this keeps primitives reusable and each new composition low-risk.
+- **Mirroring is a legitimate composition tool, not just translation.** Most figures/props are symmetric, so two copies placed side by side read as identical twins, not as "facing each other" or "moving in a direction." Wrap a copy in `<g transform="translate(x y) scale(-1,1) translate(-w 0)">` (mirror around its own width `w`) when a scene needs orientation or facing — e.g. two figures flanking a shared object read more intentionally when mirrored toward it.
+- **When a concept needs to distinguish multiple actors of the same kind** (two different people's cursors, two competing options), don't reach for a third color — that breaks the two-color rule this whole system depends on. Vary fill-vs-outline instead: one instance solid-filled in the base color, the other outlined in the base color with an accent fill. This preserves the two-color contract while still making two things visually distinct.
+
+## What this style is not
+
+Be upfront about this rather than overclaiming: this produces clean, simple, geometric flat illustration — closer to a flat icon-illustration hybrid than to unDraw's own more detailed, organically-posed artwork. It's a legitimate, widely-used register (plenty of real products ship exactly this level of simplicity) and it composes and recolors reliably, which is the actual point — but it is not a pixel-for-pixel match to any specific illustrator's hand-drawn style, and shouldn't be presented as one.

package/skills/tastemaker/ideagram/references/style-dna.md

@@ -0,0 +1,43 @@
+# Style DNA (generation path)
+
+This is the style contract for **generating** original illustrations with an image model — the path that lifts ideagram past "recolor what's in the library" to "create a beautiful, on-brand illustration for any concept." Every generated image obeys this DNA so a set of them reads as one designed system, not assorted stock art.
+
+The aesthetic target is *modern editorial flat illustration* — the register of unDraw, Storyset, and top SaaS marketing sites: clean, confident, characterful, a little bit art-directed. Not corporate clip art, not AI-slop.
+
+## One sentence
+
+Clean modern flat-vector illustration on a calm background: proportioned, characterful people or a single strong metaphor object, one confident brand accent against a restrained neutral palette, generous whitespace, one clear focal point — the kind of image a tasteful design studio would ship on a product's landing page.
+
+## Must
+
+- **One idea per image.** Depict a single concept, action, or metaphor — not a busy montage. If the brief has two ideas, that's two images.
+- **One clear focal point**, carried by the brand accent. The eye should land in one place first.
+- **A real scene, not a floating object.** Ground the subject: a surface, a soft background shape, a subtle shadow, a suggested environment. (See `composition-patterns.md` — this is the thing amateur output most often misses.)
+- **Generous whitespace / calm negative space** — the subject occupies ~50–65% of the frame; the rest breathes.
+- **Proportioned characters** when people are used: natural ~7–8 head proportions, relaxed poses, simple faces. People should look designed, not deformed.
+- **Cohesive palette:** a restrained set of neutrals + skin tones + exactly one **brand accent** color (passed in per request). The accent is the only saturated color and it lands on the focal point.
+- **Consistent light, flat rendering:** soft flat shapes, gentle long shadows or a single soft drop shadow at most — depth through layering and one subtle shade, not heavy 3D.
+
+## Palette model
+
+- **Neutrals:** off-white/very-light background, mid-grey and charcoal for structure and line, near-black sparingly.
+- **Skin/organic:** natural muted skin tones (never one flat silhouette for a person).
+- **Accent:** ONE brand color (the request's hex). It is the loudest thing in the frame and marks the focal point. Optionally one *tint/shade* of it for a secondary surface — never a second unrelated hue.
+- Restraint beats variety. If a third color feels needed, the scene is trying to say too much — simplify.
+
+## Absolutely never (the anti-slop list)
+
+These are the tells that make generated illustration look cheap or generic — forbid them explicitly in every prompt:
+
+- No rainbow/multi-hue palettes; no indigo→purple or blue→cyan default gradients.
+- No glossy 3D, no bevels, no drop-shadow-everywhere, no glassmorphism, no neon glow.
+- No busy or textured backgrounds, no photo-collage, no realistic photography mixed in.
+- No corporate clip-art, no generic "diverse team high-fiving," no stock-vector stiffness.
+- No cute children's-book or mascot-poster cartooniness (unless the brand is explicitly playful).
+- No dense infographic / PowerPoint / flowchart-with-every-node-labeled look.
+- No text baked into the image unless a label is essential (and then ≤3 short words).
+- No deformed hands/faces — prefer simple, confident features over ambitious detail that breaks.
+
+## Aesthetic direction
+
+Confident, tasteful, a little bit clever. Clean but not sterile; simple but not empty; characterful but not busy. It should feel *art-directed by someone with taste*, not auto-generated. When in doubt: fewer elements, more whitespace, one strong idea, one accent.

package/skills/tastemaker/ideagram/references/undraw-anatomy.md

@@ -0,0 +1,49 @@
+# unDraw anatomy — how the real illustrations are built, and how to reuse them
+
+This is the result of dissecting real unDraw SVGs. The headline finding: **you cannot hand-author illustration at this quality, and you don't need to.** Every unDraw figure is dozens of hand-placed bezier anchors drawn in Illustrator by a professional (Katerina Limpitsouni) — freehand-generating those coordinates produces pictograms, not illustration. The quality is *in the path data*. So the skill's job is to **reuse the real path data** — recolor whole illustrations to a brand, and compose whole real components into new scenes — not to redraw.
+
+## The real palette
+
+Extracted by frequency across a corpus of unDraw SVGs:
+
+| Hex | Role |
+|---|---|
+| `#090814` | Near-black ink — outlines, hair, trousers, the dominant "dark" |
+| `#6c63ff` | **The accent** — the one purple that defines each illustration's "pop" (screens, logos, highlights). This is the ONLY color you swap for a brand. |
+| `#e6e6e6` | Light grey — shirts, background panels, the ground-shadow ellipse |
+| `#ed9da0` | Skin (also `#9f616a`, `#a0616a`, `#ffb6b6`, `#fbbebe`, `#e8989b` — unDraw uses several skin tones) |
+| `#3f3d56` / `#3f3d58` / `#2f2e41` | Dark clothing / hair variants |
+| `#d6d6e3` | Light lavender-grey — subtle shading |
+| `#8ed16f`, `#ff6584` | Occasional secondary accents (green, pink) |
+
+**Shading technique:** unDraw layers semi-transparent black (`opacity="0.05"`–`0.2"`) over a base fill to create shadow tones, rather than defining a separate darker hex. That's why the shading looks cohesive.
+
+## How a figure is structured
+
+A figure is one `<g transform="translate(x y)">` group. Inside, in rough back-to-front order: back limbs → trousers/legs (`#090814`) → torso/jacket (`#3f3d56`) → shirt (`#e6e6e6` or the `#6c63ff` accent) → arms + hands (skin) → neck → head (a skin `circle`) → hair (one intricate `#090814` bezier path over the head). The hair and hands are the most detailed paths — and the hardest to fake, which is exactly why you reuse them rather than draw them.
+
+## A whole illustration is a SCENE, not a floating figure
+
+This is the biggest thing the old primitive approach got wrong. A real unDraw illustration is layered:
+1. **Background** — a large light panel, a big screen, a window, or an abstract shape (`#e6e6e6` / faint accent), often the biggest element.
+2. **Midground** — the device/object the scene is about (a phone, monitor, chart), carrying the accent.
+3. **Figure(s)** — often *smaller* than you'd expect, positioned relative to the background element, interacting with it.
+4. **Decorative bits** — a plant, floating dots, small shapes, a ground shadow.
+
+A figure alone on white reads as unfinished. The background + midground are what make it a designed illustration. When composing, always build the scene, not just the person.
+
+## The two reliable operations (and one fragile one)
+
+**Reliable — recolor a whole illustration to a brand.** Use `scripts/recolor_undraw.py --accent "#hex"`. It swaps only the `#6c63ff` accent family, leaving skin/ink/greys/clothing exactly as drawn. Verified on real multi-figure scenes: perfect. This alone delivers unDraw-quality, on-brand illustration with zero drawing.
+
+**Reliable — transplant a whole component into a new scene.** A whole figure group, or a whole background/device group, lifts cleanly:
+1. Find the component's `<g transform="translate(...)">` in the source.
+2. Extract it with brace-matching (`<g>`…`</g>` depth counting), keeping any parent `transform` that positions it.
+3. Drop it into a fresh `<svg>`, wrapping in a `<g transform="translate()/scale()">` to place and size it. Measure the real bounds with the browser's `getBBox()` on the group rather than guessing the viewBox — nested transforms make eyeballing wrong.
+4. Recolor to brand.
+
+**Fragile — recombining sub-parts** (grafting an arm from figure A onto torso B). Each sub-part is drawn in its own coordinate space, angle, and shading direction, so they don't cleanly connect and it looks like a Frankenstein. Avoid unless you're prepared to hand-fix the join. Reuse whole figures instead.
+
+## Why this beats the old "draw from primitives" approach
+
+The old approach hand-built figures from circles + capsules + two colors → pictograms with no finesse, no scene, no depth. This approach reuses the actual illustrator's vector work → genuine unDraw quality, because it *is* unDraw. The skill's value moves from "drawing" (which it's bad at) to "matching + recoloring + composing" (which it's reliable at).