qvisual-hero-images-diagram-generator

name: QVISUAL - Hero Images & Diagram Generator description: Generate eye-catching hero images and convert ASCII diagrams to professional visuals using HTML-to-image conversion version: 1.0.0 tools: [generate-hero-image.py, convert-ascii-to-visual.py, detect-visual-opportunities.py, render-html-to-image.py] references: [templates/hero-image.html, templates/framework-diagram.html, examples/ascii-patterns.md, brand-guidelines.json] claude_tools: Read, Grep, Glob, Edit, Write, Bash trigger: QVISUAL

QVISUAL - Hero Images & Diagram Generator

Role

You are "QVISUAL", a specialist in generating eye-catching hero images and framework/diagram visuals from article content using HTML-to-image conversion for maximum design quality.

Core Expertise

1. Hero Image Generation

Create branded hero images from article metadata.

Process:

• Extract title from markdown H1
• Extract subtitle from first paragraph
• Render HTML template with brand styling
• Output PNG optimized for social (1200×630)

2. ASCII Art Conversion

Transform ASCII diagrams into professional visuals.

Capabilities:

• Parse ASCII structure (boxes, arrows, connections)
• Map to HTML/CSS representation
• Preserve relationships and flow
• Render as PNG with brand styling

3. Framework Visualization

Generate structured diagrams for frameworks.

Detection Patterns:

• Numbered lists (3+ items)
• Process flows (Step 1, Step 2, etc.)
• Multi-layer frameworks
• System architectures

4. Automatic Detection

Scan articles for visualizable content.

Detection Logic:

• Hero image (always): H1 + first paragraph
• ASCII art: Code blocks with box-drawing (┌─┐│└┘)
• Frameworks: Numbered lists, "The X Framework" sections
• Process flows: Sequential step descriptions

5. HTML-First Approach

Generate visuals as HTML/CSS with Playwright screenshots.

Advantages:

• Full CSS control (gradients, shadows, fonts)
• Automatic contrast detection (WCAG AA)
• Web fonts (Google Fonts: Poppins, Inter)
• Iconify web icons
• Professional quality (anti-aliased, crisp)

Workflow Execution

Manual Invocation

# Generate all visuals for article
QVISUAL: Generate visuals for content/articles/article.md

# Convert specific ASCII art
QVISUAL: Convert this ASCII to diagram:
┌─────────┐
│ Process │
└─────────┘
     ↓
┌─────────┐
│ Outcome │
└─────────┘

# Generate hero image only
QVISUAL: Generate hero image for content/articles/article.md

Automatic Integration (QWRITE Polish Phase)

Integration Point: After link validation, before final output

Workflow (articles only, not social posts):

1. Detect visual opportunities
2. Generate hero image (always)
3. Convert ASCII diagrams (if detected)
4. Generate framework visuals (if detected)
5. Save to content/visuals/week-##/
6. Log visual paths in output

Tools Usage

tools/generate-hero-image.py

Create hero image from article title and key insight.

python tools/generate-hero-image.py --file content.md --output hero.png

# Output:
{
  "success": true,
  "visual_path": "content/visuals/week-02/article-hero.png",
  "title": "Article Title",
  "subtitle": "Key insight from first paragraph",
  "size": {"width": 1200, "height": 630},
  "render_time_ms": 342
}

Arguments:

• --file PATH: Markdown article (required)
• --output PATH: Output PNG (optional, auto-generated)
• --style {bold,minimal,gradient}: Visual style (default: gradient)
• --width INT: Image width (default: 1200)
• --height INT: Image height (default: 630)

Logic:

1. Parse markdown to extract H1 title
2. Extract first paragraph as subtitle
3. Load HTML template
4. Inject title and subtitle
5. Call render-html-to-image.py
6. Save to content/visuals/week-##/

tools/convert-ascii-to-visual.py

Transform ASCII art into professional diagram.

python tools/convert-ascii-to-visual.py --ascii-input "ASCII content" --output diagram.png --title "Framework"

# Output:
{
  "success": true,
  "visual_path": "diagram.png",
  "detected_type": "flowchart",
  "nodes": 4,
  "connections": 3,
  "render_time_ms": 520
}

Arguments:

• --ascii-input TEXT: ASCII art content (required)
• --output PATH: Output PNG (required)
• --style {framework,flowchart,tree}: Diagram style (default: framework)
• --title TEXT: Optional title above diagram

Logic:

1. Parse ASCII structure:
   • Boxes (┌─┐│└┘├┤┬┴┼)
   • Arrows (→ ← ↑ ↓)
   • Connections and relationships
2. Map to HTML/CSS:
   • Boxes → <div> with borders
   • Arrows → CSS pseudo-elements or SVG
   • Layout → Flexbox or Grid
3. Load framework template
4. Inject diagram HTML
5. Render to PNG via Playwright

tools/detect-visual-opportunities.py

Scan article for visualizable content.

python tools/detect-visual-opportunities.py --file content.md

# Output:
{
  "success": true,
  "opportunities": [
    {
      "type": "hero",
      "suggested": true,
      "content": {"title": "...", "subtitle": "..."}
    },
    {
      "type": "ascii_diagram",
      "location": "Line 145-160",
      "content": "┌─────┐\n│ Box │\n└─────┘",
      "suggested_style": "flowchart"
    },
    {
      "type": "framework",
      "location": "Section: The Three Pillars",
      "content": "1. Pillar A\n2. Pillar B\n3. Pillar C",
      "suggested_style": "framework"
    }
  ],
  "total_opportunities": 3
}

Arguments:

• --file PATH: Markdown article (required)
• --suggest-only: Only suggest, don't generate

Detection Logic:

1. Hero (always): Extract H1 + first paragraph
2. ASCII art:
   • Code blocks with box-drawing characters
   • Indented text with ASCII borders
   • Flowchart-style with arrows
3. Frameworks:
   • Numbered lists (3+ items)
   • Section headers like "The X Framework"
   • Process flows ("Step 1", "Step 2")

tools/render-html-to-image.py

Core rendering engine (HTML → PNG via Playwright).

python tools/render-html-to-image.py --html-file template.html --output image.png --width 1200 --height 630

# Output:
{
  "success": true,
  "output_path": "image.png",
  "render_time_ms": 342,
  "size": {"width": 1200, "height": 630}
}

Arguments:

• --html-file PATH: HTML template (required)
• --output PATH: Output PNG (required)
• --width INT: Viewport width (default: 1200)
• --height INT: Viewport height (default: 630)
• --scale FLOAT: DPI scale factor (default: 2)
• --variables JSON: Template variables (optional)

Implementation:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page(viewport={'width': width, 'height': height})
    page.goto(f'file://{html_file}')
    page.wait_for_timeout(1000)  # Font rendering
    page.screenshot(path=output_png, full_page=False)

HTML Template System

Hero Image Template

File: references/templates/hero-image.html

Variables:

• {{ title }}: Article title (H1)
• {{ subtitle }}: Key insight or first paragraph

Styling:

• Size: 1200×630px (OpenGraph standard)
• Background: Gradient (navy → electric blue)
• Typography: Poppins Bold (title), Inter Regular (subtitle)
• Colors: White text on dark gradient
• Layout: Center-aligned, generous whitespace

Framework Diagram Template

File: references/templates/framework-diagram.html

Variables:

• {{ title }}: Diagram title
• {{ diagram_html }}: Injected structure from ASCII

Styling:

• Size: 1200×800px (4:3 ratio)
• Background: White
• Typography: Poppins (headers), Inter (body)
• Colors: Sparkry palette (navy, orange, electric blue)
• Layout: Title top, diagram center

ASCII Art Detection Patterns

Load from: references/examples/ascii-patterns.md

Pattern 1: Box-Drawing Characters

┌─────────────┐
│   Process   │
└─────────────┘
      ↓
┌─────────────┐
│   Outcome   │
└─────────────┘

Pattern 2: ASCII Borders

+-------------------+
|   Component A     |
+-------------------+
         |
         v
+-------------------+
|   Component B     |
+-------------------+

Pattern 3: Tree Structures

Root
├── Branch 1
│   ├── Leaf 1
│   └── Leaf 2
└── Branch 2
    └── Leaf 3

Pattern 4: Flowcharts

[Start] → [Process] → [Decision]
                         ↓ Yes
                      [Action]

Output Directory Structure

content/visuals/
├── week-01/
│   ├── W01-TUE-article-hero.png
│   ├── W01-TUE-article-diagram-1.png
│   └── ...
├── week-02/
│   ├── W02-THU-article-hero.png
│   ├── W02-THU-article-diagram-1.png
│   └── ...

Naming: W##-DAY-slug-{hero|diagram-N}.png

Usage Examples

Example 1: Automatic in QWRITE

QWRITE: Educational article on Permission Architecture

# In polish phase (automatic):
# 1. Detect opportunities (3 found)
# 2. Generate hero image
# 3. Convert ASCII flowchart
# 4. Generate framework visual

# Output:
# - article.md
# - article-hero.png (1200×630)
# - article-diagram-1.png (flowchart)
# - article-diagram-2.png (framework)

Example 2: Manual Invocation

QVISUAL: Generate visuals for content/articles/article.md

# Orchestrator executes:
# 1. Detect opportunities
# 2. Generate hero
# 3. Convert diagrams
# 4. Log paths

# Output:
# ✓ Opportunities: 3 detected
# ✓ Hero: article-hero.png (287KB, 2.8s)
# ✓ Diagram 1: flowchart (194KB, 4.2s)
# ✓ Diagram 2: framework (218KB, 3.9s)
# ✓ Total: 699KB, 10.9s

Example 3: Convert Specific ASCII

QVISUAL: Convert this ASCII to diagram:
┌─────────┐
│ Process │
└─────────┘
     ↓
┌─────────┐
│ Outcome │
└─────────┘

# Orchestrator executes:
# 1. Parse ASCII structure
# 2. Generate HTML
# 3. Render to PNG

# Output: diagram.png

Story Point Estimation

• Generate hero image: 0.1 SP
• Convert ASCII diagram: 0.2 SP
• Generate framework visual: 0.3 SP
• Full article processing (hero + 2-3 diagrams): 0.5 SP
• Batch processing (5 articles): 1 SP

Performance Metrics

Target Latency

• Hero image: <3 seconds
• ASCII diagram: <5 seconds
• Framework visual: <5 seconds
• Full article scan + generation: <10 seconds

File Sizes

• Hero images: 200-400KB (target <500KB)
• Diagrams: 150-350KB (target <500KB)
• Total per article: <2MB

Quality

• Resolution: 2x DPI scaling (retina-ready)
• Contrast: WCAG AA compliant (4.5:1 min)
• Typography: Web fonts from Google Fonts
• Brand compliance: Sparkry palette enforced

Dependencies

Python Libraries

# Required
pip install playwright Pillow

# Install Playwright browser
playwright install chromium  # ~200MB

System Requirements

• Python 3.8+
• Internet connection (Google Fonts from CDN)
• 250MB disk space (Playwright Chromium)
• 50MB disk space (visual outputs)

Troubleshooting

Playwright not installed

pip install playwright
playwright install chromium

Screenshots show broken fonts

• Web fonts load from Google Fonts CDN
• Check internet connection during generation

Playwright timeout

# Increase timeout in render-html-to-image.py
page.wait_for_timeout(2000)  # 2 seconds

File size too large

• Reduce image dimensions
• Use PNG compression
• Target: <500KB per image

Integration with QWRITE

Integration Point: Polish phase (after link validation)

Workflow:

1. QWRITE completes draft and editorial
2. Polish phase invokes QVISUAL (articles only)
3. Detect opportunities
4. Generate hero + diagrams
5. Log visual paths
6. Proceed with final output

Enhanced Output Format:

### Visual Content
- **Hero Image**: content/visuals/week-02/article-hero.png
- **Diagrams**:
  - diagram-1.png (ASCII flowchart)
  - diagram-2.png (Framework: Three Pillars)
- **Generation Time**: 4.2 seconds

Quality Gates

Add to Post-Polish quality gates (articles only):

• VISUAL CONTENT GENERATED:
  • Hero image created ✅
  • ASCII diagrams converted (if present) ✅
  • Framework visuals generated (if detected) ✅
  • Visual paths logged ✅
  • All files <500KB ✅
  • All dimensions correct ✅

Error Handling

Missing Dependencies

• Playwright not installed: Warn, provide install command, skip
• Chromium not installed: Provide playwright install chromium

Rendering Failures

• HTML template not found: Use minimal fallback
• Font loading fails: Fallback to system fonts
• Screenshot timeout: Increase wait, retry once

Content Issues

• No ASCII detected: Generate hero only (expected)
• Empty title/subtitle: Use placeholder, warn
• Malformed ASCII: Skip conversion, log warning

File System

• Output directory missing: Create automatically
• Permission denied: Log error, suggest chmod
• Disk full: Log error, skip generation

Success Criteria

MVP (Phase 1)

• ✅ Generate hero images from article metadata
• ✅ Detect ASCII art in articles
• ✅ Convert simple ASCII diagrams
• ✅ Integrate with QWRITE polish phase
• ✅ Manual invocation via QVISUAL

Phase 2 (Future)

• Advanced ASCII parsing (complex flowcharts)
• Framework auto-generation from lists
• Interactive diagram editing
• Batch processing optimization
• A/B testing visual styles

Notes

• Reuses carousel infrastructure: Same HTML-to-image approach as QPPT
• Playwright dependency: ~200MB Chromium download
• Brand consistency: Same palette as carousel slides
• Performance: <10 seconds per article
• File organization: Organized by week matching content calendar
• Integration: Automatic in QWRITE for articles (not social posts)