visual-output
Emit rich visual output in chat via <widget> tags — styled HTML cards, charts, tables, interactive tools, and drawn SVG/canvas diagrams, illustrations, and animations — theme-aware, centered, and responsive instead of clashing or cramped.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-05
- Stars
- ★ 212
- Forks
- 33
01 前言 Front Matter
- name
- visual-output
- triggers
- widget, widget iframe, chart, table, visual, dashboard, render widget, illustration, diagram, draw, svg, animation, animate, graph, schematic, visualize, visual explanation, figure
- description
- Emit rich visual output in chat via <widget> tags — styled HTML cards, charts, tables, interactive tools, and drawn SVG/canvas diagrams, illustrations, and animations — theme-aware, centered, and responsive instead of clashing or cramped.
- context_tier
- heavy
03 SKILL.md 正文
Visual Output
Gideon renders rich HTML inline in chat via <widget> tags. The HTML runs
in a sandboxed iframe that inherits the dashboard's active theme through CSS
variables. Get the styling contract right and a widget looks native on every
theme — light, dark, or custom. Get it wrong (hardcoded colors, fixed pixel
sizes) and it clashes or renders tiny in a corner.
This skill covers both halves of visual output:
- The widget container — format, theme variables, CSP, interactivity, and the card design system (layout, spacing, type, surface, motion).
- Drawn visuals — SVG/canvas diagrams, schematics, charts, and animations, and the craft of making them centered, proportioned, labelled, and legible.
Format
<widget title="Sales by Region">
<div class="p-4 rounded-lg" style="background: var(--card); color: var(--card-fg);">
…content…
</div>
</widget>
- One widget per payload, self-contained.
- Tailwind CSS is available inside the iframe.
- For large HTML (long dashboards, big tables), save it to a file or an
Artifact (see the
artifactsskill) and reference it — don't inline hundreds of lines into the chat.
Design system — make it look intentional
The difference between a widget that looks native and one that looks slapped together is consistent layout, spacing, type, and alignment. Follow these.
Layout & alignment
- Cap the width and center it. Wrap content in
max-w-md/max-w-xl/max-w-2xl(pick by density) withmx-auto. A widget that sprawls full-width in a wide chat reads as broken. Dashboards:max-w-3xl; a single stat/card:max-w-sm. - One alignment spine. Left-align text content; center only standalone figures (charts, single big numbers, illustrations). Don't mix center + left in one card.
- Use a grid for multi-item layouts —
grid grid-cols-2 gap-3(orgap-4), not floats or ad-hoc margins. Equal gaps everywhere; let the grid do alignment. - Group related, separate unrelated with whitespace + hairline dividers
(
border-t border-[var(--border)]), not boxes-within-boxes.
Spacing rhythm (4px scale)
Stick to a consistent scale so spacing feels deliberate: gap-2(8) gap-3(12)
gap-4(16); padding p-4/p-5 for cards, p-3 for compact rows. Pick ONE card
padding and one gap size per widget and reuse them. Avoid arbitrary mt-[7px].
Typography hierarchy
- Title of the widget content:
text-base font-semibold(ortext-lgfor a hero),var(--text-strong). - Body:
text-sm,var(--text). Captions/labels:text-xs,var(--muted). Big stat numbers:text-2xl/text-3xl font-semibold tabular-nums. - Max ~2 type sizes per card beyond the title. Use weight + color for hierarchy,
not many sizes.
tabular-numsfor any aligned numbers/tables.
Surface & depth
- Cards:
rounded-lg(orrounded-xlfor hero),bg-[var(--card)],border border-[var(--border)]. One elevation level — don't nest cards 3 deep. - Subtle, not heavy: prefer a hairline border + tint over big shadows.
Motion
- Use CSS
transition/@keyframes(no JS needed for most). Easingcubic-bezier(0.2,0,0,1)(orease-in-out); 150–300ms for UI transitions, 2–6s for ambient loops. Animateopacity/transformonly (cheap, smooth). - Reveal-on-load is fine once; avoid perpetual motion unless it's the point
(a live pulse/orbit). Always honor reduced-motion:
@media (prefers-reduced-motion: reduce){*{animation:none!important;transition:none!important}}
Theme variables — use these, never hardcoded colors
The iframe injects the active theme's palette as CSS custom properties. Style
everything with them (directly via style="…: var(--x)" or Tailwind
arbitrary values like bg-[var(--card)]) so the widget tracks the theme:
| Variable | Use for |
|---|---|
var(--bg) |
page / outermost background |
var(--text) |
default body text |
var(--card) / var(--card-fg) |
panel surface / text on it |
var(--border) |
hairlines, dividers, input borders |
var(--accent) / var(--accent-hover) |
primary actions, links, highlights |
var(--muted) / var(--muted-strong) |
secondary / tertiary text |
var(--text-strong) |
emphasized headings |
var(--bg-elevated) / var(--bg-hover) |
raised surfaces / hover states |
var(--border-strong) |
stronger separators |
var(--ok) / var(--warn) / var(--danger) / var(--info) |
status colors |
var(--accent-subtle) / var(--ok-subtle) / var(--warn-subtle) / var(--danger-subtle) |
tinted fills/badges |
Never use bg-gray-900, text-white, #fff, or any hardcoded hex — they
break on the opposite theme. Zero hardcoded colors.
Allowed scripts (CSP)
The iframe's Content-Security-Policy restricts script-src to inline scripts
plus these CDNs only:
- Tailwind —
https://cdn.tailwindcss.com(preloaded; classes work out of the box) https://cdn.jsdelivr.nethttps://cdnjs.cloudflare.com
Load charting/visualization libs (e.g. Chart.js) from jsDelivr or cdnjs. Scripts
from any other origin are blocked. connect-src is 'none' — widgets can't make
network calls; render data you already have.
Interactive widgets
Widgets send events back to the agent. Add data-action (and optional
data-payload, a JSON string) to any clickable element:
<button data-action="approve" data-payload='{"id":"123"}'>Approve</button>
On click, the dashboard auto-submits a user message: [UI] approve: {"id":"123"}.
You receive it as the next turn and can respond with text, a new widget, or both.
Forms: inputs with a name attribute are auto-collected on click and merged
into the payload as formData. Use this for creation forms — render pre-filled
inputs, the user adjusts values, clicks submit, and you receive every field:
<input name="title" value="Untitled" class="px-2.5 py-2 rounded-md"
style="background: var(--bg-elevated); color: var(--text); border: 1px solid var(--border);" />
<button data-action="create_task">Create</button>
Living views (auto-refresh). A widget can be a living dashboard that pulls fresh data on demand instead of freezing a snapshot at creation. Give it a refresh button:
<button data-action="refresh">Refresh</button>
When the widget has been saved as an artifact (it has a stable slug), the dashboard
appends (refresh artifact "<slug>" in place) to the [UI] refresh message it sends you.
On that turn: re-fetch the current data (call the tools/searches that produced it), then
artifact_update("<slug>", ...) with the freshly-rendered HTML — the SAME artifact
updates in place (versioned), so the open view re-renders with live data rather than
spawning a new artifact. This is how you build a "my open items" / "current status"
dashboard that stays current. (If the widget isn't a saved artifact yet, save it first so
it has a slug to refresh.)
Tunable parameters (EDITMODE) — let the user restyle without asking you
A widget can declare its own tunables. The dashboard turns them into typed controls beside the render, and dragging one restyles the widget instantly — no turn, no request, no cost to you. This is how a user gets "a bit more rounded, slightly warmer accent" without spending a message on it.
Declare them ONCE, as a marker-fenced JSON object inside the widget's own script:
<widget title="Sales">
<style>
#card { background: var(--card); border-radius: var(--radius); border: 1px solid var(--accent) }
</style>
<div id="card">…</div>
<script>
/*EDITMODE-BEGIN*/{
"radius": {"label": "Corners", "type": "range", "value": "12px",
"min": 0, "max": 32, "step": 2, "unit": "px"},
"accent": {"label": "Accent", "type": "color", "value": "#3b82f6"}
}/*EDITMODE-END*/
</script>
</widget>
-
Each key is a
:rootCSS custom property, minus the--."radius"drivesvar(--radius). Reference every tunable throughvar(--key)in your CSS — a value the stylesheet doesn't read is a control that appears to do nothing. -
The markers are exact:
/*EDITMODE-BEGIN*/…/*EDITMODE-END*/, one block per widget, JSON object between them. Put it inside a<script>so it never renders. -
≤ 8 parameters. More than eight means the widget should be using theme variables rather than inventing its own, and a rail nobody can scan. Extras are dropped, visibly.
-
Four types, each with the fields it needs:
typefields control colorvalue(#rrggbb)swatch + native picker rangevalue,min,max,step?,unit?slider selectvalue,options(≥2 CSS strings)dropdown togglevalue,on,off(CSS strings)switch -
Values are CSS strings and are validated: no semicolons, braces, quotes, or
url(). A descriptor that fails validation loses its control; the widget still renders. -
You author the block; the dashboard owns it afterwards. When the user saves their tweaks, the dashboard rewrites the
valuefields in place and cuts a new artifact version. Everything outside the markers is untouched, and your other fields survive. So when you REGENERATE a widget that already had tunables, keep the same keys and carry the current values across — otherwise you throw away choices the user already made.
Marked-up corrections you will receive
On a rendered widget the user can switch on Mark elements, click the parts that are wrong, and write one short note per element. You receive ONE turn:
[UI] correction: 2 elements marked — regenerate the artifact applying every change
below, and change nothing else
```corrections
1. selector: [data-testid="cta"]
within: section[id="hero"]
element: <button data-testid="cta">Buy</button>
change: make this green
2. selector: p.price
within: section[id="hero"]
element: <p class="price">$9</p>
change: bigger
```
Treat it literally: apply every listed change, change nothing else, and if the
widget is a saved artifact (the message ends with refresh artifact "<slug>" in place) write the result back to THAT slug with artifact_update. Giving elements
a data-testid makes these anchors stable and unambiguous — worth doing on the
handful of elements a user is likely to want changed.
Sizing conventions
- Buttons:
text-xs py-1.5 px-3.5 rounded-md - Labels:
text-[11px] - Inputs:
text-sm px-2.5 py-2 rounded-md
Links
Render bare URLs as anchors. Always open external links safely and style them with the accent color:
<a href="https://example.com" target="_blank" rel="noopener noreferrer"
style="color: var(--accent);">example.com</a>
Drawn visuals — SVG, diagrams, illustrations, animations
Drawn visuals are emitted inside a <widget> (same container, theme vars, and
CSP as above). The container is easy; the craft is making the drawing itself
centered, correctly proportioned, theme-aware, labelled, and legible rather
than cramped, clipped, or off-canvas.
The #1 failure is a fixed-size
<svg width="350" height="200">that renders tiny in a corner. Always make the SVG responsive and centered (below).
The responsive-SVG contract (use every time)
<widget title="…">
<div style="max-width: 640px; margin: 0 auto;">
<svg viewBox="0 0 640 360" width="100%" height="auto"
preserveAspectRatio="xMidYMid meet" role="img" aria-label="…describe it…"
style="display:block">
…
</svg>
</div>
</widget>
viewBoxdefines the coordinate space;width="100%"makes it scale. Never set a fixed pixelwidth/heighton the<svg>— it won't be responsive.preserveAspectRatio="xMidYMid meet"centers + fits without distortion.display:block+margin:0 autoon amax-widthwrapper centers it and caps it so it doesn't sprawl edge-to-edge in a wide chat.- Pick a viewBox aspect that fits the content: 16:9 (
640 360) for scenes, 1:1 (400 400) for cycles/radial, 3:1 (720 240) for timelines/flows. - Leave internal padding — keep real content within ~6–8% of each edge so strokes and labels never touch the frame.
Theme-aware drawing — no hardcoded colors
Style strokes/fills with the theme vars (injected into the iframe, same as above):
- structural lines / axes / grids →
var(--border)(thin, 0.5–1px) - primary subject / data →
var(--accent) - secondary / supporting →
var(--muted) - emphasis / alert →
var(--danger); positive →var(--ok) - text labels →
var(--text), secondary labels →var(--muted) - filled regions →
var(--accent-subtle)/ tinted fills, never opaque black/white
Put shared style in one <style> block with classes (.axis{stroke:var(--border)})
rather than repeating stroke= on every element — easier to keep consistent.
Alignment & composition
- Establish a grid mentally: align elements to consistent x/y coordinates; don't eyeball. Equal gaps read as intentional; ragged gaps read as broken.
- Center the focal point in the viewBox; balance mass around it.
- Label directly where possible (label next to the thing) over distant legends; when a legend is needed, align it to a consistent edge with even rows.
- Text:
font: 14px/1.4 -apple-system, sans-serif;for body labels, ~12px for captions; usetext-anchor="middle"for centered labels under a node anddominant-baseline="middle"for vertical centering. Never rely on the default baseline for centered text. - Round coordinates to whole/half pixels for crisp strokes.
Animating a drawing
- Prefer CSS animations / transitions (in the
<style>block) or SMIL (<animate>,<animateTransform>) — both run in the sandbox without extra libs. - Easing + duration: ease-in-out, 200–600ms for transitions, 2–6s loops for ambient motion. Avoid linear unless it's a steady cycle (rotation, orbit).
- Loop with intent:
animation-iteration-count: infiniteonly for genuinely ambient visuals (waves, pulses, orbits). One-shot reveals should play once. - Layer rhythms: when animating multiple elements, offset their delays/durations slightly so motion feels organic, not mechanically synchronized.
- Respect reduced-motion (same media query as the card motion section above).
- Keep it subtle — motion should clarify (show flow, change, cause→effect), not distract. If the still image already communicates, don't animate.
Charts
- For data charts prefer Chart.js (load from jsDelivr — see CSP above) over
hand-drawn SVG bars; pass theme-var colors into the dataset config so it tracks
the theme. Give the canvas a fixed-aspect wrapper (
position:relative; height:0; padding-bottom:56.25%) so it's responsive. - Always title the axes + the chart; never render a chart with unlabelled axes.
Cost discipline
Prefer plain markdown by default. Promote to a widget only when styled HTML communicates clearly better — charts, color-coded tables, styled cards, visual summaries, diagrams, or simple interactive tools. Don't wrap a paragraph in a widget.
The dashboard's widget_density setting (more / less, default more)
signals how freely to reach for widgets; on less, use them only when markdown
is plainly insufficient.
Quality checklist (before emitting)
- Width capped + centered (
max-w-* mx-auto, ormax-widthwrapper for SVG) — not sprawling full-width? - Consistent spacing — one card padding + one gap size, on the 4px scale?
- Type hierarchy — clear title vs body vs caption via size/weight/color, ≤2
extra sizes? Numbers
tabular-nums? - Aligned — multi-item layouts on a grid with equal gaps, one alignment spine?
- Zero hardcoded colors — every color a theme var, looks right light + dark?
- One elevation — no cards nested 3 deep; hairline borders over heavy shadows?
- Motion (if any) — eased, 150–300ms (or 2–6s ambient), purposeful, reduced-motion-safe?
- Drawing a figure? Responsive
viewBox+width="100%"(no fixed px), centered, content inside the frame with breathing room, labels legible and correctly centered? Reads clearly at half size on both themes?
04 同仓库更多 Skills
web-verify
Verify a built web page or app actually renders and works — drive it in a real browser, check the console and network, confirm the thing you changed is the thing being served, and capture evidence. Use before claiming a frontend change works.
task-and-project
Track work as Tasks (the /api/tasks CRUD + native task provider), and decompose larger projects into independent, verifiable units — fanning parallel investigation out to subagents while keeping one coherent plan; hand open-ended goal-driven work to a goal loop.
research-campaign
Run a multi-cycle research campaign — grill the question, decompose it into answerable sub-questions, investigate each against sources, then synthesize with confidence and gaps stated. Use for open questions that need real investigation rather than one lookup.
memory-discipline
When and how to persist durable memory — save genuine user preferences, facts, and corrections; NEVER persist transient environment failures (a failed command, a flaky network call, a one-off tool error) as lessons; recall before re-asking.
loop-worker
Per-cycle protocol for an autonomous goal loop worker — the unified autonomous goal engine that runs one self-directed cycle per turn until its goal is met, then self-retires. Drives one cycle against a loop's file interface (status.json gate, brief.md goal, guidance.txt nudges, findings/cycle_NNN.json, FINDINGS.md, the type-appropriate deliverable, STOP sentinel). The worker produces work and reports evidence; a deterministic check or a separate judge — never the worker — decides done-ness.
knowledge-grounding
Search the knowledge pool before answering, ground claims in retrieved sources and cite them, recognize ingest-worthy content and capture it with knowledge_create — don't fabricate when the answer is on record.