figura-cli 0.8.1 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Command-line client for the Figura visualization SaaS",
   "license": "MIT",
   "type": "module",
@@ -28,11 +28,13 @@
     "node": ">=20"
   },
   "scripts": {
+    "gen-skill": "bun run scripts/gen-skill-reference.ts",
     "build": "bun run scripts/bundle-skill.mjs && bun build src/index.ts --target=node --minify --outfile=dist/index.js && bun build ../mcp/src/index.ts --target=node --minify --outfile=dist/mcp.js",
     "dev": "bun run src/index.ts",
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
+    "@panofm/figura-core": "workspace:*",
     "@types/node": "^20.14.0",
     "axios": "^1.7.9",
     "postgres": "^3.4.9",

package/skills/figura-fig/SKILL.md

@@ -5,6 +5,9 @@ argument-hint: '<what to visualize>'
 allowed-tools: 'Bash(figura *), Bash(bunx figura-cli *)'
 ---
 
+<!-- GENERATED — do not edit by hand. Source of truth: packages/core/src/fig/* via
+     packages/cli/scripts/gen-skill-reference.ts (run `bun run gen-skill`). -->
+
 # Figura Fig
 
 Generate ONE self-contained, on-brand HTML fig and persist it to the user's Figura team.
@@ -77,9 +80,10 @@ bunx figura-cli brand --json
 This returns `{ name, appDescription, tokensBlock, forbidden, surfaces, isCustom }`
 (`forbidden` is a string, `surfaces` is a string[]).
 
-- 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: true`** — treat the returned `tokensBlock` as the **design system that
+  wins conflicts** (palette, type, spacing, icon language) and render for `name` /
+  `appDescription`. If anything in the request conflicts with the design system, the design
+  system takes priority. 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.
@@ -97,7 +101,7 @@ engine's own generator does):
 
 **Pick the platform** from the request:
 
-- **`mobile`** (default) — an iPhone-framed app screen.
+- **`mobile`** (default) — an iPhone 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.
 
@@ -121,15 +125,29 @@ Produce ONE complete, self-contained HTML document. Whatever the platform, it MU
   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**.
+  width ~1.6) — **NO emojis anywhere**.
 - 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.
+**Mobile platform — FRAMLESS device screen.** Render the **screen contents only, at EXACTLY
+the device's logical screen size, with NO drawn phone bezel / outer border / rounded outer
+frame / notch or Dynamic-Island cutout** — the Figura viewer draws the physical device frame
++ Dynamic Island around your output, so a fig fits a real phone 1:1.
+
+- Portrait: render at **393×852** logical px. Landscape: **852×393**.
+- Lock the body to that size and fill it edge-to-edge (no outer page padding):
+  `body { margin:0; width:393px; height:852px; background:#0A0A0A; overflow:hidden; }` (swap W/H for landscape).
+- Reserve the OS-chrome safe areas: keep the top ~59px (status bar / Dynamic
+  Island) and bottom ~34px (home indicator) clear of critical controls
+  (landscape: top ~59px, bottom ~21px).
+- **Emit `<meta name="figura:artboard" content="393x852">`** (the exact W×H you
+  rendered to) so the viewer can frame it. A `.preview` media area is OPTIONAL — include it
+  only if the design calls for a hero/media region, sized to the design (any aspect ratio).
+- Hand-roll controls with the pill/capsule convention (see `reference/brand-tokens.md`); do
+  not rely on system/OS chrome.
+
+(`compare` and `both` are multi-screen comparison layouts — render each screen at the size
+above on a canvas that grows to fit them all, and do NOT emit a single `figura:artboard` meta.)
 
 **Web platform** — render a **browser window** instead (no phone frame):
 
@@ -141,6 +159,19 @@ not rely on system/OS chrome.
 .frame-web .viewport { /* full-bleed RESPONSIVE content — nav, hero, sections */ }
 ```
 
+**Hard rules (apply to every fig):**
+
+- NO emojis anywhere. Represent every icon as inline stroke SVG via <symbol>/<use> (currentColor, width ~1.6).
+- Plain HTML + INLINE CSS ONLY (a single <style> in <head>). No external stylesheets, no fonts loaded over the network, no frameworks.
+- ABSOLUTELY NO <script> tags and NO on* event handlers (onclick, onload, etc.). The fig must be fully static and render its state with CSS alone. It runs in a sandboxed iframe.
+
+**Visual quality (intentional and crafted — never generic "AI" UI):**
+
+- Color: 3–5 colors total, drawn from the design system — one primary, 2–3 neutrals, 1–2 accents; never exceed 5. If you override a background color, also override its text color for contrast.
+- Type: at most 2 font families (headings + body). No decorative fonts for body. Clear hierarchy.
+- NEVER add filler decoration: no gradient circles, blurry blobs, or abstract shapes as ornament. Avoid gradients unless the design system calls for them; prefer solid colors.
+- Real, specific content (no lorem ipsum, no "Title goes here"). Generous, consistent spacing. A clear visual identity — not a bland gray/white template.
+
 ### 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

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

@@ -1,5 +1,8 @@
 # Figura Fig — neutral default tokens (no team brand set)
 
+<!-- GENERATED — do not edit by hand. Source of truth: packages/core/src/fig/* via
+     packages/cli/scripts/gen-skill-reference.ts (run `bun run gen-skill`). -->
+
 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.
@@ -10,7 +13,7 @@ Keep it understated and professional.
 
 | Role | Value | Usage |
 |------|-------|-------|
-| Canvas | `#0E0E10` | Near-black base background. |
+| Canvas | `#0A0A0A` | Near-black base background (the fig screen). |
 | Surface | `#161618` | Cards / raised surfaces. |
 | Text | `#F4F4F6` | Primary text. |
 | Text muted | `#9aa0ad` | Secondary text, captions. |
@@ -37,43 +40,33 @@ An 8px spacing rhythm; 12–16px corner radii; 1px hairline borders; restrained
 
 ## 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.
+Inline SVG icons — define <symbol> elements in a hidden <svg> at the top of <body> and reference with <use href="#id"/>. Stroke icons (currentColor stroke, width ~1.6). NO emojis anywhere.
 
-**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; }
-```
+## Framless iPhone screen — CSS conventions
 
-**PORTRAIT phone (the common case):**
+Mobile figs are **FRAMLESS**: render the screen contents ONLY, at the device's exact logical
+screen size, with **NO drawn phone bezel / outer border / rounded outer frame / notch or
+Dynamic-Island cutout** — the Figura viewer draws the physical device frame + island around
+your output, so a fig fits a real phone 1:1. Lock the body to the screen size and emit a
+`<meta name="figura:artboard" content="WxH">` with that size.
 
-```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; }
-```
+| Orientation | Logical screen | Safe area top | Safe area bottom |
+|-------------|----------------|---------------|------------------|
+| Portrait | 393×852 | 59px | 34px |
+| Landscape | 852×393 | 59px | 21px |
 
-**LANDSCAPE phone (wide window, side island):**
+**Reset + body (lock to the screen size, fill edge-to-edge):**
 
 ```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; }
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { margin: 0; width: 393px; height: 852px; background: #0A0A0A; color: #F4F4F6; font-family: Inter, -apple-system, BlinkMacSystemFont, system-ui, sans-serif; overflow: hidden; }   /* swap W/H for landscape */
 ```
 
-**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):
+**Screen surface + 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; }
+.screen { position: absolute; inset: 0; background: #0A0A0A; 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)); }
 ```
@@ -88,31 +81,35 @@ region — size it to the design, any aspect ratio; there is no fixed film ratio
 .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):**
+**Annotation chips — yellow callouts pinned over the screen (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).
+**Inline SVG icons:** Inline SVG icons — define <symbol> elements in a hidden <svg> at the top of <body> and reference with <use href="#id"/>. Stroke icons (currentColor stroke, width ~1.6). NO emojis anywhere.
 
 ## 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.
+- Render the screen contents at EXACTLY the chosen orientation's logical size with NO device
+  frame/bezel/notch — the Figura viewer draws the physical phone frame around your output.
+- Emit `<meta name="figura:artboard" content="WxH">` with the exact logical screen size.
+- NO emojis anywhere. Represent every icon as inline stroke SVG via <symbol>/<use> (currentColor, width ~1.6).
 - 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).
+- Plain HTML + INLINE CSS ONLY (a single <style> in <head>). No external stylesheets, no fonts loaded over the network, no frameworks.
+- ABSOLUTELY NO <script> tags and NO on* event handlers (onclick, onload, etc.). The fig must be fully static and render its state with CSS alone. It runs in a sandboxed iframe.
+
+## Visual quality (intentional and crafted — never generic "AI" UI)
+
+- Color: 3–5 colors total, drawn from the design system — one primary, 2–3 neutrals, 1–2 accents; never exceed 5. If you override a background color, also override its text color for contrast.
+- Type: at most 2 font families (headings + body). No decorative fonts for body. Clear hierarchy.
+- NEVER add filler decoration: no gradient circles, blurry blobs, or abstract shapes as ornament. Avoid gradients unless the design system calls for them; prefer solid colors.
+- Real, specific content (no lorem ipsum, no "Title goes here"). Generous, consistent spacing. A clear visual identity — not a bland gray/white template.
 
 ## 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.
+- Respond with ONLY a complete HTML document. Start at <!DOCTYPE html>. No markdown code fences, no backticks, no prose before or after.
+- Set <title> to a short, descriptive fig title.
+- Include a meta tag summarizing the design intent: <meta name="figura:context" content="...">.
 - An `<h1>` naming the screen.

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

@@ -10,11 +10,13 @@ self-contained HTML document and persists it to the Figura team via `bunx figura
 
 **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,
+**Generated document:** a FRAMLESS portrait screen rendered at exactly 393×852 (no drawn phone
+bezel — the viewer frames it), with `<meta name="figura:artboard" content="393x852">`. 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).
+pinned over the screen, kept clear of the ~34px bottom safe area. 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