figura-cli 0.10.1 → 0.11.0

package/package.json

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

package/skills/fig/SKILL.md

@@ -24,19 +24,51 @@ from your brand. To change the brand, use the `figura-brand` skill, not this one
 - Before any visual / layout / state change — a wrong fig costs seconds; a wrong
   build costs a recompile-and-screenshot loop.
 
+## Existing-first — never mock a redesign blind
+
+**Before building, find out whether this screen already exists.** A fig that
+proposes a redesign without showing what it replaces is how you "improve"
+something in a vacuum — and end up rebuilding what already ships. So every time,
+*first*:
+
+- **Search the codebase** for the screen/flow you're about to mock — Grep/Glob for
+  the route, component, or page (an `onboarding/`, `settings/brand/` dir, a
+  matching route). If a real implementation exists, **Read it** and treat it as the
+  baseline you must show.
+- **Check the team's figs** — `figura fig list --area <area>` (or
+  `figura_list_figs`). If a fig of this screen already exists, **`fig revise` it**
+  (a new version in the same chain), never a fresh duplicate.
+
+If any prior design exists → build in **`mode: compare`** and render it as
+**existing (as-is) → proposed**, grounded in the real current state. Even when the
+proposal is better, it must be argued against what's there — that's the whole
+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.
+
 ## How to fig
 
-1. **Check auth** — call **`figura_whoami`** to confirm you're connected to a
-   team. Not connected? Tell the user to run `figura login`, or add the MCP:
-   `claude mcp add figura -- figura mcp`. (Creating / publishing figs needs the
-   `figs:write` scope on the team — a read-only token passes whoami but fails the
-   land step.)
+1. **Verify the destination team** — call **`figura_whoami`** (or
+   `figura whoami --json`) and check BOTH halves before generating anything:
+   - **Connected?** Not connected → tell the user to run `figura link` (or
+     `figura login`), or add the MCP: `claude mcp add figura -- figura mcp`.
+     (Creating / publishing figs needs the `figs:write` scope on the team — a
+     read-only token passes whoami but fails the land step.)
+   - **Bound to THIS project?** Read `binding.source` in the response. `project`
+     (or an explicit `env` token) → proceed, and say where the fig will land
+     ("figging to team *slug*"). **`global` → STOP before generating**: nothing
+     pins this repo to that team — the fig would land on whatever team this
+     machine last logged into (this is exactly how mocks have ended up on the
+     wrong tenant). Tell the user to run `figura link` in this repo, then
+     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`** (`publish: true`), setting
    `area`, `orientation` (`portrait` / `landscape` / `both`), `mode` (`single` /
-   `compare` / `variations`), `title`, and a real description. This uses the
+   `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
@@ -52,6 +84,42 @@ from your brand. To change the brand, use the `figura-brand` skill, not this one
 
 4. **Review** the returned link, share it, move on.
 
+## 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** —
+CSS-only radio tabs, since figs carry no `<script>`:
+
+- **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
+  wrap to one column before it can overflow — **a fig never scrolls
+  horizontally**, at any viewport.
+- **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; 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
+  minimal — the frames are the content; no legends (chips label themselves),
+  no repeated context, fluid `max-width` layout throughout.
+- **Verify before publishing.** Render the fig headless at a few viewport
+  widths: `document.scrollWidth` must equal the viewport in every view and
+  state (sideways scroll = broken — beware CSS `zoom`, which leaks unzoomed
+  width into scrollable overflow; scale minis with `transform` in
+  fixed-aspect wrappers instead), and screenshot each state to check no
+  annotation chip covers the content it annotates.
+
+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.
+
 ## Notes
 
 - **MCP unavailable** (headless / cron, or no interactive auth): fall back to the

package/skills/figura-brand/SKILL.md

@@ -17,15 +17,21 @@ directory). Default to the current repo.
 
 ## Prerequisites
 
-The user needs the `figura` CLI authenticated once (`figura login`) — the brand is
+The user needs this repo linked to its Figura team (`figura link`; a global
+`figura login` also works but is only a machine-wide fallback) — the brand is
 written to the team that token belongs to. If a `figura` **MCP server** is
 connected, prefer its `figura_set_brand` tool over the CLI. If neither the CLI nor
 `bunx figura-cli` is available, tell the user to install it
 (`curl -fsSL https://figura.so/install.sh | bash`) and stop.
 
-Confirm the target team first: `figura whoami` (or the `figura_whoami` tool). The
-brand is **team-wide and overwrites** the current one — never push without showing
-the user what you're about to set and getting an explicit OK.
+Verify the destination team first: `figura whoami --json` (or the `figura_whoami`
+tool) and check `binding.source`. `project` (or an explicit `env` token) → name
+the team out loud and continue. **`global` → STOP**: nothing pins this repo to
+that team — you could read *another product's* brand as the baseline and
+overwrite *their* profile with this repo's. Tell the user to run `figura link`
+here first. The brand is **team-wide and overwrites** the current one — never
+push without showing the user what you're about to set and getting an explicit
+OK.
 
 ## Workflow