Vellum

by Zaviel
5
4
3
2
1
Score: 47/100

Description

Obsidian plugin: mobile mockups for Obsidian plugins and vault apps, designed with your coding agent.

Reviews

No reviews yet.

Stats

0
stars
43
downloads
0
forks
7
days
1
days
7
days
12
total PRs
3
open PRs
0
closed PRs
9
merged PRs
0
total issues
0
open issues
0
closed issues
97
commits

Latest Version

7 days ago

Changelog

  • Release files are now built on GitHub and attested: check a download with gh attestation verify main.js -R zelvet-velvet/vellum.
  • Fixes for Obsidian's community review: styles set through Obsidian's API in the picture preview and the colour picker.

README file from

Github

A 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.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 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.
  3. 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, 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 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.