# Visual Identity — Agilie

Extends `smm/base.md`. Reference this skill whenever generating any visual asset
(LinkedIn graphics, X posts, carousels, illustrations) for Agilie. Verbal
copywriting rules continue to live in `smm/linkedin.md` and `smm/twitter.md`.

All asset URLs and metadata referenced below are indexed in:
**`https://assets.digitalstudiosoftware.com/brand/agilie/manifest.json`**

Fetch the manifest at the start of any visual generation task. As of schema 1.0+, every non-SVG asset includes AI-generated **enrichment** metadata: `ai_description`, `tags`, `metaphors` (for illustrations), `best_for` / `avoid_for` (for photos and illustrations), `combines_well_with` (for compositional pairing), and other category-specific fields. Use this enrichment to select assets semantically — match the topic of the post to `metaphors` and `tags`, match the post context to `best_for`. Do NOT pick assets by filename guesswork when enrichment is available.

---

## How to invoke this skill

Two interfaces are supported, both producing equivalent quality output:

**Goal-first (default).** Describe what you want; skill picks the pattern.
- "Make a LinkedIn post announcing our new AI consulting service"
  → routes to `marketing-hero`
- "Create a comparison post: monolith vs microservices"
  → routes to `educational-card`
- "Wish the team Happy Easter"
  → routes to `holiday`

**Pattern-first (override).** Name the pattern explicitly to force it.
- "Generate a `stat-card` listing 5 reasons to adopt fintech"
- "Build a `carousel` of 5 slides using `marketing-hero` style"
- "Use `editorial` pattern for this hot take on AI agents"

If a request is ambiguous, ask which pattern fits best rather than guessing.

---

## Output expectations (read this before generating)

AI-generated visuals from this skill are **drafts**, not final brand-quality
output. Always set this expectation when delivering generated work.

**What AI handles well:**
- Color palette adherence
- Layout structure and proportions
- Typography role separation (which font for which slot)
- Asset URL injection from manifest
- Text content placement

**What AI handles poorly (require human polish):**
- Letter-spacing and kerning at display sizes
- Precise icon alignment in dense layouts
- Custom logo compositions (monogram interacting with illustrations)
- Photorealistic photo composites with text
- Hand-drawn illustration style consistency with brand library

**Recommended generation paths per pattern:**

| Pattern | Primary tool | Secondary | Final polish |
|---|---|---|---|
| marketing-hero | Claude SVG | gpt-image-1 (if photo composite) | Canva |
| educational-card | Claude SVG | — | Canva (optional) |
| stat-card | Claude SVG | — | Canva (optional) |
| holiday | gpt-image-1 | Claude SVG (text overlay) | Canva |
| people-spotlight | gpt-image-1 (base) + Claude SVG (text) | — | Canva (recommended) |
| editorial | None — use real photo or text-only | — | — |
| insights-hub | gpt-image-1 | Claude SVG (text) | Canva (recommended) |

For high-stakes posts (press releases, MWC-grade campaigns, executive content),
recommend the user have a designer create custom assets rather than relying on
AI generation alone.

---

## Universal constraints (apply to ALL patterns)

### Color palette

Six colors with assigned roles. Never substitute. Never invent new ones.

| Role | HEX | When to use |
|---|---|---|
| Primary background | `#004C3F` | Default dark canvas. Marketing posts, carousel backs, holiday darks. |
| Alt dark | `#001F1F` | Dark text on light backgrounds. Sparingly as alternative dark canvas. |
| Light card | `#F9F8F5` | Default light canvas. Holiday lights, comparison post backgrounds. Never use pure `#FFFFFF`. |
| Accent illustration | `#FE9E94` | Salmon for: CTA buttons, "disadvantages" / challenges in comparisons, sketch illustration accents. Max 1–2 elements per composition. |
| Accent detail | `#FFDF49` | Yellow for: numbers, statistics, single-word headlines, marker-highlight rectangles behind names. Especially effective on dark green. |
| Text on dark | `#FFFFFF` | Text and logo on dark backgrounds. |

**Combination rules:**
- Default dark: `#004C3F` + `#FFFFFF` text + optional `#FFDF49` numeric highlight
- Default light: `#F9F8F5` + `#001F1F` text + optional `#FE9E94` illustration accent
- Never use three accent colors (yellow + salmon + something else) in one composition. Pick one accent.
- Never use pure black `#000000` — always `#001F1F` for warmth.
- Never use pure white `#FFFFFF` as background — always `#F9F8F5`.

### Derived shades (for decorative elements only)

When a pattern calls for "lighter shades of #004C3F" (e.g. blob decorations in marketing-hero), use these specific values rather than improvising:

| Shade | HEX | Use for |
|---|---|---|
| Primary +10% lightness | `#0A6651` | Blob fill at 30–40% opacity (default for marketing-hero blobs) |
| Primary +20% lightness | `#1B7D67` | Blob fill at 20–30% opacity (subtle layering) |
| Primary +30% lightness | `#2D947D` | Blob fill at 15–20% opacity (very subtle) |

Always use these with opacity 15–40% — never solid. They are atmospheric, not focal. Do not introduce new derived shades — these three cover all decorative needs.

If a pattern requires a specific shade not listed here, use a brand asset from `shapes/blobs-strokes/` (e.g. `decor-blob-dark-green-lg.png`) instead of inventing a new color.

### Typography

Two fonts with strict role separation.

**Poppins** (display): hero headings, big numbers, single-word emphasis. Bold for H1 (72–96px), Medium for H2 (40–48px). Geometric sans-serif rhymes with the brand monogram.

**Inter** (text): body, captions, long-form content. Use optical sizes by rendered size:
- Inter 28pt for ≥24px (section headers)
- Inter 24pt for 18–22px (body large, quotes, mid-range)
- Inter 18pt for ≤16px (body, captions, small text)

**Rule:** match Inter optical size to rendered size. Never use Inter 18pt at 28px or Inter 28pt at 12px.

### Font embedding for SVG output (CRITICAL)

SVG artifacts in browsers do NOT load Poppins or Inter automatically. Without embedding, fonts fall back to Helvetica/Arial — which destroys brand recognition. Always include this `<style>` block at the top of every generated SVG:

```svg
<defs>
  <style type="text/css">
    @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&amp;family=Poppins:wght@400;500;700&amp;display=swap');
  </style>
</defs>
```

Important notes:
- The `&amp;` (not raw `&`) is required for SVG XML validity
- `display=swap` allows fallback during font load (text appears immediately, swaps to brand font when ready)
- Without this block, the SVG looks "off-brand" even though all other rules are followed
- This applies to all 7 patterns when generating Claude SVG output

**For PNG/JPG export from SVG** (e.g. for LinkedIn upload): the embedded fonts will be rasterized correctly only if the export tool renders the `<style>` block. Test by exporting a 100×100 sample with "Hello" in Poppins Bold — if it looks geometric/rounded, fonts loaded; if it looks like Helvetica, the export tool ignored embedded fonts and you need to use Canva for production export.

### Logo selection

Always include logo. Match version to background:
- Light backgrounds (`#F9F8F5`, `#FFFFFF`): use `badge-dark.svg` or `icon-only-green.svg`
- Dark backgrounds (`#004C3F`, `#001F1F`): use `badge-light.svg` or `icon-only-white.svg`
- Multi-asset posts (carousels, complex graphics) often place wordmark in a **dark pill badge** as footer (light pill on dark bg, dark pill on light bg)
- Min sizes: 24px for icon-only, 80px width for badge

URLs: see `manifest.json#categories.logo.variants`.

### Asset selection — formal scoring algorithm (v1.5+)

Every non-SVG asset has AI-generated enrichment fields. Selection uses a **deterministic scoring algorithm**, not free-form filtering. Run it explicitly for each illustration/photo/asset slot.

#### Step 1 — Extract topic keywords (NOT audience)

Topic = "what the post is ABOUT". Audience = "who reads it". **Audience must NOT contribute to keyword set** — it doesn't influence which illustration fits the topic.

1. Take user's request verbatim.
2. **Strip audience phrases.** If request contains `"for [audience]"` or `"to [audience]"` patterns where the marker appears AFTER topic content, cut everything from the marker onwards before extracting keywords.
   - Example: `"Comparison of Monolith vs Microservices for FinTech CTO audience"` → topic part = `"Comparison of Monolith vs Microservices"`. The `"FinTech CTO audience"` part is dropped.
3. From the topic part, tokenize. Remove articles (a/an/the), prepositions (in/on/at/of/for/to/with/from/by/as), pronouns (we/our/you/your/this/that), conjunctions (and/or/but).
4. For each remaining token, **expand via the brand-context Synonym Table** (below). Each entry maps a user term to validated asset-vocabulary equivalents.
5. Keywords = union of original tokens + all synonym expansions.

#### Step 2 — Score every candidate asset

For each candidate asset in the relevant manifest folder, compute:

```
meta_match  = |keywords ∩ enrichment.metaphors|
tag_match   = |keywords ∩ enrichment.tags|
slot_match  = 1 if enrichment.composition_hint matches required slot OR equals "any"
              else 0
combo_match = 1 if any category in enrichment.combines_well_with appears
              in composition_so_far else 0

score = 2 * meta_match + 1 * tag_match + 1 * slot_match + 1 * combo_match
```

Metaphors are weighted **2×** because they carry semantic intent; tags are **1×** because they're surface descriptors. Slot and combo are bounded **0/1** signals.

#### Step 3 — Decision rules

Sort candidates by score descending. Then:

1. **If top score < 2** → ASK USER. No good match exists; don't force a pick.
2. **If top score >= 2 AND second-place score / top-place score < 0.85** → AUTO-PICK top.
3. **If top score >= 2 AND ratio >= 0.85** → ASK USER between top 2-3 candidates. Top scores are too close to choose deterministically.

Never silently pick something irrelevant. Never pick from filename guesswork when enrichment is available.

#### Step 4 — Bilateral exclusion (when picking 2 illustrations for one composition)

For bilateral comparisons (educational-card variant D), pick 2 illustrations — one per zone:

1. Score LEFT zone keywords against manifest.
2. Score RIGHT zone keywords against manifest.
3. **Pick the zone with the higher max score FIRST** (stronger signal = less ambiguity).
4. Apply Step 3 decision rules to that zone, get the pick.
5. Score the OTHER zone with the first pick **excluded from candidates**.
6. Apply Step 3 decision rules to that zone too.
7. Sanity check: LEFT pick != RIGHT pick. If equal despite exclusion, BUG — re-run with explicit exclude set.

#### Step 5 — Number selection (FILENAME-FIRST, not enrichment)

Number assets in `shapes/numbers/files` follow naming pattern `num-{color}-{digit}.png`. The filename is **ground truth** for digit value — Vision-derived enrichment for digits has historically been unreliable (hand-drawn digits are hard to recognize at small resolution).

When selecting numbers for stat-card numbered list:
1. Parse target digit from request (e.g. "5 reasons" → digits 1, 2, 3, 4, 5).
2. For each digit N, search `shapes/numbers/files` where:
   - filename matches `num-{any}-{N}.png`
   - `enrichment.color_variant` matches composition palette (yellow on dark green canvas, dark/green on light canvas)
3. Pick first match.

**Never type numerals as text** — always use brand asset PNG.

#### Step 6 — Photo selection refinements (people-spotlight)

For multi-photo person folders, additionally to Step 1-3 algorithm:

1. Filter where `enrichment.best_for` matches context (e.g. "birthday card", "executive content", "team feature").
2. Filter OUT where `enrichment.avoid_for` matches context.
3. **Apply person_count refinement:**
   - Personal birthday or solo spotlight → require `person_count == 1`
   - Team feature → `person_count == 1 OR == 2` OK
   - Group/team photo → `person_count >= 3`
4. Apply Step 3 decision rules to remaining photos.

If 0 candidates survive: fall back per pattern rules. For people-spotlight specifically, this means cannot proceed — ASK USER to provide a photo or skip pattern.

### Brand-context Synonym Table

This table maps user vocabulary to asset-vocabulary equivalents. Right-side terms are **validated against the actual manifest** — every synonym must match real metaphors/tags in current asset library. Out-of-domain concepts (e.g. logistics, SaaS) are intentionally absent because manifest doesn't contain illustrations for those.

| User concept | Asset vocabulary expansions |
|---|---|
| **Domains** | |
| fintech | fintech, finance, financial, payment, transaction, banking, money, investment |
| eventtech | community |
| iot | automation |
| ai | automation, innovation |
| **Comparison** | |
| comparison, vs, compare, differences | comparison, choice, integration, fit |
| pros and cons | comparison |
| **Team / people** | |
| team | team, teamwork, collaboration, people |
| in-house | team, teamwork, people |
| outsourcing | partnership, collaboration |
| partnership | partnership, collaboration, integration, connection, fit |
| collaboration | collaboration, partnership, teamwork |
| hiring, recruitment | team, people, recruitment |
| developer, engineer | team, expertise |
| cto, ceo, leadership | leadership, expertise |
| **Growth** | |
| scaling, growth, expansion | growth, progress, expansion, success |
| launch, startup, product launch | launch, product launch, innovation, debut |
| momentum | growth, progress, launch |
| **Security** | |
| security, protection, safety | security, protection, privacy, safety, data protection, defense, authentication |
| compliance | security, protection, approval, checklist |
| privacy, gdpr | security, privacy protection, data protection |
| vault | security, protection, secure storage |
| **Process** | |
| process, methodology, workflow | process, cycle, iteration, methodology, productivity, organization |
| pipeline, flow | process, cycle, flow |
| agile, iteration | process, iteration, cycle |
| discovery, research | discovery, insight |
| **Idea / innovation** | |
| idea, innovation, concept | innovation, ideation, creativity, eureka moment, creative solution |
| strategy, planning | innovation, expertise |
| inspiration, lightbulb | innovation, idea, eureka moment |
| **Solutions** | |
| solution, fix | solution, unlocking solutions, problem solving |
| problem, challenge | problem solving, challenge |
| access, unlock | access, unlocking solutions |
| **Content** | |
| content, blog, article | content, content creation, authorship, editorial |
| podcast | content, voice, editorial |
| tutorial, guide, how-to | learning, education, knowledge |
| explainer, reading | reading, content consumption, editorial |
| **Achievement** | |
| achievement, success, milestone | success, achievement, milestone, approval |
| celebration, anniversary, birthday | celebration, success, positive |
| win | success, achievement, approval |
| **Trust** | |
| trust, expertise | trust, trust building, expertise, knowledge |
| testimonial, review, endorsement | testimonial, voice, trust, approval |
| **Data** | |
| data, analytics, metrics, insights | insight, discovery, editorial |
| report | editorial, content, insight |
| **Tech / engineering** | |
| architecture, monolith, microservices, api, integration, cloud | integration, fit, connection |
| **Business** | |
| business, partnership, investment | business, partnership, investment, financial growth |
| roi, value | investment, success, positive |
| productivity | productivity, task completion, organization |

When extending this table for new domains: validate every right-side term exists in actual manifest metaphors+tags before adding. Untracked terms produce silent zero-matches.

### Worked example

Request: `"Comparison of Monolith vs Microservices for FinTech CTO audience"`, pattern educational-card.

Step 1: Strip `"for FinTech CTO audience"` → topic = `"Comparison of Monolith vs Microservices"`. Tokenize and expand: `{comparison, monolith, microservices, vs, choice, integration, fit}`.

Step 2: Score `illustrations.objects` against keywords. Top results:
- `puzzle-2piece` score 6 (meta=integration, tags=fit+integration, slot+combo=2)
- `puzzle-3piece` score 5
- Others ≤ 2

Step 3: Top score 6, ratio 5/6 = 0.83 < 0.85 → AUTO-PICK puzzle-2piece.

This is the canonical worked example for the algorithm — refer back when in doubt.

### Asset combination logic (v1.4+)

The `enrichment.combines_well_with` field on illustrations and components lists asset CATEGORIES that pair naturally. Use this for richer compositions, not just main illustration + logo.

When generating any pattern that uses a central illustration:
1. Look at the chosen illustration's `enrichment.combines_well_with`.
2. If it lists `shape_sparkle`: add 2–4 sparkles around the illustration. Pick from `shapes/sparkles-stars/files` filtered by `enrichment.color_variant` matching the composition palette. **Respect `max_per_composition`** from the sparkle's enrichment.
3. If it lists `shape_blob`: add 1–3 blobs as atmospheric background. Use derived shades from Universal Constraints, not solid colors. **Respect `max_per_composition`**.
4. If it lists `shape_number`: pair with a numbered presentation (e.g. "Reason 1 / 2 / 3" labels with `num-yellow-N.png` images, not typed digits).
5. If it lists `ui_element` or `component`: consider wrapping content in a card frame from `ui-elements/rect-outlines/` or using a banner from `components/`.

Example: For a marketing-hero post about product launch, you'd choose `comp-rocket-launch.png` as the focal illustration. Its enrichment shows `combines_well_with: [shape_sparkle, shape_blob, shape_pill]`. So the composition becomes: rocket center-right, 3 sparkles scattered (max per sparkle is 3-5), 2 background blobs at low opacity, a salmon CTA pill at bottom-left. The combination is enrichment-driven, not improvised.

**Boundary:** the combination should reinforce, not crowd. If `max_per_composition` is 3-5 for sparkles, do not also add 4 asterisks "for variety" — that violates "three accent colors in one composition" anti-pattern. Pick one accent decoration type per composition, then layer atmospheric blobs separately.

### Headline line-break logic

When a headline exceeds single-line capacity at chosen size, break by these rules in priority order:

1. Break on natural phrase boundaries (after preposition, before main subject)
2. Keep proper nouns, brand names, and dates together on the same line
3. Don't end a line with an article ("the", "a", "an"), conjunction ("and", "or"), or preposition unless absolutely necessary
4. Prefer balanced line lengths (top line shouldn't be 80% width while bottom is 30%)
5. Maximum 3 lines for hero headlines; if exceeds, ask user to shorten

Example: "Sergey Gladun speaks at TechArena 2027" (38 chars at 88px)
- ❌ "Sergey Gladun" / "speaks at TechArena 2027" (unbalanced, breaks event name)
- ❌ "Sergey Gladun speaks" / "at TechArena 2027" (ends line with verb, awkward)
- ✓ "Sergey Gladun speaks at" / "TechArena 2027" (proper noun intact, balanced)

### Proportional sizing principle (v1.5+)

Express element sizes as **% of canvas dimensions**, not absolute pixels. This way layouts scale to any canvas size (1080×1080, 1080×1350, 1200×1500) without recomputation. When generating SVG, compute pixel values from canvas at runtime: `headline_size = canvas_height * 0.056`.

| Element | % of canvas | At 1080×1080 |
|---|---|---|
| Headline (Poppins Bold) | 5.5% canvas height | 60px |
| Card title (Poppins Medium) | 3.0% canvas height | 32px |
| Body bullet text (Inter SemiBold) | 2.2% canvas height | 23px |
| Icon (checkmark, xmark, sparkle) | 4.0% canvas height | 43-44px |
| Logo width | 22% canvas width | 240px |
| CTA pill width | 24% canvas width | 260px |
| CTA pill height | 5.5% canvas height | 60px |
| Header strip height | 18% canvas height | 200px |
| Footer strip height | 10% canvas height | 110px |

For body text on social media: minimum **2.0% canvas height** (~22px at 1080) to remain readable on mobile feed scroll. **Never use 1.5% (~16px) or below for body content** — it's unreadable on mobile.

### Visual weight balance principle (v1.5+)

Two-zone composition rule: if your layout has a left zone and a right zone (or top/bottom), the visual mass of each zone should be approximately equal. "Visual mass" ≈ filled area × contrast intensity.

- One large illustration (~95% of zone) ↔ stacked cards filling other zone vertically = balanced
- Small illustration in large zone with empty space = unbalanced (avoid)
- Small text in large card with empty space = unbalanced (cards must size to content, see formula below)

**Density target:** content area should occupy **80-90% of canvas** (excluding margins). If composition has more than 15% empty space inside the bleed area, increase element sizes proportionally rather than leaving void.

### Text fit verification (v1.5+)

Before finalizing any layout with bullet text inside cards, **compute text budget explicitly**:

```
text_budget = card_width - card_pad_left - card_pad_right - icon_width - icon_text_gap
max_chars_at_size = text_budget / (font_size * 0.55)
```

The 0.55 multiplier estimates Inter SemiBold average char width as ~55% of font size in pixels.

If any bullet exceeds `max_chars_at_size`:
1. **Preferred fix**: shorten the bullet (most SMM bullets can be tightened without losing meaning).
2. **Secondary fix**: drop body font size by 1-2px (e.g. 23px → 21px).
3. **Last resort**: widen the card (rebalances layout).

Never let text overflow the card boundary — that's a generation bug.

### Bullet row sub-template (used by educational-card and stat-card)

Each bullet line follows proportional measurements. Apply uniformly within a composition:

- Row height: `icon_size + 0.022 * canvas_height` (icon + breathing room)
- Icon: positioned at `card_pad_left` from card edge, vertically centered in row
- Text: starts at `icon_x + icon_size + 0.015 * canvas_width` (small gap)
- Text vertical: baseline at `row_y + row_height/2 + body_size/3` (visually centered)
- Row gap between consecutive bullets: `0.011 * canvas_height` (~12px at 1080)
- **Text wrapping: NEVER wrap.** Apply text fit verification rule above; shorten bullet if needed.

### Card sizing — fit to content

Cards size to actual bullet count, never fixed height with empty space:

```
card_height = card_pad_top
            + title_height
            + title_to_first_row_gap
            + (n_bullets * row_height)
            + ((n_bullets - 1) * row_gap)
            + card_pad_bottom
```

If two cards stack with different bullet counts (e.g. 3 advantages + 2 disadvantages), allow each to size independently — visual asymmetry is honest. Don't pad smaller card to match larger.

### Photo selection from multi-photo folders (updated v1.4)

When `photos/individuals/[person]/` contains multiple shots, use the enrichment-driven algorithm from "Asset selection from enriched manifest" above. The flow:

1. Determine post context from request (e.g. "birthday card", "executive content for marketing-hero", "editorial about remote work").
2. Filter photos in the person's folder where `enrichment.best_for` matches the context **and** `enrichment.avoid_for` does NOT match.
3. **If exactly one photo matches**: use it without asking. Auto-pick is correct here — the enrichment provides strong evidence.
4. **If 2+ photos match**: present candidates to the user with their `enrichment.framing`, `enrichment.expression_mood`, and a brief `enrichment.ai_description` excerpt. Wait for user choice.
5. **If 0 photos match**: fall back per pattern (e.g. marketing-hero: skip photo, use blob composition; people-spotlight: cannot proceed without portrait — ask user how to handle).

Examples:

- Request: "Birthday card for Sergey" → filter `photos/individuals/sergey/` where `best_for` contains "birthday card". If 2 candidates: present both with framing info; let user pick.
- Request: "Executive content for AI consulting launch" → filter where `best_for` contains "executive content". If only photo-040 matches: use it.
- Request: "Editorial about remote work" → filter where `best_for` contains "remote work". photo-008 has `best_for: ["...", "remote work content", ...]` → auto-pick.

If the person's folder is empty for the requested person, fall back per pattern rules. If no enrichment is present (legacy assets), revert to the v1.3 "mandatory ask" behavior — present 2-3 candidates by filename and ask user.

**Why this is safer than v1.3 mandatory-ask**: With enrichment, the model has explicit evidence (`best_for` lists) for which photo fits. Auto-pick on a single clear match is faster and equally accurate. Multi-match still asks. No-match still falls back gracefully.

### Universal forbidden

These never appear in Agilie content, regardless of pattern:
- Stock photos of generic smiling people / corporate teamwork imagery
- Glowing-circuit "tech" backgrounds, abstract blue networks, hexagon meshes
- AI-generated faces resembling real people
- Pure black or pure white as primary surfaces
- Three accent colors in one composition
- Sans-serif other than Poppins or Inter
- Generic icon sets (Material, Font Awesome) — use brand assets only
- Mascots (pig, robot-crown) used more than once per post
- Asterisk shapes used as page-filling pattern (they are accents, not wallpaper)
- Mixed icon weights in one composition (no bold + thin checkmarks together)

---

## Pattern selection (decision tree)

When the user does not name a pattern explicitly, route by trigger words in the request:

| Request signal | Pattern |
|---|---|
| "launch / announce / partner / new program / introducing" | `marketing-hero` |
| "vs / compare / pros and cons / how-to / what is / explain" | `educational-card` |
| "benefits / N reasons / N ways / metrics / stats / why" | `stat-card` |
| Calendar holiday name (Easter, Halloween, Thanksgiving, Christmas, NY) | `holiday` |
| "happy birthday / N years / anniversary / [person name]" | `people-spotlight` |
| "hot take / news / repost / event recap / our thoughts" | `editorial` |
| "insights hub / episode / podcast / recap series" | `insights-hub` |

If multiple signals present, ask user which to prioritize. If carousel is requested, pattern applies to all slides unless user specifies mixed.

---

## Pattern 1: `marketing-hero`

**Use for:** Major announcements, program launches, service introductions, MWC-style B2B campaigns, conversion-driven content.

**Recommended generation:** Hybrid (Claude SVG draft → optional gpt-image-1 for hero photo composite → Canva polish for production).

### Input requirements

This pattern requires the following from the user. If any are missing, ASK before generating — never invent.

**Mandatory:**
- Headline (max 8 words for impact)
- Subline (12–18 words explaining value)
- CTA button label (2–4 words, e.g. "Early access", "Learn more")
- CTA destination URL (or note "TBD" if user hasn't decided)

**Optional (will use defaults if missing):**
- Hero photo (default: solid composition with blob shapes only)
- Specific blob count and positions (default: 3 blobs right-bleed)

**Never invent:** statistics, percentages, claimed metrics, client names, or technical specifics the user hasn't provided.

### Visual signature

Dark green canvas dominates. Large Poppins Bold headline left-aligned. Decorative blob shapes on right (organic green gradients, no hard edges). Optional photo of CEO right-bleed. Salmon CTA pill button in lower-left of headline area. Wordmark in upper-left.

### Color palette
- Background: `#004C3F`
- Text: `#FFFFFF`
- Accent (CTA only): `#FE9E94`
- Decorative blobs: lighter shades of `#004C3F` (use `manifest#categories.shapes.blobs-strokes`)

### Typography
- Headline: Poppins Bold 72–96px, white
- Subline: Inter 24pt Regular 22–26px, white at 80% opacity
- CTA button text: Poppins Medium 18–22px, dark green on salmon background

### Required assets
- `logo/badge-light.svg` upper-left (or `icon-only-white.svg` for tighter compositions)
- 1–3 blob shapes from `shapes/blobs-strokes/decor-blob-dark-green-*.png`
- Optional: photo of Sergey from `photos/individuals/sergey/` for hero compositions
- Optional: pill or rect outline from `ui-elements/` for sub-content blocks

### Layout template
```
┌────────────────────────────────────────────┐
│ [logo upper-left]                          │
│                                            │
│  HEADLINE GOES HERE                  ◯◯    │
│  IN TWO OR THREE LINES                ◯    │
│                                       ◯◯   │
│  Subline explaining the value.             │
│  Limit to 12–18 words.                     │
│                                            │
│  [salmon CTA pill]                         │
│                                            │
│ https://agilie.com  ─────────────  page #  │
└────────────────────────────────────────────┘
```

### Reference examples
"All-Inclusive Partner Program" carousel slide 1, "5-10% Cash Bonus + Free Design & Developers Hours" callout slide.

### Generation path decision

Choose primary tool based on photo source:

- **Real photo from manifest exists** (e.g. Sergey for executive content):
  → Use Claude SVG with `<image href="..." />` tag pointing at manifest URL. Skip gpt-image-1. The photo composes natively in SVG.

- **No real photo, need synthetic hero scene:**
  → Use gpt-image-1 to generate the photo composition (background + figure), then add Claude SVG text overlay for headline/subline/CTA. Compose in Canva for production polish.

- **Photo composite needed** (real photo + complex effects like double exposure, custom gradients beyond simple linear overlay):
  → Use gpt-image-1 with photo reference for the composite, then SVG overlay.

For 90% of marketing-hero requests with real Agilie photos, plain Claude SVG suffices — gpt-image-1 is the exception, not the rule.

### Generation prompts

**Claude SVG/HTML artifact:**
```
Generate a 1080x1080 SVG. Background fill #004C3F. Top-left: place
brand wordmark from https://assets.digitalstudiosoftware.com/brand/
agilie/logo/badge-light.svg sized 140px wide. Headline in Poppins
Bold 88px white, max 3 lines, left-aligned at x=80, y=380. Subline
in Inter 24pt Regular 22px white 80% opacity, 2 lines max. CTA
pill: salmon #FE9E94 rounded-full, padding 18px 36px, label in
Poppins Medium 18px dark green #001F1F. Right side: 3 organic
circles in shades of #004C3F (slightly lighter) at 40% opacity,
positioned right-bleed, sized 280px / 200px / 160px diameter.
```

**OpenAI gpt-image-1:**
```
LinkedIn brand graphic, 1:1 square format, deep forest green
background (#004C3F), large bold sans-serif white headline
left-aligned, soft semi-transparent organic green circles flowing
from right edge, salmon-pink rounded button in lower portion,
clean editorial composition, professional B2B aesthetic, no
people, no stock imagery. Style: minimalist corporate, generous
whitespace.
```

---

## Pattern 2: `educational-card`

**Use for:** Comparisons (X vs Y), pros/cons listicles, definitional content, how-to walkthroughs, methodology explanations.

**Recommended generation:** Claude SVG (structural layout, predictable output).

### Input requirements

**Mandatory:**
- Topic / comparison subject (e.g. "React vs Vue", "Monolith vs Microservices")
- 2–4 advantages as bullet points, max 8 words each
- 2–4 disadvantages as bullet points, max 8 words each (or omit if pure how-to)

**Optional:**
- Specific illustration choice (default: pick from manifest based on topic metaphor)
- CTA text (default: no CTA in educational-card; use "Read more →" if URL provided)
- Headline override (default: auto-format as "TOPIC: HOW THEY DIFFER")

**Never invent:** factual claims about technologies, statistics, "most developers prefer X" claims, or any opinion the user hasn't stated.

### Visual signature

Mostly light card layout (`#F9F8F5`) split into 2-4 zones. Hand-drawn outline illustration as central anchor (no photo, no fill — outline only). Yellow Poppins headline. Each zone has its own card with checkmarks (`#004C3F`) for advantages and salmon X-marks (`#FE9E94`) for disadvantages. Inter for body text.

### Color palette
- Background: `#F9F8F5` (or `#004C3F` for "header" panel if split)
- Text: `#001F1F`
- Headline accent: `#FFDF49`
- Disadvantage accent: `#FE9E94`
- Checkmark color: `#004C3F`

### Typography
- Headline: Poppins Bold 48–72px in `#FFDF49` if on dark, else `#004C3F`
- Card titles: Poppins Medium 24px (e.g., "Advantages", "Disadvantages")
- Body bullets: Inter 18pt Regular 14–16px

### Required assets

**Illustration selection** (apply scoring algorithm from Universal Constraints):

For unilateral comparison (single subject pros/cons) → **1 illustration**:
- Filter `manifest.categories.illustrations.objects.files` using scoring formula
- Slot: `center_focal` for variants A/B, `center_focal` for C
- Apply Step 3 decision rules

For bilateral comparison (both subjects with own positive merits) → **2 illustrations**:
- Apply bilateral exclusion algorithm (Step 4 from Universal Constraints)
- Score each zone separately with zone-specific keywords
- Pick stronger-signal zone first, exclude its pick when scoring the other
- Sanity check: LEFT pick != RIGHT pick

Common matches by topic family (verify with actual enrichment in current manifest):
- Comparison / integration / fit topics → assets with metaphors like "comparison", "integration", "fit"
- Solution / access / unlock topics → metaphors "access", "security", "solution"
- Idea / concept / strategy topics → metaphors "innovation", "ideation"
- Launch / growth / momentum topics → metaphors "launch", "growth", "ambition"
- Process / cycle / iteration topics → metaphors "cycle", "iteration", "process"
- Team / collaboration / partnership → metaphors "team", "collaboration", "partnership"

**Default checkmark icon** (use this URL unless user specifies otherwise):
`https://assets.digitalstudiosoftware.com/brand/agilie/shapes/checkmarks/decor-checkmark-dark-green-v05.png`
Alternatives: v01–v09 in same folder for variation across slides. Use bold (`decor-checkmark-bold-dark-green-*`) only when emphasis is needed. Use thin (`decor-checkmark-thin-dark-green-*`) only for subtle/dense lists. **Pick a single weight per composition** — never mix bold + thin in one image.

**Default X-mark icon:**
`https://assets.digitalstudiosoftware.com/brand/agilie/shapes/xmarks/decor-xmark-salmon-v01.png`
Alternatives: v02, v03 in same folder.

For variant D (bilateral) — both columns use **checkmarks** (no X-marks). Both sides represent positive merits, so green checkmark icons are correct on both.

Rect outlines from `ui-elements/rect-outlines/` for card frames.
Logo as dark pill badge bottom-left or bottom-right.

### Layout variants (v1.5)

Educational-card supports **four layout variants**. Same content (topic + advantages + disadvantages) can render in any of them. Use variant trigger logic to select.

#### Variant A — default (illustration LEFT, cards stacked RIGHT)
```
┌────────────────────────────────────────────┐
│  HEADLINE: TOPIC (yellow on green strip)   │
├──────────────────────┬─────────────────────┤
│                      │  ┌──────────────┐   │
│                      │  │ Advantages   │   │
│   [LARGE outline     │  │ ✓ Bullet 1   │   │
│    illustration      │  │ ✓ Bullet 2   │   │
│    ~50% canvas]      │  │ ✓ Bullet 3   │   │
│                      │  └──────────────┘   │
│                      │  ┌──────────────┐   │
│                      │  │ Disadvantages│   │
│                      │  │ ✗ Bullet 1   │   │
│                      │  │ ✗ Bullet 2   │   │
│                      │  │ ✗ Bullet 3   │   │
│                      │  └──────────────┘   │
├──────────────────────┴─────────────────────┤
│ [agilie logo]               [Talk to us →] │
└────────────────────────────────────────────┘
```

#### Variant B — mirror (cards stacked LEFT, illustration RIGHT)

Same as Variant A but mirrored horizontally. Use when text-driven reading flow is preferred (e.g. heavy-content bullets that should grab attention first).

#### Variant C — stack (illustration TOP centered, cards BOTTOM side-by-side)
```
┌────────────────────────────────────────────┐
│  HEADLINE: TOPIC (yellow on green strip)   │
├────────────────────────────────────────────┤
│                                            │
│             [400×400 illustration          │
│              centered horizontally]        │
│                                            │
├──────────────────────┬─────────────────────┤
│  ┌────────────────┐  │  ┌────────────────┐ │
│  │ Advantages     │  │  │ Disadvantages  │ │
│  │ ✓ Bullet 1     │  │  │ ✗ Bullet 1     │ │
│  │ ✓ Bullet 2     │  │  │ ✗ Bullet 2     │ │
│  │ ✓ Bullet 3     │  │  │ ✗ Bullet 3     │ │
│  └────────────────┘  │  └────────────────┘ │
├──────────────────────┴─────────────────────┤
│ [agilie logo]               [Talk to us →] │
└────────────────────────────────────────────┘
```

Use when "vs" parallel reading is the metaphor — both sides should be readable simultaneously. Cards are tighter (310px tall vs 360px in A/B) so allows max 3 bullets per side comfortably.

#### Variant D — bilateral (TWO illustrations, one per zone)
```
┌────────────────────────────────────────────┐
│  HEADLINE: SUBJECT-A VS SUBJECT-B          │
├──────────────────────┬─────────────────────┤
│  [illus for A        │  [illus for B       │
│   ~280px square]     │   ~280px square]    │
│                      │                     │
├──────────────────────┼─────────────────────┤
│  ┌────────────────┐  │  ┌────────────────┐ │
│  │ Subject A wins │  │  │ Subject B wins │ │
│  │ ✓ Bullet 1     │  │  │ ✓ Bullet 1     │ │
│  │ ✓ Bullet 2     │  │  │ ✓ Bullet 2     │ │
│  │ ✓ Bullet 3     │  │  │ ✓ Bullet 3     │ │
│  └────────────────┘  │  └────────────────┘ │
├──────────────────────┴─────────────────────┤
│ [agilie logo]               [Talk to us →] │
└────────────────────────────────────────────┘
```

Use when both sides of comparison have **own positive merits** — not pros/cons of single subject. Both columns use checkmark icons (no salmon X-marks). Each illustration scored against its own zone keywords using bilateral exclusion algorithm.

### Variant selection logic

When generating educational-card, pick variant by these rules in priority order:

1. **Bilateral signal detected?** If request describes "X vs Y" where both X and Y have own positive merits (e.g. "In-house vs Outsourcing", "React vs Vue") → **Variant D**.
2. **Unilateral pros-and-cons?** If request describes single subject with advantages and disadvantages (e.g. "Outsourcing pros & cons") → start with **Variant A** (default).
3. **Variant override from user?** If user explicitly says "make it different", "another variant", "вариант B", "with illustration on top", etc. → switch per below.

Variant cycling on user requests for variation:
- First request → **Variant A**
- "Make it different" / "another layout" / "вариант 2" → **Variant B**
- "Another one" / "ещё вариант" again → **Variant C**
- After C → cycle back to A, OR offer different pattern entirely ("we've tried all 3 educational-card variants — want stat-card approach?")

Explicit variant overrides:
- "Mirrored" / "flip" / "illustration on the right" → **Variant B**
- "Illustration on top" / "stack layout" / "side by side cards" → **Variant C**
- "Two illustrations" / "show both sides" → **Variant D** (regardless of unilateral content — user's design preference wins)

Always apply the **bullet row sub-template** and **proportional sizing** rules from Universal Constraints within each variant.

### Reference examples
"Agile vs Waterfall: How They Differ", "Outsourcing Models" T&M-vs-Fixed-Price card.

### Generation prompts

**Claude SVG/HTML artifact (Variant A — default):**
```
Generate 1080x1080 SVG with mixed dark+light layout.

Header strip (0-200px) #004C3F with Poppins Bold 60px headline
in #FFDF49 centered. (If headline > 28 chars, drop to 56px or
break to 2 lines per headline-line-break logic.)

Content area split 50/50:
  Left zone (x=0 to 540, y=210 to 920): hand-drawn outline
  illustration from manifest, scored using selection algorithm.
  Size 510×510 centered (95% of zone width). preserveAspectRatio
  meet.

  Right zone (x=555 to 1050): two stacked cards.
  - Card 1 (Advantages, y=210 to 555): rect stroke #001F1F 1.5px,
    rx 14, fill none. Title "Advantages" Poppins Medium 32px
    #004C3F. 3 bullet rows: checkmark 44×44 icon at left padding
    28px, Inter SemiBold 23px #001F1F text. Apply text fit rule.
  - Card 2 (Disadvantages, y=585 to 920): same structure.
    Title #FE9E94, X-mark icon, salmon #FE9E94 icon color.

Footer (970-1080):
  - Logo badge-dark@2x.png 240×64 at x=30
  - CTA pill 240×60 salmon #FE9E94 at right (x=810). Label
    "Talk to us →" Poppins Medium 22px #001F1F centered.

Embed Google Fonts via <style> @import (CRITICAL).
```

**Variant B (mirror):** Swap left and right zones in above prompt — cards on left, illustration on right.

**Variant C (stack):** Restructure content area:
- Illustration band y=210 to 630 (420px tall), 400×400 illustration centered horizontally
- Cards row y=650 to 960 (310px tall), 2 cards side-by-side: card-left 30 to 525, card-right 555 to 1050. Each card 495 wide × 310 tall.

**Variant D (bilateral):** Score TWO illustrations using bilateral exclusion algorithm. Layout:
- Two columns 50/50 split
- Each column: illustration TOP (320×280 box, centered horizontally in column), card BOTTOM (495 wide × ~580 tall)
- Both cards use checkmark icons (no salmon X-marks for bilateral)
- Card titles like "Subject A wins" / "Subject B wins"

**OpenAI gpt-image-1 (any variant):**
```
Educational comparison infographic, square format, warm off-white
background, hand-drawn line illustration in [zone per variant],
right/bottom side shows cards listing pros with green checkmarks
and cons with salmon-pink X marks, clean editorial layout,
hand-drawn aesthetic mixed with structured cards, no photos.
```

---

## Pattern 3: `stat-card`

**Use for:** "N benefits of X", numbered lists, single-topic deep dives with bullet structure, "why choose Y" content.

**Recommended generation:** Claude SVG (highly structured pill rows).

### Input requirements

**Mandatory:**
- Topic / list subject
- 3–6 bullet points, max 10 words each
- Whether numbered or icon-only (default: icon-only)

**Optional:**
- Specific illustration in lower-right (default: matched to topic from manifest)
- Headline override (default: "Benefits of [Topic]" or "[N] Reasons to [Action]")

**Never invent:** counts ("3 reasons" must match actual bullet count user provides), benefits the user hasn't listed.

### Visual signature

Dark green canvas. Large yellow Poppins headline at top. Body is a column of pill-shaped rows, each with an illustration icon + label in white. Sketch illustration object in lower-right corner. Wordmark dark pill at bottom-left.

### Color palette
- Background: `#004C3F`
- Headline: `#FFDF49`
- Pill rows: slight tint of background (`#004C3F` at 70% opacity over `#001F1F`)
- Pill text: `#FFFFFF`
- Pill icon: `#FFDF49`
- Sketch illustration: `#FFFFFF` outline with optional `#FFDF49` highlights

### Typography
- Headline: Poppins Bold 56–72px in `#FFDF49`
- Pill labels: Inter 24pt Regular 18–22px white
- Numbers (if numbered): use `shapes/numbers/num-yellow-*.png` images, NOT typed digits

### Required assets
- 4–6 small icons (yellow): pick from `illustrations/objects/files` or `shapes/sparkles-stars/files`. **Use enrichment-driven selection**: filter by `enrichment.color_variant = yellow` (or matching the composition palette) and `enrichment.compositional_role = supporting_accent` for the icon role.
- 1 large sketch illustration in lower-right from `illustrations/objects/files`. Filter by `enrichment.metaphors` matching the post topic (e.g. for "FinTech benefits" post, match metaphors like "fintech", "payments", "financial growth"). Prefer assets with `enrichment.composition_hint = lower_right` if available, otherwise `center_focal` or `any`.
- Pill rows: visual style reference `shapes/pills/files` (long horizontal pill containers — filter by `enrichment.shape_subtype` matching "long pill" or similar)
- Logo: `logo/badge-light.svg` as pill badge bottom-left
- If numbered list: pull digit images from `shapes/numbers/files` filtered by `enrichment.digit` (matching the bullet position) and `enrichment.color_variant = yellow`. Do NOT type numerals as text.

### Layout template
```
┌────────────────────────────────────────────┐
│  Benefits of X (yellow, Poppins Bold)      │
│                                            │
│  ╭──────────────────────────────────────╮  │
│  │ 🟡  Bullet point 1                   │  │
│  ╰──────────────────────────────────────╯  │
│  ╭──────────────────────────────────────╮  │
│  │ 🟡  Bullet point 2                   │  │
│  ╰──────────────────────────────────────╯  │
│  ╭──────────────────────────────────────╮  │
│  │ 🟡  Bullet point 3                   │  │
│  ╰──────────────────────────────────────╯  │
│                                            │
│  [agilie pill badge]      [sketch illus]   │
└────────────────────────────────────────────┘
```

Apply the **bullet row sub-template** with 90px row height for pill rows.

### Reference examples
"Benefits of a Multicurrency Wallet" (X thread image with 4 yellow-icon pills on dark green).

### Generation prompts

**Claude SVG/HTML artifact:**
```
Generate 1080x1080 SVG. Background #004C3F. Top: Poppins Bold 64px
headline "Benefits of [Topic]" in #FFDF49 at x=80, y=120. Below:
4 horizontal pill containers, each 920x90px, rounded-full, filled
with rgba(0,31,31,0.4), stroked at 1px #001F1F. Apply bullet-row
sub-template: yellow icon 28x28px at left padding 24px, white
Inter 24pt 20px label centered vertically. Stack pills vertically
with 16px gap. Bottom-right: sketch illustration from manifest
illustrations.objects sized 320x320px. Bottom-left: agilie wordmark
in dark pill badge at 140px wide.
```

**OpenAI gpt-image-1:**
```
Dark forest green background social media graphic, 1:1 format,
yellow bold headline at top "Benefits of [topic]", series of
4–5 horizontal pill-shaped rows below with yellow icons and
white text labels, hand-drawn white sketch illustration in
lower right corner, structured listicle layout, professional
B2B fintech aesthetic.
```

---

## Pattern 4: `holiday`

**Use for:** Calendar holidays (Easter, Halloween, Thanksgiving, Christmas, New Year, Valentine's, etc.). Not for personal birthdays — use `people-spotlight`.

**Recommended generation:** gpt-image-1 (sketch illustrations are native to image gen).

### Input requirements

**Mandatory:**
- Holiday name
- Greeting message (1–3 sentences max, light tone)

**Optional:**
- Sub-style override (4a or 4b — default chosen by holiday mapping below)
- Specific illustration request (default: chosen from available brand assets or generated)

### Sub-style mapping

Choose by holiday — these are the brand's established defaults:

| Holiday | Sub-style | Reason |
|---|---|---|
| Easter | 4a (light) | Spring / joyful tone matches cream card |
| Thanksgiving | 4a (light) | Warm gratitude tone matches cream card |
| Valentine's | 4a (light) | Soft / affectionate tone |
| Halloween | 4b (dark) | Spooky / playful contrast on dark green |
| New Year | 4b (dark) | Festive launch energy on dark |
| Christmas | 4b (dark) | Cozy evening / warm-on-dark |
| Other / unknown | Default to 4a (light) | Safer for unfamiliar holidays |

If user has a stylistic preference that overrides defaults, ask before generating.

### Visual signature

**4a. Light card holiday:** cream/sage background, large Poppins Bold headline (mixed colors — main word in `#004C3F`, accent word in `#FE9E94`), centered or right-positioned hand-drawn sketch illustration of holiday subject (bunny, turkey, snowman). Dark pill wordmark badge bottom-left.

**4b. Dark holiday:** `#004C3F` background, white sketch illustration positioned next to (or composed with) the brand monogram. Yellow accent on the holiday word. Logo light pill bottom-left.

> **Note on monogram-in-illustration compositions (4b):** The Halloween "witch hat on logo" example was custom-designed by a human. AI generation may produce visible distortions of the Agilie monogram. For low-stakes posts (X holiday greetings, internal celebrations), AI attempt is acceptable. For high-visibility posts (LinkedIn campaigns, press content), recommend custom design instead. Always show a placeholder generated draft to the user with a note: "monogram composition is approximate; consider designer touch-up before publishing."

### Color palette
- Background: `#F9F8F5` (4a) or `#004C3F` (4b)
- Headline mix: `#004C3F` for main words + `#FE9E94` or `#FFDF49` for emphasis word
- Sketch illustration: dark green strokes on light, white strokes on dark
- Optional secondary accents in illustration: `#FFDF49`, `#FE9E94`

### Typography
- Headline: Poppins Bold 64–96px, mixed-color words
- Subline (optional): Inter 24pt 18–22px

### Required assets

**Available holiday-specific illustrations in brand library:**

Check manifest before generating. Currently confirmed brand assets:
- Easter → bunny illustration available
- Thanksgiving → turkey illustration available

**Fallback for holidays WITHOUT brand-specific assets** (Christmas, NY, Valentine's, Halloween, etc.):

For Claude SVG generation:
- DO NOT attempt to compose custom holiday illustration in SVG. Custom illustrations must be designed by humans.
- Instead, use a generic brand asset that supports the metaphor. **Use enrichment-driven search**:
  - Filter `illustrations/objects/files` where `enrichment.metaphors` matches the holiday spirit
  - Examples of likely matches in the current manifest (verify with actual enrichment):
    - NY / launch / fresh start → search metaphors for "launch", "ambition", "growth"
    - Christmas / idea sharing / warmth → search metaphors for "innovation", "ideation", "celebration"
    - Anniversary / achievement → search metaphors for "milestone", "success", "achievement"
    - Default fallback → use a brand mascot (filter `illustrations/characters/files` for any with `enrichment.tags` containing "playful" or "celebration")
- Keep typography as the focal element; illustration is supportive.

For gpt-image-1 generation:
- Describe the desired sketch illustration in the prompt (e.g. "hand-drawn snowman with santa hat, white outline strokes on dark green background")
- Specify "in the style of Agilie's existing brand illustrations: hand-drawn outline only, white strokes on dark green or deep forest green strokes on cream, occasional yellow and salmon accents"
- Accept that output will be approximate, not pixel-matching brand library.
- For high-stakes posts, recommend user have a designer create a custom asset.

**Common required assets:**
- For 4b: brand monogram `logo/icon-only-white.svg`
- Sparkles/stars accent: `shapes/sparkles-stars/decor-sparkle-*` or `decor-star-yellow-*`
- Logo pill at bottom

### Layout template (4a — light)
```
┌────────────────────────────────────────────┐
│                                            │
│   Happy Easter                             │
│   from Agilie         [bunny+egg sketch]   │
│                                            │
│   We wish you a                            │
│   joyful celebration!                      │
│                                            │
│   [agilie pill]                            │
└────────────────────────────────────────────┘
```

### Layout template (4b — dark)
```
┌────────────────────────────────────────────┐
│   Happy Agilie       ✦                     │
│   Halloween!  (yellow)                     │
│                                            │
│              [logo + holiday element]      │
│                  (centered)                │
│                                            │
│   [agilie pill]                            │
└────────────────────────────────────────────┘
```

### Reference examples
"Happy Easter from Agilie" (light, bunny sketch), "Happy Agilie Halloween!" (dark, monogram + witch hat), "Happy Thanksgiving Day!" (light, turkey sketch with salmon+yellow text).

### Generation prompts

**OpenAI gpt-image-1 (4a — light):**
```
Hand-drawn sketch illustration on warm off-white background
(#F9F8F5), centered subject: [holiday icon, e.g. cute easter
bunny with egg / cartoon turkey wearing pilgrim hat / snowman
reading], deep forest green outline strokes (#004C3F), occasional
salmon-pink and yellow color accents in the illustration, large
bold sans-serif headline "Happy [Holiday]" with one word in deep
forest green and emphasis word in salmon-pink, social media
square format, generous whitespace, joyful but understated tone.
```

**OpenAI gpt-image-1 (4b — dark):**
```
Dark forest green background (#004C3F), hand-drawn white sketch
illustration centered: [holiday element such as witch hat /
santa hat / fireworks] adjacent to or overlapping the Agilie
brand monogram (4-petal flower shape), white strokes only with
possible yellow sparkle accents (#FFDF49), large headline "Happy
[Holiday]!" with the holiday word in warm yellow, playful
corporate tone.

Note on output: monogram geometry may be imperfect — present as
draft for human review before publishing.
```

---

## Pattern 5: `people-spotlight`

**Use for:** Birthdays of team members, work anniversaries (N years with Agilie), employee promotions, leadership feature posts.

**Recommended generation:** gpt-image-1 base composition + Claude SVG text overlay → Canva polish (recommended for production).

### Input requirements

**Mandatory:**
- Person's full name
- Their role at Agilie
- Occasion (birthday / N-year anniversary / promotion / etc.)
- Greeting / tribute message (1–3 sentences)
- A real portrait photo from `photos/individuals/[person]/` if available

**Optional:**
- Date for date-tag (e.g. "27 MAR" for birthdays)
- Watermark text override (default rules apply, see below)

**Critical:** Never generate AI faces resembling the person. If no real photo is available, fall back to `marketing-hero` pattern with the person's name as headline instead of attempting AI portrait.

### Visual signature

Photo-driven. Full-bleed or large portrait of person. Dark green gradient overlay on photo for text legibility. Poppins Bold headline white, multi-line. Yellow rectangle marker-highlight behind person's name (not text color — actual yellow rectangle). Subline in Inter describing role/celebration. Wordmark in upper-right.

### Typographic watermark — when to use

The repeating "HAPPY BIRTHDAY" watermark in the background is reserved for **personal birthday posts only**. It signals personal celebration register and shouldn't appear elsewhere.

**Use watermark for:**
- Personal birthdays (text: "HAPPY BIRTHDAY")

**Do NOT use watermark for:**
- Work anniversaries — use solid dark green background instead
- Company anniversaries — use `marketing-hero` pattern, not this one
- Promotions or role changes — use solid background
- Holiday posts — those have their own visual treatment in pattern 4

The watermark renders at very low opacity (~10%) using Inter 28pt SemiBold, repeated diagonally.

### Color palette
- Background: `#004C3F` with gradient to darker, OR person photo with dark green vignette
- Text: `#FFFFFF`
- Name highlight rectangle: `#FFDF49` solid block behind name text
- Name text on highlight: `#001F1F` dark

### Typography
- Main headline ("Happy Birthday"): Poppins Bold 72–88px white
- Person name: Poppins Bold 36–44px dark on yellow highlight
- Role/subline: Inter 24pt Regular 18–22px white 80% opacity
- Watermark "HAPPY BIRTHDAY": Inter 28pt at very low opacity (~10%)

### Required assets
- Portrait from `photos/individuals/[person]/` — choose a portrait, not a group shot
- Logo `badge-light.svg` upper-right
- Optional: gold confetti / ribbon described in prompt (not from manifest)
- Optional: sparkle from `shapes/sparkles-stars/` near name

### Layout template
```
┌────────────────────────────────────────────┐
│  HAPPY BIRTHDAY  ←watermark      [agilie] │
│  HAPPY BIRTHDA                             │
│   HAPPY BIRT                               │
│                                            │
│   Happy            ┌──────────────────┐   │
│   Birthday         │   PERSON NAME    │   │
│                    │   (on yellow)    │   │
│   Role at Agilie   └──────────────────┘   │
│                                            │
│                                  [photo]   │
│                                            │
└────────────────────────────────────────────┘
```

### Reference examples
"Sergey Gladun — CEO and Founder Agilie" cover slide, "Happy Birthday — Sergey Melashych — Chief Technology Officer" 11th anniversary post.

### Generation prompts

**Hybrid approach (gpt-image-1 base + Claude SVG text overlay):**

gpt-image-1 base composition:
```
Portrait photo composite, person on right side over deep forest
green to teal gradient background, faint typographic watermark
"HAPPY BIRTHDAY" repeating pattern in background at 10% opacity,
gold confetti ribbons cascading down sides, vertical 4:5 LinkedIn
format, professional but celebratory mood, cinematic lighting
on subject. Leave left 60% of canvas clear for text overlay.
```

Claude SVG text overlay:
```
Add text layer at top-left "Happy Birthday" Poppins Bold 84px white.
Below: person name "[NAME]" Poppins Bold 38px in #001F1F on a
#FFDF49 solid rectangle (rectangle padding 12px horizontal, 6px
vertical). Below name: role text Inter 24pt Regular 20px white
80% opacity. Top-right: agilie wordmark in light pill badge.
```

**No-photo fallback:** If no real portrait is available for the person, default to `marketing-hero` with their name as headline. Do not generate AI faces.

---

## Pattern 6: `editorial`

**Use for:** Hot takes on industry news, event recaps with real photos, repost commentary, "our thoughts on X" content. Photo-driven OR text-only.

**Recommended generation:** None. Use real photo or text-only post. Editorial pattern intentionally breaks brand visual consistency to feel like genuine commentary rather than corporate marketing.

### Input requirements

**Mandatory:**
- Post text content
- Either: a real photo, a real screenshot of news/article, or no image (text-only is valid)

**Forbidden:**
- Generated visuals matching brand style (defeats the editorial register)
- Stock photography
- AI portraits

### Visual signature

Minimal branding. Either real photography (event photos, screenshots of news, third-party content with overlay) OR purely text post with no graphic. Agilie avatar is the only brand presence. Hashtags carry editorial weight. No headlines, no decorative shapes, no Poppins display type.

### Color palette
N/A — uses real photography colors as-is. Branded overlay (if any) limited to small wordmark in corner.

### Typography
Native LinkedIn/X post text only. No image typography.

### Required assets
- Real photo from event (not from manifest)
- For repost commentary: third-party screenshot or article preview
- No logo overlay needed (account avatar handles it)

### Layout
- Single full-bleed photo or photo collage
- Or no image at all (text-only post)

### Reference examples
"MWC Barcelona 2026 — MWC celebrated its 20th anniversary…" (LinkedIn, photo collage), "ai agents in demos are gods. in production they're a liability…" (X, Replit AI screenshot).

### Generation prompts

For editorial pattern, **don't generate the visual** if the user has a real photo. The pattern is for content where authenticity matters more than brand consistency.

If user explicitly asks for a generated editorial-style image (rare):
```
Photo-realistic editorial illustration matching the news topic,
no Agilie branding, clean composition, journalistic aesthetic.
Treat as standalone news graphic.
```

---

## Pattern 7: `insights-hub`

**Use for:** "Agilie Insights Hub" episode covers, podcast cover art, "Looking Back at Q[N]" recap series, themed content collections. This is a **sub-brand** with its own visual register.

**Recommended generation:** gpt-image-1 (complex sketch composition) → Claude SVG for episode badge text → Canva polish.

### Input requirements

**Mandatory:**
- Episode number
- Episode topic/theme
- Tagline or headline summarizing episode content (5–12 words)

**Optional:**
- Specific scene/character preference (default: chosen based on theme)
- Seasonal hint (e.g. winter/summer/holiday-adjacent if relevant)

### Visual signature

Distinct from other patterns. Dark green background but with **larger, more illustrative** central scene — sketch character (snowman reading, person at desk, character with clipboard) interacting with branded objects (gift box, light bulb in box, magazine). Massive Poppins Bold headline left-aligned: "Agilie Insights Hub" with "Insights Hub" in teal/green tint. Episode number in white pill badge bottom-left. More whitespace, more visual breathing room than other patterns.

### Color palette
- Background: `#004C3F`
- Main headline ("Agilie"): `#FFFFFF`
- Sub-headline ("Insights Hub"): teal/green tint (lighter `#004C3F` mixed with white, ~`#3A8B73`)
- Sketch illustration: white outline strokes, with `#FFDF49` and `#FE9E94` color accents
- Episode badge: `#F9F8F5` background, `#001F1F` text

### Typography
- Stacked headline: Poppins Bold 72–88px, "Agilie" in white, "Insights" / "Hub" each on own line in teal tint
- Episode label: Inter 24pt Medium 16–18px in `#001F1F` on light pill

### Required assets
- Character illustration from `illustrations/characters/` or thematic from `illustrations/people/` (e.g., reading insights, snowman variant for seasonal)
- Branded prop from `illustrations/objects/` (lamp, gift, magazine, rocket — pick one)
- Sparkle accents from `shapes/sparkles-stars/`
- White pill for episode badge (custom shape, not from manifest)

### Layout template
```
┌────────────────────────────────────────────┐
│                                            │
│   Agilie    ✦                              │
│   Insights              [character +       │
│   Hub                    branded prop      │
│                          sketch]           │
│                                            │
│                                            │
│   [Episode N]                              │
└────────────────────────────────────────────┘
```

### Reference examples
"Agilie Insights Hub — Episode 23 — Looking Back at 2025: The Fintech Insights That Mattered Most" (snowman + gift box composition).

### Generation prompts

**OpenAI gpt-image-1:**
```
Podcast/series cover art, square format, deep forest green
background (#004C3F), large stacked headline left-aligned
"Agilie Insights Hub" with first word in white and remaining
words in lighter teal-green, hand-drawn sketch illustration
on right side: [character/scene matching episode theme, e.g.
snowman in santa hat reading magazine with glowing light bulb
nearby, gift box at base], white outline strokes with yellow
and salmon accents in illustration, sparkle stars decorative
elements, white episode badge pill in lower-left "Episode N",
generous whitespace, magazine cover aesthetic, hand-drawn meets
editorial design.
```

---

## Carousel extension

Carousels apply a base pattern to all slides with rhythm variations. Standard sizes: 1080x1080 LinkedIn carousel, 4–10 slides typical.

### Input requirements (carousel mode)

Carousel mode REQUIRES additional input beyond the chosen pattern's single-slide requirements. Before generating any carousel, collect:

**Mandatory:**
- Total slide count (typically 4–10)
- Per-slide content outline — what goes on slides 2 through N-1. Each slide entry should be 1–3 sentences describing focus + key visual element. Example for a 5-slide marketing-hero carousel:
  - Slide 1 (cover): "Agilie All-Inclusive Partner Program" headline + early-access CTA
  - Slide 2: "5–10% cash bonus + free dev hours" — the offer
  - Slide 3: "How it works" — 3-step pipeline diagram
  - Slide 4: "Who it's for" — target partner profiles
  - Slide 5 (closing): "Ready to partner?" CTA card with FAQ
- Closing slide intent (CTA / recap / contact card / something else)

**Optional:**
- Mix dark and light slides? (default: all dark unless marketing-hero with photo composite, where dark is mandatory)
- Carousel-back template preference (default: clean #004C3F unless user requests pre-styled background from manifest carousel_backs)

If per-slide outline missing, ASK before generating. NEVER hallucinate slide content. Generating 5 identical cover slides is also wrong — ask for content if user only provided cover info.

### Slide rhythm rules

- **Cover slide (1):** Always the chosen pattern at full intensity. Sets visual register.
- **Body slides (2 to N-1):** Same pattern, alternating layouts to avoid monotony. For `marketing-hero` carousel: alternate dark-with-photo and dark-with-illustration. For birthday carousel: same teal pattern background, varying the centered card content.
- **Closing slide (N):** Often a CTA-focused variant. For marketing: `marketing-hero` with stronger CTA. For educational: a recap card. Always include URL or contact in footer.

**Carousel-back templates:** Pre-designed background variations are available in `manifest#categories.components.carousel_backs` (5 numbered templates). Use them as starting backgrounds for slides where you want pre-styled decoration; fall back to plain `#004C3F` for clean slides.

**Page numbers:** Footer right side, format `page / total`, Inter 18pt Regular 14px in white at 60% opacity. For light slides use `#001F1F` at 60% opacity.

**Page transitions:** When mixing dark and light slides in same carousel (allowed, but not recommended for first carousel), preserve the same horizontal margin grid so contents feel anchored across slides.

---

## Anti-patterns (what to avoid)

These are subtle drift errors — they look "kind of like Agilie" but break consistency. Reject if they appear:

- **Three accent colors in one composition.** Pick yellow OR salmon, never both as primary accents in the same image.
- **Asterisk shapes used as background pattern.** Asterisks are 1–2 per composition max, as accents — never as repeated wallpaper.
- **Mascots in serious contexts.** Pig and robot-crown mascots are for playful posts (anniversary, celebration). Don't put them in marketing-hero or educational-card.
- **Stock photography slipping in.** Especially "diverse smiling team in modern office" or "hands typing on glowing keyboard." Always preferred: real Agilie photos or sketch illustrations.
- **Generic icon sets.** Don't pull Material/Font Awesome/Heroicons. Brand has its own checkmark, X-mark, arrow, and number assets — use them.
- **Logo without proper background contrast.** Green logo on green background, white logo on white — always check contrast ratio first.
- **Filling whitespace with decoration.** Agilie uses generous whitespace. Don't add blobs/sparkles/asterisks just because there's empty space.
- **AI-generated faces.** Never. Use real team photos from `photos/individuals/` or no person at all.
- **Pure black text on pure white.** Always `#001F1F` text on `#F9F8F5` for that warm editorial feel.
- **Three or more fonts.** Only Poppins and Inter. No system fonts, no decorative scripts, no replacements.
- **Carousel monotony.** Don't use the exact same layout for all slides. Vary the position of headline, illustration, CTA across slides while keeping the pattern.
- **Mixed icon weights in one composition.** Don't use bold checkmarks alongside thin checkmarks — pick one weight per image.
- **Inventing content.** If user hasn't provided statistics, bullet points, or specifics — ASK. Don't fill in plausible-sounding facts.
- **Ignoring enrichment metadata.** When manifest has `enrichment` fields populated, do NOT pick assets by filename intuition. Apply the formal scoring algorithm — filter by `metaphors`, `tags`, `best_for`, then score, then decide. Filename-based selection is the pre-v1.4 fallback for legacy manifests without enrichment — wrong when enrichment exists.
- **Exceeding `max_per_composition`.** If a sparkle's enrichment says max 3-5 per composition, never place more than 5. This is brand voice protection — too much accent decoration breaks the editorial register.
- **Audience keywords polluting topic scoring.** When extracting keywords, "for FinTech CTO audience" describes WHO reads the post, not WHAT the post is about. Strip audience phrases before scoring. (Otherwise FinTech-related illustrations win irrelevant searches.)
- **Same illustration on both sides of bilateral comparison.** When generating Variant D (bilateral), enforce exclusion: LEFT pick != RIGHT pick. If exclusion logic produces same asset, that's a bug — re-run with explicit exclude set.
- **Pixel-based sizing in generated SVGs.** Express sizes as proportions (% of canvas), not absolute pixels. This way layouts scale to non-square canvases. Hardcoded `font-size: 16px` is brittle; `font-size: ${canvas_height * 0.022}` is correct.
- **Body text below 22px on 1080×1080 canvas.** SMM posts are read on mobile feed scroll where 1080px renders at ~400-500px wide. Anything below 2% canvas height (22px) becomes unreadable. Always 22px+ for body content on social media.
- **Text overflow in cards.** Before finalizing, compute text budget: `card_width - paddings - icon - icon_gap`, divide by `font_size * 0.55` to get max chars. If any bullet exceeds this, shorten the bullet — never wrap, never overflow, never let text clip card boundary.
- **Typed numerals in stat-card numbered lists.** `<text>5</text>` is wrong — use brand asset `num-yellow-5.png` (or color-appropriate variant). Number assets carry the hand-drawn brand aesthetic; typed numerals look like Google Doc.

---

## Update & evolution

This skill version: **1.5** (2026-05-07).

Changelog from v1.4:
- **Formal scoring algorithm** for asset selection — replaces boolean overlap with weighted scoring (`2*meta + tag + slot + combo`), explicit decision rules (auto-pick when ratio < 0.85, ask user otherwise)
- **Brand-context Synonym Table** with 89 user-vocabulary entries mapped to validated asset vocabulary — eliminates ambiguity in keyword extraction
- **Topic vs Audience separation** — strip "for [audience]" / "to [audience]" phrases before keyword extraction so audience descriptors don't pollute scoring
- **Bilateral exclusion rule** for compositions with 2 illustrations — pick stronger-signal zone first, exclude that pick when scoring the other zone
- **Multi-illustration logic per pattern** — explicit rules for when to use 1 vs 2 illustrations (bilateral comparison vs unilateral pros/cons, stat-card numbered vs icon-only, etc.)
- **Number selection filename-first** — Vision-derived `enrichment.digit` is unreliable; filename pattern `num-{color}-{digit}.png` is ground truth
- **Photo person_count refinement** — birthday/solo spotlight require person_count == 1 even if best_for matches
- **Proportional sizing principle** — express element sizes as % of canvas (5.5% headline, 2.2% body, 4% icon, 22% logo width) for layout scalability
- **Visual weight balance principle** — explicit two-zone composition rule with density target 80-90% canvas
- **Text fit verification rule** — compute text budget before finalizing layout; never overflow
- **Four layout variants for educational-card** — A (default illus LEFT), B (mirror illus RIGHT), C (illus TOP), D (bilateral 2 illus). Variant cycling on user "сделай ещё" requests
- Bullet row sub-template now proportional (no hardcoded 56px/90px row heights)

Changelog from v1.3:
- Added "Asset selection from enriched manifest" section in Universal constraints — algorithms for picking illustrations by `metaphors`, photos by `best_for` / `avoid_for`, numbers/shapes by `enrichment.digit` / `color_variant`
- Added "Asset combination logic" section — uses `combines_well_with` for richer compositions instead of single-illustration layouts
- Reformed Fix 21 (mandatory photo ask) — now auto-picks when enrichment shows exactly one match, asks only when 2+ candidates fit, falls back gracefully when 0 fit
- Updated educational-card, stat-card, and holiday-fallback asset selection to use enrichment fields instead of hardcoded filenames
- Added anti-patterns: "Ignoring enrichment metadata" and "Exceeding max_per_composition"

Changelog from v1.2:
- Added derived shades palette for blob decorations (3 specific HEX values instead of "improvise lighter shades")
- Added font embedding rules for SVG output — Google Fonts `<style>` import block (without this, all SVGs render in Helvetica fallback)
- Added card-sizing formula — cards fit to bullet count, no fixed heights with empty space
- Strengthened photo selection rule to mandatory ask — never pick photo automatically, even on goal-first requests

Changelog from v1.1:
- Added carousel-mode input requirements (per-slide content outline mandatory)
- Added headline line-break logic to universal constraints
- Added photo selection guidance for multi-photo individual folders
- Added explicit generation path decision tree for marketing-hero (when SVG vs gpt-image-1)

Changelog from v1.0:
- Added "Output expectations" section with per-pattern generation paths
- Added input requirements block to all 7 patterns
- Added bullet-row sub-template to universal constraints
- Added explicit default URLs for checkmarks/xmarks (educational-card)
- Added holiday → sub-style mapping table
- Added fallback strategy for holidays without brand-specific assets
- Added warning note about monogram-in-illustration AI generation quality
- Clarified watermark scope (personal birthdays only)
- Added "mixed icon weights" and "inventing content" to anti-patterns

When the brand evolves:
1. New assets added to Canva → re-download → re-run `build_manifest.py` → rsync
2. New pattern emerges from real posts (3+ examples in the wild) → propose addition here, increment version
3. Color palette change → update both this skill and `manifest.json` simultaneously to avoid drift
4. Logo refresh → update `logo/` directory and update version

For pattern modifications: edit the relevant pattern section, update reference examples list, regenerate any cached prompts.

When in doubt about whether something fits the brand: check the 3 most recent published Agilie posts on LinkedIn / X. If your generated content would feel out of place next to them, adjust before publishing.