Earlier formats

JSON Render

How ui and canvas artifacts work: one JSON spec on the stout component set, rendered the same for every reader. Earlier formats, kept for the artifacts that use them.

An earlier format

For a new mockup, prototype, dashboard, or report, write an HTML page: a full web page that looks and behaves as you wrote it. The ui and canvas formats on these pages are kept for the artifacts that use them, and still work as described here.

How it worksLink to this section

A ui artifact is a json-render spec: one JSON object that names components and their props. artifacts.space renders it with its own component set, called stout, built on the same primitives as the rest of the site. The renderer is @json-render/core and @json-render/react 0.21.1.

  1. The agent reads the component guide with artifacts_formats_guide (kind: "ui").
  2. It writes a spec and checks it with artifacts_validate. Every problem comes back at once, with the element key and the fix.
  3. It saves the spec with artifacts_create or artifacts_update. The server runs the same validation and refuses a spec with errors.
  4. Readers see a page in the artifacts.space look, or in the artifact's own theme, in light or dark, on any screen.

Agent code never runs on the page. A spec is data: no scripts, no CSS, no network calls. Inputs such as Switch and Slider change only the page's own state, and nothing is saved or sent.

Spec anatomyLink to this section

Every spec has the same four top-level fields.

versionLink to this section

The component-set version the spec was written for. Always "version": 1 today. Leaving it out is a warning; any other number is an error. When the component set changes in a way that alters existing props, the version goes up and older specs are migrated on read, so a saved page keeps its meaning.

root and elementsLink to this section

elements is a flat map from a key you choose to one element. root names the top element. Each element has a type (a component name), props, and optionally children, visible, repeat, and on. Keys are up to 100 characters; short, readable keys such as kpi-revenue make validation messages easy to follow.

One elementjson
{
  "kpi-revenue": {
    "type": "Metric",
    "props": { "label": "Revenue", "value": 1284000, "format": "currency" },
    "children": [],
    "visible": { "$state": "/showMoney" }
  }
}

childrenLink to this section

children lists child keys in order. Nesting comes from keys, not from nested objects, so a deep layout stays a flat, easy-to-edit list. Each element has exactly one parent, and the root has none. Only layout components (Section, Stack, Grid, Card, Tabs, Accordion) show children; a leaf with children gets a warning.

childrenjson
{
  "page": {
    "type": "Stack",
    "props": { "gap": "lg" },
    "children": ["title", "kpis"]
  },
  "kpis": {
    "type": "Grid",
    "props": { "columns": 3 },
    "children": ["kpi-revenue", "kpi-churn", "kpi-nps"]
  }
}

stateLink to this section

state is the page's starting data: any JSON object. Props read it with $state, inputs write it with $bindState, and repeat renders a list from an array in it. State lives in the reader's browser and resets on reload. See Dynamic props and actions.

statejson
{
  "state": {
    "showMoney": true,
    "filters": { "team": "Platform" },
    "services": [{ "name": "api" }]
  }
}

A minimal specLink to this section

The smallest useful spec: a Stack with a heading and a paragraph.

Hello, artifacts

Hello, artifacts

This page is one JSON object: a root key and a flat map of elements.

Show JSON
{
  "version": 1,
  "root": "page",
  "elements": {
    "page": {
      "type": "Stack",
      "props": { "gap": "md" },
      "children": ["title", "body"]
    },
    "title": {
      "type": "Heading",
      "props": { "text": "Hello, artifacts", "level": 1 }
    },
    "body": {
      "type": "Text",
      "props": {
        "text": "This page is one JSON object: a root key and a flat map of elements."
      }
    }
  }
}

A full dashboardLink to this section

Metrics with sparklines, a stacked bar chart and a table in tabs, and a toggle that shows a callout. Copy the JSON, change the numbers, and it is yours.

Weekly delivery dashboard

Switch tabs and flip the toggle: inputs change on-page state only.

Delivery, week 45

Deploys, failures, and lead time across all services.

Deploys

128

+14%

Change failure rate

3.1%

-0.8%

Lead time

5.2h

-1.1 h

Deploys per day
  • Succeeded
  • Failed
LabelSucceededFailedTotal
Mon12012
Tue17118
Wed20121
Thu16117
Fri23124
Sat18119
Sun16117
Show JSON
{
  "version": 1,
  "root": "page",
  "elements": {
    "page": {
      "type": "Section",
      "props": {
        "title": "Delivery, week 45",
        "description": "Deploys, failures, and lead time across all services."
      },
      "children": ["kpis", "tabs", "risk-toggle", "risks"]
    },
    "kpis": {
      "type": "Grid",
      "props": { "columns": 3 },
      "children": ["kpi-deploys", "kpi-failure", "kpi-lead"]
    },
    "kpi-deploys": {
      "type": "Metric",
      "props": {
        "label": "Deploys",
        "value": 128,
        "change": 14,
        "changeFormat": "percent",
        "goodDirection": "up",
        "sparkline": [12, 18, 21, 17, 24, 19, 17]
      }
    },
    "kpi-failure": {
      "type": "Metric",
      "props": {
        "label": "Change failure rate",
        "value": 3.1,
        "format": "percent",
        "change": -0.8,
        "goodDirection": "down"
      }
    },
    "kpi-lead": {
      "type": "Metric",
      "props": {
        "label": "Lead time",
        "value": 5.2,
        "unit": "h",
        "change": -1.1,
        "goodDirection": "down"
      }
    },
    "tabs": {
      "type": "Tabs",
      "props": { "tabs": [{ "label": "Trend" }, { "label": "Failures" }] },
      "children": ["trend", "failures"]
    },
    "trend": {
      "type": "Chart",
      "props": {
        "type": "bar",
        "stacked": true,
        "title": "Deploys per day",
        "labels": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
        "series": [
          {
            "name": "Succeeded",
            "values": [12, 17, 20, 16, 23, 18, 16]
          },
          { "name": "Failed", "values": [0, 1, 1, 1, 1, 1, 1] }
        ]
      }
    },
    "failures": {
      "type": "Table",
      "props": {
        "columns": [
          { "key": "service", "label": "Service" },
          { "key": "when", "label": "When" },
          { "key": "cause", "label": "Cause" },
          {
            "key": "minutes",
            "label": "Minutes down",
            "align": "right",
            "format": "number"
          }
        ],
        "rows": [
          {
            "service": "api",
            "when": "Tue 14:02",
            "cause": "Migration lock timeout",
            "minutes": 6
          },
          {
            "service": "web",
            "when": "Thu 09:40",
            "cause": "Missing env var",
            "minutes": 2
          },
          {
            "service": "worker",
            "when": "Sat 22:15",
            "cause": "Queue backlog",
            "minutes": 11
          }
        ]
      }
    },
    "risk-toggle": {
      "type": "Switch",
      "props": {
        "label": "Show open risks",
        "checked": { "$bindState": "/showRisks" }
      }
    },
    "risks": {
      "type": "Callout",
      "props": {
        "tone": "warning",
        "title": "Open risks",
        "text": "The worker queue backs up on Saturdays. Add a second consumer before the holiday traffic."
      },
      "visible": { "$state": "/showRisks" }
    }
  },
  "state": { "showRisks": false }
}

Try it live

Open the playground to edit this dashboard and watch it re-render as you type.

The component setLink to this section

The stout set has 43 components in six groups. Each page shows live examples and a props table generated from the schema the server checks against.

Layout

Arrange other elements. Only these components show their children.

SectionStackGridCardTabsAccordionSeparatorBox

Content

Headings, text, Markdown, code, links, and icons.

HeadingTextMarkdownCodeCalloutBadgeListStepsLinkQuoteIconAvatarAvatarGroupKbdRating

Data

Tables, numbers, charts, and diagrams.

TableMetricChartKeyValueProgressTimelineDiagram

Planning

Read-only boards and calendars.

BoardCalendar

Inputs

Controls that change on-page state only.

ChecklistCheckboxSelectSwitchSliderButtonInputTextarea

Media

Uploaded images and files, by id, and stand-ins for a mockup.

ImageFilePlaceholder

Canvases: boards of screensLink to this section

A canvas artifact is a board of frames that show screens of websites and apps. Each frame is one screen at a width you choose, and its spec is a ui spec, so every component and rule on these pages works inside a frame. Readers drag to move the board, zoom in to read a frame, and open the board full screen to give it the whole window; on a phone the frames stack in the page, each scaled to fit. No HTML or CSS is involved, and each frame keeps its own state.

Frame fieldRequiredWhat it does
idYesA short, unique name: up to 40 lowercase letters, digits, and hyphens. Keep it when you change the frame.
nameYesWhat people see above the frame, up to 80 characters.
widthYesThe frame's width in CSS pixels, 240 to 2,560. Usual sizes: 1440 (desktop), 768 (tablet), 390 (phone).
heightNoThe least height, 120 to 10,000. Left out, the frame is as tall as its content. Longer content makes the frame taller and is never cut off.
paddingNoThe space between the frame's edge and its content: none, sm, md (the default), or lg.
x, yNoThe frame's top-left corner on the board. Left out, frames sit in one row in the order listed, 80 pixels apart.
specYesThe frame's ui spec: version, root, elements, and state.
A canvas with one page at two sizesjson
{
  "version": 1,
  "frames": [
    {
      "id": "home-desktop",
      "name": "Home, desktop",
      "width": 1440,
      "spec": {
        "version": 1,
        "root": "page",
        "elements": {
          "page": {
            "type": "Grid",
            "props": { "columns": 3 },
            "children": ["…"]
          }
        }
      }
    },
    {
      "id": "home-phone",
      "name": "Home, phone",
      "width": 390,
      "height": 844,
      "spec": {
        "version": 1,
        "root": "page",
        "elements": { "page": { "type": "Stack", "props": {}, "children": ["…"] } }
      }
    }
  ]
}

To show one screen at several sizes, add one frame per size and lay each out for its width. A canvas holds up to 24 frames and 3,000 elements across them, and each frame keeps the ui limits. The agent reads the rules with artifacts_formats_guide (kind: "canvas") and checks a canvas with artifacts_validate: each issue names the frame, then the element, and the fix. A frame with a problem shows a notice in its place, and the other frames still render. To change one screen later, the agent uses the frame tools (canvas_frames_list, canvas_frame_get, canvas_frame_save, canvas_frame_update, canvas_frame_delete): it reads and sends one frame, never the whole board. An agent that can edit the canvas can also see a frame, with canvas_frame_image: the picture is drawn by the browser of someone who may edit the canvas when they open it, so the agent sees what that person sees.