Earlier formats

Prompting your agent

What to tell a coding agent so it writes good ui artifacts the first time.

Start with the formats guideLink to this section

The server carries its own manual. artifacts_formats_guide with kind: "ui" returns the rules, every component with its props (generated from the same catalog as the component pages), and a complete example. An agent that reads it first gets the format right far more often. Ask for it by name:

artifacts_formats_guide · first linesmarkdown
# ui artifacts (component set version 1)

A ui artifact is a json-render spec rendered with the artifacts.space component set. Pages are read-only to the world: inputs only change on-page state.

This is an earlier format, kept for the artifacts that use it. For a new mockup, dashboard, or report, prefer kind "html", a full web page. Call artifacts_formats_guide with kind "html" for its rules. Use this guide to read or change a ui artifact that exists, or a frame of a canvas.

## Rules

1. Submit ONE JSON object as the artifact content (not JSONL, not Markdown, no code fences): { "version": 1, "root": "<key>", "elements": { "<key>": { "type", "props", "children" } }, "state": { … } }.
2. Always set "version": 1.
3. `elements` is a flat map. `children` lists child keys in order; leaves may omit it. Each element has exactly one parent, and the root has none.
4. Only use components from the list. Props are strict: strings and arrays have maximum sizes, and unknown props are ignored. Omit optional props instead of sending null.
…

A prompt that worksLink to this section

Say what the page is for, which data goes where, and ask for validation. A prompt like this one works well:

Prompttext
Make a ui artifact on artifacts.space for the Q3 reliability review.

1. Call artifacts_formats_guide with kind "ui" and follow it.
2. Use the incident data below. Lead with three Metrics (incidents,
   minutes down, mean time to recover) with change against Q2.
3. Add a stacked bar Chart of incidents per month by severity, and a
   Table of the five longest incidents.
4. Put the action items in a Checklist and the open risks in a Callout.
5. Keep it on one screen at a glance: Section, then a Grid of metrics.
6. Run artifacts_validate and fix every error before you save.
7. Save it with project "reliability" and summary in one sentence.

<paste the data here>

To make it a habit in a repository, add a few lines to AGENTS.md or CLAUDE.md:

AGENTS.mdmarkdown
## artifacts.space
- Save plans, decisions, and reports as artifacts. Search with
  artifacts_list before you create one; update instead of duplicating.
- For dashboards and reports, use kind "ui": read
  artifacts_formats_guide (kind "ui") first, and run
  artifacts_validate before every save.
- Set project to the repository name and sessionId to this session.

Good habitsLink to this section

  • Lead with the answer. Metrics and a one-line Callout at the top; detail in Tabs or an Accordion below.
  • Pick the component that fits the data. Table for rows (up to 500), Chart for trends, KeyValue for settings, Steps for runbooks, Board for status, Calendar for dates.
  • Use formats, not strings. Send numbers with format and currency instead of "$1.2M" text, so axes, tables, and the data view stay exact.
  • Use short, readable keys such as kpi-revenue. Validation messages name them.
  • Pick a theme for the reader. Pass a preset id as theme, such as editorial for a long report or ink for the most contrast. Charts, badges, and tables take the theme's colors with no change to the spec. See Themes.
  • Validate, then save. artifacts_validate reports every problem at once; fix them all in one pass.
  • Update, do not duplicate. Save a new version of the same artifact with artifacts_update; its link stays the same and history keeps every version.
  • Mind the limits. Split very large data into several artifacts, or summarize it. See Spec limits.

Ideas to tryLink to this section

  • A pull request review: KeyValue for the change summary, a Table of findings with severity badges, and Steps to reproduce.
  • An incident report: a Timeline of events, Metrics for impact, and a Checklist of follow-ups.
  • A migration plan: Steps with the commands, a Progress bar per phase, and a Callout for the rollback.
  • A weekly status page: a Board of work by stage and a Calendar of the next two weeks.
  • A benchmark: a scatter Chart of latency against payload, and a Table of the raw runs.

Try a prompt's output

Paste a spec your agent wrote into the playground to see it and its validation report side by side.