vDesign

View saved version →

---
name: vdesign
description: Author and edit vDesign documents — posters, slides, hero sections, card grids, any laid-out visual document — in the .vd DSL. Use when asked to create, change, or read a vDesign document, a .vd file, or when a task involves designing a layout that should stay editable and relational rather than being flattened to fixed coordinates.
---

# Authoring vDesign documents

A vDesign document is a tree of boxes whose geometry is **declarative**. A property holds
either a number or an expression, and expressions are stored as written and resolved on
read. `w=(100% - $gap * 2)` stays that formula in the file forever; change `$gap` and
everything bound to it moves.

That is the entire point of the format, and it is what you are being asked for. A document
full of literal coordinates is a worse version of a Figma file. A document of expressions
and tokens can be edited by changing one number.

## The output contract

Emit **only DSL lines**. No prose before or after, no explanation, no JSON. A fenced block
is tolerated but unnecessary.

## The grammar in one screen

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

font display = Inter
  fallback "system-ui, sans-serif"

frame page w=1280 h=720 background=paper
  rect hero.bg x=$gap y=24 w=(100% - $gap * 2) h=260 fill=accent radius=16
  text hero.title x=(@hero.bg.left + 32) y=64 w=560 h=82 size=34 weight=700 fill=paper
    "An open substrate for the "
    "agent era" fill=highlight
  group cards
    rect card.1 x=$gap y=(@hero.bg.bottom + $gap) w=((100% - $gap * 4) / 3) h=200
```

- **The first lines are the header.** `version 4` and `kind design`. Write both. `design`
  is the free-form canvas and is the only kind that exists today; a document that does not
  say which it is leaves every reader to guess from its contents.
- **Then `title "…"`** — a short human name for what you are making, two to five words
  ("Coffee shop landing", not "Document"). It is what the tab shows, so write it before the
  first page: the name should appear while the design is still arriving.
- **Two spaces of indent is one level.** Indentation is the only nesting.
- A line is `<type> <id> key=value key=value …`.
- A **quoted line** under a `text` node is one run of its content.
- A **boolean is a bare flag**: `italic`, never `italic=true`.
- **There are no comments.** `#` already starts a colour. Anything trailing a value is an
  error rather than something to ignore, so do not annotate the document.

### The one rule worth memorising

> A value is an **expression** if it starts with `$`, `@`, or `(`. Everything else is a
> literal.

So `x=$gap` and `x=@logo.right` need no parentheses, and everything else that is an
expression does: `y=(prev.bottom + 12)`, `w=(50%)`, `y=(parent.h / 2)`. A quoted value is
always a literal, which is how you write a string that starts with a sigil: `fill="$brand"`.

## Rules that decide whether the output is any good

**1. Write relationships, not coordinates.** This is the difference between a vDesign
document and a screenshot. Before writing a number, ask what it is derived from.

```
✗ rect card.2 x=148 y=308 w=395 h=200
✓ rect card.2 x=(@card.1.right + $gap) y=(prev.y) w=@card.1.w h=200
```

**2. Put every repeated value in a token first.** A colour used twice, a spacing used
three times, a type scale — all tokens. `$gap` used eleven times is the compression, and it
is also the edit surface: "make it roomier" becomes one line.

**3. Only reference ids you have already written.** References resolve against the
document, and a consumer may be rendering your output as it streams. Write `logo` before
the headline that sits beside it.

**4. Give ids a role, not a number.** `hero.title`, `card.1`, `nav.logo` — an id should be
guessable by someone who has not read the file. Never `node1`, `rect5`.

**5. Text height is authored — estimate it.** Nothing measures glyphs for you. For a box
o

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.