Visual Design Skill

Procedural guidance for generating production-quality visual mockups using AI image generation, creating multiple design directions that are validated before committing to Storybook code.

When to Use

Running /visual-design [initiative]
After design brief exists, before /proto
When exploring visual directions for a new feature
When stakeholders need to see options before functional prototyping begins
When competitive landscape reveals design patterns to match or surpass

Inputs

Initiative name
Automatically loads:
- pm-workspace-docs/initiatives/active/[name]/design-brief.md (REQUIRED)
- pm-workspace-docs/initiatives/active/[name]/competitive-landscape.md (recommended)
- pm-workspace-docs/initiatives/active/[name]/prd.md (for user stories and flows)

Prerequisites

Design brief MUST exist. If missing, suggest running /pm [name] then generating the design brief.
Competitive landscape is strongly recommended. If missing, note the gap and suggest /landscape [name] as a follow-up.

Required Context

Load before generating mockups:

pm-workspace-docs/company-context/product-vision.md - Visual identity should reflect product values
apps/web/src/index.css & color-system-v2-demo.stories.tsx - Existing design system tokens (semantic colors via Theme V2, typography, spacing)
Competitive landscape's "Design Vocabulary" section - Patterns to adopt, reject, leapfrog

Core Principle: Mockups as Communication

Generated images are NOT pixel-perfect specs. They are a visual conversation about intent. The goal is to:

Align stakeholders on visual direction before writing code
Establish shared design vocabulary that carries into implementation
Validate that the chosen direction surpasses competitive offerings
Prevent the prototype phase from reinventing visual decisions

"Make it more premium" is vague in words, obvious in pictures.

Workflow

1. Extract Key Screens from Design Brief

Read the design brief's "Key Screens / States" section. Identify the 2-4 most important screens that define the feature's visual identity:

Primary screen: The main view users will spend the most time in
Entry point: How users discover/access the feature
Key interaction: The most important action or decision point
Success state: What the "it worked" moment looks like

Do NOT generate mockups for every state. Focus on the screens that define the visual language.

2. Build Direction Framework

For each key screen, generate 2-3 visual directions:

Direction	Philosophy	Risk Level	Best For
A: Familiar	Matches existing app patterns closely. Safe, consistent, predictable.	Low	Incremental features, conservative stakeholders
B: Elevated	Pushes design quality while staying within design system spirit. Premium feel, competitive parity or better.	Medium	Most features, default recommendation
C: Distinctive	Breaks convention. New visual language, bold choices, designed to surpass competition.	Higher	Flagship features, differentiation plays

Each direction needs:

A descriptive name (not just "A/B/C" -- e.g., "Clean Data Grid", "Living Dashboard", "Ambient Intelligence")
A 1-sentence design philosophy
Rationale tied to competitive landscape (e.g., "Direction C leapfrogs Momentum's static card layout with real-time animated data flows")
Trade-off analysis (implementation complexity, accessibility implications, design system impact)

3. Craft Image Generation Prompts

Build detailed prompts for each mockup. Every prompt MUST include:

Design system grounding:

AskElephant Theme V2 semantic color palette (reference apps/web/src/index.css and color-system-v2-demo.stories.tsx)
Typography conventions (font families, size hierarchy)
Existing component patterns (cards, badges, navigation)

Screen-specific content:

What data is shown (use realistic AskElephant data, not lorem ipsum)
Layout structure (sidebar + main content, full-width, split-panel)
Key interactive elements (buttons, filters, toggles)
State being shown (populated, not empty)

Competitive differentiation context:

Reference competitive landscape design vocabulary
For Direction B/C, explicitly state what you're surpassing

Quality directives:

"Production-quality SaaS application screenshot"
"Clean, modern interface with professional data visualization"
"NOT a wireframe or sketch -- this should look like a real product"
"No placeholder text -- use realistic meeting and CRM data labels"

4. Generate and Iterate

Image generation approach (priority order):

GenerateImage tool (built-in): Primary path. Available in all environments.
nano-banana CLI (~/.claude/bin/nano-banana): If available, provides Gemini 3 Pro image generation with aspect ratio and resolution control. Check for GEMINI_API_KEY environment variable.

Aspect ratios:

16:9 -- Web dashboards, full-page views
9:16 -- Mobile views
3:4 -- Detail panels, sidebars, modals
1:1 -- Component-level mockups (cards, widgets)

Iteration guidance:

First generation is often too generic. Push for specificity.
If mockup looks "AI-generated" (generic gradients, meaningless charts, stock layout), regenerate with more specific data and layout requirements.
Reference specific competitor patterns: "Like Momentum's activity timeline but with inline CRM field editing"
Use existing app screenshots as style reference when available

5. Document in visual-directions.md

Create the structured document with all directions, images, and analysis.

Anti-Pattern: AI Slop Aesthetic

Generated mockups MUST NOT exhibit these patterns:

Generic gradient backgrounds with no purpose
Meaningless graphs showing fake upward trends
Stock placeholder text ("Lorem ipsum", "John Doe", "Sample Company")
Cookie-cutter SaaS dashboard with identical card layouts
Over-reliance on blur/glassmorphism without functional purpose
Inconsistent typography that doesn't match any real design system
"Dark mode for the sake of dark mode" without considering the product context

Instead, mockups should:

Use realistic AskElephant data labels (meeting names, CRM fields, action items)
Reflect the actual product's color palette and typography
Show meaningful data hierarchy that serves the user's job-to-be-done
Look like they belong in the existing product, elevated

Required Output Sections in visual-directions.md

1. Design Brief Summary

Key goals and constraints driving the visual directions (extracted from design brief).

2. Competitive Context

What patterns from the competitive landscape informed these directions. Reference specific competitors.

3. Key Screens

For each key screen (2-4 screens):

Screen: [Name]

Direction A: [Descriptive Name]

Philosophy: [1 sentence]
Rationale: [Why this approach, tied to competitive context]
Trade-offs: [Implementation complexity, design system impact]
Image: assets/mockups/[screen]-direction-a.png

Direction B: [Descriptive Name]

[Same structure]

Direction C: [Descriptive Name] (optional for simpler screens)

[Same structure]

4. Recommendation

Which direction is recommended and why. Consider:

Competitive positioning (does it surpass the market?)
Implementation feasibility
Design system coherence
Persona alignment (does this feel trustworthy to our users?)

5. Design Vocabulary Established

Terms and component names that emerged from the chosen direction. These carry directly into Storybook implementation.

Example: "glass metric cards", "activity river", "confidence badges", "inline field editor"

6. Chosen Direction

Updated after stakeholder review. Records:

Which direction was chosen
Any modifications requested
Date validated
Who validated

Save Locations

Document: pm-workspace-docs/initiatives/active/[name]/visual-directions.md
Mockup images: pm-workspace-docs/initiatives/active/[name]/assets/mockups/

Integration Points

Competitive Analysis: Design Vocabulary and UX Pattern Inventory inform direction generation
Design Brief: Key screens, constraints, and goals define what to mock up
Prototype Builder: Chosen direction's design vocabulary and images become the visual reference for Storybook components. When visual directions exist, the prototype varies on interaction pattern and information density, NOT visual style.
Validator / Jury: Visual directions can be validated with synthetic personas before prototype

Post-Validation Handoff

After a direction is chosen and validated:

Update visual-directions.md with the chosen direction
Update _meta.json with visual_design.direction_chosen and visual_design.validated_at
The chosen direction's mockup images and design vocabulary become PRIMARY input for /proto
When running /proto, the prototype builder reads visual-directions.md and implements the validated visual language

This means the Storybook prototype phase shifts focus from "what should this look like?" (answered) to "how should this behave?" (interactions, states, flows, data loading).

visual-design