figura-cli 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Command-line client for the Figura visualization SaaS",
   "license": "MIT",
   "type": "module",

package/skills/fig/SKILL.md

@@ -2,7 +2,7 @@
 name: fig
 description: "Mock up a screen as an on-brand, shareable HTML fig via your Figura team — render a UI state in seconds before writing the real code. Use when asked to visualize a screen, mock a UI, or 'make a fig'. iPhone-framed by default; browser frame for web/desktop."
 argument-hint: '<what to visualize>'
-allowed-tools: 'mcp__figura__figura_whoami, mcp__figura__figura_fig_scaffold, mcp__figura__figura_fig_devices, mcp__figura__figura_generate_fig, mcp__figura__figura_create_fig, mcp__figura__figura_revise_fig, mcp__figura__figura_publish_fig, mcp__figura__figura_commit_fig, Bash(figura *), Bash(bunx figura-cli *)'
+allowed-tools: 'mcp__figura__figura_whoami, mcp__figura__figura_fig_scaffold, mcp__figura__figura_fig_devices, mcp__figura__figura_generate_fig, mcp__figura__figura_compose_fig, mcp__figura__figura_create_fig, mcp__figura__figura_revise_fig, mcp__figura__figura_publish_fig, mcp__figura__figura_commit_fig, Bash(figura *), Bash(bunx figura-cli *)'
 ---
 
 # /fig — figure it out before you build it
@@ -105,28 +105,54 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
      to the user verbatim (a one-line "figura-mcp is behind / below min — run …"),
      then proceed. It's a passive nudge, shown once per session — never a blocker.
 
-2. **Default — build it yourself, with YOUR Claude.** Fetch the **canonical
-   authoring scaffold** — **`figura_fig_scaffold`** (CLI:
-   `bunx figura-cli fig scaffold --platform <mobile|web> [--device <id>] [--area <str>]`)
-   — and hand-build the fig's HTML against it, then land it with
-   **`figura_create_fig`**, setting `area`, `orientation` (`portrait` /
-   `landscape` / `both`), `mode` (`single` / `compare` / `variations` — default
-   to `compare` when Existing-first turned up a baseline), `title`, and a real
-   description. This uses the caller's own Claude (the model running this skill)
-   — no extra cost, full control for precise broken-vs-proposed diptychs.
-
-   The scaffold IS the source of truth: it's the **exact system prompt Figura
-   injects when it renders a fig server-side** — the design rules, exemplars,
-   accent hints, your team's composed brand, and the component/device kit
-   context, all in one. Follow it verbatim; never invent brand values or restate
-   design rules from memory. Match `--platform` to the target (a web fig's
-   scaffold composes the team's *web* brand surface, a mobile fig's the *mobile*
-   one). **Fallback if the scaffold fetch fails** (older engine/CLI, or the
-   `figura_fig_scaffold` tool is unavailable): fetch just the brand with
-   `bunx figura-cli brand --json` and author against that — the scaffold is the
-   preferred path, the raw brand is the degraded one.
-
-   **Landing IS hosting — leave `publish` and `commit` unset.** Creating a fig
+2. **Default — write the CONTENT, let Figura own the STRUCTURE.** Build device
+   figs with **`figura_compose_fig`**: you author only each **screen's CONTENT**
+   (the markup *inside* the phone); Figura owns the parts that used to drift — the
+   iPhone **frame** (bezel + Dynamic Island/notch + home bar), the **safe zone**,
+   the exact catalog **artboard geometry**, and the **composition** (grid /
+   diptych / overview). The frame/safe/device/composition can no longer be wrong:
+   they're sourced from the device catalog server-side, not hand-written, so the
+   chronic failures (a rolled-your-own artboard, a guessed `--fig-safe-top:59px`,
+   a forgotten `data-device`) are impossible by construction.
+
+   First fetch context — the **scaffold** (`figura_fig_scaffold`, CLI:
+   `bunx figura-cli fig scaffold --platform <mobile|web> [--area <str>]`) for the
+   brand tokens + design rules, and the **device catalog**
+   (`figura_fig_devices`) for the valid `device` ids. Then call
+   **`figura_compose_fig`** with:
+
+   - **`layout`** — `single` (one frame), `compare` (as-is → proposed diptych;
+     default this when Existing-first turned up a baseline — pass a `label` per
+     screen), `variations` (responsive grid of states + status chips),
+     `overview-focus` (the overview⇄focus toggle for arguing a redesign), or
+     `document` (NO device framing — brand/overview figs).
+   - **`screens`** — an ARRAY. Each screen's **`html` is CONTENT ONLY**: the
+     markup that goes *inside* the phone. Do **NOT** draw a frame, bezel, status
+     bar, or safe padding; do **NOT** set `--fig-safe-*`; do **NOT** wrap it in
+     `.fig-device`. For every device layout each screen also carries the typed
+     intent Figura needs — **`device`** (a real catalog id from
+     `figura_fig_devices`, e.g. `iphone-16`), **`orientation`**
+     (`portrait`/`landscape`), and **`safeZone`** (`respect` = Figura pads your
+     content to the device's real safe insets; `ignore` = edge-to-edge for a
+     splash/hero). (`document` screens need none of these.)
+   - **`sharedCss`** — ONE stylesheet every screen shares: put your brand tokens
+     (from the scaffold) and shared content classes here. Per-screen one-offs go
+     in that screen's `css`.
+   - Plus `area`, `title`, `orientation`, and a real `description`.
+
+   This uses the caller's own Claude — no extra cost. Follow the scaffold's brand
+   values verbatim; never invent brand values or restate design rules from memory.
+   **Fallback if the scaffold fetch fails** (older engine/CLI): fetch just the
+   brand with `bunx figura-cli brand --json` and author your content styles
+   against that.
+
+   **`figura_create_fig` is the escape hatch** — reach for it only for a
+   `document`/exotic fig where you must hand-author the entire HTML (or when
+   `compose` is unavailable on an older engine). It takes a full `html` document
+   and you own the whole contract yourself. For any device fig, prefer
+   `compose` — it can't drift.
+
+   **Landing IS hosting — leave `publish` and `commit` unset.** Composing a fig
    always persists it to Figura (there is no separate "save it for real" step);
    the response's **`viewUrl`** is a link you can open right now, whether or not
    anyone has decided to share it wider. It lands as a **workspace draft** —
@@ -137,15 +163,14 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    on an exploration — committing is reserved for the session's final
    recommendation (step 7).
 
-   **Pass the fig markup INLINE as `html` — never a shell reference.** The `html`
-   argument to `figura_create_fig` / `figura_revise_fig` is the *full HTML
-   document itself*, passed directly as the value. An MCP tool argument is **not**
-   a shell: `$(cat "…/fig.html")`, a backtick `` `cat file` ``, any command
+   **Pass markup INLINE — never a shell reference.** The `html` (create) and each
+   screen's `html`/`css` + `sharedCss` (compose) arguments are the *strings
+   themselves*, passed directly as the value. An MCP tool argument is **not** a
+   shell: `$(cat "…/fig.html")`, a backtick `` `cat file` ``, any command
    substitution, or a bare file path will **not** expand — the literal string is
-   stored as the fig, producing a tiny black/empty canvas (the engine now rejects
-   this with a 400). If you authored the HTML in a scratch file to render/verify
-   it (step "Verify before publishing"), **read that file's contents** and pass
-   the contents as `html` — do not reference the path.
+   stored (a tiny black/empty canvas; the engine rejects a shell-ref create with
+   a 400). If you authored content in a scratch file, **read that file's
+   contents** and pass the contents — do not reference the path.
 
 3. **Server render — the user's call, never yours.** Figura can also render the
    fig server-side against the team brand: **`figura_generate_fig`** with a
@@ -225,9 +250,15 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
 ## Presenting a redesign — overview ⇄ focus
 
 When a fig argues a change against a current state (a shipped baseline, or
-several candidate directions), build one fig with **two switchable views** —
-plain CSS-only radio tabs for THIS specific toggle (it's binary, must survive
-truncation, and doesn't need a library):
+several candidate directions), use **`figura_compose_fig` with
+`layout: 'overview-focus'`** — Figura emits the two switchable views (the
+CSS-only radio-tab Overview grid ⇄ Focus full-frame toggle) for you from your
+per-screen content. You supply each state's CONTENT + a `label`; the composition,
+the scaled overview grid, the focus pills, and the no-horizontal-scroll guarantee
+are server-owned. The design intent below still guides WHAT each state's content
+says and which is recommended — you just no longer hand-write the toggle markup
+or the frame scaling. (If you're on the `create` escape hatch instead, the same
+pattern must be hand-authored — plain CSS-only radio tabs, binary, no library:)
 
 - **Overview — side by side.** Every state at once: the honest current state
   first, then each variation, as scaled-down frames in a grid. Under each: a
@@ -336,8 +367,11 @@ with two things you do **not** hand-write:
   search and the self-improving loop. Artifact-descriptive only — no team/brand
   ids (the block is served on the public link).
 
-So when you **hand-build** a fig (the default path), you do your part of the
-contract — but the exact rules are **fetched, not restated here**: the
+With **`figura_compose_fig`** you do NOT hand-write any of the frame/safe/device
+contract below — Figura stamps it from your typed params. The rest of this
+section applies ONLY to the **`figura_create_fig` escape hatch**, where you
+hand-author the whole document: the exact rules are **fetched, not restated
+here** —  the
 presentation model (frameless single vs canvas composition), when to emit or
 omit the whole-fig `<meta name="figura:artboard">`, the `.fig-device` /
 `data-device` frame markup (Figura stamps the bezel, Dynamic Island, and

package/skills/skills.json

@@ -0,0 +1,7 @@
+{
+  "$comment": "Skill version manifest (#752) — the source of truth for each Figura skill's OWN version line, DECOUPLED from the figura-cli package version. A release bumps the version here when a skill's content changes, then regenerates the engine seed (bun packages/core/scripts/build-skill-seed.mjs) and re-seeds. Version is a date tag (YYYY.MM.DD[.n]); releasedAt is ISO-8601. The CLI/MCP stamp this version into .figura-version at install; the engine seeds the registry from it.",
+  "skills": {
+    "fig": { "version": "2026.07.26", "releasedAt": "2026-07-26T00:00:00.000Z" },
+    "figura-brand": { "version": "2026.07.26", "releasedAt": "2026-07-26T00:00:00.000Z" }
+  }
+}