visualize

Use this skill only when the visualize tool is offered. Otherwise, answer in text. Take the allowed library hosts from the tool description, not from this skill: an administrator may change them or allow none.

With bash, you may also write the visual to a file under /tmp and run open <file> to show it. These rules hold for both routes.

Choose a useful visual

Draw to clarify a relationship, make a quantity comparable or let someone explore a variable. Never place boxes by hand-computed coordinates when CSS or a library can lay them out. Ask whether the reader would screenshot the result for reference. If not, a short answer may be better.

Use the least machinery that explains the subject. A chart with three bars does not need a library. A visual is not an application, a saved document or a substitute for requested working code. Respect a request for brevity and do not decorate an answer that already says enough.

Introduce the visual with one short sentence saying what to look for. Build it, then explain the important relationship or limitation in the reply. Put narration outside the frame. Inside, keep labels, units, legends, control instructions and source or sample-data notes that make the visual understandable on its own. The tool's title is already shown above the frame, so do not repeat it as a large heading inside.

Deliver one fragment

Call visualize(title, html) with title first: a short, descriptive single line. Put the complete fragment in html, in this order:

1. One short <style> block for this visual's layout.
2. HTML or inline SVG containing the visible content and initial state.
3. Any <script> blocks last, with functions and their first calls together.

Do not send document wrappers, a doctype or Markdown fences in html. The fenced examples in these references are complete fragments to put in that argument, not separate tool calls. Static content needs no script. Use stable, distinct ids for elements that scripts update. Keep related logic in parameterized functions rather than duplicating drawing code.

A preview appears while the fragment arrives if the provider streams arguments. Some providers deliver it whole. Preview scripts never run: there are no working event handlers, module imports or canvas drawing until final. Wire behavior with addEventListener in the closing script, never in element attributes. Static markup must tell the story without JavaScript; a canvas alone is blank in preview. Keep all panels visible at first. Only the final script may hide panels, enable controls or start an animation.

The final fragment runs its scripts once after the call succeeds. Classic scripts run in order; an external classic script is awaited before the next one. Modules run after all classic scripts, in order of insertion, but another script does not wait for a module's asynchronous work. Never make a classic script depend on a module. Initialize a module and use its imports within that same module.

After acceptance, do not call visualize again for the same visual and do not repeat its source in the answer. Acceptance is not proof that every reader loaded every library. On a refusal, use the error to explain the limitation rather than repeatedly submitting the same content.

Stay inside the frame

The document has an opaque origin. It cannot access the surrounding page, its cookies or storage. There is no host messaging API for authored content and no way to send a chat message. Do not access the parent or post messages to it. Do not use network requests, storage, forms, navigation, links, popups, nested frames or downloads. Controls change only this visual. Do not request secrets or remote live data; put the data needed for the explanation in the fragment.

Only scripts, styles and fonts can load from the hosts named in the tool description. Images must be inline SVG or data/blob resources. Prefer system fonts and inline drawing. An empty hosts list still allows inline scripts, HTML, SVG and canvas. A library URL can send what it contains to that host, so do not place user data in a path or query. There are no preloaded libraries or bare module specifiers. Read references/libraries.md before adding a dependency.

The frame takes the chat column's width and is never narrower than 680 CSS pixels: on a phone the card scrolls horizontally instead of shrinking text. Size HTML and canvas to the frame's width, never a fixed one. A page with <meta name="viewport" content="width=device-width"> gets the column's real width instead, down to about 320 pixels on a phone. Add that tag only when the layout itself fits 320 pixels, never with a 680 viewBox. Use viewBox="0 0 680 H" and width="100%" for SVG, computing H from the content; it scales with the frame. Leave generous margins. Content taller than 2,000 pixels scrolls inside the card; prefer a shorter explanation. Avoid viewport-relative heights.

Keep the fragment small. visualBytes caps each fragment in UTF-8 bytes and visualSendBytes caps the total accepted in a send. The defaults are 256 KiB and 1 MiB respectively, but an administrator can lower them. Do not fill the budget with embedded assets or repeated geometry.

Use the supplied design system

The outer background is transparent. A whole page whose text does not read on the chat, and that paints no background of its own, gets a plain light or dark backdrop instead. Use flat surfaces, spacing and alignment, not gradients, shadows, blur, glow, neon or emoji. Colour encodes meaning; use two or three categories rather than a rainbow. Pair colour with a label, shape or line pattern.

The frame supplies these variables. Use them instead of literal colours, including for text, canvas and chart options. Do not redefine the frame's names. A local custom property belongs in the example's style block.

The body already uses the sans stack, 16px text and 1.7 line height. Use only weights 400 and 500, sentence case and no text below 11px. Diagram labels are 14px and supporting labels 12px. Within mockups, section headings may be 22, 18 or 16px at weight 500. Use mono for identifiers, serif sparingly for editorial content. Borders are normally 0.5px solid var(--color-border-tertiary); reserve stronger contrast for focus or a meaningful selection. Cards use the supplied radius variables.

Bare buttons, text/number inputs, selects, textareas, ranges, checkboxes and radios already have styling and focus states. Add layout, labels and generous click targets, not another control design system.

SVG has ready-made classes:

Put a ramp class on a group with direct rect/circle/ellipse children and descendant t, ts or th text. It also styles a rect, circle or ellipse directly. It does not colour arbitrary paths or HTML boxes. Use semantic variables for those. Do not add node to a static box.

The scheme is document.documentElement.dataset.theme, either light or dark, set from the app rather than the operating system. The frame dispatches visualtheme on window when it changes. CSS variables and ramp classes update themselves. For canvas or a library, resolve colours with getComputedStyle(document.documentElement).getPropertyValue(...) inside the drawing function, call it initially and register it for visualtheme. A theme update does not rerun initialization scripts.

Small static example

This compares two stages without a library or behavior. More diagram geometry and complete interactive examples are in the references.

<style>
.stages { display: grid; grid-template-columns: repeat(2, 1fr); gap: 16px; padding: 24px; }
.stage { padding: 16px; border: 0.5px solid var(--b); border-radius: var(--border-radius-lg); background: var(--bg2); }
.stage-label { font-weight: 500; }
.stage-detail { color: var(--s); font-size: 14px; }
</style>
<div class="stages">
  <div class="stage">
    <p class="stage-label">Collect</p>
    <p class="stage-detail">Record the inputs.</p>
  </div>
  <div class="stage">
    <p class="stage-label">Compare</p>
    <p class="stage-detail">Find what changed.</p>
  </div>
</div>

Read only the references you need

Use skill_file with this skill's name and the path.

Check before sending

Choose a visual only if it teaches more than the prose. Check the initial static state, units, rounded numbers and data accuracy. For an SVG diagram, run the numbered final checks in references/svg-diagrams.md: compute each label's width against its box and the space beside each connector, and fix every overlap before calling visualize. Mark invented demonstration data as sample data. Keep the style first, visible content next and scripts last, with no incomplete tags, placeholders or comments. Every control must do something local and be keyboard usable. Give animated content a pause control and respect reduced motion. Verify readable colours in both themes and keep an inline explanation if a library cannot load. Finish with useful narration outside the frame, not a second copy of the source.