| name | ai-full-figure |
| description | This skill should be used when the user asks to "generate an AI figure", "make a full AI-generated figure", "make a poster figure", "make a presentation figure", "generate a figure with AI", "create a substrate image", "AI background for a figure", "create a poster background", or wants a pictorial substrate (brain scene, microscope setup, anatomical scene, lab apparatus) generated by AI and then composited with labels and arrows in code. Defaults to the Codex CLI image_gen tool (preferred when `codex login` is configured) or the OpenAI Images API. Hard ceiling is any figure that needs data plots, axis numerals, equations, multi-arrow flowcharts, or more than 5 labeled elements should use scientific-figure or svg-figure instead. |
| version | 0.1.0 |
AI Full Figure
Generate a pictorial substrate via AI (Codex CLI or OpenAI Images API) and overlay labels, arrows, and scale bars programmatically. The output is an SVG that embeds the raster substrate and lets the [[scientific-figure]] composer place it as a panel.
When to use this skill
Reach for ai-full-figure when the figure's picture is the point:
- A brain rendering for a methods overview slide
- A microscope or apparatus illustration for a poster
- An anatomical scene as the background of a graphical abstract
- Any "what does this setup look like" pictorial
Reach for a different skill when the figure is information-dense:
| Figure type | Skill |
|---|
| Data plot (matplotlib, seaborn, plotly) | [[plot-styling]] for the plot, then [[scientific-figure]] to compose |
| Schematic with boxes / arrows / process flow | [[svg-primitives]] (programmatic) or [[svg-figure]] (hand-authored conventions) |
| Flat scientific icon as part of a figure | [[transparent-icons]] |
| Multi-panel journal figure | [[scientific-figure]] as the composer |
Hard ceiling on AI generation
gpt-image-2 and equivalent models cannot reliably render:
- Data plots with axis numerals (axes hallucinate, tick labels are nonsense)
- Equations (LaTeX or Greek-letter math)
- Multi-arrow flowcharts (arrow direction inconsistent, arrows cross wrong)
- Long labels in specific positions ("> 5 labeled elements" is a useful threshold)
- Anything that needs to be read precisely — labels >1–2 words drift
The right pattern when those are needed: substrate-only generation, programmatic overlay.
- Prompt the model for the pictorial scene with no text, no labels, no arrows.
- Compose labels, arrows, scale bars, and panel letters as a separate SVG layer.
- Ship the combined SVG.
If the user is asking for a figure that violates the hard ceiling, route to [[svg-figure]] or [[scientific-figure]] and explain why. AI generation for embedded text remains unreliable as of 2026.
The theme bible (shared with transparent-icons)
A theme.json keeps an AI-generated substrate visually consistent with the rest of the figure's palette and stroke language. The schema is the same one used by [[transparent-icons]]:
plugins/figures/skills/transparent-icons/references/theme.schema.json
Attach the theme to every generation call. The same fields apply: palette, stroke, style_tokens, negative_tokens, composition, reference_images, model_preferences. For substrates, the most load-bearing keys are:
palette.primary / accent / neutral — color tokens injected into the prompt.negative_tokens — must include text, labels, watermark, arrows, caption. The substrate must not contain any text the overlay will replace.composition.aspect — substrates are typically 16:9 ("1920x1080") or 4:3; set this explicitly.style_tokens — e.g. "photorealistic illustration", "watercolor", "isometric 3D", "schematic line art".reference_images (optional, up to 16) — for consistency across a set of substrates.
Usage
Generate a substrate
uv run --with openai --with python-dotenv --with pillow \
python scripts/generate_figure.py \
"a stylized lateral view of a human brain in soft watercolor on a clean white background" \
-o out/brain_substrate.png \
--size 1920x1080 --backend codex
generate_figure.py builds the prompt from the theme bible (when --theme path/to/theme.json is provided) and dispatches to the Codex CLI or the OpenAI Images API. Output is an opaque PNG at the requested size. No transparency post-process is applied — substrates are designed to be the bottom layer, not floated.
Compose labels on top
uv run --with svgwrite --with pillow \
python scripts/overlay_labels.py \
out/brain_substrate.png \
--label "lateral sulcus@600,420" \
--label "central sulcus@800,300" \
--scale-bar "1 cm@200,950" \
-o out/brain_labeled.svg
The output SVG embeds the PNG via <image> and adds <text> / <line> / arrow markers on top. The SVG's viewBox matches the PNG's pixel dimensions so coordinates are pixel-addressed; width/height use a mm value so [[scientific-figure]] can compose it without rescaling math.
Label positions can be pre-computed in code (when overlay is data-driven) or eyeballed via Pillow's image viewer. The overlay_labels.py script accepts --label "text@x,y" shorthand or a JSON --labels-file for batch overlay.
Example pipeline
uv run --with openai --with python-dotenv --with pillow \
python scripts/generate_figure.py \
"a stylized cell membrane with embedded receptor proteins" \
-o out/cell_substrate.png \
--size 1920x1080 --backend codex \
--theme references/cell-theme.json
uv run --with pillow \
python scripts/overlay_labels.py \
out/cell_substrate.png \
--labels-file labels.json \
-o out/cell_labeled.svg
See examples/poster_substrate.py for an end-to-end runnable demo with a small (cheap) substrate, an overlay, and a final composed figure.
Quality assurance
Invoke [[figure-qa]] after generation. The agent runs the raster branch on the substrate (alpha channel, DPI, dominant colors) and the SVG branch on the labeled output (label legibility, palette compliance, no text bleed). VLM judgment then rates aesthetic and journal-fit.
Additional resources
references/prompt-patterns.md — substrate-focused prompt patterns and failure modesreferences/overlay-recipes.md — programmatic label/arrow/scale-bar overlay patterns- Shared theme schema:
../transparent-icons/references/theme.schema.json
scripts/generate_figure.py — substrate generator (Codex preferred, API fallback)scripts/overlay_labels.py — svgwrite-based overlayexamples/poster_substrate.py — end-to-end demo
