Lab notes
Prompt recipes
Every post runs through three explicit stages you can retune independently: a strict JSON schema for copy and hotspot coordinates, reference-locked image generation so room geometry never drifts between scroll states, programmatic 2:3 and 9:16 typography in Node (never let an image model render the headline), and — starting in v2 — a product-first style bible with a versioned grading scorecard.
1. Structured post prompt
prompts/post-schema-prompt.md
# Stage 1 — Structured post prompt
Use this as the **system prompt** when generating or revising a Sorrel Design scrollytelling post. The model must return a single JSON document that validates against the Zod schema in `src/content.config.ts`. No markdown fences, no preamble.
## System prompt (verbatim)
```
You are a senior interiors editor writing shoppable desk-setup studies for a Pinterest landing page, not a generic AI listicle.
Return ONLY valid JSON that matches this TypeScript/Zod shape:
{
title: string; // specific, editorial, no clickbait spam
seoTitle: string; // includes niche keywords naturally, < 70 chars if possible
description: string; // 1–2 sentences, concrete, used for meta + intro
kicker: string; // short series label, e.g. "Home office study No. 02"
pinterestKeywords: string[]; // 8–14 phrases people actually search on Pinterest
scenes: Array<{
id: string; // slug: daylight | night | upgrade | ...
label: string; // short pill label
subtitle: string; // one sentence that earns the scroll
lighting: string; // factual lighting description
image: string; // /images/scenes/<file>.webp
imageFallback: string; // /images/scenes/<file>.jpg
alt: string; // descriptive, no keyword stuffing
hotspots: Array<{
id: string;
x: number; // 0–100, percent of image width
y: number; // 0–100, percent of image height
item: string; // product name with a concrete dimension or material
priceRange: string; // street range, e.g. "$45–$90"
category: string;
whyItWorks: string; // 80–160 words: dimensions, tradeoffs, what to skip
searchQuery: string; // retailer-agnostic search string
affiliateUrl: string; // MUST be a clearly labeled placeholder URL
}>
}>;
pinHooks: Array<{
id: string; // pin-1-daylight, etc.
sceneId: string;
badge: string;
headline: string[]; // 2–3 short lines, no punctuation spam
subhead: string;
cropX?: number; // 0–1, left origin of the 2:3 crop
}>;
}
Anti-slop rules (non-negotiable):
- Never invent Amazon ASINs, affiliate tags, or live product URLs. Affiliate links must use the placeholder form https://example.com/affiliate-placeholder?q=<slug>.
- Every hotspot must include a real dimension, a material, and a tradeoff (what this size/material gets you vs. the next option up or down).
- No generic filler: "elevate your space", "cozy vibes", "perfect for any home", "must-have", "game-changer", "unlock", "delve", "in today's fast-paced world".
- Do not name specific retail brands unless the user supplies a real SKU to feature.
- 8 unique products across the post, placed only on scenes where the object is actually visible.
- Hotspot (x, y) coordinates must be estimated from the locked camera frame, not guessed in empty corners.
- Sentences are short, specific, and slightly opinionated, like a magazine editor who has measured a 24-inch-deep desk.
- Pinterest keywords should mix head terms ("small space home office") with long-tails ("walnut acoustic slat wall office").
```
## User prompt skeleton
```
Write the JSON for a scrollytelling post in the niche "Home Office & Small-Space Desk Setups".
Locked visual brief:
- Desk: 48" W × 24" D walnut top on matte black steel legs
- Display: 27" 1440p IPS on a single gas-spring arm
- Seating: black mesh task chair
- Scenes: (1) morning side-window daylight, light bar OFF; (2) evening 2700K lamp + light bar ON + bias glow; (3) same footprint with vertical walnut acoustic slat wall and warm evening accent light
Camera is a slightly elevated front-left three-quarter. Keep product set identical across scenes except for the lamp (scene 2+) and slat wall (scene 3).
Audience: renters and small-apartment WFH setups. Monetization path: Amazon Associates placeholders only (Home/Furniture 3%, PC 2.5%).
```
2. Reference-locked scene visuals
prompts/scene-visual-prompt.md
# Stage 2 — Reference-locked scene visuals Images are generated with the `GenerateImage` tool at aspect ratio `4:3`. Scene 1 is a fresh photograph-style generation. Scenes 2 and 3 pass Scene 1's exact saved file path in `reference_image_paths` so camera, furniture, and geometry stay locked for scroll crossfades. Do **not** let the image model render headline typography. Pins are composited in `scripts/generate-pins.mjs`. ## Scene 1 — `desk-scene-1-daylight.png` (base, 4:3) Tool: `GenerateImage` `filename`: `desk-scene-1-daylight.png` `aspect_ratio`: `4:3` `reference_image_paths`: none Prompt used (verbatim): ``` A realistic, authentic-looking photograph (not CGI, not overly glossy, not AI-perfect), shot with a real camera look: slight natural grain, true-to-life color, gentle lens softness at the edges, natural window light. Compact 48-inch minimalist home office desk setup against a warm-white painted wall. Natural morning daylight streams in from a window on the LEFT side of the frame, casting soft, believable shadows across a clean walnut wood desktop with visible wood grain. The desk sits on simple matte black metal hairpin or square-tube legs. On the desk: a 27-inch black-bezel monitor on a sleek matte-black gas-spring monitor arm, a compact low-profile mechanical keyboard centered in front of the monitor, a simple black mouse, a slim monitor light bar mounted on top of the monitor (currently OFF, unlit), and a small healthy green potted plant on the right side of the desk. An ergonomic black mesh office chair is tucked slightly under the desk, facing the camera-right of center. Cables are neatly managed and barely visible. The camera is at a slightly elevated three-quarter angle from the front-left, showing the full desk, chair, wall, and a sliver of light wood or grey-brown floor. No people, no text, no watermarks, no logos, no brand names. Photorealistic interior photography, editorial lifestyle, like a high-end design magazine photo taken in a real apartment. ``` Saved source (this run): `/cursor/stores/user/grok-bot/agents/74f198b9-bed7-4357-866e-78a847113a37/assets/23aa3385cfee2012d697273ef2dfaba9eb7eb6a779f5ad4c9ab79653c080d268.jpg` ## Scene 2 — `desk-scene-2-night.png` (reference-locked edit, 4:3) Tool: `GenerateImage` `filename`: `desk-scene-2-night.png` `aspect_ratio`: `4:3` `reference_image_paths`: `[<exact Scene 1 saved path>]` Prompt used (verbatim): ``` Using the provided reference photograph, keep the IDENTICAL camera angle, lens, framing, furniture layout, desk footprint, chair position, monitor, monitor arm, keyboard, mouse, plant, and wall geometry. Do not restage the room. Transform ONLY the lighting and time of day into a moody evening scene: the left window is now dark night with faint cool moonlight, no bright daylight. A warm 2700K amber desk lamp now sits on the left side of the walnut desktop (near the window) and glows softly, casting warm pools of light across the wood grain. The slim monitor light bar on top of the monitor is now ON, glowing with a soft warm-white wash down the screen (screen itself can show a dim dark desktop, not bright white). Add a subtle bias backlight / faint warm glow behind the monitor against the wall. Overall mood is cozy, dim, cinematic evening, authentic photography with gentle grain, not CGI. No people, no text, no watermarks, no logos. ``` Saved source (this run): `/cursor/stores/user/grok-bot/agents/74f198b9-bed7-4357-866e-78a847113a37/assets/628728276db0ff933b875f248a05400efc4f5f42d984366b1b6b10322412d533.jpg` ## Scene 3 — `desk-scene-3-slat-upgrade.png` (reference-locked edit, 4:3) Tool: `GenerateImage` `filename`: `desk-scene-3-slat-upgrade.png` `aspect_ratio`: `4:3` `reference_image_paths`: `[<exact Scene 1 saved path>]` Prompt used (verbatim): ``` Using the provided reference photograph, keep the IDENTICAL camera angle, lens, framing, desk footprint, chair position, monitor, monitor arm, keyboard, mouse, plant, and overall furniture layout. Do not restage the room or change the camera. Upgrade the blank warm-white wall BEHIND the desk with vertical walnut wood slat acoustic wall paneling (narrow vertical walnut slats with black felt backing, floor-to-upper-wall coverage behind the desk, like a modern acoustic wood slat feature wall). Lighting should be a warm evening accent look: softer ambient light than the original daylight photo, with a gentle warm glow grazing the walnut slats to emphasize the vertical texture, and the monitor light bar softly on. Cozy, architectural, authentic interior photography with gentle grain, not CGI or glossy 3D. No people, no text, no watermarks, no logos. ``` Saved source (this run): `/cursor/stores/user/grok-bot/agents/74f198b9-bed7-4357-866e-78a847113a37/assets/eaab74f2f1e560bf81e2c8211f9c20093268411711f2f0321b1fd84d116cfd3a.jpg` ## Conversion for the site All three sources are copied into `public/images/scenes/` as: - `<name>.jpg` — original for pin compositing and `<picture>` fallback - `<name>.png` — lossless original for pin compositing - `<name>.webp` — quality 82, served on the scrollytelling page Geometry rule for future scenes in this series: always pass the Scene 1 path (not Scene 2) as the reference so lighting edits cannot compound.
3. Pin copy & A/B hooks
prompts/pin-copy-prompt.md
# Stage 3 — Pinterest SEO keyword & A/B hook prompt
Use this when writing `pinHooks` and `pinterestKeywords` for a post. Headlines are composited programmatically by `scripts/generate-pins.mjs` (Sharp + SVG). **Never ask an image model to render the type.**
Pin canvas is always **1000 × 1500 (2:3)**. Keep headlines to 2–3 short lines, no more than ~28 characters per line, no exclamation points, no ALL CAPS words except short badges.
## System prompt (verbatim)
```
You write Pinterest pin copy for a shoppable interiors site. Output JSON only:
{
"pinterestKeywords": string[], // 8–14 search phrases, mix of head + long-tail
"pinHooks": [
{
"id": "pin-1-daylight" | "pin-2-night" | "pin-3-upgrade" | string,
"sceneId": string,
"badge": string, // 1–3 words, title case, no emoji
"headline": string[], // 2–3 lines, concrete noun + benefit, no clickbait
"subhead": string, // one supporting line, ≤ 60 characters
"cropX": number // 0–1, left origin of the vertical crop on a 4:3 source
}
]
}
Rules:
- Each scene gets a DISTINCT hook. Do not repeat the same promise in different words.
- Lead with a specific object, dimension, price, or transformation ("The 48-Inch Desk", "The $80 Wall Upgrade", "Same Desk. Night Mode.") rather than mood words ("cozy", "aesthetic", "vibes").
- Keywords should be the phrases a Pinterest shopper types ("small space home office", "walnut acoustic slat wall office"), not a pile of single tokens.
- No emoji, no fire/sparkle unicode, no "Link in bio", no "Shop now" in the headline (the pin already has a shop affordance in the subhead or site mark).
- Write for a mobile thumb: the first line of the headline must make sense if the rest is cropped by a UI chrome.
- Assume Pinterest may label the image "AI modified". The hook should still promise a useful, specific setup, not "AI room inspiration".
```
## A/B hooks used for study No. 01
| Pin file | Scene | Badge | Headline | Subhead |
|---|---|---|---|---|
| `pin-1-daylight.png` | Morning daylight | Small-space office | The 48-Inch Desk / That Feels Twice / as Wide | Eight shoppable pieces for a compact home office. |
| `pin-2-night.png` | Evening, 2700K | Lighting | Same Desk. / Night Mode. | 2700K lamp + light bar, zero screen glare. |
| `pin-3-upgrade.png` | Walnut slat wall | Weekend project | The $80 Wall / Upgrade | Walnut acoustic slats that finish the room. |
Generate pins with:
```
npm run pins
```
Output lands in `dist-pins/`.
4. v2 style bible & product-first recipe
prompts/warm-midcentury-style-prompt.md
# v2 — Warm mid-century style bible & product-first recipe This is the v2 pipeline. It is different from the v1 desk study: we pick real, in-stock products first, then stage an original room around them. We never copy a creator's layout, and we never invent a URL or a price. Style bible: `styles/warm-midcentury.json` Reference board: `style-references/ref-01` through `ref-09` (palette and mood only) Grading: `evals/scorecard.json` — quality gate is `minOverallScore: 8.0` ## 1. Product-first sourcing Search and verify six buyable pieces before any image is generated: 1. Burnt-rust / cognac / terracotta tufted low-profile sofa 2. Fluted walnut media console / credenza 3. Oversized rice-paper globe pendant (prefer official Akari) 4. Sculptural amber-glass or ceramic mushroom table lamp 5. Organic walnut or travertine low coffee table 6. Deep olive velvet swivel chair (or a cream Moroccan rug) For every item, record the exact title, brand, retailer, a `curl`-verified URL (403 anti-bot on a known retailer is allowed; drop 404s), a current price, and `affiliateTagReady: true`. Do not fabricate ASINs or attach an affiliate tag that does not exist. Save downloadable product photographs to `assets-raw/products/`. ## 2. Reference-locked editorial scenes (4:3) Use `GenerateImage` at 4:3. Ground the prompt in the style bible (terracotta plaster, oiled walnut, 2200K–2700K amber, 35mm editorial film, lived-in human scale, no white walls, no corporate minimalism). Pass the real product photographs as `reference_image_paths` so silhouettes match the buyable items. Do **not** pass the Instagram reference screenshots as composition references — they are for palette and mood only, and the room must be original. - **Scene 1 — Golden hour.** Late-afternoon sunbeams, dust motes, rich shadows. Sofa, table, credenza, official-style paper lantern, mushroom lamp, bird-of-paradise, cream rug, record player. No olive chair, no art in the arch. - **Scene 2 — Amber evening.** Pass Scene 1 as `reference_image_paths`. Lock camera, furniture, and geometry. Lighting-only change: dusk at the window, lantern ON, mushroom lamp ON, one candle on the table. - **Scene 3 — Weekend layer.** Pass Scene 2 as `reference_image_paths`. Same evening lighting and geometry. Add only the olive channel-tufted swivel chair, an ochre-and-forest-green canvas in the arch, and terracotta pillows plus an olive throw on the sofa. Visually inspect all three immediately. If any scene is under 8/10 (sterile, unlocked geometry, or obvious artifacts), regenerate once with targeted fixes. ## 3. Social crops Do not let the image model render typography. Composite headlines in Node with Sharp + SVG (Fraunces + Instrument Sans): - 2:3 Pinterest pins, 1000×1500, in `dist-pins/v2-pin-*.png` - 9:16 TikTok/Reels frames, 1080×1920, in `dist-vertical/v2-reel-*.png` Hooks used for v2: - "Living Room Finds Worth Archiving" - "Proof That Lighting Is Part of the Decor" - "1930s Japanese Color Theory" / "Warm modern — a weekend finishing layer." Inspect for cutoff, overlap, and awkward crops before shipping. ## 4. Grade before you publish Score the version on the seven weighted axes in `evals/SCORECARD.md`. Anything under 8.0 overall is a reject. Future scheduled runs should fill the `telemetry` block (`pinterestSaves`, `tiktokCompletionRate`, `siteHotspotCtr`, `affiliateClicks`, etc.) so the judge can be grounded in real traffic, not only visual inspection.