Vellum

Mobile mockups for Obsidian plugins and vault apps, designed with your coding agent.

English · 繁體中文

Sketch your plugin's screens on a real phone frame, inside your vault. Vellum keeps each screen as a small JSON file: your agent reads exactly where everything is and builds the plugin to match, with no screenshots and no long descriptions. Colours, fonts and icons come from your Obsidian theme, so the 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.}

Install · Quick start · With your agent · File format · FAQ

_{Screens of ZeLedger, a personal finance app built in Obsidian, designed in Vellum with Claude Code. Every number is made up.}

Features

Real devices iPhone 12 – 17, Pixel 8, Galaxy S24 / S25, or any size, with cut-outs and safe areas.	Portrait and landscape A layout for each, one switch for the whole editor.	Blocks and gravity Text and shapes keep an anchor point, an offset, and hug / fixed / fill sizes.
Pictures and icons Images by address or vault path; Lucide icons by name.	Frames Screens share a layout and store only what they change.	Snapping Edges, middles, margins and neighbours, with guide lines.
Screen map Every screen as a tree, joined by how you get there.	Its own window A full editor on a computer, a bottom sheet on a phone.	Plain JSON One file per screen, one block per line. Small diffs.

_{Map: every screen as a tree; mocks have a dashed outline}

Install

• BRAT: add the beta plugin zelvet-velvet/vellum.
• Manual: copy main.js, manifest.json and styles.css from the latest release into <vault>/.obsidian/plugins/vellum/, then enable Vellum.

Quick start

1. Click Vellum in the ribbon. The editor opens on Screens/.
2. New Screen, add a block, place items in it.
3. 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.

1. The agent drafts your app's screens, or proposes new ones.
2. You adjust them in the editor and leave a Note on what to change.
3. The agent builds from the screens you changed.

The card with the mix bars, as its file holds it: {"name": "Card 2", "kind": "card", "x": 16, "y": 397, "w": 396, "h": 182, "items": [ {"type": "text", "v": "MIX VS YOUR TARGET", "size": 12}, {"type": "text", "v": "4 WARNINGS", "dx": 286, "color": "dim"}, {"type": "text", "v": "Stock ETF", "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.

Read github.com/zelvet-velvet/vellum's README for the file format.
Write each page of my app as a Vellum screen in Design/Screens, one JSON file per screen.
Use real text, pictures by https address and icons by Lucide name. Keep ids stable.
Draw a card's background or outline with the block's own fill / stroke, and a chip or tile with the text's own box,
not with rectangles under them.

[!TIP] Frames belong to what they frame: a block has its own fill, stroke and sides, 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 ZeLedger were designed this way, with Claude Code.}

File format

flowchart LR
  D["Doc<br/>device, safe areas"] --> P["Page<br/>one screen"]
  P --> B["Block<br/>x, y, w, h, kind"]
  B --> I["Item<br/>text · rect · ellipse · line<br/>img · icon · row · col"]
  P -. "inherit: true" .-> F["Parent page<br/>used as its frame"]

A folder holds one JSON file per screen, plus _doc.json for the device and the screen order. Show it in a note with:

```vellum
src: Design/Screens
```

{"id": "home", "name": "Home", "blocks": [
  {"id": "b1", "name": "Title", "kind": "nav", "x": 16, "y": 70, "w": 370, "h": 44, "items": [
    {"id": "t1", "type": "text", "v": "HOME", "font": "display", "size": 32, "g": "l"}]}]}

Shortcuts

FAQ

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.