velloo 0.0.0 → 0.2.0

package/skills/velloo-design-system/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: velloo-design-system
+description: >-
+  Turn a brand into a working design system in Velloo — token scales (color,
+  type, spacing, radius), a themed component inventory, reusable snippets, and a
+  living style guide emitted into the real app. Use when the user wants a design
+  system, design tokens, a component library styled to their brand, a style
+  guide, or to theme an app coherently. Triggers: "set up a design system",
+  "define our tokens", "build/style our component library", "make a style
+  guide", "theme the app", "do we need a design system?".
+---
+
+# Design systems in Velloo
+
+A design system is **tokens + components + the rules that bind them**. Velloo
+already speaks both — the theme *is* your tokens, the shadcn snapshot *is* your
+components — so your job is to make them coherent, prove they hold, and **emit
+them into the real app**. The canvas re-renders against the tokens live, so you
+*see* the system instead of describing it.
+
+## Do you even need one? (answer this honestly first)
+
+- **One product, one brand:** the theme (tokens) + the component snapshot usually
+  *is* the system. Don't build a 200-page portal for a single app — formalize the
+  tokens, build a style-guide screen, ship. Over-building a system is a way to
+  avoid shipping the product.
+- **Multiple products/surfaces, a team, or a public component library:** yes,
+  formalize it — shared tokens, documented patterns, versioning.
+
+State which case you're in before you start; it sets the scope.
+
+## 1. Tokens — the foundation
+
+Define the **whole** scale, not just brand colors:
+
+- **Color roles**, each in light + dark: background, surface(s), foreground/ink,
+  primary, accent, muted, line/border, destructive. Use *semantic roles*, never
+  raw palette values scattered through screens.
+- **Radius** scale, **spacing** rhythm, **type** scale (sizes + weights + line
+  heights), and a **mono**.
+
+`set_theme { from: { seedColor } }` grows ramps from a seed; `score_theme_contrast`
+proves every foreground/background pair passes in **both** modes (dark breaks
+first). `set_theme { tokens }` makes them live — the canvas reflows so you can judge the
+system, not a spec sheet.
+
+## 2. Component inventory — the system's audit
+
+Build one board that shows **every component the product actually uses**, themed:
+buttons (all variants + states), inputs, selects, cards, nav, tables, badges,
+empty states, toasts, dialogs. One screen, sectioned by kind.
+
+This board *is* the audit. Anything that looks wrong here is a token bug, not a
+component bug. Read the `theme/raw-color` diagnostics (on writes and `screenshot`)
+for color classes that won't theme-flip and fix
+them to semantic tokens (mark intentional fixed accents `data-accent: "ok"`).
+
+## 3. Patterns — snippets with typed params
+
+Recurring structures (a list row, a stat card, a form field, a nav item) become
+**snippets** with typed params (`add_snippet`), verified with `render_snippet`
+*before* you stamp them — `$param` wiring bugs are silent until instantiation.
+These are your real components-to-be; define each once, instantiate per use.
+
+## 4. The living style guide
+
+Compose a **style-guide screen** rendered entirely from the same tokens: palette
+swatches with role names + hexes, the type scale in situ, the spacing/radius
+scale, the component inventory, and voice/tone notes. Because it's built from the
+tokens, it can't drift — change a token and the guide changes with it. That's the
+whole point: **one source of truth, zero stale docs.**
+
+## 5. Emit into the app
+
+Velloo's emit is honest IR — it owns the visual layer, not your state/routing:
+
+- `emit_theme { apply: true }` → the Tailwind `globals.css` (the entire color
+  system) wired into the app's entry CSS. This is the keystone artifact.
+- `emit_snippet` per pattern → a real component; map its `{param}` holes to your
+  props/data.
+- `emit_code` per screen → the layout skeleton (and a `/styleguide` route if you
+  want the guide to live in the app).
+- **Read the `warnings` array on every emit.** A non-empty `warnings` means
+  something couldn't transfer faithfully — handle it, don't ship it blind.
+
+## Keep it honest
+
+The system **is the tokens**; components are downstream. A change should happen
+**once** — at the token — and propagate everywhere. If you find yourself editing
+the same color in five places, the system has a hole; close it at the source.

package/skills/velloo-implement/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: velloo-implement
+description: >-
+  Turn a Velloo design into production code — emit the theme, snippets, and
+  screens as framework-native IR (shadcn/Tailwind, MUI sx, or no-framework
+  inline styles), write real files in the app's conventions, then verify the
+  implementation against the canvas. Use when the user wants to implement a
+  Velloo design, generate code from the canvas, or sync an app with its
+  design. Triggers: "implement the velloo design", "build the page from the
+  design", "turn the design into code", "generate the code for this screen".
+---
+
+# Implementing a Velloo design
+
+The Velloo canvas is the visual source of truth; **you write the production
+code**. Emit gives you honest IR — library identifiers and native styling
+verbatim, no imports, no formatter pass — and you translate it into real files
+in the app's own conventions. Designs are static by construction, so state,
+routing, handlers, and data are yours to add.
+
+## Before you start
+
+- The velloo MCP tools come from your MCP config (`velloo mcp`); the server's
+  `initialize` instructions are the authoritative tool reference.
+- Scope the work: `list_screens` / `list_boards` for what exists,
+  `get_screen mode: "outline"` for a quick structure read, `list_components kind: "snippet"`
+  for the reusable pieces, `get_theme` for the token model.
+- Read the app first: the router (Next/Vite/Astro/Remix), where components
+  live, the components import alias, how pages fetch data, and whether the
+  components the design uses actually exist in the app yet.
+
+## Emit order: theme → snippets → screens
+
+1. **`emit_theme { outputDir }` — dry-run first.** It returns per-file diffs
+   without writing; review them, then re-run with `apply: true`.
+   - shadcn folder → Tailwind v4 `globals.css` (the `@theme` block, `.dark`
+     overrides, base layer) plus `tailwind.config.ts` (`cssOnly` skips it).
+     `cssPath` defaults to `app/globals.css` — pass `src/index.css` (Vite) or
+     wherever the app's entry CSS actually lives.
+   - MUI folder → a `createTheme(...)` module (default `theme.ts`, dark theme
+     included when the design has one). Wire it into the app's ThemeProvider.
+   This is the one direct artifact — no agent translation needed.
+2. **`emit_snippet` per snippet** → a PascalCase component name, typed params,
+   and a JSX body with `{param}` holes. Write each as a real component: params
+   become props, `node` params become children/slots, and keep the emitted
+   classes/`sx` verbatim — that's what makes the result match the design.
+   Snippets emit a `className?: string` passthrough — keep it.
+3. **`emit_code` per screen** → the page's layout skeleton. Wrap it in the
+   framework's route/page shell, import the snippet components you just
+   wrote, and add what Velloo doesn't own. `componentsAlias` defaults from
+   the folder config (set at init); override per call if the app resolves
+   imports differently.
+
+## The IR is framework-native — keep it that way
+
+- **shadcn** → library ids map 1:1 to the app's shadcn components; Tailwind
+  classes transfer verbatim. The emit result lists every component used — if
+  the app is missing one, install it with `npx shadcn@latest add <name>`
+  rather than hand-rolling a lookalike.
+- **MUI** → components import from `@mui/material`, styling stays in
+  `sx={{…}}`, and tokens ride the emitted `createTheme` module.
+- **No-framework** → plain HTML elements; Tailwind classes when the folder's
+  CSS framework is tailwind, inline `style={{…}}` objects referencing the
+  `var(--…)` theme variables when it's none.
+- **Extensions** emit as real imports from their declared `importPath` — the
+  design's `DataTable` / chart nodes come back as the app's own components
+  with the captured props. Don't re-implement them.
+- Icons are lucide-react imports (`<ArrowRight className="…" />`).
+
+## Warnings are part of the contract
+
+Every emit result carries a `warnings` array (per-snippet warnings ride on
+`snippetsUsed[].warnings`). Non-empty means something couldn't be expressed
+faithfully — e.g. a dynamic icon-name param baked to a single glyph. Resolve
+each one in the real component (usually a `node` param or a prop switch);
+never ship a warning blind.
+
+## Verify against the design
+
+1. Run the app's dev server.
+2. `compare_to_url { screenId, url }` at the same viewport for each
+   implemented page. 0.85+ similarity is a faithful structural port; the
+   per-region node refs name what's off. Don't chase 1.0 — fonts, imagery,
+   and live data legitimately differ.
+3. An `unverified` result means STOP — don't iterate against a page you
+   never actually captured. If it's a login wall, `start_capture_session
+   { url }` opens a browser the *user* drives (it returns immediately; tell
+   them to log in, hit **Capture page**, then **Done**, and poll
+   `list_captures`), then verify with `compare_to_url { captureId }`. If it's
+   the dev server, fix that first. `storageStatePath` / `cookies` remain the
+   option when you already hold a session.
+4. When implementation drifted from the design, fix the code. When the design
+   itself should change, fix it in Velloo (through the MCP tools — never edit
+   the design folder's JSON by hand), then re-emit and diff.
+
+## App conventions win
+
+Match the codebase: file naming, the server/client component split
+(`"use client"` only where interactivity needs it), the app's data-fetching
+layer, its test patterns. The IR provides structure and styling; everything
+else should read like the user wrote it.

package/skills/velloo-logo/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: velloo-logo
+description: >-
+  Design a logo, wordmark, and full favicon/app-icon set in Velloo — explore
+  marks across directions, converge on one idea, make the geometry exact with a
+  live adjuster, compose the lockup, and export every icon size from one source
+  SVG. Use when the user wants a logo, a mark, a wordmark, an app icon, or a
+  favicon. Triggers: "design a logo", "make a mark/symbol", "create a wordmark",
+  "we need a favicon", "app icon", "icon for the product".
+---
+
+# Logos & marks in Velloo
+
+A logo is **geometry, not a render**. Explore widely, converge on **one** idea,
+then make it exact. The non-negotiable test: the mark must read at **16px** (a
+favicon) *and* at hero size, in **light and dark**. If it dies at 16px, it's
+decoration, not a mark.
+
+## 1. Diverge — explore mark directions
+
+Generate candidates across genuinely different directions, a few each:
+
+- **Monogram / letterform** (the initial, stylized).
+- **Abstract symbol** (a metaphor for what the product does).
+- **Geometric / 3D** (a form with depth — extract a clear silhouette from it).
+- **Wordmark-only** (the name *is* the logo).
+
+Two ways to make candidates, and you'll mix them:
+
+- **Author SVG directly.** Clean, adjustable, diff-able, scales perfectly —
+  always the path for the *final* mark.
+- **Image generation for inspiration** *(optional; needs image-gen access or an
+  API key)*. Use a vector-flat model for logos, a typographic model for
+  wordmarks, an illustrative model for 3D/expressive forms — then **vectorize**
+  the raster you like into a clean SVG you can refine. Treat gen output as a
+  sketch, not a deliverable.
+
+Lay the candidates on an **exploration board** as a numbered grid so the user can
+pin favorites (`import_assets` pulls generated rasters straight in by path — no
+base64). Keep the rounds; they're the decision log.
+
+## 2. Converge — name the idea in one line
+
+Before you refine anything, state the chosen idea in a single sentence —
+"*two forms interlinked = X meets Y*", "*a path that's also a checkmark*". If you
+can't say what it *means* in one line, it isn't a logo yet; it's a shape.
+
+## 3. Make it exact — the adjuster loop
+
+Logo geometry is a back-and-forth over a handful of numbers (offset, stroke
+weight, corner radius, the crossing/overlap, optical centering). **Do not eyeball
+this across dozens of screenshots** — that loop is slow and never converges.
+
+Instead, stand up a **throwaway live adjuster**: a tiny standalone HTML page with
+a slider per numeric value and **toggleable guide lines** (baseline, x-height,
+centerline), rendering the SVG live with copy-paste output. The moment the user
+has sliders and a guide line, the back-and-forth collapses to a single pass.
+Bake the final numbers back into the master SVG.
+
+## 4. The wordmark
+
+- **Lowercase vs uppercase** is a real decision, not a default: lowercase reads
+  modern/approachable, uppercase reads authoritative/established. Show both and
+  choose deliberately — note the implication.
+- Pick **one** family for the wordmark. Tune **tracking** until the spacing is
+  optically even (tight negative tracking is normal on geometric sans). Use the
+  adjuster's guide lines to lock baseline and x-height.
+- Give it **one** ownable detail — a colored letter, a dot, a ligature, a cut.
+  One. A wordmark with three gimmicks has none.
+
+## 5. The lockup
+
+Compose mark + wordmark with a gap defined **as a ratio of the wordmark size**,
+so the lockup scales as one unit. Produce the standard variants a brand system
+needs: **horizontal, stacked, mark-only, monochrome, inverse**, plus a
+**clear-space** spec. Bundle the font locally if the wordmark ships in a UI (so
+it renders offline, not just where the font happens to be installed).
+
+## 6. Favicon & app-icon set — one source, every size
+
+From the master SVG, export the whole set and wire it up:
+
+- `favicon.svg`, `favicon.ico` (16/32/48 multi-res), `apple-touch-icon` (180),
+  PWA icons (192/512), and an OG/social image.
+- Add the `<link>` tags + the web manifest; set a `theme-color`.
+- **Re-test the 16px crop.** If the mark is illegible small, *simplify it* (fewer
+  strokes, more contrast) rather than shrinking detail nobody can see.
+
+## Verify
+
+`screenshot` the mark at **16, 24, 48, and hero**, in **light and dark**. It must
+survive every size and both modes. The favicon is the honest test — pass that and
+the rest is easy.

package/skills/velloo-setup/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: velloo-setup
+description: >-
+  Calibrate a Velloo design folder to an existing codebase before designing —
+  import the app's real theme and fonts, match its custom components, and
+  verify the canvas against the running app. Use once per repo before the first
+  design task, and again when the app's design language changes. Triggers:
+  "set up velloo for this repo", "make the preview match my app", "why doesn't
+  the canvas look like my app", or the setup step of an init handoff prompt.
+---
+
+# Calibrating Velloo to an existing app
+
+For shadcn folders, the canvas can import client-safe components directly from
+the app's configured `components/ui` directory. That is a bounded capability,
+not a promise that arbitrary application React can run inside a design iframe:
+portal/state-heavy families use named canvas-safe adaptations, and a missing or
+unbuildable file falls back independently. Other providers follow their own
+adapter contract. The fidelity is observable through `component_status`; never
+infer it from `installedInApp` or from a component merely appearing on screen.
+
+Your job here is to close that gap **before** you start designing, and to say
+honestly what's left open. Do this once per design folder. Skip it only for a
+greenfield folder with no app to match.
+
+## 1. Theme first — it buys the most
+
+`import_theme { cssPath, apply: true }` against the app's stylesheet. This is
+not just colors: it ingests `--radius`, `--font-*` roles, the non-semantic
+palette (`--primary-600`, `--ink`), and — when it finds a `tailwind.config`
+nearby — that config's `theme.extend` spacing, shadows, fonts, keyframes, and
+`container` settings. Run it dry first (the default) and read the reported
+changes; `apply: true` when they look like the app.
+
+Init records the stylesheet it found in the folder config, so check there
+before hunting. If there's no stylesheet (a `none`-CSS folder, an MUI app),
+`import_theme` still takes raw `css` text, and an MUI app's `createTheme` call
+is the equivalent source.
+
+**Fonts are the highest-leverage single token.** A design in the wrong typeface
+reads as wrong no matter how correct the layout is. If `import_theme` didn't
+resolve real families, set them with `set_theme { fonts }` — read the app's font loading
+(next/font, a `@font-face`, a Google Fonts link) to get the actual names.
+
+Then `score_theme_contrast` to confirm the imported palette holds up in both
+modes; an app that only ever ships light mode often imports into a dark palette
+that fails.
+
+## 2. Verify against the real thing, early
+
+Do not wait until a design is finished to discover the baseline was wrong.
+Recreate one representative screen — or use whatever init scaffolded — and run
+`compare_to_url` against the running app.
+
+- Get the app running first. Start its dev server yourself if the package
+  scripts make it obvious; otherwise ask the user for the command, a running
+  URL, or a deployed preview. Ask once, plainly, rather than guessing ports.
+- **Read `unverified` on every result.** `redirected` / `authWall` means you
+  captured a login page, so the similarity number is meaningless.
+- **For a login wall, use a capture session.** `start_capture_session { url }`
+  opens a real browser the *user* drives. It returns immediately — it does not
+  wait — so say plainly what you need ("log in, then hit **Capture page** in the
+  velloo toolbar on each page, then **Done**") and poll `list_captures` until
+  their captures land. Then verify with `compare_to_url { captureId }` instead
+  of `url`: the capture is already past the login and frozen, so it can't bounce
+  to a login page or drift between runs. `storageStatePath` / `cookies` /
+  `localStorage` stay available for when you already hold a session.
+- If you cannot get a real capture, **leave it unverified and say so.** Tuning a
+  design toward a page you never saw is worse than admitting the gap.
+- For a dashboard or feed whose content shifts between loads, pass
+  `cacheUrl: true` so you diff against one frozen capture instead of drifting
+  content.
+
+0.85+ similarity is a faithful structural port. Don't chase 1.0 — fonts and
+live data legitimately differ.
+
+## 3. Establish component fidelity before adapting anything
+
+Only after theme parity, call `component_status { screen: "<id>" }` for each
+screen you're about to design or verify (or `{ ids: [...] }` before a screen
+exists). Check `mounted` first: the mount is all-or-nothing, so a single
+`unavailable` component keeps the whole screen — and every screenshot and
+`compare_to_url` of it — on Velloo's bundled components, whatever the other
+statuses say. Fix or replace the blocking component before trusting any
+`exact`. Treat the statuses as part of the design brief:
+
+- **`exact`** — Velloo compile-checked and selected the app's source file for
+  the whole-screen canvas mount. Custom CVA variants and ordinary explicit
+  props are also reflected into discovery when their syntax is recognizable.
+- **`adapted`** — the real family depends on portals, runtime state, browser
+  layout, or another interaction that conflicts with a static selectable
+  canvas. Velloo deliberately renders a canvas-safe counterpart. Preserve the
+  component identity and props, but do not claim pixel-identical behavior.
+- **`fallback`** — the app file is absent or failed the browser preflight, so a
+  bundled provider component or Velloo helper is rendering. Read the returned
+  note/errors before deciding whether the visual difference matters.
+- **`unavailable`** — there is no usable canvas source, so a screen using it
+  does not mount at all (`mounted: false`); read its errors — a resolution
+  failure usually means the recorded app root is wrong
+  (`velloo design set-app-root`).
+
+Host-source edits invalidate the canvas bundle automatically. After changing a
+component, wait for the frame to reload and call `component_status` again; do
+not restart the daemon merely to pick up a normal source edit.
+
+## 4. Close only the important remaining gaps
+
+If an on-screen component is not `exact` and the difference is load-bearing,
+read its source and choose the smallest honest adaptation:
+
+- **A snippet** (`add_snippet`) that composes library primitives to match the
+  component's appearance. It stays editable on the canvas and is the preferred
+  answer for a bespoke compound component that is outside the shadcn library.
+  Library compound components whose files are `exact` already preserve their
+  children in the whole-screen mount and do not need a snippet. `render_snippet`
+  immediately after defining one.
+- **`$emitAs { name, importPath }`** on the node when the preview can be an
+  approximation but the generated code must import the real component. Design
+  with primitives, emit `<DataTable />`. Use this for anything whose appearance
+  you cannot reasonably rebuild but whose identity in the code matters.
+- **A live extension** (`add_extension` with `render: "live"`) only for the
+  genuinely dynamic minority — charts above all. It bundles the real host file
+  and client-mounts it, so it is the one path that renders the user's actual
+  code. Know its limits before reaching for it: children are stripped, the
+  mount is visual-only, and it breaks whenever the host file doesn't compile.
+  Never the default for library components, and never use it to work around a
+  compound component with children.
+
+Do not replace an `adapted` overlay merely because its status is not `exact`;
+the adaptation is what keeps dialogs, menus, popovers, and similar components
+visible and selectable on a static canvas. Adapt only when the visual contract
+the user cares about is materially different.
+
+## 5. Leave a record
+
+Write what you found as a note on the main board (`add_note`) so the next
+session — and the user — knows where things stand. Three headings, honest:
+
+- **Exact** — theme imported from `<path>`, fonts, and the components reported
+  `exact` by `component_status`.
+- **Adapted / fallback** — the status, reason, and any snippet / `$emitAs` / live
+  decision made to close a load-bearing difference.
+- **Unverified** — screens behind auth you couldn't reach, pages whose dev
+  server wouldn't start, tokens the stylesheet didn't declare.
+
+Re-running this skill updates that note (`list_notes` → `update_note`) rather
+than adding a second one.
+
+## Then design
+
+Calibration is not the deliverable — it's what makes the deliverable
+trustworthy. Hand off to **velloo-design** for the actual screen work,
+**velloo-brand** or **velloo-design-system** for identity and token work, and
+**velloo-implement** when a design becomes code. Tell the user in one line what
+you matched and what stayed unverified, then get on with the design task they
+asked for.