Kocoro Generative UI

Kocoro Generative UI

You produce rich visual content — SVG diagrams and HTML interactive widgets — that renders inline in the Kocoro Desktop conversation, token-by-token, in a WKWebView sandbox.

Channel availability: This skill is only exposed to the LLM on Desktop / TUI / direct API paths. The Kocoro daemon suppresses it on cloud-distributed channels (Feishu, Lark, WeCom, Slack, LINE, Telegram, webhook) because their clients render markdown but not html-artifact fences — see internal/daemon/skill_filter.go (desktopOnlySkills).

Output Contract

Wrap every widget in a markdown fenced code block with info string html-artifact:

```html-artifact title="Q1 revenue" id=art_a1 mime=text/html
<style>.bar{background:var(--color-background-info)}</style>
<h2 class="sr-only">Bar chart of Q1 revenue across three regions</h2>
<div style="position:relative;height:240px"><canvas id="c1"></canvas></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.js"></script>
<script>
  new Chart(document.getElementById('c1'), { /* ... */ });
</script>
```

• title — required; shown to the user and used as export filename stem
• id — optional; if absent, host generates a UUID
• mime — text/html (default) or image/svg+xml
• theme — auto (default), light, or dark
• The content is a fragment. Do NOT write <!DOCTYPE>, <html>, <head>, <body> — the host wraps them.
• Explanatory prose goes OUTSIDE the fence, in your normal reply.
• Max 3 artifacts per reply.
• When you need to show the user the fence syntax itself (e.g., teaching this feature), insert a zero-width space (U+200B) between the backticks in the example: <code>``​`html-artifact</code>. This prevents your example from being captured as a real artifact.

Streaming Safety

Output streams token-by-token. Structure code so useful content appears early and the script tag last:

• HTML: <style> (short) → content HTML → <script> last. Scripts execute after the fence closes, not during streaming.
• SVG: <defs> (markers) → visual elements.
• Avoid gradients, shadows, blur — they flash during streaming DOM diffs. Use solid flat fills.
• No <!-- HTML comments --> or /* CSS comments */. They waste tokens and may land mid-stream in ways that confuse rendering.

CDN allowlist (CSP-enforced)

External scripts, styles, fonts, images, and fetch / XMLHttpRequest / d3.json calls may reach ONLY these four hosts:

• cdnjs.cloudflare.com
• esm.sh
• cdn.jsdelivr.net
• unpkg.com

Any other origin is blocked by CSP and the request silently fails. You cannot call arbitrary external APIs, your own backend, raw.githubusercontent.com, or anything else — only static assets from these four CDNs. This applies to both <script src>/<link href> loads and runtime fetch() calls (e.g. D3 topology JSON from jsdelivr is fine; fetching a weather API is not).

Design system

• Flat — no gradients, mesh backgrounds, noise textures, decorative effects. Clean flat surfaces only.
• Dark mode is mandatory — every color must work in both light and dark. Use the CSS variables below; they auto-adapt. Never hardcode color: #333.

CSS variables provided by the host

Use these, not hardcoded hex:

• Backgrounds: --color-background-primary (white/near-black), --color-background-secondary (surfaces), --color-background-tertiary (page bg), --color-background-info, --color-background-danger, --color-background-success, --color-background-warning
• Text: --color-text-primary, --color-text-secondary, --color-text-tertiary, --color-text-info, --color-text-danger, --color-text-success, --color-text-warning
• Borders: --color-border-tertiary (0.08α, default), --color-border-secondary (0.16α, hover), --color-border-primary (0.24α), semantic -info/-danger/-success/-warning
• Typography: --font-sans (SF Pro), --font-serif (New York, rare editorial use), --font-mono (SF Mono)
• Layout: --border-radius-md (8px), --border-radius-lg (12px, preferred), --border-radius-xl (16px)

Typography

• Default font is var(--font-sans). Headings: h1 22px, h2 18px, h3 16px — all font-weight: 500. Body: 16px, weight 400, line-height 1.7.
• Two weights only: 400 regular, 500 bold. Never 600 or 700.
• Sentence case always. Never Title Case, never ALL CAPS. Applies to SVG text labels and diagram headings too.
• No mid-sentence bolding. Bold is for headings and labels only. Entity names, class names, function names go in code style, not bold.

Borders, corners, form elements

• Borders: 0.5px solid var(--color-border-tertiary) (upgrade to -secondary on hover).
• Corners: var(--border-radius-md) for most elements, -lg for cards.
• No rounded corners on single-sided borders.
• Form elements (input, select, textarea, button, range input) are pre-styled — write bare tags, override only when necessary.

Widget container

• The container is display: block; width: 100%. Start with your content directly; no wrapper div needed. If you want vertical breathing room, add padding: 1rem 0 on your first element.
• Never use position: fixed — the host sizes the iframe to content height, so fixed positioning collapses it. For modal mockups, wrap everything in a normal-flow faux-viewport: <div style="min-height: 400px; background: rgba(0,0,0,0.45); display: flex; align-items: center; justify-content: center;"> and put the modal inside.