@efectoapp/mcp-studio 0.1.0

package/skills/STUDIO-SKILL.md

@@ -0,0 +1,802 @@
+# Efecto Studio — Design Web Pages with AI
+
+Efecto Studio is a real-time web design tool that AI agents control programmatically. You create a **session**, the user opens a URL in their browser, and you push design commands that render instantly. Every node maps to a real HTML element styled with Tailwind CSS — web-native, semantic, and pixel-accurate.
+
+**Prerequisite**: The `efectostudio` MCP server must be configured (`npx @efectoapp/mcp-studio install`), or you must have access to the Studio session REST API.
+
+---
+
+## How Sessions Work
+
+```
+Agent ──POST /execute──> Server ──SSE──> Browser (renders live)
+Agent <──poll/response── Server <──POST── Browser (returns results)
+```
+
+1. You create a session via the MCP server or REST API
+2. The user opens the returned Studio URL in their browser
+3. You push tool calls — each one executes in the browser and returns a result
+4. The user sees every change live as you build the design
+
+Sessions expire after 15 minutes of inactivity. The browser must be connected before tool calls can execute.
+
+---
+
+## Quick Start — Build a Page in 7 Steps
+
+### Step 1: Create a Session
+```
+create_session
+  label: "Landing page design"
+```
+Returns `{ sessionId, studioUrl }`. Tell the user to open `studioUrl`. The session ID is stored automatically — all subsequent tools use it.
+
+### Step 2: Wait for Browser Connection
+```
+session_status
+```
+Poll until `browserConnected: true`. The browser must be open before you can push tools.
+
+### Step 3: Create an Artboard
+```
+create_artboard
+  name: "Homepage"
+  width: 1440
+  height: 900
+  backgroundColor: "#ffffff"
+  className: "flex flex-col"
+```
+Returns the artboard ID. **Always set className to "flex flex-col"** so children stack vertically.
+
+### Step 4: Add Sections with JSX
+```
+add_section
+  parentId: "<artboard-id>"
+  jsx: '<nav className="flex items-center justify-between px-16 py-5 bg-white w-full">
+    <h2 className="text-xl font-bold text-gray-900">Acme</h2>
+    <div className="flex items-center gap-8">
+      <a className="text-sm text-gray-600" href="#">Features</a>
+      <a className="text-sm text-gray-600" href="#">Pricing</a>
+      <button className="px-4 py-2 text-sm font-medium text-white bg-gray-900 rounded-lg">Get Started</button>
+    </div>
+  </nav>'
+```
+This is the most efficient way to build complex layouts — one JSX string per section.
+
+### Step 5: Read Current State
+```
+get_document
+```
+Returns JSX-like markup with `data-id` attributes on every node. Use these IDs for updates.
+
+### Step 6: Fine-Tune with Updates
+```
+batch_update
+  updates: [
+    { nodeId: "abc", className: "text-2xl font-extrabold text-gray-900" },
+    { nodeId: "def", textContent: "Updated heading text" }
+  ]
+```
+
+### Step 7: Iterate
+Repeat Steps 4-6 to add more sections, adjust styling, and refine the design. The user sees every change in real time.
+
+---
+
+## The 33 Studio Tools
+
+### Reading State
+
+| Tool | Purpose |
+|------|---------|
+| `get_document` | Returns full document as JSX with data-id attributes |
+| `list_artboards` | Lists all artboards with IDs, names, dimensions |
+| `find_nodes` | Search nodes by name, text content, type, or className |
+
+### Creating Content
+
+| Tool | Purpose |
+|------|---------|
+| `create_artboard` | Creates a new artboard (screen/frame) |
+| `add_section` | Adds complex layouts from JSX markup (preferred) |
+| `add_node` | Adds a single node to a parent |
+
+### Modifying Content
+
+| Tool | Purpose |
+|------|---------|
+| `update_node` | Updates any node property (className, textContent, tag, style, src, etc.) |
+| `update_class` | Shortcut: replaces only className on a node |
+| `update_artboard` | Updates artboard properties (name, size, background, className) |
+| `batch_update` | Updates multiple nodes in one call (bulk styling) |
+| `replace_section` | Replaces a node and its children with new JSX |
+
+### Organizing Structure
+
+| Tool | Purpose |
+|------|---------|
+| `move_node` | Reparents or reorders a node |
+| `duplicate_node` | Deep-clones a node with fresh IDs |
+| `duplicate_artboard` | Deep-clones an artboard for variations |
+| `group_nodes` | Wraps selected nodes in a frame container |
+| `ungroup_node` | Unwraps a group, moving children to parent |
+| `reorder_node` | Brings to front or sends to back (z-order) |
+
+### Display & Selection
+
+| Tool | Purpose |
+|------|---------|
+| `select_nodes` | Highlights nodes for the user to see |
+| `set_visibility` | Shows/hides nodes (like Figma eye icon) |
+| `delete_nodes` | Deletes nodes and their children |
+| `delete_artboard` | Deletes an artboard and all contents |
+
+### Alignment & Distribution
+
+| Tool | Purpose |
+|------|---------|
+| `align_nodes` | Aligns multiple nodes (left/center/right/top/middle/bottom) |
+| `distribute_nodes` | Distributes nodes evenly (horizontal/vertical) |
+
+### History
+
+| Tool | Purpose |
+|------|---------|
+| `undo` | Undoes the last action (Cmd+Z) |
+| `redo` | Redoes the last undone action (Cmd+Shift+Z) |
+
+### Viewport & Document
+
+| Tool | Purpose |
+|------|---------|
+| `zoom_to_artboard` | Zooms viewport to show a specific artboard |
+| `zoom_to_fit` | Zooms to fit all artboards in the viewport |
+| `set_viewport` | Sets viewport zoom level and/or pan position |
+| `rename_document` | Renames the Studio document |
+| `new_document` | Creates a new blank document (replaces current) |
+
+### Canvas & Reading
+
+| Tool | Purpose |
+|------|---------|
+| `move_artboard` | Repositions an artboard on the canvas for multi-screen flows |
+| `deselect_all` | Clears the current node selection |
+| `get_node_tree` | Returns JSX for one node/artboard subtree (faster than full document) |
+
+---
+
+## Node Types & HTML Tags
+
+Every node maps 1:1 to an HTML element. The `type` determines behavior; the `tag` determines which HTML element renders.
+
+| Type | Default Tag | All Valid Tags | Content Property |
+|------|-------------|----------------|-----------------|
+| **frame** | `div` | div, section, article, aside, main, nav, header, footer, ul, ol, li, figure, figcaption, form, table, thead, tbody, tr, th, td | (none — pure container) |
+| **text** | `p` | p, span, h1, h2, h3, h4, h5, h6, blockquote, label, li | `textContent` |
+| **image** | `img` | img | `src`, `alt`, `objectFit` |
+| **button** | `button` | button, a, div | `textContent`, `variant` |
+| **link** | `a` | a, button, div, span | `textContent`, `href`, `target` |
+| **icon** | `svg` | svg, div | `iconName` (Phosphor, PascalCase) |
+| **input** | `input` | input, textarea, select | `placeholder`, `inputType`, `label` |
+| **video** | `video` | video | `src`, `poster`, `autoPlay`, `loop`, `muted` |
+| **component** | `div` | div | `componentId`, `overrides` |
+
+### Tag Determines Type in JSX
+
+When writing JSX for `add_section`, the HTML tag determines the node type:
+
+```
+<div>       -> frame       <img>        -> image
+<section>   -> frame       <button>     -> button
+<nav>       -> frame       <a>          -> link
+<header>    -> frame       <input>      -> input
+<footer>    -> frame       <video>      -> video
+<h1>-<h6>   -> text        <svg>        -> icon
+<p>         -> text
+<span>      -> text
+```
+
+---
+
+## The `add_section` JSX Format
+
+This is the primary way to build layouts. Write standard JSX with HTML tags and Tailwind `className` attributes.
+
+### Format Rules
+
+1. **Use HTML tags** — div, section, nav, h1, p, img, button, a, etc.
+2. **Style with className** — Tailwind CSS classes only
+3. **Text goes between tags** — `<h1 className="...">Hello</h1>`
+4. **Images are self-closing** — `<img src="https://..." alt="..." className="..." />`
+5. **Use `data-id`** only when referencing existing nodes (from `get_document`)
+6. **No React-specific syntax** — no `onClick`, `useState`, fragments, or components
+
+### Example: Complete Section
+
+```jsx
+<section className="flex flex-col items-center gap-12 px-16 py-24 bg-white w-full">
+  <div className="flex flex-col items-center gap-4 max-w-2xl">
+    <span className="text-sm font-semibold text-blue-600 uppercase tracking-widest">Why Choose Us</span>
+    <h2 className="text-4xl font-bold text-gray-900 text-center">Everything you need to scale</h2>
+    <p className="text-lg text-gray-500 text-center">Built for modern teams that move fast and ship faster.</p>
+  </div>
+  <div className="flex gap-8 w-full max-w-5xl">
+    <div className="flex flex-col gap-3 p-8 bg-gray-50 rounded-2xl grow">
+      <h3 className="text-lg font-semibold text-gray-900">Lightning Fast</h3>
+      <p className="text-sm text-gray-500">Deploy in seconds, not hours. Our edge network ensures sub-50ms latency worldwide.</p>
+    </div>
+    <div className="flex flex-col gap-3 p-8 bg-gray-50 rounded-2xl grow">
+      <h3 className="text-lg font-semibold text-gray-900">Enterprise Security</h3>
+      <p className="text-sm text-gray-500">SOC 2 certified with end-to-end encryption. Your data stays yours.</p>
+    </div>
+    <div className="flex flex-col gap-3 p-8 bg-gray-50 rounded-2xl grow">
+      <h3 className="text-lg font-semibold text-gray-900">24/7 Support</h3>
+      <p className="text-sm text-gray-500">Our team is always on. Get answers in minutes, not days.</p>
+    </div>
+  </div>
+</section>
+```
+
+---
+
+## Tailwind CSS Patterns That Work
+
+### Layout
+```
+flex                    /* Horizontal flex row */
+flex flex-col           /* Vertical flex column */
+items-center            /* Center cross-axis */
+items-start             /* Align to start */
+justify-between         /* Space between children */
+justify-center          /* Center main-axis */
+gap-2 gap-4 gap-8      /* Gap between flex children */
+grow                    /* Fill remaining space (DO NOT use flex-1) */
+```
+
+### Spacing
+```
+p-4 p-6 p-8 p-12       /* Padding all sides */
+px-6 py-4               /* Horizontal / vertical padding */
+pt-8 pb-16              /* Top / bottom padding */
+mx-auto                 /* Center horizontally */
+```
+
+### Sizing
+```
+w-full                  /* Full width of parent */
+w-auto                  /* Width from content */
+w-fit                   /* Shrink-wrap width */
+w-[600px]               /* Fixed pixel width */
+max-w-2xl max-w-5xl     /* Maximum width constraints */
+min-h-screen            /* Minimum full viewport height */
+h-[400px]               /* Fixed pixel height */
+```
+
+### Typography
+```
+text-xs text-sm text-base text-lg text-xl text-2xl text-3xl text-4xl text-5xl text-6xl text-7xl text-8xl text-9xl
+font-light font-normal font-medium font-semibold font-bold font-extrabold font-black
+leading-tight leading-snug leading-normal leading-relaxed
+tracking-tight tracking-normal tracking-wide tracking-widest
+text-left text-center text-right
+uppercase lowercase capitalize
+```
+
+### Colors (NAMED ONLY)
+
+Use named Tailwind colors. **Never use arbitrary hex** like `bg-[#f9f9f9]` — it silently fails at runtime.
+
+```
+/* Backgrounds */
+bg-white bg-black bg-gray-50 bg-gray-100 bg-gray-900 bg-neutral-950
+bg-blue-50 bg-blue-500 bg-blue-600 bg-indigo-500 bg-purple-500
+bg-green-50 bg-green-500 bg-red-50 bg-red-500 bg-amber-50 bg-yellow-400
+
+/* Text */
+text-white text-black text-gray-400 text-gray-500 text-gray-600 text-gray-700 text-gray-900
+text-blue-600 text-blue-500 text-indigo-600 text-green-600 text-red-600
+
+/* Borders */
+border-gray-100 border-gray-200 border-gray-300 border-blue-500
+
+/* If you MUST use a specific hex color, use inline style instead: */
+style: { "background-color": "#f9f9f9" }
+```
+
+### Borders & Radius
+```
+border border-2                      /* Border width */
+border-gray-200 border-gray-300      /* Border color */
+rounded rounded-lg rounded-xl rounded-2xl rounded-full  /* Border radius */
+```
+
+### Effects
+```
+shadow-sm shadow shadow-md shadow-lg shadow-xl
+opacity-50 opacity-75
+ring-1 ring-2 ring-blue-500          /* Ring / outline */
+```
+
+### Gradients
+```
+bg-gradient-to-r from-blue-500 to-purple-500
+bg-gradient-to-b from-white to-gray-50
+bg-gradient-to-br from-indigo-500 via-purple-500 to-pink-500
+```
+
+---
+
+## Artboard Best Practices
+
+### Standard Sizes
+| Name | Width | Height | Use Case |
+|------|-------|--------|----------|
+| Desktop | 1440 | 900+ | Full website pages |
+| Desktop (narrow) | 1280 | 800+ | Content-focused pages |
+| Tablet | 768 | 1024 | Tablet responsive view |
+| Mobile | 375 | 812 | iPhone / mobile view |
+
+### Always Start With
+```
+create_artboard:
+  name: "Homepage"
+  width: 1440
+  height: 900
+  backgroundColor: "#ffffff"
+  className: "flex flex-col"
+```
+
+- **`className: "flex flex-col"`** is essential — without it, children overlap at (0,0)
+- **`backgroundColor`** is an inline style property, NOT a Tailwind class
+- Height grows automatically when content overflows, but set an initial height
+
+---
+
+## Common Section Patterns
+
+### Navigation Bar
+
+```jsx
+<nav className="flex items-center justify-between px-16 py-5 bg-white w-full border-b border-gray-100">
+  <h2 className="text-xl font-bold text-gray-900">Acme</h2>
+  <div className="flex items-center gap-8">
+    <a className="text-sm font-medium text-gray-600" href="#">Features</a>
+    <a className="text-sm font-medium text-gray-600" href="#">Pricing</a>
+    <a className="text-sm font-medium text-gray-600" href="#">About</a>
+    <button className="px-5 py-2.5 text-sm font-medium text-white bg-gray-900 rounded-lg">Get Started</button>
+  </div>
+</nav>
+```
+
+### Hero Section (Centered)
+
+```jsx
+<section className="flex flex-col items-center justify-center gap-8 px-16 py-32 bg-white w-full">
+  <div className="flex flex-col items-center gap-6 max-w-3xl">
+    <span className="px-4 py-1.5 text-xs font-semibold text-blue-700 bg-blue-50 rounded-full uppercase tracking-wider">Now in Beta</span>
+    <h1 className="text-6xl font-bold text-gray-900 text-center leading-tight">Build beautiful websites at the speed of thought</h1>
+    <p className="text-xl text-gray-500 text-center">The AI-powered design tool that turns ideas into production-ready pages. No code required.</p>
+  </div>
+  <div className="flex items-center gap-4">
+    <button className="px-8 py-3.5 text-base font-semibold text-white bg-blue-600 rounded-xl">Start Free Trial</button>
+    <button className="px-8 py-3.5 text-base font-semibold text-gray-700 bg-white border-2 border-gray-200 rounded-xl">Watch Demo</button>
+  </div>
+</section>
+```
+
+### Hero Section (Split — Text Left, Image Right)
+
+```jsx
+<section className="flex items-center gap-16 px-16 py-24 bg-white w-full">
+  <div className="flex flex-col gap-6 grow">
+    <h1 className="text-5xl font-bold text-gray-900 leading-tight">Ship your next product in record time</h1>
+    <p className="text-lg text-gray-500">From prototype to production in minutes. Our platform handles the complexity so you can focus on what matters.</p>
+    <div className="flex items-center gap-4">
+      <button className="px-6 py-3 text-base font-semibold text-white bg-gray-900 rounded-lg">Get Started</button>
+      <a className="text-base font-medium text-gray-600" href="#">Learn more</a>
+    </div>
+  </div>
+  <img src="https://placehold.co/600x400" alt="Product screenshot" className="w-[560px] h-[380px] rounded-2xl object-cover bg-gray-100" />
+</section>
+```
+
+### Feature Grid (3 columns)
+
+```jsx
+<section className="flex flex-col items-center gap-16 px-16 py-24 bg-gray-50 w-full">
+  <div className="flex flex-col items-center gap-4 max-w-2xl">
+    <h2 className="text-4xl font-bold text-gray-900 text-center">Powerful features for modern teams</h2>
+    <p className="text-lg text-gray-500 text-center">Everything you need to design, build, and ship — all in one place.</p>
+  </div>
+  <div className="flex gap-8 w-full max-w-6xl">
+    <div className="flex flex-col gap-4 p-8 bg-white rounded-2xl shadow-sm grow">
+      <div className="flex items-center justify-center w-12 h-12 bg-blue-100 rounded-xl">
+        <span className="text-blue-600 text-lg font-bold">1</span>
+      </div>
+      <h3 className="text-xl font-semibold text-gray-900">Real-Time Collaboration</h3>
+      <p className="text-sm text-gray-500 leading-relaxed">Work together with your team in real time. See cursors, selections, and changes as they happen.</p>
+    </div>
+    <div className="flex flex-col gap-4 p-8 bg-white rounded-2xl shadow-sm grow">
+      <div className="flex items-center justify-center w-12 h-12 bg-green-100 rounded-xl">
+        <span className="text-green-600 text-lg font-bold">2</span>
+      </div>
+      <h3 className="text-xl font-semibold text-gray-900">One-Click Deploy</h3>
+      <p className="text-sm text-gray-500 leading-relaxed">Push to production with a single click. Built-in CI/CD, preview deployments, and rollbacks.</p>
+    </div>
+    <div className="flex flex-col gap-4 p-8 bg-white rounded-2xl shadow-sm grow">
+      <div className="flex items-center justify-center w-12 h-12 bg-purple-100 rounded-xl">
+        <span className="text-purple-600 text-lg font-bold">3</span>
+      </div>
+      <h3 className="text-xl font-semibold text-gray-900">AI Assistant</h3>
+      <p className="text-sm text-gray-500 leading-relaxed">Built-in AI that understands your codebase. Generate components, fix bugs, and refactor with natural language.</p>
+    </div>
+  </div>
+</section>
+```
+
+### Testimonial / Social Proof
+
+```jsx
+<section className="flex flex-col items-center gap-12 px-16 py-24 bg-white w-full">
+  <div className="flex flex-col items-center gap-6 max-w-2xl">
+    <p className="text-2xl text-gray-700 text-center leading-relaxed italic">"This tool completely transformed our workflow. We shipped our redesign in two weeks instead of two months."</p>
+    <div className="flex items-center gap-4">
+      <div className="w-12 h-12 bg-gray-200 rounded-full"></div>
+      <div className="flex flex-col">
+        <span className="text-sm font-semibold text-gray-900">Sarah Chen</span>
+        <span className="text-sm text-gray-500">VP of Design, Stripe</span>
+      </div>
+    </div>
+  </div>
+  <div className="flex items-center gap-12">
+    <span className="text-sm font-medium text-gray-400">Trusted by</span>
+    <span className="text-lg font-bold text-gray-300">Stripe</span>
+    <span className="text-lg font-bold text-gray-300">Vercel</span>
+    <span className="text-lg font-bold text-gray-300">Linear</span>
+    <span className="text-lg font-bold text-gray-300">Notion</span>
+    <span className="text-lg font-bold text-gray-300">Figma</span>
+  </div>
+</section>
+```
+
+### Pricing Cards
+
+```jsx
+<section className="flex flex-col items-center gap-12 px-16 py-24 bg-gray-50 w-full">
+  <div className="flex flex-col items-center gap-4">
+    <h2 className="text-4xl font-bold text-gray-900">Simple, transparent pricing</h2>
+    <p className="text-lg text-gray-500">No surprise fees. Cancel anytime.</p>
+  </div>
+  <div className="flex gap-8 w-full max-w-4xl">
+    <div className="flex flex-col gap-6 p-8 bg-white rounded-2xl border border-gray-200 grow">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold text-gray-900">Starter</h3>
+        <div className="flex items-baseline gap-1">
+          <span className="text-4xl font-bold text-gray-900">$19</span>
+          <span className="text-sm text-gray-500">/month</span>
+        </div>
+        <p className="text-sm text-gray-500">Perfect for individuals and small projects.</p>
+      </div>
+      <button className="w-full py-3 text-sm font-semibold text-gray-700 bg-gray-100 rounded-lg">Get Started</button>
+    </div>
+    <div className="flex flex-col gap-6 p-8 bg-gray-900 rounded-2xl grow">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold text-white">Pro</h3>
+        <div className="flex items-baseline gap-1">
+          <span className="text-4xl font-bold text-white">$49</span>
+          <span className="text-sm text-gray-400">/month</span>
+        </div>
+        <p className="text-sm text-gray-400">For growing teams that need more power.</p>
+      </div>
+      <button className="w-full py-3 text-sm font-semibold text-gray-900 bg-white rounded-lg">Get Started</button>
+    </div>
+    <div className="flex flex-col gap-6 p-8 bg-white rounded-2xl border border-gray-200 grow">
+      <div className="flex flex-col gap-2">
+        <h3 className="text-lg font-semibold text-gray-900">Enterprise</h3>
+        <div className="flex items-baseline gap-1">
+          <span className="text-4xl font-bold text-gray-900">$99</span>
+          <span className="text-sm text-gray-500">/month</span>
+        </div>
+        <p className="text-sm text-gray-500">For large organizations with custom needs.</p>
+      </div>
+      <button className="w-full py-3 text-sm font-semibold text-gray-700 bg-gray-100 rounded-lg">Contact Sales</button>
+    </div>
+  </div>
+</section>
+```
+
+### CTA (Call to Action)
+
+```jsx
+<section className="flex flex-col items-center gap-8 px-16 py-24 bg-gray-900 w-full">
+  <h2 className="text-4xl font-bold text-white text-center">Ready to get started?</h2>
+  <p className="text-lg text-gray-400 text-center max-w-xl">Join thousands of teams already building faster. Start your free trial today.</p>
+  <div className="flex items-center gap-4">
+    <button className="px-8 py-3.5 text-base font-semibold text-gray-900 bg-white rounded-xl">Start Free Trial</button>
+    <button className="px-8 py-3.5 text-base font-semibold text-gray-300 bg-transparent border border-gray-700 rounded-xl">Talk to Sales</button>
+  </div>
+</section>
+```
+
+### Footer
+
+```jsx
+<footer className="flex items-center justify-between px-16 py-8 bg-white border-t border-gray-100 w-full">
+  <span className="text-sm text-gray-500">2026 Acme Inc. All rights reserved.</span>
+  <div className="flex items-center gap-6">
+    <a className="text-sm text-gray-500" href="#">Privacy</a>
+    <a className="text-sm text-gray-500" href="#">Terms</a>
+    <a className="text-sm text-gray-500" href="#">Contact</a>
+  </div>
+</footer>
+```
+
+### Stats / Metrics Row
+
+```jsx
+<section className="flex items-center justify-center gap-16 px-16 py-16 bg-blue-600 w-full">
+  <div className="flex flex-col items-center gap-2">
+    <span className="text-4xl font-bold text-white">10K+</span>
+    <span className="text-sm text-blue-200">Active Users</span>
+  </div>
+  <div className="flex flex-col items-center gap-2">
+    <span className="text-4xl font-bold text-white">99.9%</span>
+    <span className="text-sm text-blue-200">Uptime SLA</span>
+  </div>
+  <div className="flex flex-col items-center gap-2">
+    <span className="text-4xl font-bold text-white">50ms</span>
+    <span className="text-sm text-blue-200">Avg Latency</span>
+  </div>
+  <div className="flex flex-col items-center gap-2">
+    <span className="text-4xl font-bold text-white">4.9/5</span>
+    <span className="text-sm text-blue-200">User Rating</span>
+  </div>
+</section>
+```
+
+---
+
+## Tips, Gotchas, and Best Practices
+
+### The Golden Rules
+
+1. **Always `get_document` first** before modifying an existing design. You need the `data-id` attributes.
+2. **Never guess node IDs** — always read them from `get_document` or `find_nodes`.
+3. **Use `add_section` with JSX** for building structures. It is far more efficient than `add_node` one element at a time.
+4. **Use `batch_update`** for multiple small changes. One call instead of many.
+5. **Prefer updating over deleting and recreating.** Use `update_node` or `update_class`.
+
+### Critical Gotchas
+
+**Artboard className must include `flex flex-col`**
+Without it, children overlap at (0,0). This is the #1 mistake.
+
+**Artboard backgroundColor is a property, NOT a className**
+```
+WRONG:  className: "bg-gray-900 flex flex-col"
+RIGHT:  backgroundColor: "#1a1a1a", className: "flex flex-col"
+```
+
+**Never use arbitrary hex colors in className**
+Tailwind 4 generates CSS at build time. Dynamic classes like `bg-[#f9f9f9]` have no CSS at runtime and are invisible.
+```
+WRONG:  className: "bg-[#f9f9f9] text-[#333333]"
+RIGHT:  className: "bg-gray-50 text-gray-700"
+ALSO OK: style: { "background-color": "#f9f9f9", "color": "#333333" }
+```
+Note: The system auto-converts arbitrary hex to inline styles, but prefer named colors.
+
+**`flex-1` does not work — use `grow` instead**
+`flex-1` gets classified as unmapped by the Tailwind bridge. Use `grow` for the same effect.
+
+**Frame nodes have no textContent**
+Frame types (div, section, nav, header, footer) cannot hold text directly. Use text nodes (h1, p, span) inside them.
+
+**Button nodes ignore children**
+The button renderer only uses `textContent`. Do not nest icons or other elements inside buttons — place them as siblings.
+
+**Top-level sections need `w-full`**
+The auto-fixer adds this, but always include `w-full` on direct children of the artboard so they span the full width.
+
+**Images without `src` get a placeholder**
+If you omit `src`, the system inserts `https://placehold.co/600x400`. Always provide a real src for production designs.
+
+### Design Tips
+
+- **Max-width containers**: Use `max-w-5xl` or `max-w-6xl` centered with content inside for readable text widths
+- **Consistent spacing**: Use the Tailwind spacing scale (4, 6, 8, 12, 16, 24 are common section padding values)
+- **Color hierarchy**: Use gray-900 for headings, gray-500 for body text, gray-400 for secondary text
+- **Section rhythm**: Alternate between white and gray-50 backgrounds for visual separation
+- **Button hierarchy**: Primary = solid dark, Secondary = outline or light background
+
+---
+
+## Complete Recipe: SaaS Landing Page
+
+Build a complete SaaS landing page from scratch — step by step.
+
+### Step 1: Create Session and Artboard
+
+```
+create_session
+  label: "SaaS Landing Page"
+```
+
+Wait for browser connection (`session_status`), then:
+
+```
+create_artboard:
+  name: "Landing Page"
+  width: 1440
+  height: 900
+  backgroundColor: "#ffffff"
+  className: "flex flex-col"
+```
+
+### Step 2: Navigation
+
+```
+add_section:
+  parentId: "<artboard-id>"
+  jsx: |
+    <nav className="flex items-center justify-between px-16 py-5 bg-white w-full border-b border-gray-100">
+      <div className="flex items-center gap-2">
+        <div className="w-8 h-8 bg-blue-600 rounded-lg"></div>
+        <h2 className="text-lg font-bold text-gray-900">Launchpad</h2>
+      </div>
+      <div className="flex items-center gap-8">
+        <a className="text-sm font-medium text-gray-600" href="#">Product</a>
+        <a className="text-sm font-medium text-gray-600" href="#">Features</a>
+        <a className="text-sm font-medium text-gray-600" href="#">Pricing</a>
+        <a className="text-sm font-medium text-gray-600" href="#">Docs</a>
+      </div>
+      <div className="flex items-center gap-3">
+        <a className="text-sm font-medium text-gray-600" href="#">Sign In</a>
+        <button className="px-5 py-2 text-sm font-medium text-white bg-blue-600 rounded-lg">Start Free</button>
+      </div>
+    </nav>
+```
+
+### Step 3: Hero
+
+```
+add_section:
+  parentId: "<artboard-id>"
+  jsx: |
+    <section className="flex flex-col items-center gap-10 px-16 py-32 bg-white w-full">
+      <div className="flex flex-col items-center gap-6 max-w-3xl">
+        <span className="px-4 py-1.5 text-xs font-semibold text-blue-700 bg-blue-50 rounded-full uppercase tracking-wider">New: AI-Powered Workflows</span>
+        <h1 className="text-6xl font-extrabold text-gray-900 text-center leading-tight tracking-tight">Ship products faster than ever before</h1>
+        <p className="text-xl text-gray-500 text-center leading-relaxed">The all-in-one platform for modern product teams. Design, build, test, and deploy from a single dashboard.</p>
+      </div>
+      <div className="flex items-center gap-4">
+        <button className="px-8 py-4 text-base font-semibold text-white bg-blue-600 rounded-xl">Start Free Trial</button>
+        <button className="px-8 py-4 text-base font-semibold text-gray-700 bg-white border-2 border-gray-200 rounded-xl">Watch Demo</button>
+      </div>
+      <p className="text-sm text-gray-400">Free for 14 days. No credit card required.</p>
+    </section>
+```
+
+### Step 4: Social Proof Bar
+
+```
+add_section:
+  parentId: "<artboard-id>"
+  jsx: |
+    <section className="flex items-center justify-center gap-12 px-16 py-12 bg-gray-50 border-y border-gray-100 w-full">
+      <span className="text-sm text-gray-400">Trusted by leading teams at</span>
+      <span className="text-lg font-bold text-gray-300">Stripe</span>
+      <span className="text-lg font-bold text-gray-300">Vercel</span>
+      <span className="text-lg font-bold text-gray-300">Linear</span>
+      <span className="text-lg font-bold text-gray-300">Notion</span>
+      <span className="text-lg font-bold text-gray-300">Figma</span>
+    </section>
+```
+
+### Step 5: Feature Grid
+
+```
+add_section:
+  parentId: "<artboard-id>"
+  jsx: |
+    <section className="flex flex-col items-center gap-16 px-16 py-24 bg-white w-full">
+      <div className="flex flex-col items-center gap-4 max-w-2xl">
+        <h2 className="text-4xl font-bold text-gray-900 text-center">Built for speed, designed for scale</h2>
+        <p className="text-lg text-gray-500 text-center">Powerful tools that grow with your team. No compromises.</p>
+      </div>
+      <div className="flex gap-6 w-full max-w-5xl">
+        <div className="flex flex-col gap-4 p-8 bg-gray-50 rounded-2xl grow">
+          <div className="flex items-center justify-center w-12 h-12 bg-blue-100 rounded-xl">
+            <span className="text-blue-600 font-bold">1</span>
+          </div>
+          <h3 className="text-lg font-semibold text-gray-900">Visual Editor</h3>
+          <p className="text-sm text-gray-500 leading-relaxed">Drag-and-drop interface with pixel-perfect precision. Design at the speed of thought.</p>
+        </div>
+        <div className="flex flex-col gap-4 p-8 bg-gray-50 rounded-2xl grow">
+          <div className="flex items-center justify-center w-12 h-12 bg-green-100 rounded-xl">
+            <span className="text-green-600 font-bold">2</span>
+          </div>
+          <h3 className="text-lg font-semibold text-gray-900">Instant Deploy</h3>
+          <p className="text-sm text-gray-500 leading-relaxed">One-click deployment to our global CDN. Preview environments for every branch.</p>
+        </div>
+        <div className="flex flex-col gap-4 p-8 bg-gray-50 rounded-2xl grow">
+          <div className="flex items-center justify-center w-12 h-12 bg-purple-100 rounded-xl">
+            <span className="text-purple-600 font-bold">3</span>
+          </div>
+          <h3 className="text-lg font-semibold text-gray-900">AI Copilot</h3>
+          <p className="text-sm text-gray-500 leading-relaxed">AI that understands your design system. Generate components, layouts, and content automatically.</p>
+        </div>
+      </div>
+    </section>
+```
+
+### Step 6: CTA
+
+```
+add_section:
+  parentId: "<artboard-id>"
+  jsx: |
+    <section className="flex flex-col items-center gap-8 px-16 py-24 bg-gray-900 w-full">
+      <h2 className="text-4xl font-bold text-white text-center">Start building today</h2>
+      <p className="text-lg text-gray-400 text-center max-w-xl">Join 10,000+ teams already shipping faster with Launchpad. Free trial, no strings attached.</p>
+      <div className="flex items-center gap-4">
+        <button className="px-8 py-4 text-base font-semibold text-gray-900 bg-white rounded-xl">Start Free Trial</button>
+        <button className="px-8 py-4 text-base font-semibold text-gray-300 bg-transparent border border-gray-700 rounded-xl">Talk to Sales</button>
+      </div>
+    </section>
+```
+
+### Step 7: Footer
+
+```
+add_section:
+  parentId: "<artboard-id>"
+  jsx: |
+    <footer className="flex items-center justify-between px-16 py-8 bg-gray-900 border-t border-gray-800 w-full">
+      <div className="flex items-center gap-2">
+        <div className="w-6 h-6 bg-blue-600 rounded-md"></div>
+        <span className="text-sm font-semibold text-gray-400">Launchpad</span>
+      </div>
+      <span className="text-sm text-gray-500">2026 Launchpad Inc. All rights reserved.</span>
+      <div className="flex items-center gap-6">
+        <a className="text-sm text-gray-500" href="#">Privacy</a>
+        <a className="text-sm text-gray-500" href="#">Terms</a>
+        <a className="text-sm text-gray-500" href="#">Status</a>
+      </div>
+    </footer>
+```
+
+### Step 8: Verify and Refine
+
+Call `get_document` to verify the structure. Use `batch_update` for any tweaks — adjust colors, spacing, or text content across multiple nodes at once.
+
+---
+
+## Responsive Design Workflow
+
+To create responsive variations:
+
+1. Build the desktop design (1440px) first
+2. Use `duplicate_artboard` to clone it for tablet (768px) and mobile (375px)
+3. Use `batch_update` to adjust:
+   - Switch horizontal flex rows to `flex flex-col` for stacking
+   - Reduce padding: `px-16` to `px-6`, `py-24` to `py-16`
+   - Scale down text: `text-6xl` to `text-4xl`, `text-4xl` to `text-2xl`
+   - Change gap values: `gap-8` to `gap-4`
+   - Change grid layouts: 3-column features to 1-column stack
+
+---
+
+## Dark Mode Design
+
+For dark-themed pages:
+
+1. Set artboard `backgroundColor: "#0a0a0a"` or `"#111111"`
+2. Use inverted color scale:
+   - Headings: `text-white` or `text-gray-100`
+   - Body: `text-gray-400`
+   - Secondary: `text-gray-500`
+   - Backgrounds: `bg-gray-900`, `bg-gray-800`, `bg-neutral-900`
+   - Borders: `border-gray-800`
+   - Cards: `bg-gray-900` with `border border-gray-800`
+3. Buttons: `bg-white text-gray-900` for primary, `border border-gray-700 text-gray-300` for secondary