Vetta UI Design

Vetta UI Design

A design document is ONE directory — login-app.vetd/ — holding everything:

login-app.vetd/
  design.json           ← canvas manifest. GENERATED — see below.
  frames/               ← one TSX file = one canvas frame = one route
    index.tsx           ← the site root "/"
    login.tsx           ← "/login"
    _layout.tsx         ← optional shared shell; `_` files are NOT frames
  components/           ← shared React components
  assets/               ← images, imported relatively
  theme.css             ← color/radius/shadow tokens (Tailwind v4 @theme)
  package.json          ← this design's npm dependencies; vetd_install writes it
  DESIGN.md             ← optional spec; OVERRIDES defaults in this skill

You write the sources; the plugin owns the manifest and reconciles automatically. Every save hot-reloads the canvas. Two consequences worth internalising before you start:

• The file name IS the route and the frame id. Create a screen by writing frames/<kebab-id>.tsx, delete one by deleting the file. There is no registration step anywhere.
• Editing design.json is pointless, not just forbidden. It is regenerated from your tsx declarations on every save, so any hand-edit is overwritten seconds later. If a frame is not showing up the way you expect, the answer is always in the tsx.

It is a project, not a picture

The output is a running front-end app the user can click through in preview, built from sources meant to ship. Decide structure BEFORE writing screens:

1. Routes — frames/login.tsx is /login, index.tsx is /.
2. Navigation — import { Link, useNavigate } from "react-router".
3. Shared chrome written once — nav bar / sidebar / tab bar goes in components/, or in frames/_layout.tsx rendering <Outlet /> when it must survive navigation. Never paste it into each frame.
4. Shared vocabulary — colors/radii/shadows from theme.css tokens (bg-primary, not #0d99ff); repeated blocks become components.

If changing the nav bar means editing more than one file, the structure is wrong. Posters, slides and infographics are standalone artwork — steps 1-3 do not apply to them.

The one rule you have to hold in your head

Frame meta is the FIRST statement, one flat line (regex-parsed):

export const frame = { width: 390, height: 844, title: "Login" };

Every frame declares its own. Omit it and the frame is rendered at a size inferred from the rest of the design — it still reaches the canvas, but nothing about that size is yours, and issues will keep asking until you declare one. Sizes come from the product type below; when the design already has frames, vetd_status lists their sizes and the design's defaultFrameSize — match them unless the new screen is a different product type.

It gets its own section because it is the only convention here that needs judgment from you. Everything else is either caught automatically or visible in the render.

Caught for you — copy the templates and these never come up

A checker parses every source you write; violations come back as issues on vetd_screenshot and vetd_status, naming the file and line. A file that does not parse, or that imports a package the engine does not have, comes back the same way. The templates below are already correct on all of it:

• h-full, never h-screen/min-h-screen — a frame is a fixed-size canvas, not a viewport.
• Icons are Iconify classes — a <span> with a class, NOT a component: <span className="icon-[lucide--search] size-4" />. There is no icon package to import: import { Search } from "lucide-react" fails to build, and so does every other icon library. Never your own icon component, never inline SVG paths. Offline sets, and only these: lucide, tabler, mdi, simple-icons — naming any other set fails to build too.
• <Link to> from react-router for internal screens, never <a href="/…">, and never a locally redefined Link/useNavigate/useLocation.
• No remote image URLs (<img>, background-image) — they break screenshots. Import from assets/, or use a gradient/token color/Iconify glyph.
• Normal formatting, one element per line for nested markup. Everything on one line destroys element→source mapping, and the user's "Ask Vetta" edits then point every element at the same line.
• One default export per frame, rendering edge-to-edge — no page margins.
• react, react-router, Tailwind v4 and Iconify are always there. Anything else has to be installed into the design first (see below) — importing a package that is not installed fails the build. No remote font links (Google Fonts <link>/@import url(...)) — typefaces are installed packages, see below.

Dependencies are yours to choose — and yours to justify

A design is a real npm project: vetd_install adds packages to its own package.json, and they travel with the design. vetd_status lists what is already installed — read that before adding anything.

Install when the job is a solved domain problem where a hand-rolled version is visibly worse: chart geometry and axes, Markdown or rich-text rendering, date math and calendars, virtualised long lists, gesture/physics animation.

Build it yourself when Tailwind and React state already do it well — cards, tabs, modals, dropdowns, toggles, steppers, progress bars, a simple bar or donut drawn with divs or inline SVG, and layout of every kind. A UI kit pulled in for a rounded card costs more than it gives: it arrives with its own design language and spends the rest of the design fighting theme.css.

Never install an icon package (icons are Iconify classes), a CSS framework (Tailwind v4 is here) or a router (react-router is here).

Install everything you need in ONE call, then import normally.

Typefaces are packages too

System fonts alone cannot give a display face and a body face that differ, and that sameness is a large part of why generated UI looks generated. A typeface is an npm package here like any other library:

1. vetd_install the faces — @fontsource-variable/<slug> when the family has a variable build (one file covers every weight), else @fontsource/<slug>, whose bare import is weight 400 only — import each other weight you use (@import "@fontsource/<slug>/700.css";) or the browser fakes the bold.
2. Import them at the TOP of theme.css, above @theme. Install first: theme.css feeds every frame, so importing a package that is not there yet breaks the styling of the whole canvas, not one frame.
3. Declare them as --font-* tokens and use the matching font-* class.

@import "@fontsource-variable/fraunces";
@import "@fontsource-variable/geist";

@theme {
	--font-display: "Fraunces Variable", "Songti SC", "SimSun", ui-serif, serif;
	--font-sans: "Geist Variable", "PingFang SC", "Microsoft YaHei", ui-sans-serif, system-ui, sans-serif;
}

The family name must be the one the package registers: the -variable packages append Variable, the static ones do not. A mismatch silently falls back — issues reports it, as it reports an installed face nobody imports.

Latin faces only. CJK packages are megabytes per weight; Chinese and Japanese copy uses the platform faces listed after the Latin one in the stack above (serif: Songti SC / SimSun; sans: PingFang SC / Microsoft YaHei), so every stack names both.

The one thing nothing catches: a token that does not exist

Theme tokens in className (bg-primary, text-muted) instead of hex — but the token must exist in theme.css @theme. Tailwind generates nothing for a class it cannot resolve, so bg-brand without --color-brand leaves the element with no background at all. Same mechanism as a blank icon: the source reads perfectly, and nothing renders. Add the token first, then use it.

Structure first, lines second

Reach for whitespace, alignment and surface tone before you reach for a border: a gap twice the size of the gaps inside a group already reads as a separation, and a shared gutter already reads as a column. Then, for every line, divider or card wrapper you are about to draw, answer one question — what does it do that space could not?

The question does not presume the answer is no. A dense table, an object the user acts on, a layer that overlaps scrolling content and a field that has to be findable all answer it in a word; a wireframe, a report, a terminal UI or an engineering console answers it for most of their lines. What it catches is the line drawn out of habit — the box around every section, the rule under every heading — which is a generated-UI tell rather than neutral styling. references/taste/whitespace.md has the substitutions, the per-product-type notes, and the cases where lines are the design.

Pick the product type

This is the first decision, not an afterthought: vetd_create requires it (product, or frameSize in pixels for anything the enum cannot express), and it becomes the design's default size. Read it off the user's own words, in whatever language they wrote them — a phone app is mobile, an admin console or dashboard is desktop. An explicit user instruction always wins. Do not default to a phone frame; a dashboard at 390 wide is the most common failure.

The design default only covers frames that forgot to declare a size. A document can mix product types — a poster next to three phone screens — as long as each frame declares its own.

Templates

Start from these three. They are the shape the checker expects; deviating from them is how the mechanical issues above get triggered.

Their copy is English only because this file is; it says nothing about which language to design in. Frame titles and every label inside a frame go in the language the USER is writing to you in — same rule as your own replies.

// frames/products.tsx — a screen is composition, nothing structural
export const frame = { width: 1440, height: 900, title: "Products" };

import { StatCard } from "../components/StatCard";

export default function Products() {
	return (
		<div className="flex h-full flex-col gap-6 bg-surface p-8 text-surface-foreground">
			<h1 className="text-xl font-semibold">Products</h1>
			<div className="grid grid-cols-4 gap-4">
				<StatCard label="In stock" value="1,284" />
			</div>
		</div>
	);
}

// frames/_layout.tsx — the shell, mounted once, renders <Outlet /> itself.
// `h-full` here too: this wraps the frame, it is not a page.
import { Outlet, useLocation } from "react-router";
import { NavBar } from "../components/NavBar";

export default function Layout() {
	const { pathname } = useLocation();
	// Screens outside the app shell (login, onboarding) opt out here.
	if (pathname === "/login") return <Outlet />;
	return (
		<div className="flex h-full flex-col bg-surface">
			<NavBar />
			<div className="min-h-0 flex-1 overflow-auto">
				<Outlet />
			</div>
		</div>
	);
}

// components/NavBar.tsx — the ONLY definition of this chrome
import { Link, useLocation } from "react-router";

const items = [
	{ to: "/", label: "Overview", icon: "icon-[lucide--layout-dashboard]" },
	{ to: "/products", label: "Products", icon: "icon-[lucide--package]" },
];

export function NavBar() {
	const { pathname } = useLocation();
	return (
		<nav className="flex items-center gap-1 px-4 py-3">
			{items.map((item) => (
				<Link
					key={item.to}
					to={item.to}
					className={`flex items-center gap-2 rounded-md px-3 py-1.5 text-sm ${
						pathname === item.to ? "bg-primary/10 text-primary" : "text-muted"
					}`}
				>
					<span className={`${item.icon} size-4`} />
					{item.label}
				</Link>
			))}
		</nav>
	);
}

Workflow

New document: pick the product type → vetd_create with it → set the direction → start building. Do NOT offer the user a menu of styles: design systems are a thing the user opts into from the Design sidebar, not something you propose. Just design well for what they asked for, deriving the palette and type scale from the product itself.

If the project root has a design-resources/<slug>/ directory, the user started this project from that style in the Design sidebar; it is the style reference pack for this project and following it is the default:

• Read its INDEX.md (the file inventory), then its DESIGN.md — that spec is the style contract for what you are about to design.
• After vetd_create, write the pack's theme.css content into the design's own theme.css before building frames.
• Before your first frame, Read the pack's demo HTML and screenshots too (INDEX.md marks which is which). The demo is the spec applied to a full page — it answers what DESIGN.md alone cannot: real density, spacing rhythm, component shapes, how the palette is actually distributed. Skipping it is how a design ends up on-token but off-style. They are visual reference only: study layout and mood, never copy their markup or code into frames — frames are React + the tokens you just copied, not HTML.
• The user outranks the pack: if they ask for a different style, follow the user. Several packs side by side and no user pick: ask which one first.

The pack stays the contract in later sessions too: adding screens to a design that grew out of one, re-read its DESIGN.md (and glance at the demo) before designing anything new.

If DESIGN.md exists in the design document, the user has already applied a system — read it first and follow it, and do NOT rewrite it or theme.css.

Set the direction when neither a pack nor DESIGN.md sets the style. Left to defaults, every design converges on the same thing — the scaffold's indigo and slate, one system sans at two sizes, centred cards, a three-column feature row — and users recognise it instantly as generated. Before the first frame:

1. Read references/taste/directions.md and references/taste/whitespace.md, then the file for the product type: references/taste/landing-structures.md for a landing page, references/taste/app-density.md for app screens and dashboards.
2. Decide tone, anchor hue, type pairing and structure, and state them in one line of your reply — Direction: technical · cobalt (256°) · Space Grotesk + Geist · dense workbench. The user redirects from that line; no menu.
3. Rewrite every value in the scaffold theme.css with the direction's palette (keep the token names), vetd_install the two faces, and import them at the top of theme.css — all before the first frame, so no frame is ever built on the placeholder palette.

Read references/taste/color.md, typography.md and copy.md when a decision in them is in front of you, not up front. With a pack or DESIGN.md in charge, skip the direction and still screen every capture against references/taste/anti-patterns.md — no style asks for those.

Existing document: vetd_status ONCE first. It returns the frame ids/sizes, sharedShell (existing _layout.tsx + components/ — reuse them) and issues. Read theme.css and reuse what is there. You do not need to call it again afterwards — vetd_screenshot returns issues per frame.

Then, for a multi-screen product, write in two passes:

1. Skeleton pass. Write the shared parts (_layout.tsx, components/), then EVERY frame as a short file: the frame meta line plus the page's structural blocks — header, the grid, section placeholders. A few dozen lines each. The whole set lands on the canvas within seconds, so the user sees the screen inventory and the layout immediately, and a wrong size or a wrong route shows up before you have written any detail.
2. Detail pass in coherent batches. Fill in real content for a small group of related frames (or the whole set when it is simple), then call vetd_screenshot once with frames: [...]. Read the returned contact sheet once and compare the screens together. Use the single frame form only for a targeted recheck after a fix. Each save still hot-reloads, so the user sees progress while one model/tool round verifies several screens.

Single screens, posters and slides skip the skeleton pass — just write the file.

Going back: every design keeps its own version history — one version per turn that changed it, saved automatically, titled with what the user asked for. So "undo that", "go back to before the nav bar moved", "restore the previous version" is vetd_history then vetd_restore, NOT you editing files until they resemble the old version from memory. Restoring is safe in both directions: it is saved as a new version too, so a wrong pick is one more vetd_restore away from being corrected — the response tells you where the pre-restore state went. The user can also do it themselves from the canvas's history panel, where the versions carry thumbnails.

Verify visually: call vetd_screenshot with all frames you created or changed (frames: [...], or all: true when the whole design is in scope), then Read the returned overview image once. You are looking for rendering defects the code cannot show you — run the checklist in references/quality.md, which starts with the three that account for most of them: misalignment, unintended text wrapping, and classes that resolve to nothing (a blank icon, or a surface whose theme token was never defined). A frame that does not parse is listed as a failed member without discarding the other captures — fix the reported line and recheck that frame only.

Every successful frame also carries a verification observation. If stalled: true, two consecutive checks produced the same image and the same issues. Do not make a third blind edit: inspect whether the checker assumption fits the visible result, and report the stalled finding when it is a false positive. vetd_status.issues: [] is source-only and is never visual proof; renderVerification tells you whether prior captures are current or stale.