bhamz-ux/agentic-quote-cards

Quote Card Generator — Master Agent Skill

What This Skill Does

Generates premium, pixel-perfect 1080×1350px (4:5 portrait ratio) dark-mode quote cards featuring:

• A transparent portrait of the author dynamically blended with custom radial spotlight lighting.
• Intelligent typography autoscaling to prevent awkward wrapping or text overflow.
• Clean brand accent block with author name and title.
• Deterministic, high-resolution rendering and export via Playwright (zero AI text hallucination or font distortion).

---

Skill Activation & Prerequisites

Step 0: First-Time User Onboarding Check

Whenever this skill is triggered, always check if brand_config.json exists in the repository root or current workspace:

1. If brand_config.json DOES NOT exist (or contains placeholder values):
   • Follow the Interactive Onboarding Protocol immediately before generating any card.
   • Politely ask the user for their:
     • Author Name (e.g., Alex Morgan)
     • Author Title / Tagline (e.g., Founder & AI Engineer, HyperScale)
     • Brand Accent Color Hex (e.g., #2FAD64 or #6366F1)
     • Path to their transparent portrait PNG.
   • Save these to brand_config.json.
   • Verify Playwright is installed (playwright install chromium).
2. If brand_config.json EXISTS:
   • Load the user's brand preferences and proceed directly to card generation.

---

Dynamic Layout & Adaptive Design System

1. Dynamic Typography Autoscaling

Analyze the character count of the quote text before rendering:

Quote Length	.quote-text Font Size	Line Height	Margin Bottom	Best Use Case
Short (< 45 chars)	52px – 56px	1.32	45px	Punchy one-liners & bold axioms
Medium (45–85 chars)	40px – 44px	1.38	40px	Standard multi-sentence insights
Long (> 85 chars)	32px – 36px	1.42	32px	Detailed technical or strategic breakdowns

Rule: Highlight 1–3 high-impact keywords using <span class="quote-highlight">keyword</span> with the brand's accent color.

2. Adaptive Portrait Positioning

Inspect the author's portrait photo dimensions and posture:

• Default (Portrait Left, Text Right):
  • .portrait-img: position: absolute; bottom: -2%; left: -8%; width: auto; height: 100%; max-height: 105%; object-fit: contain; object-position: bottom left; z-index: 2;
  • .content-section: position: absolute; top: 22%; right: 6%; width: 36%; z-index: 4; display: flex; flex-direction: column; justify-content: center;
• Reversed (Portrait Right, Text Left):
  • If the subject faces left, mirror the layout: portrait on right (right: -8%), .content-section on left (left: 6%; width: 36%).
• Clearance Rule: Maintain a generous visual gap (at least 60px) between the portrait's subject outline and the text container. The text and author block must NEVER overlap the subject's body, arms, or accessories.

3. Lighting & Backdrop Composition

• Base Canvas: radial-gradient(circle at 35% 50%, #172230 0%, #080c12 90%) (or customized via brand theme).
• Spotlight Glow: Circular glow centered behind the author's head with radial gradient using brand accent color at 20%-25% opacity.
• Bottom Seamless Blend: A subtle gradient overlay (linear-gradient(to top, #080c12 10%, rgba(8, 12, 18, 0.6) 50%, transparent 100%)) across the bottom 15% of the card to softly blend torso cutoffs.

---

Generation & Export Workflow

Follow this systematic 4-step execution:

graph TD
    A["Receive Quote & Author Intent"] --> B["Load brand_config.json"]
    B --> C["Compile HTML Template with Base64 Assets & Scaled CSS"]
    C --> D["Save to temporary preview file (e.g., scratch/quote_card.html)"]
    D --> E["Run Playwright Exporter: python export.py"]
    E --> F["Visual Audit: Verify crisp text and zero overlap"]
    F --> G["Present Final 1080x1350 PNG to User"]

Step 1: Prepare Assets & Data

• Read brand_config.json for author.name, author.title, theme.accent_color, and assets.portrait_path.
• Convert the portrait image to an inline base64 string (data:image/png;base64,...) so the HTML is 100% self-contained.

Step 2: Compile HTML Canvas

• Populate template.html with:
  • Base64 portrait image.
  • Formatted quote with <span class="quote-highlight">...</span>.
  • Author block with dynamic left border colored with theme.accent_color.
  • Injected dynamic font-size CSS rules.
• Save the compiled HTML to a scratch preview path (e.g., scratch/quote_card.html).

Step 3: Headless Playwright Export

Run the bundled export engine:

python .agents/skills/quote-card/export.py --input scratch/quote_card.html --output output/quote_card.png

Step 4: Quality & Visual Audit (MANDATORY)

Before presenting the final asset to the user, you MUST verify the output.

• Rule of Perfection: The agent must inspect the exported image to confirm that there is generous space between the text block (quote and title) and the author's silhouette.
• If there is any overlap or if the text looks too close to the image, you must adjust the .content-section width/margins or font sizes in the HTML and re-run export.py.
• Do not come back to the user until you are absolutely sure the quote card is perfectly laid out and professional.
• Confirm that Google Font (e.g., Outfit) is loaded and sharp.
• Confirm the output resolution is exactly 1080×1350px.