README file from
GithubA light plugin for UI drafts that never leaves your vault: no design app, no website, no account. Lay screens out on a real phone frame; each one is a small JSON file, so any agent that can open the vault reads exactly where everything is and edits the same files. No screenshots, no long descriptions.
- Any app, not only plugins: a side project or a work project. If your notes live in Obsidian, its screens can too.
- Point at a piece, ask for a change: copy a block or an item for the agent in one click, say what to change, see it on the phone.
- Talk through the flow, not just the pixels: the Map shows how the screens connect, so you and the agent can work out the app's logic and UX together.
Colours, fonts and icons come from your Obsidian theme, so a plugin's mockup already looks like the plugin.
The JSON is a layout intent, not native layout code. It maps directly to HTML and CSS, so to Obsidian plugins; for SwiftUI or Compose, see the FAQ.
Features
Install
- Community plugins: in Settings → Community plugins → Browse, search for Vellum, install and enable it.
- BRAT: add the beta plugin
zelvet-velvet/vellum. - Manual: copy
main.js,manifest.jsonandstyles.cssfrom the latest release into<vault>/.obsidian/plugins/vellum/, then enable Vellum.
Quick start
- Click Vellum in the ribbon. The editor opens on
Screens/. - New Screen, add a block, place items in it.
- Ctrl+S to save.
Want sample screens? Copy examples/Vellum Demo.md into your vault.
With your agent
Any agent that reads and writes files works: Claude Code, Codex, Cursor. No plugin API, no server.
- The agent drafts your app's screens, or proposes new ones.
- You point and ask: choose a block, press Copy reference (Ctrl Shift C), paste it to the agent with what to change. Or leave a mark on the screen: a pinned note, a named area, a guide line. The agent can answer with marks of its own.
- The agent builds from the screens you changed.
The card with the mix bars, as its file holds it:
{"name": "Mix vs your target", "kind": "card",
"x": 16, "y": 323, "w": 396, "h": 183, "items": [
{"type": "text", "v": "MIX VS YOUR TARGET", "size": 12},
{"type": "text", "v": "5 WARNINGS", "dx": 286, "color": "dim"},
{"type": "text", "v": "ETFs", "dy": 29, "size": 15},
{"type": "rect", "dy": 54, "w": 396, "h": 16, "fill": "dim"}
]}
One screen is one small file. The agent reads exactly where each thing is, and changes only what it needs to.
Start your agent with this; the guide for agents tells it what Vellum can do:
Read github.com/zelvet-velvet/vellum/blob/main/docs/for-agents.md.
Write each page of my app as a Vellum screen in Design/Screens, then tell me the folder.
When I ask for options, make them as Vellum mocks, not as a web page.
[!TIP] Frames belong to what they frame: a block has its own
fill,strokeandsides, a text its own box. A rectangle drawn as a frame (an older screen) shows Make it the block's look or Make it the text's box when you choose it.Ask for two or three mocks (
"mock": true) as sub screens and keep the one you like. The agent can write while the editor is open: Vellum reloads the files and never overwrites your unsaved edits.
The screens of Morellonomicon and Ledgerline were designed this way, with Claude Code.
File format
One folder per app, one small file per screen:
Design/Screens/
├─ _doc.json the phone: device, safe areas, corner, status bar; the screen order
├─ Home.json a screen
└─ Settings.json another screen
A screen is a few blocks, boxes on the phone. Each block holds items, placed by an anchor:
{"id": "home", "name": "Home", "blocks": [
{"id": "title", "name": "Title", "kind": "nav", "x": 16, "y": 70, "w": 396, "h": 44, // a box, in points
"items": [
{"id": "t1", "type": "text", "v": "HOME", "font": "display", "size": 32, "g": "l"}, // left, centred down
{"id": "i1", "type": "icon", "name": "settings", "g": "r"} // right: a Lucide icon
]}
]}
Show the screens in a note with a code block vellum holding src: Design/Screens. Every field is below; agents have their own guide.
| Level | Fields |
|---|---|
| Doc | device; safe, safeLand (top bottom left right, each optional); radius (the screen's corner, 0 for a square screen; else the device's); bar (the status bar: style ios, android or none, fill, ink, time; as high as safe.top when that is set) |
| Page | name, note, parent, link (how you get there), inherit (true: the parent is its frame), device, bg, mock, blocks, land (the landscape layout), marks |
| Block | name, kind, note, x y w h (screen points), bleed (true: may go into the safe areas; a block wholly outside the screen is a draft, kept beside it in the editor and not built), its own look: fill stroke sw r and sides (the outline on some sides only: "b", "tb"…), items |
| Any item | g (anchor: tl t tr l c r bl b br), dx dy, w h (a number, "hug" or "fill"), op, note |
text |
v size wt font color ls lh upper, and a box of its own: fill stroke sw r pad (a chip, a tile, a button; with a set h the text sits in its middle) |
rect ellipse line |
fill stroke sw r (r: one radius, or four: [tl, tr, br, bl]) |
img |
src (https://… or a vault path), fit (cover · contain · fill), pos (CSS object-position), r |
icon |
name (Lucide), color size sw |
row col |
items gap pad main cross, fill stroke sw r |
group |
items, each placed in the group's w h box by its own g dx dy; moved as one |
| Mark | A note on the screen for you and the agent, never part of the design: id, kind (note: a pin · area: a box w h with a guide in it if wanted, thirds phi spiral diag center · line: axis "x" down or "y" across), x y, text, color, size (its text's size, 11 if not set), w on a note (its bubble's width, else as wide as its text), land, by ("agent") |
Frames. A page with "inherit": true draws its parent's blocks under its own. An own block with the same id replaces the parent's one; the page stores only its own blocks.
Colours and fonts. Items use theme names (paper text dim line tile loud accent; ui display mono), set in Settings → Vellum, or any CSS value. The editor's own panels follow your Obsidian theme, or the Editor theme colours in the same settings.
Shortcuts
| ← → ↑ ↓ | Nudge 1 pt, with Shift one grid step |
| Ctrl Z · Ctrl Shift Z | Undo · redo |
| Ctrl D · Delete | Duplicate · delete |
| Ctrl S | Save |
| Alt / Shift while dragging | No snapping · keep the shape |
| Middle button, drag · Ctrl + wheel | Move the view · zoom at the pointer (up to 1600 %) |
| Drag on empty space · with Ctrl | Choose the blocks inside the area (or the items it crosses) · always the items |
| Shift click · Ctrl A | Add to the chosen or take out · every block |
| Ctrl G · Ctrl Shift G | Group the chosen items · ungroup |
| N · Shift N | The mark tool (a click: a note, a drag: an area) · show / hide the marks |
| Ctrl ' | Show / hide the overlays |
| Ctrl Shift C | Copy a reference to the chosen screen, block or item, for the agent |
| ← → in Show | The previous · the next screen |
| Hold a number box, then drag up / down | Change it (a click types; ↑ ↓ step it, with Shift ×10) |
FAQ
Only to show a picture whose src is an https:// address, as an image in a note would. Vellum makes no requests of its own.
Yes, as a sketch your agent translates. Inside a block, items are placed the way native layouts work:
| Vellum | SwiftUI | Compose |
|---|---|---|
anchor point (g) |
alignment |
Alignment |
"hug" / "fill" |
.fixedSize() / .frame(maxWidth: .infinity) |
wrapContentSize() / fillMaxWidth() |
row / col |
HStack / VStack |
Row / Column |
Blocks themselves sit at fixed positions on the screen, so the agent turns those into stacks and spacing.
Yes. The editor takes the full screen, with its settings in a bottom sheet.
On the device, in Obsidian's storage for that vault, until you save.
npm install && npm run check && npm run build
npm run install-vault -- /path/to/vault
Support
Vellum is free and made in my spare time. If it helps you, a coffee keeps it going.