Guide

The .vd format

A vDesign design is a .vd file, a short, line-based text description that any model can write, read and change a line at a time. Its specification is open under CC BY 4.0.

Most design files were made for one app to save and load. A .vd file was made for a model to write, and for a person to read. It is plain text, one element per line, and it is the design: there is no separate project file behind it.

version 4
kind design
title "Launch hero"
$gap = 24
$paper = #ffffff
$accent = #5b5bd6

frame page w=1280 h=720 background=paper
  rect hero.bg x=$gap y=$gap w=(100% - $gap * 2) h=320 fill=accent radius=20
  text hero.title x=(@hero.bg.left + 40) y=(@hero.bg.top + 40) w=680 h=48 size=40 weight=700 fill=paper
    "An open document format"

What makes it different

Relationships, not coordinates. w=(100% - $gap * 2) stays that formula in the file. Change $gap and everything that reads it moves, in the file as well as on the canvas. Models are reliable describers and unreliable calculators, so the format asks them to describe and leaves the arithmetic to the runtime.

Edits are patches. A change is a few lines in the edit dialect, such as set $gap = 40, not a regenerated document. That keeps an assistant’s edits fast, cheap and easy to review.

Small, and it streams. A design is 45% of the size of the same design as JSON. A finished line is a finished element, so the canvas fills in while the model is still writing.

Names you can guess. Elements are addressed by role, like hero.title, not by a random id, so an agent can change what it means without reading the whole file again.

It carries everything. Fonts, images and music travel inside the file, so one file renders anywhere with nothing else to fetch.

Readable wherever you work

Diff it, review it and keep it in git like code.
Preview it in VS Code, Cursor and github.dev, with problems shown as you type.
Draw it in Markdown: a ```vd fence in a README, a docs site or Obsidian becomes the design (Designs in Markdown).
Export a .vd.svg, an SVG that shows everywhere and still opens as the design.
Export PNG, JPEG, WebP, SVG, PDF, Illustrator, HTML, PowerPoint, GIF and, from the app, MP4.

Open to implement

The specification is open under CC BY 4.0. You need no permission to read or write .vd files in your own software, open or closed. The full reference is in the docs, and llms-full.txt teaches any model the whole format in one file.

Questions

Is the .vd format open?

Yes. The specification is licensed under CC BY 4.0, and anyone may read and write .vd files in their own software, open or closed, without asking. The vDesign apps are free to use; their code is proprietary.

Why not JSON or HTML?

A design in .vd is 45% of the size of the same design in vDesign's JSON form, it streams a finished node per line, and an edit is a short patch rather than a rewrite. Geometry is kept as relationships, so a model describes intent and the runtime does the arithmetic.

What can a .vd file hold?

Pages of any size with shapes, text, images, icons, groups and components, named tokens for colours, sizes and spacing, fonts, motion and music for video, and a brand's palette, type and rules. Images travel inside the file.

Can I open a .vd file outside vDesign?

Yes. It is plain UTF-8 text, so any editor opens it. The vDesign extension previews it in VS Code, Cursor and github.dev, a ```vd fence in Markdown is drawn as the design, and a .vd.svg export is a picture everywhere that still carries the design.