figura-cli 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Command-line client for the Figura visualization SaaS",
   "license": "MIT",
   "type": "module",
@@ -21,13 +21,14 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "engines": {
     "node": ">=20"
   },
   "scripts": {
-    "build": "bun build src/index.ts --target=node --minify --outfile=dist/index.js",
+    "build": "bun run scripts/bundle-skill.mjs && bun build src/index.ts --target=node --minify --outfile=dist/index.js",
     "dev": "bun run src/index.ts",
     "prepublishOnly": "bun run build"
   },

package/skills/figura-fig/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: figura-fig
+description: "Generate an on-brand, device- or browser-framed HTML fig using your Figura team's design system, save it to your team, and (optionally) publish a shareable link. iPhone frame by default; browser frame for web/desktop UIs. Use when asked to mock up a screen, build a fig, or visualize a UI state."
+argument-hint: '<what to visualize>'
+allowed-tools: 'Bash(figura *), Bash(bunx figura-cli *)'
+---
+
+# Figura Fig
+
+Generate ONE self-contained, on-brand HTML fig and persist it to the user's Figura team.
+It renders with the **team's brand profile** (their design tokens). When the team hasn't set
+a brand, Figura is brand-neutral by construction — render with clean, modern, accessible
+**neutral defaults**, never another company's brand.
+
+The argument (`$ARGUMENTS`) is what to visualize, e.g. "the settings screen with a sticky
+save bar" or "the pricing page".
+
+## Prerequisites
+
+The user needs the `figura` CLI installed once…
+
+```bash
+curl -fsSL https://figura.so/install.sh | bash   # or, with a runtime: bun add -g figura-cli  /  npm i -g figura-cli
+```
+
+…and an authenticated session, established once:
+
+```bash
+figura login
+```
+
+`figura login` opens a short browser authorize page — a **device flow**, so there's no
+token to paste, no localhost port, and it works over SSH. Approve there and the CLI writes
+the credential to `~/.figura/config.json` (it also honors the `FIGURA_TOKEN` env var for
+CI/headless). **Never mint or fabricate a token yourself.**
+
+If the CLI is missing or the user isn't logged in, you'll hit it at the **persist** step
+([§4](#4-persist-and-optionally-publish-to-the-figura-team)) — handle it there: guide them
+through install / `figura login`, then retry. (If `figura` isn't on PATH, use
+`bunx figura-cli` in its place everywhere below.)
+
+## Workflow
+
+### 0. New fig or a revision?
+
+Decide this first. If the request **iterates on an existing or just-made fig** — "make
+the earlier settings screen darker", "tweak that pricing page", "same screen but landscape"
+— it's a **REVISION**: jump to [§4b](#4b-persist-a-revision) instead of creating a new fig.
+Otherwise fall through and create a new fig as normal. When genuinely unsure, default to a
+new `fig create`.
+
+**Resolve the prior fig id** (priority order):
+
+1. The id printed by a `fig create`/`fig revise` earlier **in this session** — use it directly.
+2. An id, a `*.figura.so` URL, or a slug the **user pasted/named** — extract the id from it.
+3. Otherwise list and match: `bunx figura-cli fig list --json` (optionally `--area <area>`),
+   then match by title / area / tags / recency. If **more than one** plausibly matches, ASK
+   (cite id + title) — never silently revise the wrong fig.
+
+**Fetch the prior HTML** so you can edit on top of it rather than regenerating from scratch:
+
+```bash
+bunx figura-cli fig open <priorFigId> --print
+```
+
+This round-trips the stored document to stdout. Apply the user's change on top of it,
+keeping the brand tokens and overall structure stable.
+
+### 1. Resolve the brand + platform
+
+**Fetch the team's brand profile first:**
+
+```bash
+bunx figura-cli brand --json
+```
+
+This returns `{ name, appDescription, tokensBlock, isCustom }`.
+
+- If **`isCustom: true`** — use the returned `tokensBlock` as the ground-truth design
+  system (palette, type, spacing, icon language) and render for `name` / `appDescription`.
+  Never invent off-brand values.
+- If **`isCustom: false`** (no brand set) — render with **neutral defaults**: read
+  `reference/brand-tokens.md` (next to this file). It is a clean, brand-neutral baseline —
+  understated and professional, NOT any specific company's look.
+
+**Pick the platform** from the request:
+
+- **`mobile`** (default) — an iPhone-framed app screen.
+- **`web`** — a browser-framed web/desktop UI (a marketing page, dashboard, SaaS screen).
+  Choose this when the product is a website/web app rather than a phone screen.
+
+Optionally skim `reference/examples.md` for worked prompt → output pairs.
+
+### 2. Confirm scope (only if ambiguous)
+
+- **area** — the part of the product this screen belongs to (e.g. `feed`, `profile`,
+  `settings`, `onboarding`, or `other`). It's a free-form hint that grounds the design; pick
+  what the prompt implies.
+- **orientation** — `landscape` / `portrait` / `both` (mobile only; web is responsive).
+
+Pick what the prompt implies; confirm only if you genuinely can't.
+
+### 3. Generate the HTML
+
+Produce ONE complete, self-contained HTML document. Whatever the platform, it MUST:
+
+- Start at `<!DOCTYPE html>` — a full document, inline CSS only (one `<style>` in `<head>`).
+- Contain **NO `<script>` tags** and **NO `on*` event handlers**. Fully static; it renders
+  its state with CSS alone (it runs in a sandboxed iframe).
+- Use the resolved brand's tokens for all color/type/spacing — never invent off-brand values.
+- Represent every icon as **inline stroke SVG** via `<symbol>`/`<use>` (currentColor,
+  width ~1.6) — **NEVER emoji**.
+- Set `<title>` to a short screen name, include `<meta name="figura:context" content="…">`
+  (one-line design-intent summary), and an `<h1>` naming the screen.
+
+**Mobile platform** — render an **iPhone device frame** (`.device-port` for portrait,
+`.device-land` for landscape) with a dynamic island, per the reference. A `.preview` media
+area is OPTIONAL — include it only if the design calls for a hero/media region, and size it
+to the design (any aspect ratio). Hand-roll controls with the pill/capsule convention; do
+not rely on system/OS chrome.
+
+**Web platform** — render a **browser window** instead (no phone frame):
+
+```
+.frame-web { width: 980px; max-width: 100%; border: 1px solid #2a2a2c; border-radius: 12px; overflow: hidden; }
+.frame-web .bar { display: flex; gap: 8px; align-items: center; height: 40px; padding: 0 14px; }
+.frame-web .dot { width: 12px; height: 12px; border-radius: 50%; }   /* r/y/g window controls */
+.frame-web .urlbar { flex: 1; height: 22px; border-radius: 6px; }    /* address pill */
+.frame-web .viewport { /* full-bleed RESPONSIVE content — nav, hero, sections */ }
+```
+
+### 4. Persist (and optionally publish) to the Figura team
+
+**Generating the HTML is not "creating the fig" — the fig only exists once it's saved to the
+user's team and the CLI returns an id.** Always upload the HTML straight to Figura; **never**
+write it to a local file or leave it only in the conversation as the result. Pipe the
+generated document into the CLI over stdin:
+
+```bash
+cat <<'HTML' | bunx figura-cli fig create \
+  --title "Settings — account & notifications" \
+  --area settings \
+  --orientation portrait \
+  --tags settings,toggles \
+  --publish
+<!DOCTYPE html>
+… the generated document …
+HTML
+```
+
+**If the upload fails because the user isn't authenticated** — a 401, "No Figura token", or
+"token validation failed" — they haven't logged in. Run `figura login` (the browser device
+flow from [Prerequisites](#prerequisites)), then **retry the same `fig create`**. Don't
+report the fig as done and don't fall back to writing the HTML to a local file — it isn't a
+fig until the persist succeeds and returns an id. (Same for a missing CLI: point them at the
+install one-liner, then retry.)
+
+- `--publish` (recommended when the user wants to share it) flips the fig public and returns
+  a **shareable `*.figura.so` URL**. It requires an active subscription (any paid tier); on a
+  free team the CLI reports the fig is saved privately. Omit `--publish` to keep the fig
+  private to the team.
+- Do NOT use `--file` or `mktemp`/temp files — stream the HTML via stdin so no local copy is
+  left behind.
+- `--title` matches the `<title>`; `--area` / `--orientation` are the confirmed facets;
+  `--tags` is a short comma-separated list.
+- The token resolves automatically from `FIGURA_TOKEN` or `~/.figura/config.json`.
+
+The command prints the result as JSON. When published it includes the shareable `url` —
+surface that to the user. To publish a fig created earlier: `bunx figura-cli fig publish <id>`.
+
+### 4b. Persist a revision
+
+When the request iterates on an existing fig (resolved in [§0](#0-new-fig-or-a-revision)),
+persist the updated HTML as a **new linked version** with `fig revise <priorFigId>`:
+
+```bash
+cat <<'HTML' | bunx figura-cli fig revise <priorFigId> \
+  --title "Settings — darker theme" \
+  --tags settings,toggles,dark \
+  --publish
+<!DOCTYPE html>
+… the full updated document …
+HTML
+```
+
+- `revise` creates a NEW row on the SAME root chain with an incremented `version` — it does
+  NOT edit the prior fig in place. `<priorFigId>` is a positional argument.
+- `--area` / `--orientation` are **inherited from the parent** unless you override them — a
+  refine keeps the same surface. Pass the same Create options otherwise (`--title`, `--tags`,
+  `--publish`).
+- The result JSON includes `id`, `version`, and `rootFigId`. Surface it as
+  "revision vN of \<root\>" plus the shareable URL when `--publish` was used.
+- To inspect the chain: `bunx figura-cli fig revisions <id>` (any id in the chain; oldest to
+  newest).
+
+### 4c. Request a teammate's feedback
+
+When the user wants a specific person to look at a fig — "I want Adam's feedback on this",
+"get Sara's eyes on it", "ask Maya to review this" — request feedback on the fig. The teammate
+gets a notification (in-app bell, web push, email) and the discussion happens in the fig's
+comment thread on Figura. Use the fig id from this session (the one you just created/revised),
+or resolve it via [§0](#0-new-fig-or-a-revision) first.
+
+```bash
+bunx figura-cli fig request-feedback <figId> --from "Adam" --note "does the empty state read right?"
+```
+
+- `--from` is the teammate by **name or email**, resolved within your team. If it's ambiguous
+  or not found, the CLI says so — relay that and ask the user to clarify (or invite them first).
+- `--note` is optional; pass along whatever the user wants reviewed.
+- This is the entry point for "tell Claude Code → teammate notified → chat on the figura page".
+  Report the teammate asked + the fig URL it prints.
+
+### MCP fast path
+
+If a `figura` **MCP server** is connected, prefer its tools over shelling out to the CLI:
+
+- New fig → `figura_create_fig` (fields: html, title, area, orientation, tags, `publish`).
+- **Revision** of an existing fig → `figura_revise_fig` (fields: `id`, html, title?, tags?,
+  area?, orientation?, `publish`?) — mirrors how `figura_create_fig` is preferred for new figs.
+- Inspect the chain → `figura_list_revisions` (field: `id`).
+- **Request a teammate's feedback** → `figura_request_feedback` (fields: `id`, `from`, `note?`).
+
+Prefer the MCP tools when available; fall back to the CLI otherwise.
+
+## Output
+
+Report back the persisted fig — the shareable URL if published, otherwise that it was saved
+privately to the team — plus a one-line description of what was rendered. Do not paste the
+full HTML into the conversation unless the user asks to see it.

package/skills/figura-fig/reference/brand-tokens.md

@@ -0,0 +1,118 @@
+# Figura Fig — neutral default tokens (no team brand set)
+
+Use this baseline ONLY when `figura brand --json` returns `isCustom: false` (the team
+hasn't set its own brand). It is a clean, modern, accessible, brand-NEUTRAL default — never
+any specific company's look. The moment a team sets tokens, use those instead.
+
+Keep it understated and professional.
+
+## Colors (neutral defaults — keep to ONE accent)
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Canvas | `#0E0E10` | Near-black base background. |
+| Surface | `#161618` | Cards / raised surfaces. |
+| Text | `#F4F4F6` | Primary text. |
+| Text muted | `#9aa0ad` | Secondary text, captions. |
+| Hairline | `rgba(255,255,255,.10)` | 1px borders / dividers. |
+| Accent | `#4C8DFF` | ONE calm blue accent — primary actions, active state, focus. |
+
+No more than one accent hue. No decorative gradients unless the prompt asks. Status tints
+only when genuinely needed: amber `#E8A33D` (warn), green `#3ee07a` (success), error `#ff5f57`.
+
+## Type
+
+System / neutral sans only — declare stacks, never load fonts over the network:
+
+| Role | CSS stack |
+|------|-----------|
+| Sans (everything) | `Inter, -apple-system, BlinkMacSystemFont, system-ui, sans-serif` |
+| Mono (numbers/code) | `ui-monospace, SFMono-Regular, 'JetBrains Mono', monospace` |
+
+Clear hierarchy: ~13px body, semibold headings, generous line-height.
+
+## Spacing & shape
+
+An 8px spacing rhythm; 12–16px corner radii; 1px hairline borders; restrained shadows.
+
+## Icon language
+
+Every icon is **inline stroke SVG** via `<symbol>`/`<use>` (`stroke="currentColor"`,
+`stroke-width` ~1.6). **NEVER emoji.**
+
+## iPhone device frame — CSS conventions
+
+Reuse these class names + proportions so every mobile fig reads as one house style.
+
+**Reset + page:**
+
+```css
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { background: #161618; color: #F4F4F6; font-family: Inter, -apple-system, BlinkMacSystemFont, system-ui, sans-serif; padding: 30px; }
+.page { display: flex; flex-direction: column; align-items: center; gap: 14px; }
+.row { display: flex; gap: 30px; flex-wrap: wrap; justify-content: center; align-items: flex-start; }
+.col { display: flex; flex-direction: column; align-items: center; gap: 11px; }
+.col-label { font-size: 11px; letter-spacing: .6px; text-transform: uppercase; color: #9aa0ad; font-weight: 600; }
+```
+
+**PORTRAIT phone (the common case):**
+
+```css
+.device-port { position: relative; width: 300px; height: 640px; background: #000; border-radius: 44px; border: 6px solid #2a2a2a; box-shadow: 0 18px 40px rgba(0,0,0,.5), inset 0 0 0 2px #000; overflow: hidden; }
+.device-port .island { position: absolute; top: 9px; left: 50%; transform: translateX(-50%); width: 92px; height: 26px; background: #000; border-radius: 15px; z-index: 8; }
+```
+
+**LANDSCAPE phone (wide window, side island):**
+
+```css
+.device-land { position: relative; width: 660px; height: 318px; background: #000; border-radius: 44px; border: 6px solid #2a2a2a; box-shadow: 0 24px 50px rgba(0,0,0,.55), inset 0 0 0 2px #000; overflow: hidden; }
+.device-land .island { position: absolute; left: 9px; top: 50%; transform: translateY(-50%); width: 26px; height: 96px; background: #000; border-radius: 16px; z-index: 8; }
+```
+
+**Screen + OPTIONAL media area** (include `.preview` only if the design needs a hero/media
+region — size it to the design, any aspect ratio; there is no fixed film ratio):
+
+```css
+.screen { position: absolute; inset: 0; background: #0E0E10; color: #F4F4F6; overflow: hidden; }
+.preview { position: absolute; background: #18181b; }   /* optional media/hero region */
+.scrim { position: absolute; inset: 0; background: linear-gradient(to bottom, rgba(0,0,0,.45), transparent 22%, transparent 70%, rgba(0,0,0,.55)); }
+```
+
+**Capsule chrome — pill controls, count badge (all fully rounded):**
+
+```css
+.time-pill { position: absolute; background: rgba(0,0,0,.55); border-radius: 999px; padding: 4px 11px; font-size: 9.5px; color: #fff; display: inline-flex; gap: 6px; align-items: center; }
+.tool-tabs { position: absolute; display: inline-flex; gap: 4px; background: rgba(0,0,0,.5); border-radius: 999px; padding: 3px 4px; }
+.tool-tabs span { font-size: 8.5px; color: rgba(255,255,255,.6); width: 18px; height: 18px; border-radius: 50%; display: flex; align-items: center; justify-content: center; }
+.tool-tabs span.on { background: rgba(255,255,255,.92); color: #111; font-weight: 700; width: auto; padding: 0 7px; }
+.badge { min-width: 15px; height: 15px; padding: 0 4px; background: var(--accent, #4C8DFF); border-radius: 999px; font-size: 9px; font-weight: 700; color: #fff; display: flex; align-items: center; justify-content: center; }  /* a quiet count, never a red alarm */
+```
+
+**Annotation chips — yellow callouts pinned over the frame (label intent):**
+
+```css
+.annot { position: absolute; font-size: 9px; font-weight: 500; color: #ffe066; background: rgba(0,0,0,.82); border: 1px solid rgba(255,224,102,.45); padding: 3px 6px; border-radius: 4px; pointer-events: none; z-index: 20; max-width: 180px; line-height: 1.3; }
+```
+
+**Inline SVG icons:** define `<symbol>` elements in a hidden `<svg>` at the top of `<body>`
+and reference with `<use href="#id"/>`. Stroke icons (`stroke="currentColor"`,
+`stroke-width` ~1.6).
+
+## Hard rules (non-negotiable)
+
+- Lay the screen out to fill the chosen orientation; use whatever media/aspect ratios the
+  design needs — there is no fixed aspect-ratio requirement.
+- NO emojis anywhere. Every icon is inline stroke SVG.
+- Hand-roll every control with the pill/capsule convention above — do not rely on system/OS
+  chrome or platform glass effects.
+- Plain HTML + INLINE CSS ONLY (a single `<style>` in `<head>`). No external stylesheets,
+  no network fonts, no frameworks.
+- ABSOLUTELY NO `<script>` tags and NO `on*` event handlers. Fully static; renders state
+  with CSS alone (runs in a sandboxed iframe).
+
+## Document contract
+
+- Respond with a complete HTML document starting at `<!DOCTYPE html>`.
+- `<title>` = short screen name.
+- `<meta name="figura:context" content="…">` = one-line design-intent summary.
+- An `<h1>` naming the screen.

package/skills/figura-fig/reference/examples.md

@@ -0,0 +1,104 @@
+# Figura Fig — Examples
+
+Two worked examples of a prompt → what gets generated and saved. Each produces ONE
+self-contained HTML document and persists it to the Figura team via `bunx figura-cli fig create`.
+(These use the neutral default tokens; with a custom team brand, swap in its palette/type.)
+
+---
+
+## Example 1 — "mock up a settings screen with a sticky save bar" (mobile)
+
+**Resolved scope:** area `settings`, orientation `portrait`.
+
+**Generated document:** a `.device-port` iPhone frame with a top dynamic-island. Inside, a
+`.screen`: a "Settings" header + a search field, then grouped rows (Account, Notifications,
+Privacy) — each row a label + an inline stroke-SVG glyph + a control (chevron, or a CSS-only
+toggle in the accent color). A sticky bottom save bar ("3 unsaved changes" + Save / Discard)
+pinned over the screen. No `.preview` media area (this screen has none).
+
+A `.annot` chip points at the toggles: "active = accent #4C8DFF". `<title>` = "Settings —
+account & notifications"; `<meta name="figura:context">` summarizes the unsaved-changes
+state; `<h1>` reads "Settings".
+
+**Persisted (and shared):**
+
+```bash
+cat <<'HTML' | bunx figura-cli fig create \
+  --title "Settings — account & notifications" \
+  --area settings \
+  --orientation portrait \
+  --tags settings,toggles,save-bar \
+  --publish
+… the generated document …
+HTML
+```
+
+Then report the returned shareable `url`.
+
+---
+
+## Example 2 — "the pricing page, three tiers" (web)
+
+**Resolved scope:** platform `web` (a marketing page, not a phone screen).
+
+**Generated document:** a `.frame-web` browser window (r/y/g window dots + an address pill)
+around a responsive `.viewport`: a top nav (wordmark + links + a CTA button in the accent),
+a centered headline + subhead, then a 3-column pricing grid — each card a name, price,
+feature list with inline stroke-SVG checks, and a button (the middle/recommended card
+emphasized with the accent border). Neutral near-black canvas, one accent hue, system sans,
+8px rhythm. No phone frame, no fixed aspect ratio — responsive content fills the frame.
+
+A `.annot` chip marks the recommended card. `<title>` = "Pricing — three tiers";
+`<meta name="figura:context">` summarizes the comparison; `<h1>` reads "Pricing".
+
+**Persisted (private — omit `--publish` to keep it team-only):**
+
+```bash
+cat <<'HTML' | bunx figura-cli fig create \
+  --title "Pricing — three tiers" \
+  --area other \
+  --tags pricing,marketing,web
+… the generated document …
+HTML
+```
+
+Then report the fig (saved privately, or the shareable `url` if you added `--publish`).
+
+---
+
+## Example 3 — "make the earlier settings screen darker" (revision)
+
+**Resolved as a revision** (it iterates on a fig from Example 1, not a new screen).
+
+**Resolve the prior id:** if the settings fig was created earlier in this session, reuse the
+id it printed. Otherwise list and match by title/area:
+
+```bash
+bunx figura-cli fig list --json --area settings
+```
+
+Pick the matching row's `id` (ask if more than one plausibly matches). Then fetch its HTML:
+
+```bash
+bunx figura-cli fig open <priorFigId> --print
+```
+
+**Edit on top of it:** keep the same structure (header, grouped rows, sticky save bar) and
+re-tint the surfaces to neutral **dark** values — near-black canvas, raised dark surfaces for
+the cards/rows, light text — keeping the SAME single accent hue for active toggles. Don't
+regenerate from scratch; preserve the design system.
+
+**Persist as a new version:**
+
+```bash
+cat <<'HTML' | bunx figura-cli fig revise <priorFigId> \
+  --title "Settings — darker theme" \
+  --tags settings,toggles,dark \
+  --publish
+… the updated document …
+HTML
+```
+
+The result JSON includes `version` (e.g. `2`) and `rootFigId`. Report it as "revision v2 of
+\<root\>" plus the shareable `url` if published. `--area`/`--orientation` were inherited from
+the parent, so they didn't need to be passed again.