figura-cli 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.16.0",
+  "version": "0.17.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_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_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 *)'
 ---
 
 # /fig — figure it out before you build it
@@ -47,6 +47,44 @@ point. Only build a standalone `single` fig when the screen is genuinely net-new
 Unsure whether a version already exists? **Ask the user** rather than assume
 greenfield.
 
+### Reconstruct the baseline from SOURCE — required, no screenshot
+
+The existing/current/broken frame of a `compare` fig must be a **faithful
+recreation of what actually ships**, not a hand-approximation — an approximated
+"before" quietly rebuilds a strawman and the diptych argues against a screen that
+doesn't exist. So when you build the baseline state and **no screenshot is
+provided**, studying the source and rebuilding its layout is a **REQUIRED step**,
+not optional reading:
+
+1. **Locate the screen** — Grep/Glob for the route dir, the `page`/`route`
+   file, and the component(s) it renders (e.g. `apps/*/src/app/<route>/page.tsx`
+   plus imported views).
+2. **Read the component file(s)** and extract the real structure:
+   - the **JSX/TSX element hierarchy and order** (containers → sections →
+     controls, top to bottom);
+   - the **class names / style modules / design tokens** on each element
+     (`flex`/`grid`, spacing, radii, colors) — these are the layout;
+   - the **imported UI primitives** (`Button`, `Input`, `Card`, …) and *their*
+     rendered shape (a `variant="cta"` white pill vs an `outline` button is a
+     visible difference — open the primitive if unsure);
+   - **conditional branches** — auth-provider variants, stages, empty/error/
+     loading states — and decide which branch the baseline depicts (state it);
+   - the **real copy and labels** (headings, placeholders, button text, error
+     banners) verbatim, not paraphrased.
+3. **Rebuild that layout as the baseline** — real element hierarchy, real
+   controls, real copy, real spacing — so the "before" frame matches the shipped
+   screen line-for-line, then drift only the *proposed* frame.
+4. **Fallback (only if the source genuinely can't be located/read):**
+   approximate, and **caption the baseline as an approximation** (a chip / note on
+   the frame: "approximated — source not found") so no one mistakes a guess for
+   the shipped UI.
+
+This is what "grounded in the real current state" above means: the baseline is
+**source-faithful by reconstruction**, or it is explicitly labelled a guess —
+never a silent approximation. It applies to **both** the hand-build path and the
+server render below — on a server render you can't read the repo *for* the engine,
+so you hand it the studied structure in the brief (see step 3, "Server render").
+
 ## How to fig
 
 1. **Verify the destination team** — call **`figura_whoami`** (or
@@ -64,16 +102,26 @@ greenfield.
      re-verify. If the response has no `binding` field (older CLI/MCP), confirm
      the team slug matches this project with the user before proceeding.
 
-2. **Default — build it yourself, with YOUR Claude.** Fetch the team's design
-   system — `bunx figura-cli brand --json` — 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 — and applies the team's brand from the
-   fetched design system. **Follow that design system verbatim; never invent brand
-   values.**
+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
    always persists it to Figura (there is no separate "save it for real" step);
@@ -110,6 +158,19 @@ greenfield.
    on brand). Never pick this path on your own to save effort: it costs credits
    and hand-built figs track the brand better.
 
+   **The engine CANNOT read your repo — carry the studied baseline in the brief.**
+   `figura_generate_fig` runs server-side against the team brand; it has no access
+   to the caller's filesystem, so for a `compare`/existing state it would otherwise
+   *guess* the "before" too. Close the seam yourself: do the source study from
+   "Reconstruct the baseline from SOURCE" above **first**, then pass the
+   reconstructed structure into the `prompt` brief as an explicit "before" spec —
+   the file you grounded it in, the element order top-to-bottom, the real controls
+   and primitive shapes, the branch depicted, and the verbatim copy/labels. The
+   `prompt` is free NL text, so this needs no extra parameter — the studied layout
+   just becomes the baseline half of the brief (the proposed half describes the
+   change). If you truly couldn't locate the source, say so in the brief and label
+   the baseline an approximation, same as the hand-build fallback.
+
 4. **Open the HOSTED fig for approval — never a local file.** Run
    `figura fig open <id>` (the id `figura_create_fig`/`figura_generate_fig` just
    returned). It opens **`viewUrl`** in the reviewer's browser — the actual
@@ -173,7 +234,9 @@ truncation, and doesn't need a library):
   as annotation chips: what's broken today, what each variation improves,
   what it trades away.
 - **In both views:** render the current state honestly from the shipped
-  implementation; color-code chips by function (broken / improved /
+  implementation — **reconstructed from source** per "Reconstruct the baseline
+  from SOURCE" (no screenshot ⇒ study the component file(s) and rebuild the real
+  layout, don't approximate); color-code chips by function (broken / improved /
   trade-off / detail) using the team's status colors from the fetched design
   system; mark the recommended variation and close with a short "my read"
   arguing the pick against the others. Keep the chrome around the frames
@@ -255,11 +318,20 @@ with two things you do **not** hand-write:
 
 So when you **hand-build** a fig (the default path), do your part of the contract:
 
-- **Mobile:** size the body to the exact logical screen and emit
-  `<meta name="figura:artboard" content="WxH">` matching it (iPhone portrait
-  `393x852` / landscape `852x393`). For OS-chrome insets prefer
-  `var(--fig-safe-top, 59px)` / `.fig-safe-top` over hardcoded pixels — the stamp
-  fills the value, the fallback keeps you correct if the kit is absent.
+- **Bare mobile screen — and ONLY then:** when the fig's HTML *is* one raw app
+  screen (no masthead, no state pills, no hand-drawn `.fig-device` frames — the
+  Figura viewer draws the iPhone shell around it), size the body to the exact
+  logical screen and emit `<meta name="figura:artboard" content="WxH">` matching
+  it (iPhone portrait `393x852` / landscape `852x393`). For OS-chrome insets
+  prefer `var(--fig-safe-top, 59px)` / `.fig-safe-top` over hardcoded pixels —
+  the stamp fills the value, the fallback keeps you correct if the kit is absent.
+- **A document-style fig NEVER gets an artboard.** The artboard meta is the
+  viewer's opt-in signal for "size me to exactly WxH and wrap me in a device
+  shell" — stamped on an overview ⇄ focus redesign page (or any compare /
+  variations document with its own masthead, pills, or hand-drawn device
+  frames), it crams the whole document into a phone frame. A document fig
+  renders full-page precisely because it carries NO artboard meta, even when
+  every screen it depicts is a mobile app.
 - **Always:** emit `<meta name="figura:context" content="...">` (design intent).
 - **Optional but valued:** if the fig grounds a specific feature or flag, emit
   `<meta name="figura:feature" content="<flag-or-slug>">` so it links back to the
@@ -270,8 +342,9 @@ So when you **hand-build** a fig (the default path), do your part of the contrac
 - **MCP unavailable** (headless / cron, or no interactive auth): fall back to the
   CLI — `bunx figura-cli fig create` / `fig publish`, with `fig revise` /
   `fig revisions` for versions, `fig commit` / `fig uncommit` (or `--commit` on
-  the final create/revise) for the team library, and
-  `bunx figura-cli brand --json` for the brand.
+  the final create/revise) for the team library, `bunx figura-cli fig scaffold`
+  for the authoring scaffold, and `bunx figura-cli brand --json` for the raw
+  brand (the scaffold's fallback).
 - **`figura_create_fig`/`figura_revise_fig` itself fails** (no network, API down,
   auth expired): the fig never entered Figura, so there is no `id`/`viewUrl` to
   open. Only THEN write the HTML to a local scratch file (project-scoped —