Visualkan

---
name: visualkan
description: Generate visual explanations (whiteboard, infographic, presentation, diagram, mindmap, mockup) from any content, via native subscription image generation or an API backend (OpenAI, Gemini, OpenRouter, Grok).
argument-hint: "[--style whiteboard|infographic|presentation|diagram|mindmap|mindmap-structured|mockup] [--draw-level sketch|normal|polished] [--device mobile|desktop|tablet] [--complexity simple|moderate|detailed] [--from mermaid|mermaid-file <path>] [--backend native|openai|gemini|openrouter|grok] [--model <model_name>] <content>"
disable-model-invocation: true
allowed-tools: Bash, Read, Write, Glob, Grep
---

Generate a visual explanation (whiteboard, infographic, presentation, diagram, mindmap, or mockup) from content using the platform's own native subscription image generation, or an image generation API.

## Usage

- `/visualkan Explain how DNS resolution works` — whiteboard style (default)
- `/visualkan --style infographic How machine learning models are trained`
- `/visualkan --style presentation The software development lifecycle`
- `/visualkan --style diagram --complexity detailed Kubernetes pod networking`
- `/visualkan --style mindmap The principles of object-oriented programming` — colorful radial mindmap
- `/visualkan --style mindmap-structured Project management methodologies` — clean, data-oriented XMind-style
- `/visualkan --style mockup A mobile app login screen with email, password, and social login` — polished UI wireframe
- `/visualkan --style mockup --device desktop An admin dashboard with sidebar navigation and data tables` — desktop wireframe
- `/visualkan --style mockup --draw-level sketch A settings page with toggles and dropdowns` — hand-drawn wireframe
- `/visualkan --draw-level sketch How the internet works` — rougher hand-drawn feel
- `/visualkan --draw-level polished --style whiteboard React component lifecycle`
- `/visualkan --style infographic --from mermaid` — convert a Mermaid diagram into a polished infographic
- `/visualkan --style whiteboard --from mermaid-file docs/architecture.mmd` — read a .mmd file and convert it
- `/visualkan --backend gemini How the water cycle works` — use Gemini/Nano Banana 2 instead of OpenAI
- `/visualkan --backend openrouter --model bytedance-seed/seedream-4.5 How async/await works` — use OpenRouter with SeeDream model
- `/visualkan --backend openrouter --model black-forest-labs/flux-1.1-pro Microservice communication` — use OpenRouter with Flux model
- `/visualkan --backend grok How TLS handshakes work` — use xAI Grok Imagine, including on a platform that has its own image generation tool

## Arguments

The argument string is available as `$ARGUMENTS`. Parse it according to these rules:

### Flags (all optional)

| Flag | Default | Description |
|------|---------|-------------|
| `--style S` | `whiteboard` | Visual style: `whiteboard`, `infographic`, `presentation`, `diagram`, `mindmap`, `mindmap-structured`, `mockup` |
| `--device D` | `mobile` | Device frame for mockup style: `mobile` (phone), `desktop` (browser window), `tablet` (iPad-style). Only used with `--style mockup`. |
| `--draw-level L` | `normal` | How hand-drawn vs polished: `sketch` (rough/playful), `normal` (balanced), `polished` (clean/professional) |
| `--complexity C` | `moderate` | Number of sections: `simple` (3-4), `moderate` (5-7), `detailed` (8-12) |
| `--size WxH` | style-dependent | Image dimensions. Defaults: whiteboard=`1536x1024`, infographic=`1024x1536`, presentation=`1536x1024`, diagram=`1024x1024`, mindmap=`1536x1024`, mindmap-structured=`1536x1024`, mockup=`1024x1536` (mobile/tablet) or `1536x1024` (desktop) |
| `--output DIR` | `visualkan-output/` | Output directory. See "Where the image goes" in Step 7 for how to resolve it. |
| `--prefix NAME` | `visualkan` | Filename prefix |
| `--mode M` | `single` | `single` (one image) or `multi-frame` (series of images building up the concept) |
| `--from F` | (none) | Input source: `mermaid` (inline Mermaid in content or clipboard), `mermaid-file PATH` (read from a .mmd/.md file) |
| `--backend B` | auto-detected | Image generation backend: `native` (the platform's own image generation tool, included in its subscription), `openai` (gpt-image-2), `gemini` (Nano Banana 2), `openrouter` (OpenRouter API key), or `grok` (xAI Grok Imagine). |
| `--model M` | `bytedance-seed/seedream-4.5` | **`--backend openrouter` only.** Model name to use. Supported: `bytedance-seed/seedream-4.5`, `black-forest-labs/flux-1-schnell`, `krea/krea-image`, `qwen/qwen-image`, `riverflow`, etc. Used with any other backend, this flag is an error (see ADR 0003). |

### Everything else is the content

After extracting flags, join the remaining text as the content to visualize.

## Steps

### Step 1: Validate input and choose the route

If no content remains once the flags are removed, and no `--from` flag was given, go to Step 3 and run Clarification. Do not ask a single loose question here.

A `--from` flag carries the Content in a file or in the conversation, not in the argument. `--from mermaid-file docs/architecture.mmd` therefore looks empty at this point and is not. Run Step 1b before you judge the Content missing.

There are exactly two routes. Pick one and do not improvise a third.

**`--backend` decides before anything else.** If the user passed `--backend` naming anything other than `native`, take the CLI route, even where a native tool exists. Someone who names a backend has chosen it, and quietly routing them elsewhere generates with a different model than the one they asked for.

If they passed `--backend native` and no native tool exists here, stop and tell them. Do not fall back to the CLI route. They asked for the option that costs nothing, and spending their money instead is not a helpful correction.

**Native route.** With no `--backend` given, use a native image generation tool if this environment has one. It is called `generate_image` on some platforms and `image_generation` on others, and either qualifies. Image generation is included in the platform's own subscription there, so no API key, CLI, or shell command is needed.

Decide whether such a tool exists by reading the list of tools you were given, and by nothing else. Never call it to find out. A call that fails costs a turn and tells you less than the list already does.

**CLI route.** Otherwise, run the Runtime. It is at `scripts/visualkan_run.py`, inside this skill's own directory. Resolve that relative path against the directory this skill was loaded from, not against the current working directory, and write it with forward slashes:

```bash
python3 "<this skill's own directory>/scripts/visualkan_run.py" generate --prompt-file <file> ...
```

That path needs no PATH lookup and no particular working directory. Do not search for a `visualkan` command. The Runtime performs backend detection, API key validation, `--model` checking, size selection, the HTTP request, and writing the file.

Do NOT do any of the following yourself:

- Read or test `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, or `XAI_API_KEY`
- Decide which backend to use
- Call an image API with `curl`
- Parse a response with `jq`, or decode base64 by hand

If that file does not exist, the install is incomplete. Stop and tell the user to run this:

```bash
npx skills add dapih/visualkan
```

The Runtime prints the backend and model it selected to stderr before it calls the API. Pass that line through to the user.

### Step 1b: Detect and parse Mermaid input

If `--from mermaid` or `--from mermaid-file PATH` is specified, OR if the content contains Mermaid syntax (lines starting with `graph`, `flowchart`, `sequenceDiagram`, `classDiagram`, `stateDiagram`, `erDiagram`, `gantt`, `pie`, `mindmap`, `timeline`, or fenced in a ` ```mermaid ` block), treat the input as a Mermaid diagram and parse it.

**How to parse Mermaid input:**

If `--from mermaid-file PATH` is specified, read the file at PATH first using the Read tool.

If `--from mermaid` is specified without a file path, the content itself IS the Mermaid code (it may also appear inline in the content argument, or the user may have pasted it in a previous message — check the conversation context).

Parse the Mermaid syntax to extract the following structured data:

1. **Diagram Type**: What kind of Mermaid diagram is it? Map to the best visual style:

   | Mermaid Type | Suggested Style (if user didn't specify) |
   |---|---|
   | `flowchart` / `graph` | diagram or whiteboard |
   | `sequenceDiagram` | diagram or whiteboard |
   | `classDiagram` | diagram |
   | `stateDiagram` | diagram or whiteboard |
   | `erDiagram` | diagram |
   | `gantt` | infographic |
   | `pie` | infographic or presentation |
   | `mindmap` | mindmap or mindmap-structured |
   | `timeline` | infographic or whiteboard |

   If the user explicitly specified a `--style`, always use their choice — ANY Mermaid diagram type can be rendered in ANY visual style. The table above is only for auto-selection when no style is given.

2. **Nodes/Entities**: Extract every node with its:
   - ID (internal reference)
   - Display label (the human-readable text)
   - Shape hint (if the Mermaid syntax specifies one — e.g., `[rect]`, `(round)`, `{diamond}`, `[(cylinder)]`, `((circle))`)

3. **Connections/Edges**: Extract every connection with:
   - Source node → Target node
   - Arrow style (solid `-->`, dotted `-..->`, thick `==>`, bidirectional `<-->`)
   - Edge label (text on the arrow, if any)

4. **Subgraphs/Groups**: Extract any `subgraph` blocks as logical groupings with their title and contained nodes.

5. **Participants/Actors** (sequence diagrams): Extract participant names, aliases, and message flow.

6. **Attributes/Fields** (class/ER diagrams): Extract class names, methods, fields, relationships, cardinality.

7. **Timeline/Gantt data**: Extract dates, milestones, sections, task names, durations.

8. **Title**: If a `title` directive exists, use it. Otherwise, infer a title from the diagram content.

**CRITICAL**: Mermaid input gives you EXACT structure — use it. Every node becomes a labeled visual element. Every edge becomes an arrow or connection. Every subgraph becomes a visual grouping/container. This is MORE precise than free-text input, so the resulting prompts should be MORE detailed, not less.

After parsing, proceed to Step 2 using the extracted structure as the input for analysis. The Mermaid data pre-fills much of the analysis:
- Nodes → **grouped into** Sections, by the rule in field 2. A node is not a Section, and a file usually carries more nodes than the Complexity allows Sections. Every node still reaches the Image Prompt as its own labelled element.
- Edges → Relationships, with exact labels
- Subgraphs → Layout groupings
- You still need to add: Visual Metaphors, Colors, and Exact Text

### Step 2: Analyze the content

Build the Content Analysis before you build any prompt. An image model draws what the prompt names and invents the rest, so every structural decision you leave out here becomes a decision the model makes for you.

Follow "Content Analysis: the mandatory breakdown", near the end of this file. Write all seven fields out in the conversation, under the headings that section gives.

When Step 4 runs, the user reads those fields to catch a wrong reading of the Content before anything is spent.

When Step 4 does not run, nothing pauses between here and Step 7. The fields then stand as the record of what you decided, and the user reads them after the fact. Write them for a reader who has already paid.

This step also decides whether the run continues. The Sections field carries the count, and Step 3 tests that count against the Section Floor.

### Step 3: Clarification

Run this step when one of these two conditions is true. Skip it in every other case.

1. **No content exists.** Step 1 sent you here.
2. **Step 2 cannot reach the section floor.** `simple` needs 3 sections, `moderate` needs 5, and `detailed` needs 8.

Content that cannot fill the floor forces you to invent sections. An invented section produces an image that looks confident and states nothing true. That is the failure this step prevents.

Do NOT run this step because two styles both fit. `whiteboard` is an acceptable default, and Step 4 lets the user change the style at no cost.

**How to ask:**

- Ask at most three questions.
- Send them in one message, numbered.
- Give each question a recommended answer that one word accepts. The recommendation may propose a scope, an audience, or a source to read. It may never propose the missing Content itself. "Shall I read your CI config?" is safe. "Standard pipeline: commit, build, test, ship?" is not, because a user who accepts it has approved Sections you invented, and the Section Floor is then satisfied by a guess wearing consent.
- Never ask what the content already answers.

Ask about the gap you found, not about the flags. Good questions name the missing structure: which parts matter, who reads the result, what the reader must do next.

After the answers arrive, run Step 2 again with the new content. Then go to Step 4.

If the user declines to answer, lower the complexity to the highest level that the content supports. Say which level you chose and why. If the content cannot fill 3 sections, stop and say so.

### Step 4: Confirm the plan

Run this step when one of these three conditions is true. Skip it in every other case.

1. Step 3 ran.
2. The literal line `VISUALKAN-WIZARD-RUN` appears in this conversation. That is the Handoff Token, and the Wizard prints it when it hands over a run.
3. The user passed none of `--style`, `--draw-level`, `--complexity`, `--device`, or `--mode`. Those five shape what the picture looks like. Each is then a default the user never chose, and this block is the only place they see it before the money is spent.

   `--backend`, `--model`, `--size`, `--output`, `--prefix`, and `--from` do not count here. They route the run; they do not decide what is drawn.

A user who typed exact flags asked for an image, not a conversation. Never interrupt that user here. A user who typed no flags asked for nothing in particular, so show them what they are about to get.

When condition 3 is what brought you here, add this line under the block:

```
Every Control above is a default. Change any of them here, or run /visualkan-wizard to be walked through them.
```

Name the Wizard, and stop there. Never read the Wizard's own skill body, and never follow its steps. It reads this file; this file does not read it.

State the plan in one block:

```
Style: [style]        Draw Level: [draw-level]    Complexity: [complexity]
Mode: [mode]          Backend: [name, and why it won]
Core Concept: [one sentence]
Sections: [numbered titles, no descriptions]
Cost: [one image, or N images for multi-frame]
```

The Backend line must say why. For the native route, name the tool you actually found, as in `native (generate_image tool detected)` or `native (image_generation tool detected)`.

For the CLI route, ask the Runtime. The `controls` command reports which backends hold a key, calls no API, and costs nothing:

```bash
python3 "<path from Step 1>" controls
```

It marks each backend `available` or names the key it needs, and it states that the default is the first available one in the list. Report the backend that wins plus the reason, for example `OpenRouter (no image generation tool here; first key found)` or `Grok (you passed --backend grok)`. A user who expected their platform's own image generation must be able to see, in one line, that it was not available.

Then stop and wait. Do not construct the image prompt. Do not call the image API. The user reads this block to find out what will appear before any money is spent.

If the user changes a control, apply the change and print the block again. If the user changes the content, run Step 2 again first.

### Step 5: Construct the image generation prompt

Read the Style Template first, using the instructions under "Style Templates" below, then build the prompt from it.

The Runtime rejects a prompt under 300 words, and sets no upper limit.

Length follows the Section count, the number of labelled connections, and how much exact text the picture carries. It is an outcome, not a target, and runs of the same Complexity vary widely. Never cut detail to reach a word count. A vague prompt produces a generic image, and that is the one failure a longer prompt cannot cause.

**CRITICAL PROMPT ENGINEERING RULES:**
- Describe the EXACT layout with spatial positions (top-left, center, bottom-right, etc.)
- Specify EVERY icon, illustration, and decorative element
- Include exact text/labels that should appear in the image
- Describe colors using specific names (not just "colorful")
- Specify typography style (bold headers, handwritten labels, etc.)
- Describe connections between elements (arrows, dotted lines, flowing curves)
- Include background details and textures
- Specify the overall composition and visual flow (where the eye should travel)

### Step 6: Handle multi-frame mode

If `--mode multi-frame` is specified:

1. Break the content into 3-5 progressive frames that build up the concept
2. Frame 1: Introduction — show the core concept and title
3. Frame 2-N-1: Progressive elaboration — add sections one at a time
4. Frame N: Complete picture with all elements and a summary
5. Generate each frame as a separate image, maintaining consistent style/layout
6. Each prompt should reference "this is frame X of Y in a series" for consistency

### Step 7: Generate the image(s)

### Where the image goes

Both routes land the image in the same place. The user chooses with `--output`. When they did not:

- Write to `visualkan-output/` inside the workspace or project directory this platform gave you.
- If this platform states no workspace or project directory, write to `visualkan-output/` in the user's home directory.
- Never write inside the platform's own configuration or state directory, and never inside this skill's directory. A user cannot find an image filed under the tool that made it.

Resolve that to an absolute path and use it on both routes. You know where the workspace root is; the Runtime does not, because it sees only whatever directory its shell happens to be standing in.

### Native route

Invoke the environment's image generation tool with the constructed prompt. If it accepts an aspect ratio, pass `3:2` for landscape, `2:3` for portrait, or `1:1` for square, matching the size this Style resolved to.

Assume nothing else about its shape. These tools differ across platforms: some write a file and hand you a path, some return the image bytes, and no two agree on parameter names. What is fixed is the outcome, not the call:

The image ends up at `<output directory>/visualkan_<yyyymmdd>_<hhmmss>.<ext>`, where the timestamp is the moment you generated it and the extension states the real format.

If the tool wrote the file elsewhere, move it there. If it handed you bytes, write them there yourself. Report that path and not the one the tool picked.

### CLI route

Write the prompt to a file first. Never pass the prompt as a command-line argument. A prompt contains double quotes, apostrophes, and newlines, and a shell will corrupt at least one of them.

1. Write the constructed prompt to a temporary file, for example `.visualkan-prompt.txt`, using the Write tool.
2. Run the CLI:

```bash
python3 "<path from Step 1>" generate --prompt-file .visualkan-prompt.txt --style <style> --output <dir> --prefix <prefix>
```

3. Delete the temporary prompt file.

The CLI writes the saved image path to stdout, and the backend and model it selected to stderr.

Pass through each flag the user supplied:

| User flag | CLI flag |
|---|---|
| `--backend` | `--backend openai`, `gemini`, `openrouter`, or `grok` |
| `--model` | `--model NAME` (openrouter only, the CLI rejects it elsewhere) |
| `--size` | `--size WxH` |
| `--device` | `--device mobile`, `desktop`, or `tablet` |
| `--output` | `--output DIR` |
| `--prefix` | `--prefix NAME` |

Always pass `--style`, because the CLI derives the default image size from it.

For `--mode multi-frame`, call the CLI once per frame with that frame's own prompt file. The CLI timestamps each file to the second, so frames generated moments apart already sort in the order they were made. Keep `--output` and `--prefix` identical across the frames.

If the CLI exits with a non-zero status, show its message to the user unchanged. The message is written for them. Do not retry with a different backend, and do not fall back to `curl`.

### Step 8: Generate structured text companion

After generating the image, also output a structured text summary in this format:

```
## Visualkan: [Title]

**Style:** [style] | **Backend:** [the backend that ran, or "native" for the platform's own tool] | **Draw Level:** [draw-level] | **Complexity:** [complexity]

### Sections
1. **[Section Title]** — [brief description]
2. **[Section Title]** — [brief description]
...

### Key Relationships
- [Concept A] → [Concept B]: [relationship]
...

### Text you may want to check
- [any claim field 7 could not cut, one line each]
- [the specimen text, summarised in one line, e.g. "8 order rows and 4 status names, invented"]
- [omit this heading entirely when field 7 listed neither]

### Image
Generated: [filepath]
```

If Step 4 did not run, no one has asked the Runtime which backend wins, and Step 7 reports it only on stderr. Run `controls` to fill the Backend line. It calls no API and costs nothing:

```bash
python3 "<path from Step 1>" controls
```

The "Text you may want to check" heading is the only place the user learns which words in the picture came from you rather than from them.

Keep it short enough to be read. Field 7 already drops the connective and decorative text for this reason: a list of twenty entries hides the one that matters as effectively as no list at all.

### Step 9: Summary

Report to the user:
- The generated image path(s)
- The style and settings used
- A brief description of what's depicted
- Suggestions for refinement (e.g., "Try `--draw-level sketch` for a more casual feel" or "Try `--style infographic` for a more structured layout")

---

## Content Analysis: the mandatory breakdown

Step 2 sends you here. Write the seven fields in the order given, under these headings.

Read the Style Template for your Style before you start. Fields 5, 6 and 7 draw on it, and Step 5 is where the skill first names it.

**Field 2 can end the run.** It holds the Section count, and Step 3 tests that count against the Section Floor. If field 2 sends you to Step 3, stop there and write no further field. Writing metaphors and colours for Sections that just failed the floor invents exactly what the floor blocks.

### 1. Core Concept

One sentence naming the single idea the picture teaches. Every Section supports it.

If the Content needs two sentences, it holds more than one picture. Say so, name the one you chose, and name what you left out.

### 2. Sections

A Section is one unit of Content that the picture draws as its own element, under its own title.

Every Section must assert something traceable to the Content the user gave you. A Section you cannot trace is invented, and an invented Section produces an image that looks confident and states nothing true. That is the failure the Section Floor exists to prevent.

**Traceable** means the Content names it, or a file the user pointed you at names it. What you already know about the subject is not Content. A deployment pipeline you can recite from experience is knowledge, and knowledge cannot fill the floor. The test is whether you can quote the words that put the Section there.

List the Sections as a numbered list, titles only. Then write the count on a line of its own, as `Count: 6`.

Compare the count against the Complexity:

| Complexity | Sections |
|---|---|
| `simple` | 3 to 4 |
| `moderate` | 5 to 7 |
| `detailed` | 8 to 12 |

If the count sits below the floor, stop here and go to Step 3. Never pad the list to reach the floor.

If the count sits above the ceiling, merge the two closest Sections and name the pair you merged.

**Mermaid Content usually carries more nodes than the ceiling allows.** A node is not a Section. Group the nodes into Sections by subgraph, by stage, or by the natural phases of the flow, and record which nodes belong to each Section. Every node still reaches the Image Prompt as its own labelled element. The Section count shapes this analysis. The node count shapes the picture.

### 3. Relationships

One line for each connection between Sections: the source, the target, and the label the picture will carry.

Where the Content is Mermaid, keep every edge label word for word. A paraphrased label becomes an arrow that says something the user never said.

### 4. Visual Metaphors

One concrete object for each Section, named precisely enough to draw.

"A padlock with the key still in it" is a metaphor. "A security icon" is a category, and a model asked for a category draws generic clip art. This field decides whether the picture teaches or merely decorates.

If a Section resists a metaphor, say so and give it a plain labelled shape. An honest empty slot beats a forced image.

### 5. Layout Strategy

Name the arrangement, and name the path the eye takes through it. Write both.

For example: "Radial. The Core Concept sits at the centre, and six Sections run clockwise from the top left. The eye enters at the title, drops to the centre, then travels clockwise."

The Style Template offers arrangements that suit its Style. Choose one of those before you invent another.

### 6. Colors

Give each Section one named colour, and name the background.

Use colour names a model can act on, such as `cherry red` or `slate blue`, rather than `blue-ish` or `a warm tone`. Where the Style Template fixes a palette, take the colours from the template and assign them to your Sections here.

A palette can hold fewer colours than the Complexity allows Sections. Where that happens, give one colour to each group of Sections that belong together, and say which Sections share a colour. Do not add colours the template excluded.

### 7. Exact Text

Sort the text that will appear inside the picture into three kinds. Only one of them is a problem, and collapsing them buries it.

**Claims.** Any figure, quantity, date, percentage, proper noun, or statement of fact. `20ms`, `200+ edges worldwide`, `99.9% uptime`, a named customer.

Write every claim on its own line and mark it `traced` or `invented`. A claim is `traced` when the Content states it. Everything else is `invented`, including a figure you are confident about.

**Refuse every invented claim.** Cut it, or replace it with a label that asserts nothing: `low latency` rather than `20ms`. A model renders a number as fact, and an image stating a figure the user never gave is the failure this skill names in its own words: confident, and true about nothing. This is the only kind you must act on.

**Specimen text.** The plausible filler a Style needs to read as itself: table rows, example names, sample dates, placeholder copy. A `mockup` is not a wireframe without it.

Keep it, and list it in one line rather than one line per item, for example `8 order rows, invented`. Say if it proposes a vocabulary the user did not give you, such as a set of status names for their workflow, because that is a design decision wearing the clothes of filler.

**Connective and decorative text.** Arrow labels, section captions, and the encouragement a template asks for by name, such as `Key!` on a whiteboard. This text carries the structure you already recorded in field 3, or the template mandated it.

Keep it and do not list it. Listing it is what makes the disclosure useless: a run that lists `fast`, `slow` and `Key!` buries the one fabricated number at item 14 of 24, where nobody reads it.

**Invented visual meaning counts as a claim.** A dashed stroke, a red fill, or a heavy border asserts something when a Style uses it to mean something. If you assign a visual property a meaning the Content did not give it, write it here as a claim and mark it `invented`.

Section titles are exempt only when the Content supplied them. Where you wrote the titles yourself, as happens with Mermaid input, they are your words: list them as specimen text.

---

## Style Templates

The seven Style Templates do not live in this file. Each one is a separate reference file inside this skill's `references/` directory.

Read `references/style-<style>.md` from this skill's own directory, using the Style you resolved in Step 1. Resolve that relative path against the directory this skill was loaded from, not against the current working directory, and write it with forward slashes:

```
<this skill's own directory>/references/style-<style>.md
```

Build the Image Prompt from the template you read. Do not write a prompt from memory, and do not invent a template. A skipped template fails the run rather than producing a weaker image.

**Keep every ALL-CAPS header, spelled exactly as the template spells it.** The Runtime checks for those headers literally and rejects a prompt that renames or drops one. Carrying them across is the whole contract, so you never need to read the Runtime source to learn what it wants.

**Resolve every draw-level branch, and write only the wording you chose.** The template marks a branch with a note such as `[If sketch: ... If polished: ...]`. Choose the wording for the Draw Level of this run, and write that wording as plain description. Never copy the brackets, the words `If sketch`, or the wording you did not choose. A model reads all of it as things to draw, and it will draw every branch at once.

If a branch names no wording for your Draw Level, choose wording that sits between the two levels it does name.

**No square bracket may survive into the Image Prompt, unless the template asks for one as literal text.** A template uses brackets for more than draw-level branches. It also carries authoring notes such as `[For each UI element described in the content, specify:]`, slot markers such as `[Title text]`, and optional parts such as `[If applicable ...]`. Each of those is an instruction to you, never text to draw. Resolve every one, then search the finished prompt for `[` before you send it.

The single exception is a bracket the template names as words to render, such as the `"[Image]"` placeholder label inside a `mockup` wireframe. That one is quoted in the template because it is text in the picture. Keep it, and treat every unquoted bracket as an instruction.

---

## Prompt Quality Checklist

The Runtime already checks two things, so do not spend effort on them by eye: the ALL-CAPS headers its Style requires, and the 300-word floor. Carry the template headers across and both pass.

Check what the Runtime cannot see. A prompt passes the gate and still draws the wrong picture when any of these is missing:

- [ ] Every Section from the Content Analysis appears, under its own title
- [ ] Every icon and illustration is described by what it looks like, not named by category
- [ ] Every relationship from the Content Analysis is expressed: as an arrow carrying its label where the Style draws connections, or as position and grouping where it does not, such as `mockup`
- [ ] Colour names match the Content Analysis, and a model can act on each one
- [ ] A spatial position is stated for each element, rather than implied by the order of the text
- [ ] No square bracket survives anywhere in the prompt
- [ ] Every line marked `invented` in field 7 is one the Style genuinely needs
- [ ] The device frame matches `--device`, when the Style is `mockup`
- [ ] Exact label text is written out, rather than described

If an item is missing, add it before you generate.

## Error Handling

The CLI owns every error about backends, API keys, and models. Its messages are written for the user, so show them unchanged and do not translate or summarise them. Your own error handling covers only these cases:

- If no content is provided, run Step 3
- If `--backend native` was passed and this environment has no image generation tool, say so and stop. Never substitute an API backend: the user chose the option that costs nothing.
- If the Runtime file is missing and no image generation tool exists, tell the user to run `npx skills add dapih/visualkan`. That command reinstalls the whole skill directory, which is the only thing that can put the Runtime back.
- If the CLI exits non-zero, print its message and stop. Do not retry with another backend.
- If the content is too complex for the chosen complexity level, suggest upgrading to `detailed`
- If the content is too thin for the chosen complexity level, run Step 3. Never invent sections to fill the floor.

## Notes

- The prompt engineering is the primary value of this skill — spend time on analysis and prompt construction
- The same prompts work across every backend; the style templates are backend-agnostic
- The CLI already requests the highest quality each backend offers. Do not try to set quality yourself.
- For best results with text-heavy content, prefer `infographic` style
- For process/flow content, prefer `diagram` style
- For engaging/fun explanations, prefer `whiteboard` style
- For hierarchical/categorical content, prefer `mindmap` (colorful) or `mindmap-structured` (data-oriented)
- For UI wireframes and screen layouts, use `mockup` style with `--device` to select the frame type
- The `mockup` style is ideal for rapid wireframing from PRDs, brainstorming UI layouts, or visualizing modernized interfaces for existing code
- Use `mindmap` when the audience values visual appeal and creativity
- Use `mindmap-structured` when the audience values precision, data density, and professional presentation
- The `draw-level` parameter changes every style template. Its effect is strongest on `whiteboard`, `mockup`, `diagram`, and `presentation`. It is lightest on `infographic`, which is a polished format by definition.
- `mindmap` stays vibrant at every draw level, and `mindmap-structured` keeps its data elements at every draw level. Each template states this. The two styles differ by data elements, not by polish (see ADR 0002).
- Multi-frame mode costs more (one API call per frame) — warn the user about cost
- Estimated cost (OpenAI): ~$0.053 per image at medium quality, 1024x1024. High quality ~$0.211
- Estimated cost (Gemini): Free tier available; check current pricing at aistudio.google.com
- Estimated cost (Grok): not published per image at the time of writing. The Runtime asks for `2k` resolution, which may cost more than the `1k` default. Check current pricing at console.x.ai before a multi-frame run.