Diagrams in bits

A diagram can carry what a paragraph cannot: the order of a handoff, which system calls which, where a decision branches. Bits can hold diagrams drawn as SVG, the vector format diagram tools and AI assistants produce. Most diagrams in Floxar are made the way the rest of the content is: you describe what you want to your AI client, it draws the diagram, and it writes it into the bit for you.

What readers see

A diagram shows in the bit at the width of the column, on its own white background in both light and dark mode, so its colours always read as drawn. Readers can open it to the full screen: select the diagram, or the expand button in its corner. There they can zoom with the mouse wheel, a pinch or the zoom buttons, drag to move around, double-click to zoom in on a spot, and return to the whole diagram with Fit to screen or the 0 key. Because SVG is a vector format, text and lines stay sharp at any zoom, so a detailed diagram can stay in one piece instead of being split up to stay legible.

Photos and screenshots work the same way: one shown smaller than its real size can be opened to the full screen too.

A diagram must carry everything it needs

Floxar shows a diagram as an image. An image displays only what is inside its own file: it fetches nothing from anywhere else and runs no code. A diagram that looks perfect in the tool that drew it can lose its colours, fonts or pictures when it leaves that tool, because the tool's page was supplying them.

So Floxar accepts a diagram only when it is self-contained:

• Its styling is inside it. Colours, line styles and fonts are defined in a <style> section within the diagram itself, not by the page of the tool that drew it. If the tool has a light and a dark theme, the diagram uses the light one.
• Its fonts and pictures are embedded. A custom font or a picture inside the diagram is embedded in the file (as a data: URL), not loaded from a web address.
• It is not interactive. Hover effects, animated tracing driven by code and buttons inside the diagram do not work in a bit. Animation written as plain styling, such as a dashed line that moves, does.
• It fits the size limit: at most 256 KiB and 5,000 drawing elements. Embedding only the characters a font actually uses keeps a diagram well inside it.

A diagram that breaks one of these rules is refused when it is written, with a message that names the problem and the fix, so your AI client can correct it and try again on its own. It is never saved in a broken state.

Asking your AI client for a diagram

Most diagram tools offer two forms of the same drawing: the interactive view you look at in the tool, and an export meant to be used elsewhere. Ask for the standalone SVG export. It is usually self-contained already; the interactive view usually is not.

When your AI client draws the diagram itself, a request like this one gets a diagram that works the first time:

Draw this as one self-contained SVG for a Floxar bit: give it a <title> naming what it shows and a <desc> describing it in a sentence or two, put all styling in a <style> element inside the SVG using the light theme, embed any fonts as data: URLs, no scripts or hover effects, and keep it under 256 KiB.

If a diagram was refused, pass the refusal on to your AI client, or simply ask it to "make the SVG self-contained". The message tells it exactly what to change.

Large diagrams: upload the file

An AI client normally writes a diagram straight into the bit's content. A coding client that can read and send files (Claude Code, Codex and similar) can instead upload the SVG file, which keeps a large drawing out of the conversation. It takes two calls, both through call_operation:

1. Get an upload address. Call the createSvgUploadUrl operation with the bitId and the file's fileName (ending in .svg). The answer holds an upload id (svg_upload_id), a url and a set of fields. The address is valid for a few minutes.

2. Send the file as a multipart form POST to the url: every returned field first, in any order, and the file last as file. With curl, one -F per field:

   curl -F "key=<key>" -F "Content-Type=image/svg+xml" -F "Policy=<policy>"         -F "<each other field>=<its value>" -F "file=@diagram.svg" "<url>"

3. Place it. Call the createBitSvgNode operation with the bitId, the bitDraftId of your open draft, the svgUploadId, exactly one of afterNodeId (add the diagram after that top-level block) or replaceNodeId (replace an existing diagram, keeping its id), an optional width in pixels, and a clientIntentId: a new UUID v4 for this placement, reused unchanged if you resend it after an unclear failure, so the diagram is placed once.

The uploaded file is checked by the same rules as a diagram written inline, and is removed once placed; an upload never placed is cleared automatically within about two days. A client without file access, such as a web chat, keeps writing the diagram inline.

What an AI client reads instead of the drawing

Not every reader can see a picture. An AI agent running a step on a text-only model, or a person using a screen reader, gets a short text in the diagram's place: its title, its description, and the labels drawn in it, in the order they appear. That text comes from inside the diagram itself: the <title> and <desc> the diagram declares, and its visible labels. So a diagram must name and describe itself: a diagram without a title is refused when it is written, with a message that tells your AI client what to add. A diagram saved before this rule stays as it is and reads as "untitled" until it is given a title.

Because of this, the step's own text must carry everything a reader needs to do the step. The diagram adds the shape of it: who hands what to whom, which branch applies, where a system sits. A step whose instruction exists only inside the picture is completed wrong by a reader who cannot see it.

A client whose model can see pictures can also ask for a rendered picture of a diagram, and it is told how in the same read: every diagram listed with a step or a bit carries the call that fetches its picture. The picture is drawn on Floxar's servers from the diagram itself, at most about a thousand pixels wide, in one standard font, so it shows the shapes, the arrows and the labels rather than the exact look of the original. A picture costs the client more than text, so a well-made client asks for one only when the title, description and labels leave a question. A diagram that cannot be drawn (one saved before the rules, or one too large) answers the text instead, never an error.

Make the diagram earn its place

A diagram is worth adding when it shows a structure the reader needs at this step: who hands what to whom, which branch applies, where a system sits. Keep the step's instruction in the text and let the diagram support it; a reader should be able to act from the text alone. Give the diagram a title and a description inside it (a <title> and a <desc>), so it is named for screen readers, in the full-screen view and for AI clients, label the things it draws with visible text, and draw it for a white background. For a large map that many steps need, put it in a reference and link the reference from those steps instead of repeating it in each.

Last reviewed: 2026-10-22