Tawa Artifact — build and edit portal pages section by section

About

Human explainer: https://portal.insureco.io/spaces/iec-portal/pages/walkthrough-maker Styling rules: https://brand.insureco.io/artifact-spec.md

Skill Content

This is the raw markdown that gets installed as a Claude Code command.

---
description: Build or edit a portal artifact page (designed HTML — report, plan, dashboard, one-pager, product explainer) through jci-mcp without reading or resending the whole document. Use when asked to make, update, fix or restyle an artifact / HTML page in the portal, or for the "Walkthrough Maker" flow. Not for screenshot walkthroughs of a service (that is /tawa-walkthrough) or for forms that collect answers (create_form).
---

# Tawa Artifact — build and edit portal pages section by section

Human explainer: https://portal.insureco.io/spaces/iec-portal/pages/walkthrough-maker
Styling rules: https://brand.insureco.io/artifact-spec.md

**Argument:** what to make or change, and which project/page.

## The one rule

Never pull or push the whole document when a section will do. `read_page` returns an **outline**
by default (`version`, `outline.blocks: [{id, tag, heading, preview}]`). Work from that.

## New page

1. `list_artifact_kits` — pick the kit for the page's job, and note its `blocks` snippets:
   - `document` (default): a report, brief, plan or spec, read top to bottom
   - `reference`: a runbook or API reference that people look things up in (endpoints, params, code)
   - `decision`: a choice. Verdict first, then options, comparison and trade-offs
   - `dashboard`: KPIs and charts someone scans
   - `app`: something operated, like a queue, tracker or calculator (toolbar, form controls, table,
     states). Open it with example rows marked as example data
   - `landing`: a product page, launch page or HypeSite
   - `explainer`: who uses a product, what each of them sees, and what one real example earns or
     costs them. Use it for "explain the product", user-story and overview pages. See
     [Product explainer](#product-explainer) below
   - `deck`, `one-pager`, `letter`: slides, one printed sheet, correspondence

   The shared blocks (`stat-row`, `comparison`, `timeline`, `checklist`, `faq`, `tabs`, `code`,
   `diagram`, …) work in every kit. Draw diagrams with the `diagram` block, never ASCII art in
   `<pre>`.
2. `find_pages` in the project — revise an existing page rather than duplicating it.
3. `create_page({ project, title, type: "artifact", kit, pageKey })` with **no content**. The portal
   writes the styled starter. (Sending `content` too makes the kit ignored, with a warning.)
4. `read_page` → outline. Add sections with `update_page({ blockOps, expectedVersion })`, filling in
   the kit's snippets. Colour only via kit CSS variables, never hex. For a `document`, the order is
   `title` block, then (for five or more sections) the `toc` block, then one `section` per topic with
   an `id` the TOC links to. All three go inside `<main class="iec-doc">`. Don't add an
   `.iec-doc-layout` wrapper: the TOC becomes a sidebar on its own, and the wrapper would take the
   header and TOC out of reach of `blockOps`. Tables go in `.iec-table-wrap` directly in a section,
   which lets them grow past the prose width.
5. Publish (`status: "published"`) only when asked.

## Design style

A kit is the shape of the page; a **design style** is its look (colours, type, radius). A product
with its own identity has a style in the portal's design list. `list_design_styles` shows them;
pass `style: "<slug>"` with `kit` on `create_page`, and the starter links it. PolicyOS is
`policyos-signal`. Never put InsurEco's look on a product that has its own (PolicyOS: no Exo 2,
navy, magenta or the gradient rule). To save a new style: `import_design_style` with a DESIGN.md and
`tokensCss`. In a Google Fonts `@import`, write `;` as `%3B` until iec-portal's css-validate fix
lands.

## Images

`generate_image` is for **context**: people, devices, places, hardware. Never for UI, because image
models can't render readable interface text. Build screens in HTML instead.

- Preset `plain` for any product with its own identity. `iec-etched` / `iec-dark` are InsurEco's
  house looks.
- Write the subject as what is in the frame, and say "no readable text, no logos". Echo the
  product's accent colour in the hardware so the photos belong to the page.
- Look at the preview; re-roll a bad one. Then `save_image` onto the page as `img/<name>.jpg` and
  reference `assets/img/<name>.jpg`. Assets are public. 100 generations per org per day: don't loop.

## Product explainer

Pattern: https://portal.insureco.io/spaces/iec-portal/pages/product-explainer-pattern-how-to-build-one
Reference: https://portal.insureco.io/spaces/policyos/pages/policyos-user-stories-explainer

One scrolling page, never a carousel: hero with a generated photo, the units, a card index of
roles, then one story block per role, a numbered timeline of one real example with a totals table,
an access matrix with dots, the stack, and open decisions.

- **Screens look real.** Build each in the product's app styles at a fixed 760px canvas inside a
  browser or phone frame (`.iec-ex-shot`, `.iec-ex-phone`); iec-ui.js scales it to fit. Crop with a
  negative left margin so it reads as zoomed in, and label it (`Zoomed: Today`).
- **Pins.** Put `<i class="iec-ex-pin">1</i>` inside the element it points at; the note beside the
  screen carries the same number.
- **Numbers come from tables**, not prose, so screens and totals agree.
- Check it at desktop width, at 375px (no sideways scroll), light and dark, and inside the portal
  (images load from `assets/`). Name anything left as a placeholder.

## Data-heavy page (dashboard, status board, KPIs)

Skip the HTML. `create_page({ project, title, type: "artifact", spec })` where
`spec = { version: 1, kit, data, blocks: [{ id, type, props }] }`. Pick `type`s that
`list_artifact_kits` marks `renderable`, and follow their `props` and `example`. Bind
data with `{"$data": "path"}`. Use `{ id, type: "html", html }` for anything the
catalog lacks. To change the numbers later, send
`blockOps: [{ op: "render", id, block: { type, props } }]` with `expectedVersion`.
`SPEC_INVALID` names the block at fault.

## Changing a page

1. `read_page({ project, slug })` → outline + `version`.
2. Need exact text? `read_page({ ..., section: "<id>" })` — one section's HTML, not the page.
3. Change it, always passing `expectedVersion`:
   - whole section → `blockOps: [{op: "replace"|"insert_after"|"insert_before"|"delete", id, html}]`
   - small text inside a section → `edits: [{old, new}]` (old copied from the section read)
   - whole-document rewrite only → `include: "full"` read, then `content`
   One of `content` / `edits` / `blockOps` per call; ops apply in order, all-or-nothing.

Block ids: `data-block`, else the element's `id` (kit sections: `summary`, `numbers`…), else
`pos-N`. Blocks are the children of `<main>` (or the kit root). A header and TOC inside `main` are
blocks like any section. On older pages that wrap them in `.iec-doc-layout` they sit outside `main`
and are not, so use `edits` for titles and dates there.

## When refused

- `VERSION_CONFLICT` — someone saved since your read. Re-read the outline, re-apply, retry. Never
  fall back to `content` to force it.
- `BLOCK_NOT_FOUND` — use one of the ids listed in the error.

## Don't

- `include: "full"` "just to look" — the outline or a section is enough.
- Paste base64 images — `upload_page_asset` / `save_image`, then `assets/<name>`.
- Draw UI with `generate_image`, or use a carousel to show roles side by side.
- Put questions in an artifact — it can't collect answers; use `create_form`.

Install

Copy the skill content and save it to:

~/.claude/commands/tawa-artifact.md

Details

Format

Command

Category

platform

Version

1.0.7281

Tokens

~1,862

Updated

2026-10-13