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#

TypeBest forDashboardKPI metrics, data tables, timelines, progress bars, badges, iconsCalendarRead-only month views with highlighted dates and event detailChartBar charts with multi-series comparisonsDonutProgress rings, savings goals, category breakdowns

API workflow#

1. Fetch capabilities — discover supported protocol versions and component catalogs.
2. Build payload — assemble an A2UI JSON bundle targeting the live contract values.
3. Validate — confirm the payload is well-formed before creating.
4. Create — publish the bundle and receive the share link.

Endpoints#

Base URL: https://api.guiro.io

ActionMethodPathCapabilitiesGET/v1/create/capabilitiesValidatePOST/v1/validateCreatePOST/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#

bash

# 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:

json

{
  "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#

ComponentPropsDescriptionCardchild (string id)Container card; use as the root wrapperColumnchildren (string id[]), gap ( sm | md | lg)Vertical stackRowchildren (string id[]), gap ( sm | md | lg)Horizontal stackListchildren (string id[])Ordered list

Content#

ComponentPropsDescriptionTexttext, variant ( h1 | h2 | body), tone ( muted)Heading or paragraphBadgelabel, variant ( secondary | outline | success), size ( sm)Status badge or tagIconname or icon, size, strokeWidth, color, labelLucide icon accent for headers, callouts, and status cuesProgressIndicatorvalue (number), max (number)Progress barDataTablecolumns ( {key, header}[]), data (object[])Tabular dataCalendartitle, description, month (YYYY-MM-DD), selected (YYYY-MM-DD), selectionMode ( single), events ( {date, label, detail, tone}[])Read-only calendar with highlighted days and details belowCharttitle, description, chartType ( bar | donut), xKey, series ( {key, label}[]), data (object[]), valueFormat ( currency), currency (ISO code)Bar or donut chart

Component tree example#

json

[
  { "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:

json

{ "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:

json

{
  "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.