Guiro – Shareable Visual Snapshots
Guiro (https://guiro.io) is an ephemeral Presentation Layer as a Service. You give it a structured JSON bundle describing a layout of visual components, and it returns a short-lived, publicly accessible share link (e.g. https://guiro.io/s/{slug}). The rendered page is a polished, read-only visual — a dashboard, report, chart, calendar, or status page. No login or account is needed to view it.
Use this skill whenever you produce structured results — metrics, tables, timelines, financial data, event schedules, progress tracking — and want to turn them into a shareable visual artifact the user can open in a browser, send to a colleague, or print to PDF.
What you can build
| Type | Best for |
|---|
| Dashboard | KPI metrics, data tables, timelines, progress bars, badges, icons |
| Calendar | Read-only month views with highlighted dates and event detail |
| Chart | Bar charts with multi-series comparisons |
| Donut | Progress rings, savings goals, category breakdowns |
API workflow
- Fetch capabilities — discover supported protocol versions and component catalogs.
- Build payload — assemble an A2UI JSON bundle targeting the live contract values.
- Validate — confirm the payload is well-formed before creating.
- Create — publish the bundle and receive the share link.
Endpoints
Base URL: https://api.guiro.io
| Action | Method | Path |
|---|
| Capabilities | GET | /v1/create/capabilities |
| Validate | POST | /v1/validate |
| Create | POST | /v1/create |
Authentication
All requests require an API key via the X-API-Key header. The key is read from the GUIRO_API_KEY environment variable. If the key is missing, ask the user to provide one.
Commands
# 1 – Fetch capabilities (saves to .guiro/runtime-capabilities.json)
bash "{baseDir}/scripts/fetch-capabilities.sh"
# 2 – Write a sample payload (dashboard | calendar | chart | donut)
bash "{baseDir}/scripts/write-sample-payload.sh" ./payload.json dashboard
# 3 – Validate and create the guiro
bash "{baseDir}/scripts/create-guiro.sh" --payload ./payload.json --idempotency-key run-001
The sample payloads are starting points. Replace the placeholder content with real data relevant to the user's request.
Payload structure
A valid A2UI bundle has this shape:
{
"storage_version": "1",
"a2ui_version": "0.9",
"catalog_id": "guiro.shadcn.detached.v1",
"theme": {
"primary": "#0f766e",
"secondary": "#0f172a"
},
"messages": [
{
"version": "v0.9",
"createSurface": {
"surfaceId": "share-main",
"catalogId": "guiro.shadcn.detached.v1"
}
},
{
"version": "v0.9",
"updateComponents": {
"surfaceId": "share-main",
"components": [ ... ]
}
}
]
}
storage_version, a2ui_version, catalog_id — use values from the capabilities response.messages must contain one createSurface message and one updateComponents message.- Target exactly one surface.
Component reference
The components array is a flat list of component objects. Each has an id (unique string) and a component type. Parent components reference children by id. The tree must include a component with id: "root".
Layout
| Component | Props | Description |
|---|
| Card | child (string id) | Container card; use as the root wrapper |
| Column | children (string id[]), gap (sm|md|lg) | Vertical stack |
| Row | children (string id[]), gap (sm|md|lg) | Horizontal stack |
| List | children (string id[]) | Ordered list |
Content
| Component | Props | Description |
|---|
| Text | text, variant (h1|h2|body), tone (muted) | Heading or paragraph |
| Badge | label, variant (secondary|outline|success), size (sm) | Status badge or tag |
| Icon | name or icon, size, strokeWidth, color, label | Lucide icon accent for headers, callouts, and status cues |
| ProgressIndicator | value (number), max (number) | Progress bar |
| DataTable | columns ({key, header}[]), data (object[]) | Tabular data |
| Calendar | title, description, month (YYYY-MM-DD), selected (YYYY-MM-DD), selectionMode (single), events ({date, label, detail, tone}[]) | Read-only calendar with highlighted days and details below |
| Chart | title, description, chartType (bar|donut), xKey, series ({key, label}[]), data (object[]), valueFormat (currency), currency (ISO code) | Bar or donut chart |
Component tree example
[
{ "id": "root", "component": "Card", "child": "page" },
{ "id": "page", "component": "Column", "gap": "lg", "children": ["heading", "metrics"] },
{ "id": "heading", "component": "Text", "text": "Monthly Report", "variant": "h1" },
{ "id": "metrics", "component": "Row", "gap": "md", "children": ["badge1", "progress1"] },
{ "id": "badge1", "component": "Badge", "label": "Active: 42", "variant": "outline" },
{ "id": "progress1", "component": "ProgressIndicator", "value": 75, "max": 100 }
]
Theme
Colors accept hex (#0f766e) or oklch (oklch(0.527 0.154 150.069)) values:
{ "primary": "#0f766e", "secondary": "#0f172a" }
Choose theme colors that suit the content. Use contrasting primary and secondary values.
Rules
- Always fetch capabilities first and use the returned values for
storage_version, a2ui_version, and catalog_id.
- Always validate before create.
- The bundle must target exactly one surface.
- The
updateComponents array must include a component with id: "root".
- Treat validation errors as authoritative — fix the payload and re-validate until it passes.
- Use the sample payloads as structural templates but replace all placeholder content with real data from the user's request.
- Prefer
Icon for section headers, callouts, and status accents when it improves scanability.
Output
Successful create returns:
{
"slug": "abc123",
"url": "https://guiro.io/s/abc123",
"expires_at": "2025-07-15T12:00:00Z"
}
Share the url with the user. Guiros are ephemeral — after expires_at, the link shows a standardized "This Guiro has Expired" page.
