SKILL.md · jhustle44/jcr-guide-pro

Code Commits Issues Pulls Cloud Agent CI/CD

main

copilot/add-firebase copilot/change-app-name-to-jcrguru copilot/create-zip-file copilot/create-zip-file-again copilot/merge-any-updates main master

md 872 lines 28.6 KB

Rendered Raw

1	---
2	name: ad-creative
3	description: Design static ad creatives for social media and display advertising campaigns.
4	---
5
6	# Ad Creative Maker
7
8	Design static ad creatives for social media ads, display banners, and digital advertising campaigns. Build production-ready ads via the design subagent and present them as iframes on the canvas.
9
10	## When to Use
11
12	- User needs ad creatives for Facebook, Instagram, LinkedIn, Google Display, or TikTok
13	- User wants banner ads or display advertising assets
14
15	- User needs multiple ad variants for A/B testing
16	- User wants ad copy and visual design together
17
18	- User wants to iterate on ad creative based on performance data
19	- User asks for carousel ads (Instagram, Facebook, X/Twitter)
20
21	- User wants retargeting/remarketing ad creatives
22	- User provides their own product photos or brand images and wants ads built around them
23
24	- User needs ads in multiple sizes/formats (square + portrait + landscape)
25	- User wants a product launch or teaser campaign
26
27	- User wants seasonal or holiday-themed ads
28	- User needs app install ad creatives
29
30	- User wants to refresh or update existing ads without performance data
31	- User asks to make ads that match their website's look and feel
32
33	## When NOT to Use
34
35	- Organic social media content (use content-machine skill)
36	- Video ads or animated content (use storyboard skill for planning)
37
38	- Full landing pages (use the artifacts skill)
39
40	## Golden Rules (check before every ad)
41
42	1. <20 words total on the image — everything else goes in primary text / description fields
43	2. Only 4 elements per ad: Logo, Hero, Benefit line, CTA button
44
45	3. Flat solid background colors only — no gradients, no patterns, no textures (exception: awareness/launch ads may use a hero image as the background)
46	4. Real brand logo, always — never substitute plain text for a logo (see Logo Extraction below)
47
48	5. Left-align content — logo top-left, text left-aligned, CTA left-aligned. Centered layouts look generic.
49
50	## Methodology
51
52	### Step 1: Creative Brief
53
54	Gather: Platform and Format, Objective, Target audience, Key message, CTA, Brand assets, Performance data (if iterating).
55
56	Brand research (mandatory before building): Always use web search to look up the brand's actual visual identity before designing. Search for `[brand] brand font typeface typography`and`[brand] brand colors hex`. Use the brand's real fonts, colors, and visual language — never guess or substitute generic alternatives. If the official fonts are commercial/licensed, find the closest Google Fonts alternatives used in the brand's own guidelines. Common pairings: a sans-serif for headlines (e.g., Poppins) and a serif for body text (e.g., Lora). Include these in the subagent task instructions so every angle uses the correct brand identity.
57
58	Font loading (mandatory in every ad HTML): After identifying the brand's fonts (or closest Google Fonts alternatives), include them in the head of every ad HTML file:
59
60	```html
61
62	<head>
63
64	<link rel="preconnect" href="https://fonts.googleapis.com">
65
66	<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
67
68	<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;700;900&family=Lora:wght@400;700&display=swap" rel="stylesheet">
69
70	<style>
71
72	.headline { font-family: 'Poppins', sans-serif; }
73
74	.benefit { font-family: 'Lora', serif; }
75
76	</style>
77
78	</head>
79
80	```
81
82	Always specify the exact weights needed (400, 700, 900). Never rely on browser defaults or system fonts — every ad must load its fonts explicitly.
83
84	Extract real brand colors from the site (mandatory). Do not trust web search results for colors — they are frequently wrong. Instead, fetch the actual CSS from the brand's website:
85
86	```bash
87
88	curl -s -L "https://brand.com" \| grep -iE '(theme-color\|TileColor\|mask-icon.*color)' \| head -5
89
90	curl -s -L "https://brand.com" \| tr -d '\n' \| grep -oP 'href="[^"]\\css[^"]"' \| head -3
91
92	curl -s "https://brand.com/path/to/style.css" \| grep -oP '#[0-9a-fA-F]{3,8}' \| sort -u
93
94	```
95
96	### Step 2: Platform Specifications (2025-2026)
97
98	#### Meta (Facebook/Instagram) — Visual
99
100	\| Placement \| Dimensions \| Safe zone \|
101
102	\|---\|---\|---\|
103
104	\| Feed (square) \| 1080x1080 \| ~100px margin all edges \|
105
106	\| Feed (portrait) — preferred \| 1080x1350 (4:5) \| 4:5 outperforms 1:1 on CTR \|
107
108	\| Stories \| 1080x1920 \| Top 14% + bottom 20% = dead zones \|
109
110	\| Reels \| 1080x1920 \| Top 14% + bottom 35% = dead zones \|
111
112	\| Universal safe core\|1010x1280 centered \| Works across all placements \|
113
114	Upload at 2x pixel density for Retina sharpness. JPG/PNG, 30MB max.
115
116	#### Meta — Text
117
118	\| Element \| Limit \| Notes \|
119
120	\|---\|---\|---\|
121
122	\| Primary text \| ~72 chars visible in Reels / 125 in Feed \| Write for 72 \|
123
124	\| Headline \| 40 chars rec \| Below image \|
125
126	\| Description \| 30 chars rec \| Often hidden on mobile \|
127
128	#### Google Ads
129
130	RSA: Headlines 30 chars (each must work standalone — Google mixes randomly), Descriptions 90 chars, up to 15 headlines / 4 descriptions. Pin sparingly — pinning drops Ad Strength.
131
132	RDA: Landscape 1200x628 (1.91:1), Square 1200x1200 (required), Portrait 1200x1500 (4:5, optional). Short headline 30 chars, Long headline 90 chars, Description 90 chars. All images 5MB or less, keep under 150KB for fast load.
133
134	Highest-inventory static sizes (if uploading fixed banners): 300x250, 728x90, 320x50, 300x600, 336x280.
135
136	Performance Max: Same asset pool serves across Search/Display/YouTube/Gmail/Maps/Discover. Upload all 3 image ratios + a YouTube video — don't let Google auto-generate one.
137
138	#### LinkedIn Ads
139
140	Intro text 150 chars rec (600 max), Headline 70 chars rec (200 max), Image 1200x627 or 1200x1200.
141
142	#### TikTok Ads
143
144	1080x1920 (9:16), Ad text 100 chars max (~80 visible). Spark Ads (boosting organic creator posts) outperform In-Feed Ads on engagement.
145
146	#### X / Twitter Ads
147
148	\| Placement \| Dimensions \|
149
150	\|---\|---\|
151
152	\| Single image \| 1200x675 (1.91:1) or 1080x1080 (1:1) \|
153
154	\| Carousel cards \| 1080x1080 (1:1), 2-6 cards \|
155
156	\| Portrait \| 1080x1350 (4:5) \|
157
158	Tweet text 280 chars (~100 visible with media). Card headline 70 chars.
159
160	### Step 3: Determine Campaign Mode
161
162	Before defining angles, determine whether this is direct-responseorawareness/launch.
163
164	#### Direct-Response (default)
165
166	Use for conversion, lead generation, app installs, purchases. This is the default — most ad requests are direct-response.
167
168	#### Awareness / Launch Campaigns
169
170	Use for product launches, brand announcements, event teasers, top-of-funnel awareness. Prioritize mood and brand impression over clicks.
171
172	##### Key differences from direct-response
173
174	- No CTA button on the image. The CTA lives in the post text or link, not the visual.
175	- Even less text: ~10-15 words max — typically brand name, one positioning line, and a date/tagline.
176
177	- Visual metaphor over product shots. Use evocative imagery that communicates feeling or aspiration.
178	- Multiple visual worlds per campaign. For carousels or multi-asset campaigns, create 3-5 distinct aesthetic treatments — different palettes, subjects, moods — while keeping typography and logo placement consistent.
179
180	- Layout pattern: Logo (top corner) then Hero visual (fills most of the frame) then Brand name/headline (bottom, large, bold) then Subtitle + date (smaller, below headline).
181	- Hero images allowed. Unlike direct-response, awareness ads may use a full-bleed generated image as the background (see Image Guidance below).
182
183	When to use awareness mode: Pre-launch teasers, brand-building campaigns, event promotion, or when the user says "announce," "tease," "launch," or asks for something "premium" without conversion goals.
184
185	### Step 3b: Define Angles
186
187	Before writing individual copy, establish 3-5 distinct angles — different reasons someone would click:
188
189	\| Category \| Example \|
190
191	\|----------\|---------\|
192
193	\| Pain point \| "Stop wasting time on X" \|
194
195	\| Outcome \| "Achieve Y in Z days" \|
196
197	\| Social proof \| "Join 10,000+ teams who..." \|
198
199	\| Curiosity \| "The X secret top companies use" \|
200
201	\| Identity \| "Built for [specific role/type]" \|
202
203	\| Urgency \| "Limited time: get X free" \|
204
205	\| Contrarian \| "Why [common practice] doesn't work" \|
206
207	For retargeting ads, adjust angles for warm audiences who already know the brand:
208
209	- Reminder: "Still thinking about X?"
210	- Incentive: "Come back for 15% off"
211
212	- Social proof: "See why 10,000 others chose us"
213	- Scarcity: "Only 3 left in your size"
214
215	- Objection handling: "Free returns, no risk"
216
217	### Step 4: Design Principles
218
219	- Under 20 words total on the image — this is the most important rule. Icons, stats rows, feature grids, and badges all violate this. If it doesn't fit in Logo + Hero + Benefit + CTA, it belongs in the primary text.
220	- Visual hierarchy: Logo (top-left) then Hero element then Benefit then CTA
221
222	- WCAG 4.5:1 contrast minimum
223	- CTA: contrasting color, rounded corners, verb-first, left-aligned
224
225	- No gradients — flat solid colors only. Use different solid colors across ads for variety. Exception: awareness/launch ads may use a bottom readability gradient over a hero image.
226
227	### Steps 5-6: Generate and Validate Copy
228
229	Vary word choice, specificity, tone, and structure across angles. Always validate character counts before delivering. Include counts in your output.
230
231	```text
232
233	## Angle: [Pain Point — Manual Reporting]
234
235	### Headlines (30 char max)
236
237	1. "Stop Building Reports by Hand" (29)
238	2. "Automate Your Weekly Reports" (28)
239
240	3. "Reports in 5 Min, Not 5 Hrs" (27)
241
242	### Descriptions (90 char max)
243
244	1. "Marketing teams save 10+ hours/week with automated reporting. Start free." (73)
245	2. "Connect your data sources once. Get automated reports forever. No code required." (80)
246
247	```
248
249	### Step 7: Build Ad Creatives
250
251	#### File Setup
252
253	Place all ad HTML files in `artifacts/mockup-sandbox/public/ads/`— served by the mockup-sandbox Vite dev server at`/__mockup/ads/filename.html`.
254
255	After copying image assets from `attached_assets/`, always fix permissions:
256
257	```bash
258
259	chmod 644 artifacts/mockup-sandbox/public/ads/.png artifacts/mockup-sandbox/public/ads/.jpg
260
261	```
262
263	Files copied from `attached_assets/`default to`rw-------` (unreadable by the server).
264
265	#### Cache Busting
266
267	Canvas iframes cache aggressively. After editing any ad file, increment `?v=N` on the iframe URL:
268
269	```text
270
271	https://your-domain.dev/__mockup/ads/angle1.html?v=2
272
273	```
274
275	#### Parallel Subagents — Full Task Template
276
277	Launch one design subagent per angle simultaneously. Each subagent gets a complete, self-contained task with all brand details, the HTML structure, and styling rules baked in. Do not assume the subagent knows any of the golden rules — repeat them explicitly.
278
279	```javascript
280
281	await startAsyncSubagent({
282
283	task: `Create a production-ready ad creative as a standalone HTML file.
284
285	Brand:
286
287	- Name: [Brand Name]
288	- Primary color: [hex] \| Secondary: [hex] \| Accent: [hex]
289
290	- Headline font: [Font Name] (Google Fonts — load via link tag in head)
291	- Body font: [Font Name] (Google Fonts — load via link tag in head)
292
293	- Logo: [inline SVG code or path to logo file]
294
295	Ad Details:
296
297	- Platform: [Meta Feed / Google Display / LinkedIn / TikTok / X]
298	- Angle: [Pain Point / Outcome / Social Proof / etc.]
299
300	- Headline: "[exact headline text]"
301	- Benefit: "[one short benefit line]"
302
303	- CTA: "[verb-first CTA text]"
304	- Background color: [hex — flat solid, NO gradients]
305
306	File: Write to artifacts/mockup-sandbox/public/ads/[filename].html
307
308	MANDATORY HTML STRUCTURE — follow exactly:
309
310	The ad must use this structure:
311
312	- html/body: width 100vw, height 100vh, overflow hidden, margin 0, padding 0
313	- .ad container: width 100vw, height 100vh, solid background color (NO gradients), flex column, justify-content space-between, padding 6vh 7vw
314
315	- .logo: top-left, inline SVG at height 5vh
316	- .middle: flex column, gap 3vh, containing headline, benefit, and CTA
317
318	- .headline: brand headline font, font-size 8vw, font-weight 900, line-height 1.1
319	- .benefit: brand body font, font-size 3vw, slightly transparent white
320
321	- .cta: inline-block, padding 2vh 5vw, accent color background, border-radius 1vw, font-weight 700, align-self flex-start (LEFT-ALIGNED)
322	- .footer: font-size 1.8vw, subtle color, brand URL
323
324	RULES — do not violate:
325
326	- Only 4 elements: Logo, Headline, Benefit, CTA. No icons, stats, badges, feature grids, or dividers.
327	- Under 20 words total visible on the ad.
328
329	- Flat solid background color — NO gradients, NO patterns.
330	- All sizing in vw/vh — NO fixed pixel dimensions.
331
332	- Left-align everything — logo top-left, text left-aligned, CTA left-aligned. Do NOT center.
333	- Load fonts from Google Fonts in the head. Do NOT use system fonts or Inter.
334
335	- The CTA button must use a contrasting accent color and be verb-first.`,
336
337	specialization: "DESIGN",
338
339	relevantFiles: ["artifacts/mockup-sandbox/public/ads/[filename].html"]
340
341	});
342
343	// Repeat for each angle — all launch simultaneously
344
345	```
346
347	After launching, call the `wait_for_background_tasks` tool to wait for every ad-design subagent. Then embed each ad as an iframe on the canvas using `apply_canvas_actions`, and call `presentArtifact({ artifactId, shapeIds: [...] })` with the IDs of the new iframe shapes.
348
349	#### Viewport-Relative Sizing (mandatory)
350
351	```css
352
353	html, body {
354
355	margin: 0; padding: 0;
356
357	width: 100vw; height: 100vh;
358
359	overflow: hidden;
360
361	}
362
363	```
364
365	All internal sizing must use vw/vh. No fixed pixel dimensions on containers.
366
367	#### Ad HTML Structure (mandatory pattern)
368
369	Every ad must follow this exact structure — 4 elements, no more:
370
371	```html
372
373	<div class="ad">
374
375	<div class="logo"><!-- SVG or img --></div>
376
377	<div class="middle">
378
379	<div class="headline">Hero text here</div>
380
381	<div class="benefit">One short benefit line.</div>
382
383	<div class="cta">Verb-first CTA</div>
384
385	</div>
386
387	<span class="footer">brand.com</span>
388
389	</div>
390
391	```
392
393	```css
394
395	.ad {
396
397	width: 100vw;
398
399	height: 100vh;
400
401	background: \#SOLID_COLOR;
402
403	display: flex;
404
405	flex-direction: column;
406
407	justify-content: space-between;
408
409	padding: 6vh 7vw;
410
411	box-sizing: border-box;
412
413	}
414
415	.middle {
416
417	display: flex;
418
419	flex-direction: column;
420
421	gap: 3vh;
422
423	}
424
425	```
426
427	Do not add icons, stats rows, feature grids, badges, dividers, or any decorative elements. If you are tempted to add a 5th element, move that information to the primary text instead.
428
429	#### Image Guidance
430
431	##### When to use generated images
432
433	- Awareness/launch campaigns — the hero image IS the ad, with text overlaid on a bottom gradient
434	- When the user explicitly requests photo-based or image-heavy ads
435
436	###### When NOT to use images (default for direct-response)
437
438	- Standard direct-response ads use flat solid color backgrounds with bold typography
439	- The 4-element rule (Logo, Hero text, Benefit, CTA) works best without competing with a background image
440
441	###### If using a hero image (awareness/launch mode only)
442
443	Generate images using `generateImage`from the media-generation skill. Save to`artifacts/mockup-sandbox/public/images/`and reference via`/__mockup/images/[filename].png`.
444
445	Image prompt strategy:
446
447	- Lead with a specific, tangible subject (object, scene, or person)
448	- Specify lighting (studio, dramatic, golden hour, Rembrandt)
449
450	- Specify camera quality ("shot on Hasselblad," "editorial photography")
451	- Add negative prompts: "text, words, letters, logos, watermark, blurry, low quality, cartoon, illustration"
452
453	- Each ad should use a different visual metaphor — same brand, different visual world
454
455	Image-first HTML structure (awareness/launch only):
456
457	```css
458
459	.ad {
460
461	width: 100vw; height: 100vh;
462
463	position: relative; overflow: hidden;
464
465	}
466
467	.hero-img {
468
469	position: absolute; inset: 0;
470
471	width: 100%; height: 100%;
472
473	object-fit: cover;
474
475	}
476
477	.gradient-overlay {
478
479	position: absolute; bottom: 0; width: 100%;
480
481	height: 50vh;
482
483	background: linear-gradient(transparent, rgba(0,0,0,0.8));
484
485	}
486
487	.content {
488
489	position: absolute; bottom: 0; left: 0;
490
491	padding: 6vh 7vw;
492
493	}
494
495	```
496
497	If the user provides their own images: Use the user's images instead of generating new ones. Copy from `attached_assets/`to`artifacts/mockup-sandbox/public/images/`, fix permissions with`chmod 644`, and reference via`/__mockup/images/[filename]`. Use the awareness/launch image-first layout structure above.
498
499	#### Brand Logo Extraction
500
501	Always use the brand's actual logo — never substitute plain text for a logo.
502
503	Step 1: Extract the SVG directly from the brand's website. This is the most reliable method — the actual logo is already embedded in their HTML:
504
505	```bash
506
507	curl -s -L "https://brand.com" \| tr -d '\n' \| grep -oP '<svg viewBox="[^"]"[^>]>.*?</svg>' \| head -1 > /tmp/brand-logo.svg
508
509	wc -c /tmp/brand-logo.svg
510
511	```
512
513	Should be over 1KB for a real logo.
514
515	Step 2: Verify the extracted SVG path data is complete. SVG path data can be silently truncated during shell extraction. Always verify the max coordinates fit within the viewBox:
516
517	```bash
518
519	node -e "
520
521	const fs = require('fs');
522
523	const svg = fs.readFileSync('/tmp/brand-logo.svg', 'utf8');
524
525	const dMatch = svg.match(/d=\([^\\]+)\\/);
526
527	if (dMatch) {
528
529	const d = dMatch[1];
530
531	console.log('Path data length:', d.length);
532
533	console.log('Last 80 chars:', d.slice(-80));
534
535	const nums = d.match(/[\d.]+/g).map(Number);
536
537	const maxX = Math.max(...nums.filter((_, i) => i % 2 === 0));
538
539	console.log('Max X:', maxX);
540
541	}
542
543	"
544
545	```
546
547	If path data length is under ~2000 characters for a wordmark logo, the data was likely truncated. Re-extract with a larger buffer.
548
549	Step 3: Embed inline. Embedding the SVG directly in the HTML avoids file permission issues, eliminates loading delays, and scales perfectly:
550
551	```html
552
553	<svg viewBox="0 0 100 32" fill="none" xmlns="http://www.w3.org/2000/svg"
554
555	style="height:5vh;width:auto;">
556
557	<path fill-rule="evenodd" clip-rule="evenodd" d="..." fill="white"/>
558
559	</svg>
560
561	```
562
563	Use `fill="white"`on dark backgrounds,`fill="#BrandDarkColor"` on light backgrounds.
564
565	Step 4: Position the logo top-left, not centered. The logo should sit in the top-left corner as part of the visual hierarchy. Do not center-align logos — centered layouts look generic and reduce brand recognition.
566
567	Fallback: If the website doesn't have an inline SVG, search for `[brand] logo SVG site:wikimedia.org OR site:brandfetch.com`. As a last resort, use a logo + wordmark pattern with the brand's font.
568
569	If using an image file for the logo, always use both max-width and max-height together:
570
571	```css
572
573	.logo-img {
574
575	max-width: 38vw;
576
577	max-height: 12vh;
578
579	width: auto;
580
581	height: auto;
582
583	object-fit: contain;
584
585	}
586
587	```
588
589	Never use `width: Xvw; height: auto` alone on a square logo — at width 38vw, a square image is also 38vh tall and will overflow its container into content below.
590
591	Logo images have built-in padding. The visible logo mark may only occupy 50-70% of the image dimensions. Size the image larger than you'd expect.
592
593	##### Logos without transparent backgrounds
594
595	\| Scenario \| Strategy \|
596
597	\|---\|---\|
598
599	\| Ad bg color matches logo bg exactly \| Use that logo version — backgrounds blend seamlessly \|
600
601	\| White ad background \| Use white-background logo + mix-blend-mode: multiply \|
602
603	```css
604
605	.logo-img { mix-blend-mode: multiply; }
606
607	```
608
609	#### Canvas Layout
610
611	Place ad iframes side-by-side in a row for easy comparison. Use square iframes (600x600) so they fit on the canvas without clipping. Space them with ~50px gutters:
612
613	```text
614
615	x=0, y=0: [Iframe: Angle 1] (600x600)
616
617	x=650, y=0: [Iframe: Angle 2] (600x600)
618
619	x=1300, y=0: [Iframe: Angle 3] (600x600)
620
621	```
622
623	For portrait/stories ads (9:16): Use 608x1080 iframes:
624
625	```text
626
627	x=0, y=0: [Iframe: Story 1] (608x1080)
628
629	x=658, y=0: [Iframe: Story 2] (608x1080)
630
631	x=1316, y=0: [Iframe: Story 3] (608x1080)
632
633	```
634
635	For multi-format output (same angle in multiple sizes): Stack formats vertically per angle:
636
637	```text
638
639	x=0, y=0: [Iframe: Angle 1 — Square] (600x600)
640
641	x=0, y=650: [Iframe: Angle 1 — Portrait] (450x600)
642
643	x=650, y=0: [Iframe: Angle 2 — Square] (600x600)
644
645	x=650, y=650: [Iframe: Angle 2 — Portrait] (450x600)
646
647	```
648
649	For carousel ads: Place cards in sequence left-to-right:
650
651	```text
652
653	x=0, y=0: [Iframe: Card 1] (600x600)
654
655	x=650, y=0: [Iframe: Card 2] (600x600)
656
657	x=1300, y=0: [Iframe: Card 3] (600x600)
658
659	x=1950, y=0: [Iframe: Card 4] (600x600)
660
661	```
662
663	Do not add text labels above iframe shapes — iframes already display their componentName in the title bar. Set componentName to something descriptive like "Angle 1: Outcome — Think deeper. Get further."
664
665	With landing page mock-ups (optional — include when the user wants to see the full click-through experience): Place the landing page iframe next to each ad:
666
667	```text
668
669	x=0, y=0: [Iframe: Angle 1 Ad] (600x600)
670
671	x=650, y=0: [Iframe: Angle 1 Landing] (1280x720)
672
673	x=0, y=650: [Iframe: Angle 2 Ad] (600x600)
674
675	x=650, y=650: [Iframe: Angle 2 Landing] (1280x720)
676
677	```
678
679	The landing page should look like where the ad actually leads — hero section echoing the ad's message, value props, social proof, and a CTA. Not a wireframe.
680
681	#### Export
682
683	Ads use vw/vh sizing so they adapt to any viewport. For export at specific pixel dimensions:
684
685	```bash
686
687	npx playwright screenshot artifacts/mockup-sandbox/public/ads/angle1.html --viewport-size=1080,1080 -o angle1-1080.png
688
689	npx playwright screenshot artifacts/mockup-sandbox/public/ads/angle1.html --viewport-size=1080,1350 -o angle1-portrait.png
690
691	npx playwright screenshot artifacts/mockup-sandbox/public/ads/story1.html --viewport-size=1080,1920 -o story1.png
692
693	```
694
695	The user can also screenshot each iframe directly from the canvas, or open the HTML files in a browser at the desired size.
696
697	## Prompt-Specific Workflows
698
699	### Carousel Ads
700
701	When the user asks for carousel ads (Instagram, Facebook, X/Twitter):
702
703	1. Each card should be a self-contained visual — assume viewers swipe quickly.
704	2. Use a consistent structural layoutacross cards (same typography placement, same logo position) withvarying content/colors per card. This "same but different" effect rewards swiping.
705
706	3. For Instagram/Facebook carousels: 1080x1080 per card, 2-10 cards.
707	4. For X/Twitter carousels: 1080x1080 per card, 2-6 cards with optional headline/URL per card.
708
709	5. Launch one subagent per card in parallel. Include the card number and total count so the subagent can create a coherent sequence.
710	6. Arrange cards left-to-right on the canvas so the user can see the swipe flow.
711
712	### Retargeting / Remarketing Ads
713
714	When the user asks for retargeting ads:
715
716	1. Adjust copy for warm audiences who already know the brand — don't introduce the brand, remind them.
717	2. Use retargeting-specific angles: Reminder, Incentive, Social Proof, Scarcity, Objection Handling (see Step 3b).
718
719	3. Consider dynamic elements: "Still interested in [product]?", "Your cart is waiting", etc.
720	4. Shorter, more direct copy — they already know you.
721
722	### User-Provided Images
723
724	When the user uploads their own product photos or brand images:
725
726	1. Copy from `attached_assets/`to`artifacts/mockup-sandbox/public/images/`.
727	2. Run `chmod 644` on all copied files.
728
729	3. Use the awareness/launch image-first layout (full-bleed image with gradient overlay and text on top).
730	4. Do NOT generate new images — use the user's images as-is.
731
732	5. Adapt the text overlay colors to work with the specific image's brightness/contrast.
733
734	### Multi-Format Output
735
736	When the user needs the same ad in multiple sizes:
737
738	1. Create one HTML file per size variant (e.g., `angle1-square.html`,`angle1-portrait.html`,`angle1-landscape.html`).
739	2. The HTML structure stays the same — vw/vh sizing handles the adaptation. But adjust font sizes and padding for extreme aspect ratios (landscape needs smaller headline vw, portrait can go bigger).
740
741	3. Stack formats vertically per angle on the canvas for easy comparison.
742	4. Test each format at its target pixel dimensions to verify nothing clips or overflows.
743
744	### Awareness / Launch Campaigns (2)
745
746	When the user asks for a launch, teaser, or brand awareness campaign:
747
748	1. Switch to awareness mode (see Step 3 above).
749	2. Generate hero images using `generateImage` — each ad should use a different visual metaphor.
750
751	3. Use image-first layout with gradient overlay.
752	4. No CTA button on the image. ~10-15 words max.
753
754	5. For multi-card campaigns, maintain identical text layout and logo placement across cards while varying the hero visual and color palette.
755
756	### Seasonal / Holiday Ads
757
758	When the user asks for holiday or seasonal ads:
759
760	1. Use the standard methodology but adjust angles for urgency and timeliness.
761	2. Incorporate seasonal colors subtly — don't overwhelm the brand identity. The brand's colors should still dominate; seasonal colors are accents.
762
763	3. Include time-bound CTAs: "Order by Dec 15 for guaranteed delivery", "48-hour flash sale".
764	4. Consider the platform's ad approval timeline — submit 3-5 days before the holiday.
765
766	### App Install Ads
767
768	When the user asks for app install ad creatives:
769
770	1. CTA should be app-specific: "Download Free", "Get the App", "Try It Free".
771	2. Consider showing a device mockup or screenshot (if the user provides one).
772
773	3. For Google App Campaigns: supply landscape (1200x628), portrait (1200x1500), and square (1200x1200) images.
774	4. Keep the value proposition ultra-clear — users decide in 1-2 seconds whether to install.
775
776	### Refreshing Existing Ads
777
778	When the user wants to update or refresh existing ads without performance data:
779
780	1. Review the existing ads (ask the user to share them or describe them).
781	2. Keep the same brand identity and overall strategy.
782
783	3. Freshen: new headline variations, new background colors, new angles that weren't tested.
784	4. Do NOT change what's working — if the user says "these are doing fine, just want fresh versions," keep the structure and vary the copy/colors.
785
786	## Iterating from Performance Data
787
788	When the user provides performance data:
789
790	1. Analyze winners: Identify winning themes, structures, word patterns, and character utilization in top performers (by CTR, conversion rate, or ROAS).
791	2. Analyze losers: Identify themes that fall flat and common patterns in underperformers.
792
793	3. Generate new variations: Double down on winning themes, extend winning angles, test 1-2 new unexplored angles, avoid patterns from underperformers.
794	4. Document the iteration: Track what was learned, what's being tested, and what angles were retired.
795
796	Present the analysis to the user before building new ads:
797
798	```text
799
800	## Performance Analysis
801
802	### Winners (keep and extend)
803
804	- Pain point angles performing 2.3x above average CTR
805	- Headlines with specific numbers ("75% faster") outperform vague claims
806
807	### Losers (retire)
808
809	- Curiosity angles underperforming — audience is solution-aware, not problem-aware
810	- Long headlines (over 25 chars) getting truncated on mobile
811
812	### New Test Plan
813
814	- 2 new pain point variations (doubling down on winner)
815	- 1 social proof angle (untested category)
816
817	- Retire all curiosity angles
818
819	```
820
821	## Research Before Writing
822
823	Use web search to find examples of top-performing ads in the user's vertical. Search for ad breakdowns, swipe files, and case studies — e.g. `[industry] top performing Facebook ads 2026`or`[industry] TikTok ad examples`. Reverse-engineer: what hook, what angle, what visual pattern. Don't guess what works — look it up.
824
825	## Common Mistakes
826
827	### Content overload (most common)
828
829	- Adding icons, stats rows, feature grids, or badges — these violate the under-20-word rule. Each ad should have exactly 4 elements: Logo, Hero, Benefit, CTA.
830	- Using gradients instead of flat solid colors (except awareness/launch hero images)
831
832	- Centering all content instead of left-aligning (left-aligned text feels more intentional and professional)
833
834	#### Logo issues
835
836	- Using plain text instead of the brand's actual logo — always extract the real SVG from the brand's website first
837	- Truncated SVG path data — always verify path length and max coordinates after extraction
838
839	- Not checking that the SVG viewBox contains the full logo (max X/Y must be within viewBox bounds)
840
841	##### Brand identity
842
843	- Trusting web search for brand colors — always extract actual hex values from the site's CSS
844	- Using generic fonts (e.g., Inter) instead of the brand's actual typeface
845
846	- Not loading fonts via Google Fonts link in the HTML head — relying on system fonts
847
848	###### Technical
849
850	- width Xvw with height auto alone on square logo images (overflows container)
851	- Forgetting chmod 644 on assets copied from attached_assets (server can't read them)
852
853	- Not incrementing ?v=N on iframe URLs after editing HTML files
854	- Placing ad files in the wrong directory (use artifacts/mockup-sandbox/public/ads/, not client/public/ads/)
855
856	###### Copy
857
858	- RSA headlines that only work in sequence (Google mixes them — each must stand alone)
859	- Writing for the 125-char feed limit when Reels only shows 72
860
861	- All angles being the same message reworded (vary the psychology, not the synonyms)
862	- Text in the bottom 35% of a 9:16 ad (covered by platform UI)
863
864	- Letting Performance Max auto-generate video — always supply your own
865
866	###### Subagent delegation
867
868	- Not including the full HTML structure template in the subagent task — subagents will invent their own layout
869	- Not repeating the golden rules in each subagent task — they don't inherit context from the main agent
870
871	- Not specifying font loading instructions — subagents will use system fonts
872	- Not providing the exact brand colors and logo SVG — subagents will guess