1# Step 3: Prompt Template
2 
3Save to `prompts/cover.md`:
4 
5```markdown
6---
7type: cover
8palette: [confirmed palette]
9rendering: [confirmed rendering]
10references:
11  - ref_id: 01
12    filename: refs/ref-01-{slug}.{ext}
13    usage: direct | style | palette
14  - ref_id: 02
15    filename: refs/ref-02-{slug}.{ext}
16    usage: direct | style | palette
17---
18 
19# Content Context
20Article title: [full original title from source]
21Content summary: [2-3 sentence summary of key points and themes]
22Keywords: [5-8 key terms extracted from content]
23 
24# Visual Design
25Cover theme: [2-3 words visual interpretation]
26Type: [confirmed type]
27Palette: [confirmed palette]
28Rendering: [confirmed rendering]
29Font: [confirmed font]
30Text level: [confirmed text level]
31Mood: [confirmed mood]
32Aspect ratio: [confirmed ratio]
33Language: [confirmed language]
34 
35# Text Elements
36[Based on text level:]
37- none: "No text elements"
38- title-only: "Title: [exact title from source or user]"
39- title-subtitle: "Title: [title] / Subtitle: [context]"
40- text-rich: "Title: [title] / Subtitle: [context] / Tags: [2-4 keywords]"
41 
42# Mood Application
43[Based on mood level:]
44- subtle: "Use low contrast, muted colors, light visual weight, calm aesthetic"
45- balanced: "Use medium contrast, normal saturation, balanced visual weight"
46- bold: "Use high contrast, vivid saturated colors, heavy visual weight, dynamic energy"
47 
48# Font Application
49[Based on font style:]
50- clean: "Use clean geometric sans-serif typography. Modern, minimal letterforms."
51- handwritten: "Use warm hand-lettered typography with organic brush strokes. Friendly, personal feel."
52- serif: "Use elegant serif typography with refined letterforms. Classic, editorial character."
53- display: "Use bold decorative display typography. Heavy, expressive headlines."
54 
55# Composition
56Type composition:
57- [Type-specific layout and structure]
58 
59Visual composition:
60- Main visual: [metaphor derived from content meaning]
61- Layout: [positioning based on type and aspect ratio]
62- Decorative: [palette-specific elements that reinforce content theme]
63 
64Color scheme: [primary, background, accent from palette definition, adjusted by mood]
65Color constraint: Color values (#hex) and color names are rendering guidance only — do NOT display color names, hex codes, or palette labels as visible text in the image.
66Rendering notes: [key characteristics from rendering definition — lines, texture, depth, element style]
67Type notes: [key characteristics from type definition]
68Palette notes: [key characteristics from palette definition]
69 
70[Watermark section if enabled]
71 
72[Reference images section if provided — REQUIRED, see below]
73```
74 
75## Reference-Driven Design ⚠️ HIGH PRIORITY
76 
77When reference images are provided, they are the **primary visual input** and MUST strongly influence the output. The cover should look like it belongs to the same visual family as the references.
78 
79**Passing `--ref` alone is NOT enough.** Image generation models often ignore reference images unless the prompt text explicitly describes what to reproduce. Always combine `--ref` with detailed textual instructions.
80 
81## Content-Driven Design
82 
83- Article title and summary inform the visual metaphor choice
84- Keywords guide decorative elements and symbols
85- The skill controls visual style; the content drives meaning
86 
87## Visual Element Selection
88 
89Match content themes to icon vocabulary:
90 
91| Content Theme | Suggested Elements |
92|---------------|-------------------|
93| Programming/Dev | Code window, terminal, API brackets, gear |
94| AI/ML | Brain, neural network, robot, circuit |
95| Growth/Business | Chart, rocket, plant, mountain, arrow |
96| Security | Lock, shield, key, fingerprint |
97| Communication | Speech bubble, megaphone, mail, handshake |
98| Tools/Methods | Wrench, checklist, pencil, puzzle |
99 
100Full library: [../visual-elements.md](../visual-elements.md)
101 
102## Type-Specific Composition
103 
104| Type | Composition Guidelines |
105|------|------------------------|
106| `hero` | Large focal visual (60-70% area), title overlay on visual, dramatic composition |
107| `conceptual` | Abstract shapes representing core concepts, information hierarchy, clean zones |
108| `typography` | Title as primary element (40%+ area), minimal supporting visuals, strong hierarchy |
109| `metaphor` | Concrete object/scene representing abstract idea, symbolic elements, emotional resonance |
110| `scene` | Atmospheric environment, narrative elements, mood-setting lighting and colors |
111| `minimal` | Single focal element, generous whitespace (60%+), essential shapes only |
112 
113## Title Guidelines
114 
115When text level includes title:
116- **Source**: Use the exact title provided by user, or extract from source content
117- **Do NOT invent titles**: Stay faithful to the original
118- Match confirmed language
119 
120## Watermark Application
121 
122If enabled in preferences, add to prompt:
123 
124```
125Include a subtle watermark "[content]" positioned at [position].
126The watermark should be legible but not distracting from the main content.
127```
128 
129Reference: `config/watermark-guide.md`
130 
131## Reference Image Handling
132 
133When user provides reference images (`--ref` or pasted images):
134 
135### ⚠️ CRITICAL - Frontmatter References
136 
137**MUST add `references` field in YAML frontmatter** when reference files are saved to `refs/`:
138 
139```yaml
140---
141type: cover
142palette: warm
143rendering: flat-vector
144references:
145  - ref_id: 01
146    filename: refs/ref-01-podcast-thumbnail.jpg
147    usage: style
148---
149```
150 
151| Field | Description |
152|-------|-------------|
153| `ref_id` | Sequential number (01, 02, ...) |
154| `filename` | Relative path from prompt file's parent directory |
155| `usage` | `direct` / `style` / `palette` |
156 
157**Omit `references` field entirely** if no reference files saved (style extracted verbally only).
158 
159### When to Include References in Frontmatter
160 
161| Situation | Frontmatter Action | Generation Action |
162|-----------|-------------------|-------------------|
163| Reference file saved to `refs/` | Add to `references` list ✓ | Pass via `--ref` parameter |
164| Style extracted verbally (no file) | Omit `references` field | Describe in prompt body only |
165| File path in frontmatter but doesn't exist | ERROR - fix or remove | Generation will fail |
166 
167**Before writing prompt with references, verify**: `test -f refs/ref-NN-{slug}.{ext}`
168 
169### Reference Usage Types
170 
171| Usage | When to Use | Generation Action |
172|-------|-------------|-------------------|
173| `direct` | Reference matches desired output closely | Pass to `--ref` parameter |
174| `style` | Extract visual style characteristics only | Describe style in prompt text |
175| `palette` | Extract color palette only | Include colors in prompt |
176 
177### Step 1: Analyze References
178 
179For each reference image, extract:
180- **Style**: Rendering technique, line quality, texture
181- **Composition**: Layout, visual hierarchy, focal points
182- **Color mood**: Palette characteristics (without specific colors)
183- **Elements**: Key visual elements and symbols used
184 
185### Step 2: Embed in Prompt ⚠️ CRITICAL
186 
187**Passing `--ref` alone is NOT enough.** Image generation models frequently ignore reference images unless the prompt text explicitly and forcefully describes what to reproduce. You MUST always write detailed textual instructions regardless of whether `--ref` is used.
188 
189**If file saved (with or without `--ref` support)**:
190- Pass ref images via `--ref` parameter if skill supports it
191- **ALWAYS** add a detailed mandatory section in the prompt body:
192 
193```
194# Reference Style — MUST INCORPORATE
195 
196CRITICAL: The generated cover MUST visually reference the provided images. The cover must feel like it belongs to the same visual family.
197 
198## From Ref 1 ([filename]) — REQUIRED elements:
199- [Brand element]: [Specific description of logo/wordmark treatment, e.g., "The logo uses vertical parallel lines (|||) for the letter 'm'. Reproduce this exact treatment."]
200- [Signature pattern]: [Specific description, e.g., "Woven intersecting curves forming a diamond/lozenge grid pattern. This MUST appear prominently as a banner, border, or background section."]
201- [Colors]: [Exact hex values, e.g., "Dark teal #2D4A3E background, cream #F5F0E0 text"]
202- [Typography]: [Specific treatment, e.g., "Uppercase text with wide letter-spacing"]
203- [Layout element]: [Specific spatial element, e.g., "Bottom banner strip in dark color"]
204 
205## From Ref 1 ([filename]) — Characters (if people present):
206- **Character 1**: [Appearance, e.g., "Woman, long wavy blonde hair"] → MUST stylize: [e.g., "flat-vector, simplified face, keep blonde hair, label: 'Nicole Forsgren'"]
207- **Character 2**: [Appearance, e.g., "Man, short dark hair, stubble"] → MUST stylize: [e.g., "flat-vector, simplified face, keep dark hair, label: 'Gergely Orosz'"]
208- **Placement**: [e.g., "Right third, side by side, facing left toward main visual"]
209- **Style**: Match rendering style, NOT photorealistic
210 
211## From Ref 2 ([filename]) — REQUIRED elements:
212[Same detailed breakdown]
213 
214## Integration approach:
215[Specific layout instruction describing how reference elements combine with the cover content, e.g., "Use a SPLIT LAYOUT: main illustration area (warm cream background) occupies ~65% of the image, while a dark teal BANNER STRIP (with the woven line pattern from Ref 2) runs along the bottom ~35%, containing branding elements from Ref 1."]
216```
217 
218**Key rules**:
219- Each visual element gets its own bullet with "MUST" or "REQUIRED"
220- Descriptions must be **specific enough to reproduce** — not vague ("clean style")
221- The integration approach must describe **exact spatial arrangement**
222- After generation, verify reference elements are visible; if not, strengthen and regenerate
223 
224**If style/palette extracted verbally (NO file saved)**:
225- DO NOT add references metadata to prompt
226- Append extracted info directly to prompt body using the same MUST INCORPORATE format above:
227 
228```
229# Reference Style — MUST INCORPORATE (extracted from visual analysis)
230 
231CRITICAL: Apply these specific visual elements extracted from the reference images.
232 
233## REQUIRED elements:
234- [Same detailed bullet format as above]
235 
236## Integration approach:
237[Same spatial layout instruction]
238```
239 
240### Reference Analysis Template
241 
242Use this format when analyzing reference images. Extract **specific, concrete, reproducible** details — not vague summaries.
243 
244| Aspect | Analysis Points | Good Example | Bad Example |
245|--------|-----------------|--------------|-------------|
246| **Brand elements** | Logos, wordmarks, distinctive typography | "Logo 'm' formed by 3 vertical lines" | "Has a logo" |
247| **Signature patterns** | Unique motifs, textures, geometric patterns | "Woven curves forming diamond grid" | "Has patterns" |
248| **Colors** | Exact hex values or close approximations | "#2D4A3E dark teal, #F5F0E0 cream" | "Dark and light" |
249| **Layout** | Spatial zones, banner placement, proportions | "Bottom 30% is dark banner with branding" | "Has a banner" |
250| **Typography** | Font style, weight, case, spacing, position | "Uppercase, wide letter-spacing, right-aligned" | "Has text" |
251| **Rendering** | Line quality, texture, depth treatment | "Topographic contour lines as background texture" | "Clean style" |
252| **Elements** | Icon vocabulary, decorative motifs | "Geometric intersecting line ornaments at corners" | "Has decorations" |
253 
254**Output**: Each extracted element should be written as a **copy-pasteable prompt instruction** prefixed with "MUST" or "REQUIRED".
255