AGENT SKILL

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 artifacts skill) 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) with mx-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 (or gap-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 (or text-lg for 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-nums for any aligned numbers/tables.

Surface & depth

  • Cards: rounded-lg (or rounded-xl for 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). Easing cubic-bezier(0.2,0,0,1) (or ease-in-out); 150–300ms for UI transitions, 2–6s for ambient loops. Animate opacity/transform only (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.net
  • https://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 :root CSS custom property, minus the --. "radius" drives var(--radius). Reference every tunable through var(--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:

    type fields control
    color value (#rrggbb) swatch + native picker
    range value, min, max, step?, unit? slider
    select value, options (≥2 CSS strings) dropdown
    toggle value, 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 value fields 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>
  • viewBox defines the coordinate space; width="100%" makes it scale. Never set a fixed pixel width/height on the <svg> — it won't be responsive.
  • preserveAspectRatio="xMidYMid meet" centers + fits without distortion.
  • display:block + margin:0 auto on a max-width wrapper 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; use text-anchor="middle" for centered labels under a node and dominant-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: infinite only 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)

  1. Width capped + centered (max-w-* mx-auto, or max-width wrapper for SVG) — not sprawling full-width?
  2. Consistent spacing — one card padding + one gap size, on the 4px scale?
  3. Type hierarchy — clear title vs body vs caption via size/weight/color, ≤2 extra sizes? Numbers tabular-nums?
  4. Aligned — multi-item layouts on a grid with equal gaps, one alignment spine?
  5. Zero hardcoded colors — every color a theme var, looks right light + dark?
  6. One elevation — no cards nested 3 deep; hairline borders over heavy shadows?
  7. Motion (if any) — eased, 150–300ms (or 2–6s ambient), purposeful, reduced-motion-safe?
  8. 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

Sidiora-Labs
Sidiora-Labs/centra-gideon-agent

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.

★ 212
Sidiora-Labs
Sidiora-Labs/centra-gideon-agent

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.

★ 212
Sidiora-Labs
Sidiora-Labs/centra-gideon-agent

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.

★ 212
Sidiora-Labs
Sidiora-Labs/centra-gideon-agent

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.

★ 212
Sidiora-Labs
Sidiora-Labs/centra-gideon-agent

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.

★ 212
Sidiora-Labs
Sidiora-Labs/centra-gideon-agent

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.

★ 212