Skip to main content

Keep a Docs Mascot Consistent: Character Locks and Multi-Image Combines

Updated 6 min readMarkdown

A documentation site can survive a slightly ugly screenshot. It cannot survive a mascot that changes species between chapters. We learned this the slow way. We had a small illustrated character — a round bird with a tool belt — that was supposed to appear in getting-started pages, error-state illustrations, and a couple of social cards. After three months we had four birds. The beak got sharper. The belt became a satchel. One chapter's bird had eyebrows the others did not.

The writing team was not sloppy. We were describing the bird in prose and hoping each new scene would land on the same animal. That is not how these models work, and it is not how I would version a logo. The fix was to treat the mascot like source, and to build every new scene as a combine of that source plus a setting, inside an AI image editor that can hold character consistency and blend more than one reference in a single job.

Put the character in a repository, not in a paragraph

The file that matters is not the last PNG we published. It is the reference sheet.

docs-art/
  refs/
    mascot-front.png
    mascot-three-quarter.png
    mascot-expression-ok.png
    mascot-expression-error.png
    set-desk.png
    set-terminal-error.png
    ui-empty-state.png
  prompts/
    getting-started-desk.txt
    error-state.txt
    og-card.txt
  out/

mascot-front.png is the lock for the face and body. The three-quarter and expression sheets exist because a getting-started bird looking at a laptop is not the same pose as an error-state bird looking at a red badge, and I do not want the model to invent a fifth expression. The set files are places, not decorations: a desk we already photograph for the product, a terminal crop, an empty-state UI.

In the prompt I tag each file by role, the same way I would name layers.

Use the first image as the character's face and body. Keep the tool belt, the eye shape, and the colors exactly. Use the second image only for the desk and window light. Place the bird at the desk, looking at a laptop, mid shot, soft morning light. Do not change the character's proportions or add a second bird.

If I leave the roles unsaid, the desk texture ends up on the belt, or the bird inherits a plant from the set photo.

Character consistency is a constraint, not a style

The editor's character-consistency feature is the reason this works at all. The output is supposed to look like the input character, not like a cousin. I still write the lock in the prompt, because a constraint you do not state will be treated as optional the first time you ask for a dramatic scene.

Two rules have saved us from another flock of almost-birds:

Do not update the character in the same job that changes the scene. If we decide the belt should have one more pocket, that is a revision of mascot-front.png, reviewed like a logo change. Then every scene prompt points at the new sheet. Mixing "new belt" and "now the bird is in a server room" is how you get a new bird in a new room and cannot tell which instruction did it.

Do not use a previous scene as the only character lock. A scene already contains a desk, a pose, and lighting. If I feed that back as the identity reference, the next chapter inherits the desk. Identity references should be as clean as I can make them.

Multi-image combination is the actual production step

Most docs illustrations are not "a bird." They are "a bird plus this UI plus this room." The editor's multi-image combination is built for that blend. Depending on the model, you can attach up to fourteen references with Nano Banana 2.1, Nano Banana 2, and Nano Banana Pro, or up to sixteen with GPT Image 2.6 and GPT Image 2.5. I have never needed sixteen. I have often needed three: character, set, UI.

The UI file gets its own sentence, and it is a strict one.

The laptop screen must show the empty-state UI from the third image, including the typography. Do not rewrite labels or invent extra buttons.

Illustrated mascots and real product screens in one frame is a messy request. When the text on the screen starts to drift, I split the job: generate the bird-in-the-room with a blank or lightly blurred screen, then composite the real screenshot later, or run a second pass that only asks to place the UI. A single generate that has to invent a pose and perfectly typeset a settings page is usually doing too much.

For a wide docs banner I change only the framing. Most models support Auto and ratios from 1:1 to 21:9; Nano Banana 2.1 adds 4:1 and 8:1, which is where a thin banner actually fits. I do not crop a square mascot shot into an 8:1 strip and hope the beak stays on screen.

What we accept, and what we send back

The review looks more like a pull request than an art critique.

  • The beak, belt, and colors match the reference sheet at a glance.
  • There is one bird. A helpful second bird in the corner is a failure.
  • The UI, if any, is still our UI.
  • The set does not introduce a logo or a product we do not ship.
  • The file is named for the page it belongs to, not "final-v7-really.png."

When a take is almost right — good bird, wrong time of day — I describe only that change and reattach the same character sheet. Regenerating the whole scene from a looser prompt is how the eyebrows come back.

Outputs land in My Creations, where I download the ones we keep. I treat that library as a cache, not as the source of truth; the source of truth is refs/ in the repository. If the public-visibility default worries you for unpublished brand work, check it before you start a batch, and prefer a setup where you can turn visibility off.

The measure of this workflow is not whether the bird looks expensive. It is whether chapter four's bird would be recognized by someone who only saw chapter one. Once that is true, adding a new page is a new set photo and a new prompt, not a new character design.

No comments yet. Be the first to comment.