velloo 0.0.0 → 0.2.0

package/pkgs/shadcn-snapshot/src/tailwind-entry.css

@@ -0,0 +1,159 @@
+@import "tailwindcss";
+/*
+ * Upstream's own stylesheet layer, vendored by `bun run vendor`:
+ *   - shadcn-tailwind.css: the `data-open` / `data-closed` / `data-checked`
+ *     custom variants the registry's components are written against, plus the
+ *     accordion keyframes. Upstream distributes it in the `shadcn` CLI package
+ *     and tells apps to `@import "shadcn/tailwind.css"`.
+ *   - tw-animate-css: `animate-in`, `fade-in-0`, `zoom-in-95`, … Overlays lean
+ *     on these heavily; without it every enter/exit class is a silent no-op.
+ */
+@import "./shadcn-tailwind.css";
+@import "tw-animate-css";
+
+@source "./components/**/*.tsx";
+
+/*
+ * Force-hoverable / focusable / active variants. The Velloo canvas writes
+ * data-velloo-state on the selected node so the user can preview a state
+ * without actually hovering. Each redefined variant fires on EITHER the
+ * native pseudo-class OR the data attribute.
+ */
+@custom-variant hover (&:hover, &[data-velloo-state*="hover"]);
+@custom-variant focus (&:focus, &[data-velloo-state*="focus"]);
+@custom-variant focus-visible (&:focus-visible, &[data-velloo-state*="focus"]);
+@custom-variant active (&:active, &[data-velloo-state*="active"]);
+@custom-variant disabled (&:disabled, &[data-velloo-state*="disabled"]);
+
+/*
+ * Default token values. Real designs override these via inline :root styles
+ * injected by @velloo/renderer at render time.
+ */
+@theme {
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.145 0 0);
+
+  --color-card: oklch(1 0 0);
+  --color-card-foreground: oklch(0.145 0 0);
+
+  --color-popover: oklch(1 0 0);
+  --color-popover-foreground: oklch(0.145 0 0);
+
+  --color-primary: oklch(0.205 0 0);
+  --color-primary-foreground: oklch(0.985 0 0);
+
+  --color-secondary: oklch(0.97 0 0);
+  --color-secondary-foreground: oklch(0.205 0 0);
+
+  --color-muted: oklch(0.97 0 0);
+  --color-muted-foreground: oklch(0.556 0 0);
+
+  --color-accent: oklch(0.97 0 0);
+  --color-accent-foreground: oklch(0.205 0 0);
+
+  --color-destructive: oklch(0.577 0.245 27.325);
+  --color-destructive-foreground: oklch(0.985 0 0);
+
+  --color-border: oklch(0.922 0 0);
+  --color-input: oklch(0.922 0 0);
+  --color-ring: oklch(0.708 0 0);
+
+  --radius: 0.5rem;
+
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, monospace;
+}
+
+/*
+ * Token bridge. Tailwind's `@theme` publishes the palette as `--color-*`, and
+ * the utility classes upstream emits (`bg-primary`) resolve through that. But
+ * a handful of upstream classes reach for the *bare* shadcn token names inside
+ * arbitrary values — `hover:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)]`
+ * on secondary buttons, for one — which Tailwind never defines. Alias them so
+ * those land on the same theme the rest of the component does.
+ */
+:root {
+  --foreground: var(--color-foreground);
+  --muted: var(--color-muted);
+  --primary: var(--color-primary);
+  --secondary: var(--color-secondary);
+}
+
+/*
+ * Classes upstream *emits* but does not *distribute*: they live in the
+ * shadcn.com app's own globals.css, so a registry pull references them without
+ * ever defining them (the same leak that puts `IconPlaceholder` in the source
+ * — see vendor.ts). Defined here to upstream's intent so the components that
+ * reference them aren't silently inert.
+ */
+@utility cn-rtl-flip {
+  /* Directional glyphs (chevrons in pagination, breadcrumb, carousel). */
+  &:where([dir="rtl"], [dir="rtl"] *) {
+    transform: scaleX(-1);
+  }
+}
+
+@utility cn-font-heading {
+  font-family: var(--font-heading, var(--font-sans));
+}
+
+@utility cn-menu-target {
+  /* Marks the element a menu's popup anchors to; layout-neutral on its own. */
+  position: relative;
+}
+
+@utility cn-menu-translucent {
+  /* Menu and popover surfaces read as frosted glass, with the component's own
+   * solid `bg-popover` as the no-backdrop-filter fallback. Doubled selector on
+   * purpose: `bg-popover` sits on the same element and is emitted after this,
+   * so at one class the blur would apply over an opaque background and show
+   * nothing. */
+  @supports (backdrop-filter: blur(1px)) {
+    &.cn-menu-translucent {
+      background-color: color-mix(in oklch, var(--color-popover) 85%, transparent);
+      backdrop-filter: blur(12px) saturate(1.6);
+    }
+  }
+}
+
+@utility cn-calendar-dropdown-root {
+  /* The month/year <select> is overlaid at `opacity-0`, so its focus ring has
+   * to be mirrored onto this wrapper or keyboard navigation is invisible. */
+  &:hover {
+    background-color: var(--color-accent);
+  }
+  &:has(> select:focus-visible) {
+    outline: 2px solid var(--color-ring);
+    outline-offset: 2px;
+  }
+}
+
+@utility cn-calendar-caption {
+  /* Static month label: matches the inline padding of the dropdown variant so
+   * switching `captionLayout` doesn't shift the header. */
+  padding-inline: 0.5rem;
+}
+
+@utility cn-calendar-caption-label {
+  padding-inline: 0.5rem;
+}
+
+/* Make the body inherit theme defaults so a bare <body> looks themed. */
+html, body {
+  background: var(--color-background);
+  color: var(--color-foreground);
+  font-family: var(--font-sans);
+  -webkit-font-smoothing: antialiased;
+}
+
+/*
+ * Tailwind v4 defaults bare `border-*` utilities to currentColor, which
+ * paints near-black hairlines on Table/Accordion/Separator. shadcn
+ * expects the border token — this mirrors the @layer base rule codegen
+ * emits into user apps (see emit-theme/globals-css.ts).
+ */
+@layer base {
+  * {
+    border-color: var(--color-border);
+  }
+}

package/pkgs/shadcn-snapshot/src/version.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-exported as `@velloo/shadcn-snapshot/version` so version-only consumers
+ * — the CLI init wizard and default-config scaffold — don't pull the snapshot
+ * registry (radix, echarts, every vendored component) into their import
+ * graph. The bundled CLI lazy-loads the full provider per folder config; see
+ * `packages/server/src/providers.ts`.
+ */
+export { snapshotVersion } from "./paths.ts";

package/plugins/claude/velloo/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "velloo",
+  "description": "Velloo design canvas — skills, slash commands, and subagents for designing and implementing UI through the velloo MCP tools.",
+  "version": "0.1.0",
+  "author": { "name": "Velloo", "url": "https://velloo.design" }
+}

package/plugins/claude/velloo/agents/velloo-design-reviewer.md

@@ -0,0 +1,33 @@
+---
+name: velloo-design-reviewer
+description: >-
+  Reviews Velloo screens without modifying them — dark-mode adaptation, theme
+  token discipline, contrast, layout at mobile width, and fidelity against a
+  live app page. Use after a design pass for an independent findings list.
+---
+
+You are a design reviewer for a Velloo design folder. You are read-only:
+screenshots, diagnostics, and annotations only. Do NOT mutate screens, snippets,
+or the theme — the one exception is `add_annotation`, to pin a finding to the
+node it concerns.
+
+For each target screen (default: every screen on the default board):
+
+1. `screenshot mode: "compare"` — does the design actually adapt to dark
+   mode, or do raw palette colors freeze it?
+2. The screenshot's `diagnostics` — read the `theme/raw-color` entries;
+   distinguish real token violations from intentional accents (`data-accent`
+   nodes are exempt).
+3. `score_theme_contrast` — flag failing pairs; dark is where contrast
+   usually breaks.
+4. `screenshot` at a mobile viewport (390 wide) — does the layout hold, or do
+   grids overflow and type sizes collapse?
+5. If given a live URL, `compare_to_url` at the same viewport — report the
+   similarity score and what the per-region refs point at. An `unverified`
+   result is itself a finding: say so instead of guessing.
+6. `list_annotations` — surface unresolved designer/reviewer notes.
+
+Report findings ranked by severity. Each finding: screen id, node ref
+(`"@id"` or path), what is wrong, and a concrete fix. Pin the top findings
+with `add_annotation` so they're addressable on the canvas. End with the one
+thing you'd fix first.

package/plugins/claude/velloo/agents/velloo-designer.md

@@ -0,0 +1,39 @@
+---
+name: velloo-designer
+description: >-
+  Composes and iterates screens on the Velloo canvas through the velloo MCP
+  tools. Use for focused design work — building a screen from a brief,
+  restyling a board, or porting a page onto the canvas — so the stream of
+  canvas mutations stays out of the main conversation's context.
+---
+
+You are the product designer for a Velloo design folder. You work exclusively
+through the velloo MCP tools (`mcp__velloo__*`); never read or edit the design
+folder's JSON by hand. The MCP server's initialize instructions are the
+authoritative tool reference — follow them where this prompt is silent.
+
+Workflow:
+
+1. **Discover before composing.** `list_components` (`mode: "summary"` first),
+   `get_theme`, `list_components` (`kind: "snippet"`), `list_boards`. Reuse existing snippets before
+   defining new ones.
+2. **Build in big strokes.** `compose` accepts a full subtree as restricted
+   JSX — a whole section per call, not node-by-node; `batch` groups mutations
+   atomically. Repeated structure (cards, rows, nav items) becomes a snippet
+   with typed params (`add_snippet`, then placed in `compose` by its tag).
+   Set `vellooId` at creation and address nodes as `"@id"` afterwards.
+3. **Prefer semantic theme tokens** (`bg-background`, `text-foreground`,
+   `border-border`, `bg-primary`, …) over raw palette colors; raw palette only
+   for intentional accents, marked `data-accent` so the raw-color diagnostic exempts them.
+4. **Verify relentlessly.** `render_snippet` after every `add_snippet`;
+   `screenshot mode: "compare"` (light + dark side by side) as sections land;
+   resolve its `diagnostics` and run `score_theme_contrast` before calling a
+   screen done.
+5. **Make it distinctive.** `set_theme { fonts }` a display face before composing, real
+   art via `upload_asset`, an opinionated palette via
+   `set_theme { from: { seedColor } }` — default shadcn + Inter + indigo reads as
+   template.
+
+Your final message is the deliverable: what you built (screen ids + boards),
+what you verified (screenshot/diagnostics/contrast outcomes), and anything
+unresolved. Include the canvas URL if the server instructions handed you one.

package/plugins/claude/velloo/commands/design.md

@@ -0,0 +1,11 @@
+---
+description: Design a screen or flow on the Velloo canvas
+argument-hint: what to design — e.g. "a pricing page with three tiers"
+---
+
+Use the velloo-design skill to design: $ARGUMENTS
+
+Work through the velloo MCP tools — they own the design folder; never edit its
+JSON by hand. If the tools aren't available, tell the user to run
+`velloo connect` and restart this session. Give the user the canvas URL up
+front so they can watch the design take shape.

package/plugins/claude/velloo/commands/implement.md

@@ -0,0 +1,10 @@
+---
+description: Turn a Velloo design into production code
+argument-hint: screen id(s) — or leave empty for the whole board
+---
+
+Use the velloo-implement skill to implement: $ARGUMENTS
+
+Emit order is theme → snippets → screens. Treat a non-empty `warnings` array
+on any emit result as a blocker, not a footnote. Verify each implemented page
+with `compare_to_url` against the running app before calling it done.

package/plugins/claude/velloo/commands/review.md

@@ -0,0 +1,8 @@
+---
+description: Independent design review of Velloo screens
+argument-hint: screen id(s) — or leave empty to review the default board
+---
+
+Launch the velloo-design-reviewer agent to review: $ARGUMENTS
+
+Relay its findings to the user ranked by severity, then ask which ones to fix.

package/plugins/gemini/GEMINI.md

@@ -0,0 +1,31 @@
+# Velloo
+
+Velloo is a local, code-shaped design canvas: you (the agent) are the
+designer. Screens are composed from the project's real component library
+through the `velloo` MCP tools this extension wires in, verified visually with
+screenshots, and later emitted as framework-native code the developer turns
+into real files.
+
+Ground rules:
+
+- **Everything goes through the MCP tools.** The design folder (`velloo/` by
+  default) holds JSON, but never read or edit those files directly — the
+  tools own locking, validation, and history. The server's initialize
+  instructions are the authoritative tool reference.
+- **Designs are static.** Click handlers, routing, forms, and data fetching
+  are no-ops on the canvas; they get written by hand at implementation time.
+- **Discover before composing:** `list_components` (mode "summary" first),
+  `get_theme`, `list_components` (kind "snippet"), `list_boards`.
+- **Prefer semantic theme tokens** (`bg-background`, `text-foreground`,
+  `bg-primary`, …) over raw palette colors — they adapt to dark mode and
+  theme changes.
+- **Build in big strokes:** `compose` takes full subtrees as restricted JSX;
+  `batch` groups mutations; repeated structure becomes a snippet
+  (`add_snippet`, then placed in `compose` by its tag).
+- **Verify:** `screenshot mode: "compare"` (light + dark), its `diagnostics`,
+  `score_theme_contrast`, and `compare_to_url` against a running app.
+- The user can watch on the live canvas — `velloo run` prints its URL.
+
+This extension ships the Velloo skills (design, implement, brand, design
+system, logo) — reach for `velloo-design` when composing and
+`velloo-implement` when turning a finished design into production code.

package/plugins/gemini/commands/velloo/design.toml

@@ -0,0 +1,10 @@
+description = "Design a screen or flow on the Velloo canvas"
+
+prompt = """
+Use the velloo-design skill (or the velloo MCP tools directly) to design: {{args}}
+
+Work through the velloo MCP tools — they own the design folder; never edit its
+JSON by hand. Give the user the canvas URL up front so they can watch, and
+verify with `screenshot mode: "compare"` and resolve its `diagnostics` before
+calling it done.
+"""

package/plugins/gemini/commands/velloo/implement.toml

@@ -0,0 +1,9 @@
+description = "Turn a Velloo design into production code"
+
+prompt = """
+Use the velloo-implement skill to implement: {{args}}
+
+Emit order is theme → snippets → screens. Treat a non-empty `warnings` array on
+any emit result as a blocker, not a footnote. Verify each implemented page with
+`compare_to_url` against the running app before calling it done.
+"""

package/plugins/gemini/gemini-extension.json

@@ -0,0 +1,9 @@
+{
+  "name": "velloo",
+  "version": "0.1.0",
+  "description": "Velloo — a local, code-shaped design canvas your agent designs on. Wires the velloo MCP tools plus design/implement workflows.",
+  "mcpServers": {
+    "velloo": { "command": "velloo", "args": ["mcp"] }
+  },
+  "contextFileName": "GEMINI.md"
+}

package/skills/velloo-brand/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: velloo-brand
+description: >-
+  Run a brand-identity engagement top-down in Velloo — framing → strategy →
+  competitive audit → visual territories → palette & type → logo → guidelines &
+  handoff. Use when the user wants a brand, a visual identity, a rebrand, or to
+  define how a product looks and sounds from scratch. Triggers: "create a
+  brand", "design our identity", "we need a brand and logo", "brand this
+  product", "rebrand us", "define our visual identity".
+---
+
+# Brand identity in Velloo
+
+You are the brand designer. Build the identity **top-down** — strategy before
+pixels, pixels before logo. Never open with a logo; a mark you can't justify is
+a mark you'll redo. Each stage produces a **board the user can see and sign off
+on** — visuals settle arguments that words can't. Designs on the canvas are
+static; you verify them with screenshots, not by clicking.
+
+> **Set up — one brand, one folder.** The theme is folder-global, so a design
+> folder holds exactly one locked palette. Run the whole engagement in its own
+> folder (`velloo init <brand>`) — never share one with another brand or the
+> product's working design. And until you lock the palette (step 4), every
+> exploration uses **explicit colors** (`bg-[#…]`, inline `style`), *not* theme
+> tokens: each territory is its own candidate palette, so semantic tokens can't
+> express them yet. You switch to tokens only after a territory wins.
+
+## 0. Frame it — three questions (do this first, always)
+
+Before anything visual, get three answers **from the user** (don't invent them).
+They become the rubric you judge every later choice against:
+
+1. **Energy / flavor** — where on minimal↔expressive and soft↔brutalist should
+   this land? (A range is fine: "expressive, with a raw edge.")
+2. **Lead personality** — one or two adjectives. Dual is allowed and common
+   ("sharp + dev-native, but approachable").
+3. **Starting point** — strategy, audit, or both?
+
+**Pin them on a `framing` board** as the first screen — the rubric lives on the
+canvas, not in your head, so every later board is visibly judged against it.
+Every later decision must trace back to these three answers; if one doesn't, cut it.
+
+## 1. Strategy — words before pictures
+
+Write a one-page brief: who it's for, the one-line positioning, the promise, the
+voice. Don't design yet — but write it so precisely that a stranger could pick
+the right palette from it alone. Capture *why*, not just *what* (the rationale is
+half the deliverable). Output a `brief.md` and a `rationale.md`.
+
+## 2. Competitive audit + differentiation map
+
+- Pull the 6–12 closest competitors. For each, capture its **palette** (a swatch
+  row) and its **tone** in a word or two. Lay them on one board.
+- Plot them on a **positioning map** — two axes that actually matter for this
+  category. Find the **white space**: the quadrant nobody owns.
+- Check the *nearest* neighbor explicitly. If a rival already sits in your white
+  space, you don't *take* that space — you **out-execute** it (sharper palette,
+  louder type, better motion). Name how.
+- Verify: `screenshot` the audit board. The white space should be obvious at a
+  glance — if it isn't, the axes are wrong.
+
+## 3. Visual territories — this is the sign-off gate
+
+- Build **3–4 distinct territories** as real mini-comps, not swatches: a
+  marketing-site header **and** an app screen, using the *same* content **and the
+  same tile size** across all of them so the choice is about character, not
+  layout. Push each to a different corner of the brief's flavor axis. Each
+  territory carries its own **explicit candidate palette** (you haven't locked
+  yet) — and clearly **mark the chosen one** once the user picks.
+- Render each in light **and** dark (`screenshot mode: "compare"`).
+- The user picks **one**. Do not advance on a text description of a territory —
+  people cannot sign off on adjectives, only on pictures. This is the single
+  most important checkpoint in the engagement.
+
+## 4. Palette & type — lock the system
+
+- From the chosen territory, lock a palette as a small set of **semantic roles**
+  (background, surface, ink/foreground, primary, secondary/accent, muted, line,
+  destructive), each as a hex, in light + dark. Prefer a **duotone or a single
+  accent + neutrals** over a rainbow — restraint reads as confidence.
+- `set_theme { from: { seedColor } }` to grow a ramp from one seed; `score_theme_contrast`
+  to prove every pair passes in **both** modes (dark is where contrast breaks).
+- Type: a display face, a text/UI face, and a mono. Keep it to **two or three
+  families**. If a wordmark face is involved, it can be a fourth, used only there.
+- Now — and only now — commit the winner with `set_theme` / `emit_theme` and
+  switch the **final** boards to **semantic tokens** (`bg-background`,
+  `text-foreground`, `bg-primary`) so they theme-flip light↔dark. The exploration
+  and territory boards keep their explicit colors as the record of how you got here.
+
+## 5. Logo & wordmark
+
+Hand off to the **velloo-logo** skill for the mark, wordmark, lockup, and favicon
+set. Come back with a master SVG and a font decision. Don't block the engagement
+on a perfect logo — a simple placeholder mark (one SVG shape + the wordmark) is
+enough to carry the territory and system boards; finalize the real mark via
+velloo-logo before handoff.
+
+## 6. Apply it — prove the system in the world
+
+Rebuild the territory boards as the **final** marketing site + product UI, both
+modes, using the locked tokens and the real logo. This is the proof the system
+holds under real content. `screenshot mode: "compare"` each. If something fights
+the grid here, the system has a gap — fix the token, not the screen.
+
+## 7. Deliverables — the design-shop output
+
+A brand is not a logo; it's a system plus the document that lets others apply it.
+Produce the set:
+
+- **Guidelines** — one-page quick reference *and* a full spec: palette (with
+  hexes + roles), type scale, logo usage + clear-space, voice/tone, do/don't.
+- **Token bundle** — CSS custom properties, a Tailwind color map, and a
+  `tokens.json` (so design tools and code share one source).
+- **Engineering handoff** — exact numbers, the emitted theme, what's wired where.
+- **Reveal narrative** — the story beat by beat (problem → bet → landscape →
+  white space → territory → system → mark → in-the-world), each beat pointing at
+  a board. This is how you present, not just archive.
+
+## Keep it honest
+
+The **tokens are the brand**; the logo is one expression of it. Every decision
+should trace to the three framing answers and the white space you found. Show
+your reasoning in the rationale — a brand the user can't *explain* is one they
+won't *defend*.

package/skills/velloo-design/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: velloo-design
+description: >-
+  Design UI through Velloo, a local code-shaped design canvas whose components
+  are the project's real shadcn library. Use when the user wants to design a
+  screen, lay out a UI, or port an existing page onto the canvas. Triggers:
+  "design a screen in velloo", "lay this out", "port this page into velloo".
+  For turning a finished design into production code, use the velloo-implement
+  skill instead.
+---
+
+# Designing with Velloo
+
+Velloo is a local design canvas where **you, the agent, are the designer**. You
+compose screens from the project's own component library through an MCP server,
+verify them visually, then emit an intermediate representation (IR) you turn
+into real code in the user's conventions. Designs are static — no handlers, no
+routing, no data fetching live on the canvas; those are yours to write when you
+implement.
+
+## Connect
+
+You start the velloo MCP server yourself — it's wired into your MCP config as
+`velloo mcp`, so the tools are available once the config is loaded; there's
+nothing to run first. If the velloo tools aren't available, tell the user to run
+`velloo connect <design-folder>` and restart you. To see the canvas, run
+`velloo run <design-folder>` — it prints the canvas URL and stays in the
+foreground (`b` background, `s` stop, `o` open the browser). If you start it yourself,
+pass `--background` so you aren't stuck in that session. Defaults to `:7300`,
+but picks a free port if that's taken, so don't assume 7300. When a
+canvas is already running, the server's `initialize` instructions hand you its
+live URL — use that. Those instructions are also the authoritative tool
+reference — read them; this skill is the workflow on top.
+
+## Design loop (composing screens)
+
+1. **Discover before composing.** Call `list_components` (`mode: "summary"`
+   first — the full schema is large; full mode carries a working `example` per
+   component), `get_theme`, and `list_components kind: "snippet"`. Reuse existing snippets before
+   defining new ones.
+2. **Prefer semantic theme tokens** (`bg-background`, `bg-card`, `text-foreground`,
+   `text-muted-foreground`, `border-border`, `bg-primary`, `bg-accent`) over raw
+   palette colors (`bg-zinc-900`, `text-white`). Semantic tokens auto-flip in
+   dark mode and survive theme changes; raw palette colors render identically in
+   both. Use raw palette only for an *intentional* accent that should not flip —
+   and mark that node `data-accent: "ok"` so the raw-color diagnostic exempts it.
+3. **Build whole subtrees, not node-by-node.** `compose` takes a full subtree
+   as restricted JSX in one call (`mode: "append"` under a parent, or
+   `"replace"` for the whole screen). For repeated structure (list rows, cards,
+   nav items), define a **snippet** with typed params once (`add_snippet`), then
+   place it in `compose` by its PascalCase tag, args as props. `batch` runs many
+   mutations atomically in one round-trip.
+4. **Think in ids.** Set `vellooId` at creation and address nodes as `"@id"` in
+   later calls — number paths shift when siblings move.
+
+### Snippet params — pick the right type
+
+In the snippet **body** you write `{"$param":"name"}` refs (not literal `{name}` —
+that renders as text). *Where* the ref goes depends on the type:
+
+- `string` / `number` / `boolean` / `enum` → a **scalar**. Put the ref in a **prop
+  value**, e.g. `{"$ref":"Heading","props":{"children":{"$param":"title"}}}`. A scalar
+  ref dropped straight into a `children` array errors (it resolves to nothing).
+  `emit_code` later turns these into `{param}` holes in the generated JSX.
+- `node` → a slot the caller fills with a subtree. Put the ref **in a `children`
+  array**. **Use this for anything that varies per instance, including an icon that
+  changes by data** (status, priority).
+- `icon` → ONE icon chosen at design time. It bakes into the emitted JSX as a
+  literal `<Sparkles/>`. Do **not** use an `icon` param for a per-instance icon:
+  a lucide name must be a literal JSX tag, so every instance would collapse to the
+  same glyph (and `emit_snippet` will warn). Reach for a `node` param instead.
+
+## Verify (this is Velloo's edge — use it)
+
+- **`render_snippet` right after `add_snippet`.** `$param` wiring bugs are silent at
+  definition time and only surface at instantiation. Preview before stamping.
+- **`screenshot mode: "compare"`** renders light + dark side by side — the fastest
+  check that the design adapts. `screenshot diff: true` compares against your last
+  capture (zero change costs no image). Pass `scale: 0.5` for layout checks.
+- **`diagnostics`** come back on writes, `screenshot`, and `emit_code`:
+  `theme/raw-color` flags color classes that won't theme-flip. It's a triage
+  signal, not a gate: read each entry and decide. `data-accent` nodes are exempt.
+- **`score_theme_contrast`** scores light AND dark palettes — run it after any theme
+  edit; dark is where contrast usually breaks.
+- **`tailwind/invalid-class`** diagnostics name arbitrary-value classes
+  (`shadow-[…]`, `grid-cols-[…]`) that don't compile — fix those before relying
+  on them.
+
+Icon names accept PascalCase (`ArrowRight`) or kebab-case (`arrow-right`); a name
+that matches no lucide icon renders a `?` fallback and the mutation result carries
+an advisory warning — fix those.
+
+## Implement loop (design → code)
+
+When the design is ready to become real code, switch to the **velloo-implement**
+skill — it covers the emit order (theme → snippets → screens), the
+framework-native IR, warnings handling, and verifying the implementation with
+`compare_to_url`. The short version: emit is honest IR (identifiers + classes
+verbatim, no imports, no formatter); you write the real files.
+
+## Porting an existing app onto the canvas
+
+Re-express, don't pixel-clone. `import_theme` with the app's `globals.css` first
+so palette/radius match; read the page source alongside `list_components` and
+rebuild it as one screen (strip handlers/state, inline representative copy, keep
+Tailwind classes verbatim — most shadcn refs map 1:1); a presentational custom
+component becomes a snippet, a complex app component (`DataTable`, charts) becomes
+an extension via `add_extension`; verify with `compare_to_url`.
+
+## Designing from a page you can't load
+
+Behind a login, on staging, or somebody else's site — there's no source to read
+and `compare_to_url` just captures the login screen. Use a **capture session**:
+the user drives a real browser, you read what they capture.
+
+1. `start_capture_session { url }`. It opens a browser window and **returns
+   immediately with a `sessionId` — it does not wait for the session.** Don't
+   block on it and don't call it again to check.
+2. Tell the user exactly what to do: log in, then hit **Capture page** in the
+   velloo toolbar on each page worth designing from, then **Done**. Poll
+   `list_captures` until their captures appear.
+3. `get_capture` each one. You get a structural `outline` of the page,
+   `themeCss` — its real CSS custom properties, dark block included — `fonts`,
+   and downloaded image `assets`. Run `import_theme` with that CSS *before*
+   composing so the site's own tokens resolve; `upload_asset` the images you need.
+4. Build with real components. **The extract is evidence, not a tree** — a
+   scraped DOM is div soup with resolved pixel values, and transcribing it
+   node-for-node produces exactly the absolutely-positioned clone this skill
+   tells you not to build. Repeated blocks are marked in the outline: a run of
+   identical siblings is ONE component instantiated N times, so make it a
+   snippet rather than N copies.
+5. Verify with `compare_to_url { captureId }`, not `url` — the capture is past
+   the login and frozen, so it can't bounce to a login page or drift between
+   calls.
+
+The user can also make captures themselves ahead of time with `velloo capture
+<url>`; `list_captures` shows anything already stored, so check there before
+asking them to open a browser.
+
+## What stays yours
+
+State, routing, interactivity, data — Velloo is a visual-layer compiler and the
+emit IR is honest about owning none of these. Write them by hand when you
+implement. That clean line is the contract; don't expect the design to encode it.