vdesign15.3 KB
View saved version →
---
name: vdesign
description: Author and edit vDesign documents (posters, diagrams, slides, illustrations, social posts, web pages, any 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.
license: CC-BY-4.0 (https://creativecommons.org/licenses/by/4.0/). Credit vDesign.
---
# 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.
## No house style
vDesign draws anything. Design for the medium asked for: a poster is not a web page, so no
cards, nav bars, buttons or rounded panels unless the person asks.
## 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
```vd
version 4
kind design
title "Jazz night poster"
$m = 72
$paper = #f2e8d5
$accent = #d2462f
$ink = #1d1a16
font display = Georgia
fallback "serif"
frame poster w=1080 h=1350 background=paper
ellipse sun x=(parent.cx - self.w / 2) y=150 w=560 h=560 fill=accent
text poster.title x=$m y=(@sun.bottom + 56) w=(100% - $m * 2) h=210 font=display size=168 fill=ink
"Blue "
"Room" italic fill=accent
group stars
ellipse star.1 x=$m y=$m w=24 h=24 fill=ink
```
- **The first lines are the header.** `version 4` and `kind design`. Write both. `design`
is the free-form canvas; a document that does not say which it is leaves every reader to
guess from its contents. The one other kind is a brand, `version 5` and `kind brand`, which
`reference/brand.md` covers — make one only when asked for a brand.
- **A design in a brand** has a `brand ember@3` line under its title. Read the brand's brief
first (`vd_read_brand`), name its roles in paint (`fill=primary`, `background=background`)
and never write a colour out, and never write the brand line yourself: `vd_apply_brand` does.
- **Then `title "…"`** — a short human name for what you are making, two to five words
("Jazz night poster", 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.
```text
✗ rect step.2 x=416 y=180 w=220 h=88
✓ rect step.2 x=(@step.1.right + $gap) y=(prev.y) w=@step.1.w h=88
```
**2. Put every repeated value in a token first.** A colour used twice, a spacing used
three times, a type Preview of the first 4,000 characters. Read full instructions →
Referenced files: 11 — file references are metadata, not package contents.
