VisualSpec

VisualSpec

Deterministic visual generation for AI agents.

AI creates the imagery. VisualSpec guarantees the typography and layout.

# Instant workspace setup (no clone required)

npx @utkarshx27/visualspec init

Launch local MCP Server for Cursor, Claude Desktop, or Antigravity

npx @utkarshx27/visualspec mcp

---

The Core Problem

Most image-generation workflows fail for social and marketing graphics because a single natural-language prompt is expected to handle too many concerns at once:

• subject & background
• exact typography & wording
• platform dimensions & safe margins
• visual hierarchy & negative space
• brand color rules & constraints

Image models frequently hallucinate gibberish text, truncate words, or disregard composition rules.

The Solution: Layer Separation

VisualSpec separates generative concerns from deterministic concerns:

1. Generative Layers (AI Models): Photography, 3D subjects, atmospheric backgrounds, textures, lighting.
2. Deterministic Layers (Code & SVG Engine): Exact headlines, subtitles, badges, logos, metrics, safe margins, and layout rules.
3. Structured Visual Spec: A machine-readable YAML specification that acts as the single contract.
4. Visual QA & Targeted Repair: Verifies geometry, margins, and exact copy invariants, synthesizing localized repairs without regenerating entire scenes.

User Brief / Intent

│ ▼ Visual Spec (spec.yaml) │ ┌───┴──────────────┐ ▼ ▼ Platform Pack Template Pack │ │ └───┬──────────────┘ ▼ Spec Resolver │ ┌───┴───────────────────────┐ ▼ ▼ Model Adapter Deterministic Layout (Generative Base) (SVG Typography / Overlay) │ │ └───┬───────────────────────┘ ▼ Compositor (Sharp) │ ▼ Visual QA (Constraints, Safe Margins, Exact Copy) │ ├── PASS ──► Final Asset Bundle │ └── FAIL ──► Targeted Repair Planner

---

Documentation

• Architecture & Design Principles
• VisualSpec Schema & Contract
• MCP Server Setup (Cursor, Claude, Antigravity)
• Adding a New Image Model Provider
• Contributing Guidelines

---

Quickstart

Instant Run (No Install Required)

# Initialize a new VisualSpec workspace

npx @utkarshx27/visualspec init

Launch local MCP Server for Cursor, Claude, or Antigravity IDE

npx @utkarshx27/visualspec mcp

Or Install Globally

npm install -g @utkarshx27/visualspec

Use CLI commands directly

visual init visual mcp

Or Build from Source

git clone https://github.com/utkarshx27/visualspec.git

cd visualspec npm install npm run build

1. Initialize a Project

npx @utkarshx27/visualspec init

2. Validate a Visual Spec

npx @utkarshx27/visualspec validate examples/product-launch/spec.yaml

3. Inspect the Compiled Generation Prompt

npx @utkarshx27/visualspec compile examples/product-launch/spec.yaml --provider openai

4. Deterministic Render (No API Key Required)

Render layout, typography, and background styling locally:

npx @utkarshx27/visualspec render examples/product-launch/spec.yaml --output ./output/demo-launch

5. Run the Full Generation Pipeline

npx @utkarshx27/visualspec generate examples/product-launch/spec.yaml --provider mock --output ./output/demo-launch

6. Verify Asset Quality with Visual QA

npx @utkarshx27/visualspec check ./output/demo-launch/final.png --spec examples/product-launch/spec.yaml

---

Model Context Protocol (MCP) Server

VisualSpec runs as a native MCP server over stdio, enabling AI coding assistants (Cursor, Claude Code, Gemini CLI, and Antigravity IDE) to invoke visual tools directly:

# Launch MCP server over stdio

npx @utkarshx27/visualspec mcp

Or if installed globally

visual mcp

Available MCP Tools

• visual_brief_to_spec: Convert natural language requests into valid VisualSpec YAML.
• visual_validate_spec: Schema validation for specs.
• visual_render: Deterministic layout & typography rendering (zero API key).
• visual_generate: Full image model adapter + deterministic text overlay pipeline.
• visual_check_qa: Inspect safe margins, line counts, dimensions, and invariants.
• visual_repair: Automated diagnosis and localized typography/layout repair.
• visual_list_resources: List supported platform packs and templates.

See the MCP Setup Guide for Cursor, Claude Desktop, and Antigravity IDE configuration snippets.

---

Output Bundle

Every generation creates a complete, reproducible debug bundle:

output/demo-launch/

├── final.png # Platform-ready asset ├── visual-spec.yaml # Original input specification ├── resolved-spec.yaml # Full spec with platform & template rules applied ├── generation-request.json # Exact prompt and negative parameters sent to model ├── qa-report.json # Deterministic and constraint QA verification results └── metadata.json # Execution timestamps and file index

---

Supported Platforms & Templates

Platforms

• Instagram: Feed portrait (1080x1350, 4:5), Square (1080x1080, 1:1), Story (1080x1920, 9:16).
• LinkedIn: Feed portrait (1080x1350), Square (1080x1080), Banner (1200x628).
• Generic Social: Universal 1:1, 4:5, and 16:9 social formats.

Templates

• Product Launch: High-impact headline, feature pill, product visual region, supporting subhead.
• Quote Card: Center-focused editorial quote, author attribution, minimal atmospheric glow.
• Stat Card: Large numeric hero metric, descriptive label, and data context notes.

---

Agent Skills

The framework includes 10 standardized skill definitions located in ./skills/:

• using-visualspec: Master workflow instructions.
• visual-brief: Brief extraction and analysis.
• visual-spec: YAML authoring and schema rules.
• composition: Spatial hierarchy and negative space allocation.
• typography: Font family classing and line budgeting.
• strict-constraints: Invariant taxonomy and forbidden parameters.
• social-instagram: Instagram-specific design reasoning.
• social-linkedin: LinkedIn-specific design reasoning.
• visual-qa: Automated inspection and validation.
• visual-repair: Localized diagnosis and patch generation.

---

Roadmap & Open Contributions

We welcome contributions! Key areas to build together:

• Additional Platforms: X/Twitter (Header, Post), YouTube Thumbnails, Pinterest, TikTok Cover.
• Additional Templates: Testimonial, Product Comparison, Event Announcement, Feature List.
• Additional Image Model Adapters: Flux, Stable Diffusion / ComfyUI, Midjourney API.
• Brand Packs: Multi-brand palette overrides, custom font loading, logo clear space rules.
• Visual Studio: Local web playground / viewer for real-time spec inspection and margin toggling.

---

Contributing

Contributions are welcome! Please check our:

• Contributing Guidelines
• Code of Conduct

---

Testing

Run the automated test suite:

npm test

All 28 tests run offline without requiring any third-party API keys.

---

License

Licensed under the Apache License, Version 2.0.