{
  "markdown": "# Vellum\n\n> Local design iteration for Claude Code. A self-hosted alternative to SuperDesign that generates static HTML/CSS mockups using your real Tailwind tokens and shadcn/ui class vocabulary.\n\nNo paid service. No account. No remote API. Files live in `.claude/designs/` inside your repo.\n\n![Vellum draft using PathSync tokens — FBO pickup card with primary and outline buttons](./docs/smoke-test.png)\n\nAbove: a Vellum-generated draft for [PathSync](https://github.com/applesnort/) — neutral baseColor in dark mode, real shadcn Button class strings, real CSS-variable tokens. No React, no build step — just an `.html` file you can open in any browser.\n\n## Why\n\nSuperDesign is great, but it's a paid service that runs your design iterations on a remote canvas. Vellum does the same workflow — branch, replace, iterate — but stays entirely local and reads your project's actual design tokens, `tailwind.config.ts`, and shadcn/ui components so generated drafts match your real app at ~95% fidelity.\n\nYou stay in your editor. Drafts are git-trackable. Tokens never leave your machine.\n\n## Install\n\n```\n/plugin marketplace add applesnort/vellum\n/plugin install vellum@applesnort\n```\n\n## First-time setup\n\nFrom any frontend project root with `tailwind.config.{ts,js}` and a shadcn `components.json`:\n\n```\n/vellum init\n```\n\nThis scans `globals.css`, the Tailwind config, and ~10 shadcn primitives, and writes `.claude/designs/_context/` (tokens.css, context.md, per-component vocabularies). Re-run any time tokens change.\n\n## Workflow\n\n```\n/vellum create modal-redesign\n/vellum draft modal-redesign --title \"Baseline\" -p \"Reproduce the current trip booking modal at 1100px wide, dark theme, all sections visible.\"\n/vellum open <draft-id>\n\n# branch into 4 variants\n/vellum iterate <draft-id> --mode branch -p \"Linear command-bar header\" -p \"Editorial magazine\" -p \"Stripe-dense\" -p \"Terminal/Vercel\"\n\n# refine the winner in place\n/vellum iterate <chosen-draft-id> --mode replace -p \"Tighten field widths via 12-col grid; cap email at max-w-sm; group passenger contact in one row.\"\n```\n\nDrafts are self-contained `.html` files that load Tailwind via CDN, inline your project tokens, and use Lucide for icons. Open in any browser — no dev server needed.\n\n## Verbs\n\n| Verb | Purpose |\n|---|---|\n| `init` | One-time per repo. Extracts tokens + shadcn class vocabulary into `.claude/designs/_context/`. |\n| `create <name>` | New project folder under `.claude/designs/<slug>/`. |\n| `draft <project> --title \"X\" -p \"...\"` | Generate a baseline draft from a prompt. |\n| `iterate <draft-id> --mode replace -p \"...\"` | Refine in place. Updates same file. |\n| `iterate <draft-id> --mode branch -p \"...\" -p \"...\"` | Spawn N sibling drafts from one parent. |\n| `open <draft-id>` | Open the HTML in your default browser. |\n| `list [project]` | Show project tree of drafts. |\n\n## What Vellum is NOT (yet)\n\n- **Not a real-component renderer.** Drafts are static HTML that mimics your shadcn classes — they won't show interactive Switch state or animated Tabs transitions. Hardcoded data-state classes work for static visual mocks (the same approach SuperDesign uses).\n- **Not a Storybook replacement.** If you need real React components rendered with Vitest interactions, Storybook is still the answer. A `promote <draft-id>` verb that converts HTML → JSX with shadcn imports is on the roadmap.\n- **Not a multi-page flow generator.** One draft = one page. SuperDesign's `execute-flow-pages` equivalent is roadmap.\n\n## How it works\n\nVellum is a Claude Code skill — a markdown file (`SKILL.md`) that instructs the Claude model what to do when invoked. It doesn't run as a daemon or background process; it executes inside your Claude Code session.\n\nWhen you run `/vellum draft …`, Claude:\n\n1. Reads `.claude/designs/_context/context.md` for your project's design vocabulary\n2. Reads `HTML_TEMPLATE.html` for the boilerplate scaffold (Tailwind CDN, font wiring, token injection)\n3. Generates body markup using only the shadcn class strings extracted from your real components\n4. Writes a self-contained `.html` file you can open immediately\n\nThe intelligence is in the **`init` extraction**: it grabs your `:root` and `.dark` CSS variable blocks verbatim, your `theme.extend.colors` mapping, and the canonical className strings from each shadcn primitive. Subsequent iterations reference this context instead of re-reading the codebase, so prompts stay tight and drafts stay consistent.\n\n## Roadmap\n\n- [ ] `promote <draft-id>` — convert locked HTML draft into a React component file with proper shadcn imports and `cn()` usage\n- [ ] `serve` — local HTTP gallery for flipping through drafts side-by-side\n- [ ] Multi-page flows\n- [ ] Storybook story export\n- [ ] Per-project `.vellumrc` to override extraction paths for non-standard repo layouts\n\n## Philosophy\n\nThe name comes from drafting paper architects use — translucent, you sketch over the base drawing without committing. Vellum drafts over your real codebase. Tokens, fonts, components, conventions — all anchored to what's actually there. The sketch is always grounded.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\n## Credits\n\nInspired by [SuperDesign](https://app.superdesign.dev/), which set the bar for design-iteration agents. Vellum is the local, self-hosted variant for teams who want their iteration loop offline and in-repo.\n",
  "bytes": 5367,
  "sha": "6ba41b8a1f6055a87ff50c1323bfba99d2517014dd429205aa97e31984357dbd",
  "repo_slug": "applesnort/vellum",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_applesnort_vellum_vellum_d11b0530/readme"
}