figura-cli 0.23.0 → 0.23.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.23.0",
+  "version": "0.23.2",
   "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_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 *)'
+allowed-tools: 'mcp__figura__figura_whoami, mcp__figura__figura_fig_scaffold, mcp__figura__figura_fig_devices, mcp__figura__figura_list_figs, 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, mcp__figura__figura_request_feedback, Bash(figura *), Bash(bunx figura-cli *)'
 ---
 
 # /fig — figure it out before you build it
@@ -123,9 +123,12 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
 
    - **`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).
+     screen), `overview-focus` (**the one for arguing a redesign or several
+     candidate directions** — opens on the full-frame Focus toggle, Overview
+     grid behind the second tab), `variations` (a scan-only grid of states at
+     ~0.34 scale, NO toggle — only for a pure catalogue nobody has to read
+     detail in; never for a redesign argument), 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
@@ -140,6 +143,19 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
      in that screen's `css`.
    - Plus `area`, `title`, `orientation`, and a real `description`.
 
+   **Small screens are the SERVER's job — with one exception that is yours.**
+   Below a catalog-derived breakpoint every multi-frame layout (`compare`,
+   `variations`, `overview-focus`) restructures itself: ONE frame at a time, as
+   large as fits (never under 0.72 scale), behind a sticky bottom switcher, with
+   the Overview grid dropped. You do not write a media query, a toggle, or a
+   scale for this, and there is nothing to remember — it is emitted for you.
+   What the server CANNOT do is name the frames: **each screen's `label` IS the
+   switcher button**, so `label: 'Empty state'` / `'After save'` works and a
+   missing label degrades to `1`, `2`, `3`. Give every screen a short, distinct,
+   thumb-sized label. Design each screen's CONTENT to survive a 0.72 scale too —
+   ~11px is the floor for body copy at that scale, so 10px annotations are yours
+   to avoid.
+
    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
@@ -247,33 +263,52 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    `figura fig uncommit <id>`) returns it to a draft — the share link is
    untouched either way.
 
-## Presenting a redesign — overview ⇄ focus
+8. **Assign a reviewer.** Committing notifies the team in a digest — that is
+   ambient, not an assignment. If the fig argues a change or wants a decision,
+   finish by putting it in front of a named person with
+   **`figura_request_feedback`** (CLI: `figura fig request-feedback <id> --from
+   <name|email> --note <text>`). See "Assign a reviewer" below — this step is
+   what stops a fig from being landed, committed, and never actually read.
+
+## Presenting a redesign — FOCUS first, overview second
 
 When a fig argues a change against a current state (a shipped baseline, or
 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
+CSS-only radio-tab Focus full-frame toggle ⇄ Overview grid) 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
+the focus pills, the scaled overview grid, 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
-  status chip and ONE condensed context line (`+ / –`). This view is for
-  scanning and picking a direction, not for reading detail. The grid must
+**★ FOCUS IS THE DEFAULT VIEW.** The fig opens on ONE full-size frame with state
+pills — on desktop AND mobile. Overview is the *alternative*, behind the second
+tab, and on a phone it is dropped entirely: there the pills ARE the interface. Never open a redesign fig on the scaled grid: `layout: 'variations'` (a
+scan-only grid at the kit's `--fig-scale:0.34`) is NOT a redesign presentation —
+using it for one shipped a 4-state fig as 134px phones with ~3px annotation
+chips. A Focus-only fig is **complete on its own**; add Overview only when there
+are enough states that scanning them at once genuinely helps.
+
+- **Focus — full frame (default).** One state at a time behind state pills
+  (Today / A / B / …), each state framed identically so flipping states in place
+  reads as spot-the-difference. This is where the context lives, pinned on the
+  frame as annotation chips: what's broken today, what each variation improves,
+  what it trades away. Open on the first pill = the honest current state.
+- **Never put annotation chips inside a clipping box.** `position:absolute`
+  cannot escape an ancestor's `overflow:hidden`, so a chip that straddles a
+  rounded-corner frame ships sliced. Hang chips off a positioned wrapper as
+  siblings of the frame, anchored to grow away from its edge.
+- **Overview — side by side (alternative).** Every state at once: the honest
+  current state first, then each variation, as scaled-down frames in a grid.
+  Under each: a status chip and ONE condensed context line (`+ / –`). This view
+  is for scanning and picking a direction, not for reading detail. The grid must
   wrap to one column before it can overflow — **a fig never scrolls
   horizontally**, at any viewport. To shrink the framed phones, wrap each in the
   kit's **`.fig-mini`** wrapper (see "Scaling a framed device" below), never a
   rule on `.fig-device` and never CSS `zoom` (zoom leaks an unzoomed
   `scrollWidth` into horizontal overflow — the exact thing this view forbids).
-- **Focus — full frame.** One state at a time behind state pills (Today / A /
-  B / …), each state framed identically so flipping states in place reads as
-  spot-the-difference. This is where the context lives, pinned on the frame
-  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 — **reconstructed from source** per "Reconstruct the baseline
   from SOURCE" (no screenshot ⇒ study the component file(s) and rebuild the real
@@ -297,21 +332,29 @@ pattern must be hand-authored — plain CSS-only radio tabs, binary, no library:
      giving it dimensions. It checks every injected component (device frame,
      status bar, control bar, browser chrome), cross-checks the manifest's
      `components` array, and reports the fig's own `frameKit` / `complete` /
-     `doubleFramed` checks; `--json` for machine output. The engine won't
-     silently drop the kit anymore, and create/revise now warns loudly if it
-     ever did — this is the check that *proves* a frame renders.
-  3. **Screenshot THAT** (the printed served HTML, saved to a deterministic
-     project-scoped path — the repo's `.figura/figs/` (gitignored), or
-     `~/.figura/figs/` outside a bound repo, never `/tmp`/`mktemp`), at a few
-     viewport widths: `document.scrollWidth` must equal the viewport in every
-     view and state (sideways scroll = broken), and no annotation chip may
-     cover the content it annotates. `figura fig open <id> --local` writes the
-     same served bytes to `<repo>/.figura/figs/figura-fig-<id>.html`.
+     `doubleFramed` checks; `--json` for machine output. This is the check that
+     *proves* a frame renders. These are static checks over the served bytes —
+     `verify` reads markup and CSS, it lays nothing out, so it cannot see
+     overflow or a clipped chip.
+  3. **Screenshot THAT yourself** — layout is nothing `verify` reports. Take the
+     printed served HTML, saved to a deterministic project-scoped path (the
+     repo's `.figura/figs/` (gitignored), or `~/.figura/figs/` outside a bound
+     repo, never `/tmp`/`mktemp`), and render it at a few viewport widths.
+     `document.scrollWidth` must equal the viewport in every view and state
+     (sideways scroll = broken), no annotation chip may cover the content it
+     annotates, and no chip may be cut by a clipping ancestor: walk each chip's
+     ancestors up to `<html>` and, wherever computed `overflow` is
+     `hidden`/`clip`, assert the chip's rect stays inside that ancestor's box —
+     the viewport box for `<body>`/`<html>`, whose overflow propagates there.
+     Comparing a chip to the frame's rect alone misses the vertical escape, and
+     no rect test sees a rounded clip, which is why the authoring rule above is
+     the real guarantee. `figura fig open <id> --local` writes the same served
+     bytes to `<repo>/.figura/figs/figura-fig-<id>.html`.
 
 A **wipe-slider** stays the narrow tool for exactly two states of the same
 layout with pixel-level tweaks. Never ship a squeezed side-by-side as the
-*only* view of desktop frames, and never a full-frame toggle as the only
-view of many variations — each is one half of the pair above.
+*only* view — a scan-only grid is never the whole argument. The reverse is
+NOT true: a Focus-only toggle is a complete fig, however many states it has.
 
 ## JavaScript is ALLOWED — use it for high-fidelity animation
 
@@ -352,6 +395,31 @@ Example — a GSAP-driven entrance for a mobile screen, pinned + allowlisted:
 </script>
 ```
 
+## Assign a reviewer — a proposal fig isn't done until someone's on it
+
+**A link nobody was pointed at is a fig nobody saw.** Landing, publishing, and
+committing all produce a URL; none of them puts the fig in front of a specific
+person. Committing notifies the team in a *digest*, which is ambient — it is not
+an assignment, and it is not a decision request.
+
+So after landing any fig that **argues a change or wants a decision**, send a
+feedback request as a required final step (step 8 above):
+
+- **MCP:** `figura_request_feedback` — the fig id, the teammate, and a one-line
+  note saying what to look at or decide.
+- **CLI:** `figura fig request-feedback <id> --from <name|email> [--note <text>]`
+  (use this when the MCP is bound to a different team than the fig — the CLI
+  reads the repo's `.figura/config.json`, the MCP may not).
+
+They get an in-app notification, a push, and an email, and the discussion lands
+in the fig's comment thread. **Name what you want from them** ("does 02 close
+#2375?") rather than "thoughts?" — a request with a question attached gets
+answered; a bare link gets deferred.
+
+Ask the user who should review only when it isn't obvious from context. Skip the
+request only for throwaway/exploratory figs, or when the user explicitly wants it
+private.
+
 ## Metadata & geometry — stamped for you
 
 Every landed fig is **auto-stamped server-side** (on `create` and `generate`)

package/skills/skills.json

@@ -1,7 +1,13 @@
 {
   "$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" }
+    "fig": {
+      "version": "2026.08.04",
+      "releasedAt": "2026-08-04T17:44:19.938Z"
+    },
+    "figura-brand": {
+      "version": "2026.07.26",
+      "releasedAt": "2026-07-26T00:00:00.000Z"
+    }
   }
 }