graphic-design

Graphic Design

The primary skill for generating stunning visual graphics. Supports two output modes:

1. AI Image Generation (default) — Uses Gemini 3.1 Flash Image Preview to generate pixel-perfect graphics from prompts and reference images
2. Code Generation — Produces production-ready HTML/CSS/SVG for web-native graphics

Choose AI generation for social posts, posters, ads, and rich visuals. Choose code for interactive web graphics, animated elements, or when the output must be editable HTML.

Step 1: Load Design Context

Before any design work:

1. Read .agents/design-context.md first. Extract primary, secondary, and accent colors (hex), heading and body fonts, and style archetype
2. If the file doesn't exist, use the Default Fallbacks from design-context and tell the user the output uses defaults. Suggest running design-context for on-brand results

Step 2: Analyze the Brief

Determine the graphic's purpose:

Identify required elements:

• Headline text
• Subheadline or supporting text
• Product image or visual focal point
• CTA or action text
• Brand elements (logo, colors)
• Dimensions / aspect ratio

Step 2b: Analyze Product Image (If Provided)

1. Identify dominant colors -- extract 3-5 key colors from the image
2. Assess composition -- where is the subject, where is negative space
3. Determine mood -- warm/cool, energetic/calm, luxurious/casual
4. Choose complement strategy: harmonious (reuse image colors), contrasting (complementary colors make it pop), or monochromatic (desaturate + brand-color overlay)

Step 3: Gemini Image Generation Path (Default)

Use this path unless the output must be editable HTML, animated, or carry long/exact copy (then use Step 7). API and CLI details live in image-generation; this is the design layer. Fold in the composition, color, and typography decisions from Steps 4-6.

Craft the Prompt

Describe the scene narratively -- don't just list keywords. Put exact copy in double quotes, use hex codes, describe spatial layout, name the style, and state exclusions (full checklist: image-generation Step 2).

Create a [style] [format] for [purpose].
Scene: [foreground, background, how elements are arranged]
Colors: ["navy blue #1a2b4a background with coral #ff6b6b accents"]
Typography: [large bold sans-serif headline "[TEXT]" in white, upper third]
Mood: [energetic, calm, professional, playful]
Exclude: [no borders, no clip art, no extra text]

With a product image, pass it via --image product.png:

Place this product on a bold gradient background (#1a2b4a to #ff6b6b). Keep the product, its label and logo exactly as in the photo. Add a large headline "NEW ARRIVAL" in white bold sans-serif at the top. Add geometric accent shapes.

Pick a Supported Aspect Ratio, Then Crop to Exact Pixels

Gemini only outputs 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1 -- never put pixel sizes in the prompt and expect them honored. For any other target (1200x628, 300x250, A4), generate at the nearest ratio and let --resize center-crop + resize:

python <image-generation>

• Tell Gemini to keep text and key subjects inside the area that survives the crop ("keep all text within the central 80%")
• --size 2K for screen, 4K for print or large placements
• Several sizes from one master: generate once without --resize, then python <image-generation>/scripts/export-sizes.py master.png --group social --out exports/ (presets for social, ads, video; --focus x,y keeps the subject in frame)

Verify, Then Refine

Never deliver an image you haven't looked at:

1. Read the output PNG. Check: every word spelled exactly as briefed, text legible at the size it will be seen, brand colors correct, one clear focal point, nothing important in cropped or UI-overlaid zones, product/logo not distorted
2. Fix one issue per turn -- --image graphic.png --prompt 'Change "EVERYTHNG" to "EVERYTHING". Change nothing else.' -- and Read the result again
3. After two failed text fixes, regenerate with "no text, leave the upper third clear" and add the copy as a code overlay:

<graphic-design> is this skill's directory. The script waits for web fonts, outputs exactly the requested size, and exits 3 with a warning if content overflows the canvas (clipped text). Then Read final.png to confirm.

Step 4: Apply Composition Principles

Rule of Thirds

Divide the canvas into a 3x3 grid. Center key elements on the four line intersections (33%/67%), not in the middle cell.

Golden Ratio (1:1.618)

Use for sizing relationships between elements:

• If headline is 48px, subheadline should be ~30px (48 / 1.618)
• If main content area is 600px, sidebar/accent area should be ~370px

Focal Point Hierarchy

Every graphic needs ONE clear focal point. Layer importance:

1. Primary focal point -- the thing the eye hits first (largest, most contrasted)
2. Secondary elements -- supporting info (medium size, moderate contrast)
3. Tertiary details -- fine print, logos, decorative (smallest, lowest contrast)

Z-Pattern (for text-heavy graphics)

Eye moves: top-left -> top-right -> diagonal to bottom-left -> bottom-right

F-Pattern (for information-dense layouts)

Eye scans horizontally across top, then drops down and scans shorter horizontal lines.

Step 5: Color Scheme Selection

Start from the design-context colors, then apply these strategies:

Complementary Enhancement

Gradient Techniques

Color Overlay on Images

Step 6: Typography Treatment

Headline Hierarchy

Text Effects

• Gradient text: background: linear-gradient(...) + background-clip: text + -webkit-text-fill-color: transparent
• Outlined text: -webkit-text-stroke: 2px currentColor + -webkit-text-fill-color: transparent
• Glowing text: Multi-layer text-shadow at increasing blur/spread with decreasing opacity
• Embossed: Transparent color + light text-shadow + dark bg-clip text
• Depth/3D text: Stacked 1px-offset text-shadows in progressively darker shades

Step 7: Code Output Path

Output Structure

When the code path is chosen (editable, animated, or text-heavy output), generate a self-contained HTML file with embedded CSS. Render it to PNG at exact size with headless Chromium (see Step 3) and Read the screenshot before delivering:

Advanced CSS Techniques

Creative Shapes with clip-path

Glassmorphism

Blend Modes for Image Integration

SVG Filters

Use inline <svg> with <filter> for noise (feTurbulence + feColorMatrix + feBlend multiply) and glow (feGaussianBlur + feMerge).

Decorative Elements

• Floating circles: Absolute-positioned, radial gradient, filter: blur(40px)
• Grid/dot patterns: background-image with linear-gradient or radial-gradient at low opacity, small background-size

Subtle Animations

• Float: translateY(0 -> -10px -> 0) over 4s ease-in-out infinite
• Pulse glow: box-shadow alternating intensity over 2-3s
• Shimmer: Linear gradient at 200% background-size, animate background-position from -200% to 200%

Step 8: Style-Specific Frameworks

Starting points for the code path; for Gemini, translate the same cues into the prompt (see image-generation style patterns).

Step 9: Quality Checklist

Before delivering any graphic, verify:

• Colors match the design-context palette
• Typography uses specified fonts (loaded via Google Fonts if needed)
• Clear visual hierarchy -- eye knows where to look first
• Text contrast meets WCAG 2.x: 4.5:1 for normal text, 3:1 for large text (>=24px, or >=18.66px bold) and for UI shapes like CTA buttons
• Proper spacing -- nothing feels cramped
• Dimensions match the requested size
• Generated images: output PNG was Read and every word checked; crop to exact pixels done
• Code output: self-contained (fonts excepted), rendered screenshot Read and checked
• Decorative elements enhance, not distract
• The design matches the intended style archetype
• All text content is accurate and spelled correctly

Pro Tips

1. Start with the background -- get the mood right before adding content
2. Use opacity -- 0.05 to 0.15 opacity shapes create depth without distraction
3. Layer gradients -- multiple semi-transparent gradients create rich, unique backgrounds
4. Constrain your palette -- 3 colors maximum for most graphics, plus neutrals
5. Size contrast -- make the headline at least 3x larger than body text
6. Whitespace is design -- empty space is not wasted space, it is breathing room
7. Test at actual size -- open the HTML file and view at 100% to verify readability
8. Use CSS custom properties -- define colors once, reference everywhere for consistency