velloo 0.4.1 → 0.5.0

package/pkgs/schema/src/config.ts

@@ -28,7 +28,7 @@ export const LibrarySchema = z.object({
    * Component provider id. The server's provider loader maps ids to
    * factories; `"shadcn-upstream"` is the default for new folders.
    */
-  id: z.enum(["shadcn-upstream", "none", "mui", "antd", "chakra"]),
+  id: z.enum(["shadcn-upstream", "none", "html", "mui", "antd", "chakra"]),
   version: z.string().min(1),
   source: z.enum(["binary", "cache", "in-repo"]),
   /** Where the components live, relative to the design folder root. */
@@ -50,6 +50,19 @@ const CodegenConfigSchema = z.object({
 
 export type CodegenConfig = z.infer<typeof CodegenConfigSchema>;
 
+/**
+ * A path inside the host app, relative to its root. The config is committed
+ * with the repo and the agents are told to open what it names, so a cloned
+ * repo must not be able to aim it anywhere else: absolute paths and `..`
+ * segments make the file invalid rather than being resolved.
+ */
+const AppRelativePathSchema = z
+  .string()
+  .min(1)
+  .refine((path) => !/^(?:[\\/~]|[A-Za-z]:)/.test(path) && !path.split(/[\\/]/).includes(".."), {
+    message: "must be relative to the app root, with no absolute path or `..` segment",
+  });
+
 /**
  * Where the host app lives, used by the live-island bundler to resolve
  * a `render:"live"` extension's `importPath` (and its dependencies, e.g.
@@ -73,6 +86,11 @@ export const HostAppSchema = z.object({
    * built-in framework recipe, then no wrapper.
    */
   preview: z.string().min(1).optional(),
+  /**
+   * The app's stylesheets an HTML design is styled by, in cascade order. The
+   * design keeps copies of them under `assets/host/` (`store_host_files`).
+   */
+  stylesheets: z.array(z.string().regex(/^(?:\/(?!\/)|https:\/\/)/)).optional(),
   /**
    * Bounds repository-component discovery beyond what the app's entries and
    * routes import: `include` adds component roots (files or directories,
@@ -171,6 +189,20 @@ export const ConfigSchema = z
     styling: z.object({ framework: z.enum(["tailwind", "none"]) }).optional(),
     /** Host app location for the live-island bundler. See `HostAppSchema`. */
     hostApp: HostAppSchema.optional(),
+    /**
+     * A design-system document this folder follows — normally the repo's
+     * `DESIGN.md`.
+     *
+     * A path, never a copy. The file belongs to the repo and goes on being
+     * edited there; a copy inside the design folder would drift away from the
+     * rules it was supposed to state, which is the one thing a design system
+     * must not do. Relative to the host app root, so the usual value is
+     * `DESIGN.md`.
+     *
+     * Optional because the folder also finds one by convention — this records
+     * a file somewhere unconventional, or pins the choice when several exist.
+     */
+    designSystem: z.object({ path: AppRelativePathSchema }).optional(),
     /**
      * Named host apps for monorepos — the multi-app twin of `hostApp`, keyed
      * by a short app name (`"web"`, `"admin"`; `init`'s multi-app scan uses

package/pkgs/schema/src/css-declarations.ts

@@ -0,0 +1,41 @@
+const CSS_PROPERTY = /^(--[\w-]+|-?[a-z][a-z-]*)$/;
+
+/**
+ * CSS declaration text as a React style object (`background-size` ⇒
+ * `backgroundSize`, custom properties kept), or null when the text is not a
+ * declaration list — a class string, say. Semicolons inside `url(…)` or quotes
+ * do not split.
+ */
+export function styleObjectFromCss(text: string): Record<string, string> | null {
+  const declarations: string[] = [];
+  let depth = 0;
+  let quote: string | null = null;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (quote) {
+      if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") quote = char;
+    else if (char === "(") depth++;
+    else if (char === ")") depth = Math.max(0, depth - 1);
+    else if (char === ";" && depth === 0) {
+      declarations.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  declarations.push(text.slice(start));
+  const style: Record<string, string> = {};
+  for (const declaration of declarations) {
+    if (declaration.trim() === "") continue;
+    const colon = declaration.indexOf(":");
+    if (colon < 0) return null;
+    const property = declaration.slice(0, colon).trim().toLowerCase();
+    const value = declaration.slice(colon + 1).trim();
+    if (!CSS_PROPERTY.test(property) || value === "") return null;
+    const key = property.startsWith("--")
+      ? property
+      : property.replace(/^-(ms)-/, "$1-").replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+    style[key] = value;
+  }
+  return Object.keys(style).length > 0 ? style : null;
+}

package/pkgs/schema/src/index.ts

@@ -56,6 +56,7 @@ export {
   type ViewportPreset,
   ViewportPresetSchema,
 } from "./config.ts";
+export { styleObjectFromCss } from "./css-declarations.ts";
 export {
   isCssIdent,
   neutralizeCssText,
@@ -139,6 +140,8 @@ export {
   ColorsSchema,
   type LooseTokenGroup,
   resolveColors,
+  spacingCssTokens,
+  TAILWIND_SIZE_NAMES,
   type Theme,
   ThemeSchema,
   TypographySchema,

package/pkgs/schema/src/theme.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { isCssIdent } from "./css-sanitize.ts";
 
 const NumOrCssLen = z.union([z.number(), z.string().min(1)]);
 
@@ -56,6 +57,45 @@ export type Colors = z.infer<typeof ColorsSchema>;
  */
 export type ColorsOverride = { [K in keyof Colors]?: Colors[K] | undefined };
 
+/**
+ * Spacing names Tailwind v4 already reads as a size scale. Its `max-w-*`,
+ * `w-*` and `min-w-*` utilities resolve a `--spacing-<name>` ahead of
+ * `--container-<name>`, so a design system's t-shirt spacing (`xl: 1.5rem`)
+ * emitted under one of these names turns every `max-w-xl` into 24px and a
+ * paragraph into one word per line.
+ */
+export const TAILWIND_SIZE_NAMES: ReadonlySet<string> = new Set([
+  "3xs",
+  "2xs",
+  "xs",
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "2xl",
+  "3xl",
+  "4xl",
+  "5xl",
+  "6xl",
+  "7xl",
+  "prose",
+]);
+
+/**
+ * The named spacing tokens that become `--spacing-<name>` in CSS. Numeric
+ * steps are Tailwind's built-in scale and names Tailwind reads as sizes stay
+ * in the theme only; the canvas stylesheet and the emitted globals.css both
+ * come from this list, so they cannot disagree.
+ */
+export function spacingCssTokens(spacing: Theme["spacing"]): Array<[string, string | number]> {
+  const out: Array<[string, string | number]> = [];
+  for (const [name, value] of Object.entries(spacing ?? {})) {
+    if (!Number.isNaN(Number(name)) || !isCssIdent(name) || TAILWIND_SIZE_NAMES.has(name)) continue;
+    if (typeof value === "string" || typeof value === "number") out.push([name, value]);
+  }
+  return out;
+}
+
 /**
  * The effective colors for a mode: `colors`, with `colorsDark` layered on when
  * rendering dark.

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

@@ -1,9 +1,10 @@
 ---
 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.
+  Reviews Velloo screens without modifying them — the folder's own stated design
+  rules, 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:
@@ -11,23 +12,65 @@ 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.
 
+Start with `get_theme`. Besides the tokens it may return `designSystem.path` —
+the design system document this folder follows, normally the repo's
+`DESIGN.md`. **Open that file and read it before looking at any screen.** Velloo
+points at it rather than copying it, so the file you read is the current one.
+Its "Do's and Don'ts" section is the house rules, and they outrank your taste.
+
 For each target screen (default: every screen on the default board):
 
-1. `screenshot mode: "compare"` — does the design actually adapt to dark
+1. **The folder's stated rules** — check the screens against the Do's and
+   Don'ts in the design system document. See below; this dimension comes first
+   because it is the only one that is not generic.
+2. `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;
+3. 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
+4. `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
+5. `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
+6. 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.
+7. `list_annotations` — surface unresolved designer/reviewer notes.
+
+## Reviewing against the folder's rules
+
+Work rule by rule, not screen by screen — a rule like "one accent per screen"
+is about the whole screen, and you will miss it if you are looking at nodes.
+
+**Quote the rule verbatim in every finding it produces**, copied from the file.
+The user wrote these; a finding that paraphrases them reads as your opinion, and
+the point of this dimension is that it is not.
+
+**Check only what you can actually see.** A rule is checkable when a screenshot
+or a diagnostic settles it — how many accent colors a screen uses, whether a
+flat surface carries a shadow, whether CTAs are pill-shaped, whether a heading
+uses the display face. A rule is not checkable here when it is about behavior
+(motion, transitions, hover, focus order), about content or tone, or about
+things outside the screens you were given.
+
+For an unverifiable rule, say so once in a short list at the end — "not checked:
+rules 4, 7 (both about hover states)" — and move on. Do not guess, do not
+soften it into a maybe, and do not pad the review by restating rules you did not
+test. An honest "not checked" is worth more than a speculative finding.
+
+When a rule and one of the generic dimensions disagree, report both and say
+which is which. If the folder's rule is the reason something looks wrong to
+you, the rule wins and there is no finding.
+
+If `get_theme` returns no `designSystem`, or the document has no Do's and Don'ts
+section, the folder states no rules. Say that once — it is not the same as the
+screens passing — and review the other dimensions normally. Do not invent house
+rules to fill the gap. If the path is there but you cannot open the file, say
+that too rather than reviewing as if it were empty.
+
+## Reporting
 
-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.
+Report findings ranked by severity. Each finding: screen id, node ref (`"@id"`
+or path), what is wrong, and a concrete fix. A rule-based finding also carries
+the quoted rule. 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

@@ -16,7 +16,10 @@ 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.
+   defining new ones. When `get_theme` returns a `designSystem.path`, open that
+   file and read it: it is the folder's own design system in prose — house rules
+   that outrank the defaults below, and what the reviewer will check this work
+   against. Velloo points at the file rather than copying it, so it is current.
 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

package/skills/velloo-setup/SKILL.md

@@ -6,7 +6,8 @@ description: >-
   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.
+  the canvas look like my app", or before recreating an app's page from an
+  init handoff prompt.
 ---
 
 # Calibrating Velloo to an existing app
@@ -44,60 +45,23 @@ halfway through a design.
   tool re-probes and answers with the new state; iterate until `valid`.
 
 A snippet can't do this job: it is node data, so it can't import CSS, build a
-router or wrap the whole screen. Snippets are for step 4 below.
-
-## 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.
+router or wrap the whole screen. Snippets are for step 3 below.
+
+## 1. Theme, fonts and the compare loop
 
-0.85+ similarity is a faithful structural port. Don't chase 1.0 — fonts and
-live data legitimately differ.
+The MCP instructions and `velloo://guide/porting` own this part: import the
+app's stylesheet with `import_theme` (dry run, then `apply: true`), set its real
+fonts with `set_theme { fonts }` — read how the app loads them; a wrong typeface
+makes a correct layout read as wrong — then recreate one representative screen
+and iterate `compare_to_url` against the running app, reading `unverified`
+before trusting any number. Two additions that live only here:
+
+- Run `score_theme_contrast` after the import. An app that only ever ships
+  light mode often imports into a dark palette that fails.
+- For a dashboard or feed whose content shifts between loads, pass
+  `cacheUrl: true` so you diff against one frozen capture.
 
-## 3. Establish component fidelity before adapting anything
+## 2. 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
@@ -128,7 +92,7 @@ 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
+## 3. Close only the important remaining gaps
 
 If an on-screen component is not `exact` and the difference is load-bearing,
 choose the smallest honest adaptation:
@@ -153,7 +117,7 @@ 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
+## 4. 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: