dotharness/dotcraft/visualize

Visualize

• A request for a new standalone file, website, app page, component, or other project change is not an in-conversation visualization request, even when the deliverable contains charts or interactive content. Build those in the open project.
• A request to preview, explain, or explore a proposed interface in the conversation is an in-conversation visualization request.
• Create a visual only when the user needs to see or explore it in the conversation and it materially improves the explanation. Do not create a visual merely because the request involves data, charts, or an interactive page.
• Use a normal Markdown table when the user asks for a table; return it directly and do not create a visualization file.
• Use Mermaid when labeled nodes and edges fully explain a static structure; return a normal fenced Mermaid block and no visualization file. Use HTML for dynamics, spatial motion, adjustable inputs, and other visuals.
• When the system context has a # Generative UI section, use the generative-ui skill instead for calculators, forms, quizzes, choices, comparisons, and cards. Keep visualizations for dynamics, simulations, maps, custom graphics, and games.
• Create an HTML visualization only when the system context has an # Visualizations section with a visualization directory. Otherwise, use Mermaid, a Markdown table, an ASCII diagram, or concise prose, and never emit a content reference.
• Work silently unless blocked or the user explicitly asks for progress. Never send commentary or progress updates while reading this skill or writing or updating the file; the final response must be your first user-facing message.
• In user-facing prose, describe only what the visual helps the user see or decide. Keep it concise and do not repeat information already clear from the visual. Never announce this skill, a visualization surface, widgets, HTML, SVG, scripts, local files, inline data, or implementation details.

Read the complete skill

Read this file in full before authoring. Reread truncated ranges in smaller calls. Copy into every compaction summary: Reload the full visualize skill before creating or updating a visualization.

HTML output contract

File

• For each new visualization, choose a concise ASCII lowercase-hyphenated title and write <title>.html with WriteFile, using an absolute path directly inside the visualization directory from the system context. Never write visualization fragments anywhere else.
• To update an existing visualization, rewrite its file in place with WriteFile or EditFile. Every reply that shows that path then displays the latest version.
• Read the file back with ReadFile after every write.

Fragment

• Write only an HTML fragment: no <!doctype>, <html>, <head>, or <body>.
• Write literal markup: use <div class="card">Hi</div> plus a real newline, never <div class=\"card\">Hi</div>\n. Never embed the fragment in an inline Python, JavaScript, or shell string. Read it back; rewrite literal \" or \n.
• Keep CSS and JavaScript in the fragment only when base classes are insufficient. Load static resources only from the CDN allowlist. Never use fetch, XHR, WebSocket, or other API calls.
• Give the fragment root a unique ID and select it with document.getElementById(...). Never derive the root from document.currentScript; scripts may sit outside the root.
• Keep visualizations under 1 MB. Aggregate, bin, downsample, reduce precision, or drop unused fields from large inline datasets.
• Check that JavaScript has no undefined identifiers, every queried element exists, and the primary interaction updates the visual. The host reports the first uncaught error or unhandled rejection to the user with an action that asks you to fix the file.

Content and response

• Keep the fragment focused on the visualization. Do not include explanatory paragraphs, formulas, instructions, or narrative callouts. Include only necessary labels, legends, values, and accessible text alternatives.
• Use the normal response flow. Put any necessary concise explanation outside the fragment, and add this visualization content reference on its own line where the visual should appear, using the absolute file path:

visualize{"path":"<absolute-path>/<title>.html"}

• The JSON object may also include a title of at most 200 characters when the visual needs a more descriptive accessible name: visualize{"path":"<absolute-path>/<title>.html","title":"Monthly sales by region"}. It may also include "mode":"wide" as described next. Use no other keys.
• Add "mode":"wide" for a full-screen desktop app mockup, including its application shell. For other visuals, add it only when several compact chart panels must stay side by side for direct comparison and would be unreadable at the normal width. Never widen a single plot, map, grid, diagram, or timeline merely because it is dense. Keep contained mockups, dialogs, and mobile screens at normal width, and stack separate self-contained views vertically. A wide view breaks out of the text column up to 1,024px when the conversation has room: visualize{"path":"<absolute-path>/<title>.html","mode":"wide"}
• Whenever you create or update a visualization, include its content reference only in that same turn's final response (never in commentary or progress updates), even when editing an existing file or reusing a path shown in an earlier turn.
• Emit only the content reference for the fragment. Never announce it as an artifact, website, output, attachment, link, or download, and never add a Markdown link to it. Do not append a Markdown table or repeat the visual's data; add at most one short conclusion when the user needs an explanation.

External resources

• The CSP allows only cdnjs.cloudflare.com, esm.sh, cdn.jsdelivr.net, unpkg.com, fonts.googleapis.com, fonts.gstatic.com, and fonts.bunny.net. Other origins are blocked and fail silently. Network requests such as fetch are blocked even for these origins, so load data as script or module imports or inline it.

Runtime styles

Color

• In each color pair, the base token is a surface and its -foreground token is the content on that surface. --muted is a surface fill; use --muted-foreground for secondary text.
• Make every fill, stroke, text, border, shadow, chart, and canvas color theme-aware. Never hardcode light or dark palettes such as white panels, off-white backgrounds, black text, slate strokes, or Tailwind color literals.
• Keep text readable against its actual background. Muted or secondary colors must retain clear contrast; never use .text-muted inside .card or another filled container unless its background preserves that contrast.
• Available theme variables are --background, --foreground, --card, --card-foreground, --popover, --popover-foreground, --primary, --primary-foreground, --secondary, --secondary-foreground, --muted, --muted-foreground, --accent, --accent-foreground, --destructive, --border, --input, --ring, --viz-series-1 through --viz-series-6, and the named hues --blue, --orange, --green, --red, --purple, and --yellow. Use currentColor inside SVG.
• --popover and --popover-foreground are the tooltip pair: an inverted surface that stands apart from the visualization. Use them only for transient annotations such as a chart tooltip.
• Named hues follow the host theme. Use them for status or category identity in marks, swatches, and soft tinted fills, never for text or controls.
• The document follows the host appearance, so light-dark(<light>, <dark>) resolves to the active theme.
• Never add decorative borders, outlines, or strokes to progress tracks, meters, bars, stacked segments, or other filled quantitative marks. Use a subtle neutral or translucent track and distinguish marks with fill, contrast, spacing, or opacity.
• Use --viz-series-1 for one measure or active state. Use --viz-series-2 through --viz-series-6 only for important persistent category, series, or status identity; never give every peer a different color by default.
• For categorical tiles or nodes, prefer a soft low-opacity series fill with a neutral or transparent border; never color every outline.
• Keep mappings stable and pair color with labels, shapes, or line styles.
• Secondary series colors are theme-derived; never assume hues or use them decoratively.
• When color encodes a category or series, apply it consistently to the corresponding visual marks, not just the legend, and keep large-area fills subtle.
• Use series colors only for chart lines, marks, and legend swatches. Keep values, axis text, and direct labels in --foreground or --muted-foreground.
• Keep chart grids and inactive structure thin and neutral. Use 1-2px neutral structural paths; never thicken, dash, or double-stroke the whole structure.
• Use .btn-primary for high-emphasis actions; its neutral fill is supplied by the utility. Buttons with aria-pressed="true", .active, or data-state="active" already use the selected style; .nav-pills .nav-link.active and a selected .viz-tile keep selection neutral. Reserve --accent and --accent-foreground for subtle interactive surfaces and soft highlights.

Typography

• Scale type with --font-size-base, which follows the host's conversation text size. Use normal text by default and .text-small only for secondary annotations; at the default scale these are 14px and 12px. Never make supporting text smaller than 11px.
• h1, h2, and h3 are styled by the host. Use one concise visible heading (h2 or h3) for a self-contained chart or graph, with short panel headings only when needed. Do not restate the prompt or add a redundant title to other visualizations.
• Use only weights 400 and 500 in your own styles. Never set custom font sizes or line heights.
• Use .tabular-nums on changing or aligned numbers. Avoid it for editorial or decorative numerals.

Composition

Choose the smallest composition that fits.

• Prefer interaction detail over permanent panels, toolbars, repeated legends, or long stacks. Add only requested controls, use one mechanism per state, and never invent search, filter, or reset controls.
• Keep filters, selections, and other presentation-only interactions local. For drill-down actions that ask for further investigation or explanation of selected data, call await window.openai.sendFollowUpMessage({ prompt, title, context }), where the optional title is a concise confirmation-dialog heading of up to 250 characters. The user confirms before the message is sent. Include the selected values and requested investigation in the prompt, and label the action clearly. Pass the optional context (JSON, under 32 KiB) only when the follow-up needs structured visualization data beyond the prompt; it is appended to the user's message as visible JSON.
• Show only metrics that explain the requested behavior. Put live values in control headers or on the visual before cards. Treat maxima as ceilings, not targets. Never invent qualitative scores, status cards, or secondary fact grids to fill space.

Remembering interaction state