figura-cli 0.16.0 → 0.16.1

package/package.json

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

package/skills/fig/SKILL.md

@@ -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
@@ -110,6 +148,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 +224,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 +308,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