Skip to content
Skills Library
Design & UX · Building & coding

vdesign

/vdesign

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.

Repository
skills ↗
Licence
CC-BY-4.0
Last repository change
09.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
12
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

CC-BY-4.0, otwarta.

What it does and when to use it

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.

Original author 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.

How it works

  1. No house style
  2. The output contract
  3. The grammar in one screen
  4. Rules that decide whether the output is any good
  5. Editing an existing document
  6. Motion and video
  7. Icons
  8. Images
  9. Looking at your work, and exporting
  10. Reference
Original SKILL.md headings · 308 lines, 2,558 words
SKILL.md preview
---
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 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.** `poster.title`, `step.1`, `legend.key`: 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
of width `w` at font size `size`:

```text
characters per line ≈ w / (size * 0.5)
lines               = ceil(length of the text / characters per line)
h                   = ceil(lines * size * 1.2)
```

Round up. Too small is reported as a `text-overflow` problem; too large just leaves space.

**6. `fill` takes a token name or a CSS colour, never an expression.** `fill=accent`,
`fill=#5b5bd6`. Sizes and positions bind; colours do not.

**7. A group has no geometry.** It holds children and nothing else — no `x`, `y`, `w`, `h`.
Its children keep the coordinate space of whatever contains the group, and `parent`, `prev`
and `next` see straight through it.

**8. A page is a `frame`, and more than one page is more than one frame.** Start the
document with a frame; you do not write a `canvas` line at all. Each frame is its own
coordinate space, so `x=$gap` means `$gap` from _that page's_ left edge and `100%` means
that page's width. `parent.cx` is that page's centre too, and `parent.left` is `0`, so the
same line centres something on every page. Lay several out left to right with a gap between
them: nothing stops one page being drawn over another.

**9. Centre a label by giving it the box it sits in, never an offset.** A diagram step's
name, a badge's number, a stamp's text: same `x y w h` as the shape behind it, then
`align=center valign=middle`. The renderer centres the line inside the box, so it stays
centred at any size or font. A guessed `y=(@step.1.top + 14)` is off by a few pixels and
drifts the moment the shape or the type changes.

```vd
ellipse step.1 x=$gap y=400 w=200 h=104 fill=accent
text step.1.label x=@step.1.x y=@step.1.y w=@step.1.w h=@step.1.h align=center valign=middle
  "Placed"
```

**10. Draw a repeated part once, as a component.** A footer, frame border or legend that
appears on several pages is a frame marked `component`, in a row below the pages, and each
page places an `instance` of it. What one page shows differently is an `override` line under
that instance, never a copy of the parts:

```vd
frame foot x=0 y=1000 w=1600 h=64 component
  text foot.title x=$gap y=0 w=400 h=64 valign=middle
    "Q3 review"

frame intro x=0 y=0 w=1600 h=900
  instance intro.foot component=foot x=0 y=(100% - 64)

frame plan x=1700 y=0 w=1600 h=900
  instance plan.foot component=foot x=0 y=(100% - 64)
    override foot.title
      "Plan"
```

`reference/nodes.md` has the rest: a part's page id is the instance's id and its own
(`plan.foot.foot.title`), and references inside a component are written unprefixed.

## Editing an existing document

When given a document and asked to change it, reply with **statements**, not a new
document. Five verbs, plus `title` to rename the document and `merge` to make one shape of
several:

```vd-patch
title "Jazz night poster"
set $gap = 40
set poster.title size=($display * 1.2) weight=800
set poster.when content="SATURDAY · 9PM"
unset poster.where opacity
insert rect step.4 after step.3 x=(@step.3.right + $gap) y=(prev.y) w=@step.1.w h=88
insert frame back x=(@poster.right + 100) w=@poster.w h=@poster.h background=paper
move logo before sun
delete poster.tagline
merge union badge.ring badge.dot as badge.mark
```

An `insert` with no placement lands on the canvas, which in a multi-page document is
_beside_ the pages rather than on one. Say `after <id>` or `in <frame>` whenever the new
node belongs to a page.

Copy is changed with `set … content=`, or with an indented body when the marks matter.
Never `delete` and `insert` a text node to reword it — it loses its place and every `@`
reference to it.

Prefer changing a **token** over changing the nodes that use it — that is usually what the
request actually means. "More breathing room" is `set $gap = 40`, not eleven `set`
statements.

See `reference/edits.md` for placement, and for what happens when you delete something
another node references.

Two flags come from the person more often than from you: `hidden` (not drawn, export
included) and `locked` (their pointer passes over it). Keep them as you find them. Hide with
`set step.2 hidden` only when asked to hide — when asked to remove something, `delete` it,
because a hidden node is still in the file for the next reader to wade through. `unset
step.2 hidden` shows it again.

A top-level frame is a slide when the document is played. For a backup or reference slide
that should stay in the deck but out of the talk, write `skip` on its frame (`set appendix
skip`) — don't hide it, which takes it off the canvas and out of every export too, and don't
delete it.

## Motion and video

How a page moves in time is a `motion` section after the last page: transitions between
slides, parts of a page appearing in order, links to another page and, for a
video, words entering one by one, numbers counting up, strokes drawing on and a camera moving
across the page. The canvas at rest and every still export show each page as written, so write
the page as it looks when finished and let motion say how it gets there.

```vd
motion intro enter=fade
  intro.title enter=rise by=word
  intro.chart enter=fade step
  intro.next enter=pop go=#plan
```

Add it when the person is making something to present, click through or post as a video, and
keep a deck light. Never copy a page to animate between the copies. A web page taller than a
screen gets `motion <page> scroll`. A video can have one music track, `music <name>` under its
header, and `bpm=` to time lines in beats — from the person or the file, never a guess.
`reference/motion.md` has the rest; read `reference/video.md` before making a video (an ad, a
promo, a social clip), and check one with `vd_frames`.

## Icons

Never write an icon's path from memory: it is slow, and it comes out roughly right at best.
Icons come from the Lucide set, about 1,900 line icons, by name.

- **Over MCP**, find one with `vd_search_icon` (`"settings"`, `"notification"`) and place it
  with `vd_add_icon`, which writes the `vector` for you — the icon's path, Lucide's stroke,
  round caps. Its `x`, `y` and `size` take expressions, so place an icon by relationship like
  anything else: `x="(@step.1.right - 32)"`.
- **In the app**, find one with `search_icons` and get its line with `use_icon`, before you
  write any DSL; copy that `vector` line into your reply as it comes back.
- **Where no icon tool is offered**, draw it as a `vector` (`reference/nodes.md`).
- **Lucide has no brand logos** — GitHub, X, YouTube. A logo is an image the person supplies:
  leave it as a slot (see Images).

A placed icon is an ordinary vector named `lucide:<name>`. Recolour it with
`set <id> stroke=…`; resize it with `w` and `h`, and scale `strokeWidth` with them — 2 at 24.

## Images

A picture is an `image` node that names an asset: `image poster.logo x=40 y=32 w=160 h=48
src=logo fit=contain`. The asset's registry line (`asset logo = image/png hash=…`) and its
bytes are **never yours to write** — hashes come from the app. You only ever write `src=`.

- **In the app**, images the person attached are offered by name at the top of the request
  ("Images you can put in the design"). Place one with `src=<that name>`; an edit uses
  `insert image <id> in <frame> …`. Size it to the image's aspect ratio, and prefer
  `fit=contain` for a logo.
- **Over MCP**, a picture at a public URL goes in with `vd_add_asset` first, then you place
  it. `vd_assets` lists what a document already has.
- **A picture you cannot send** — one the person gave you in chat, or has on their machine —
  becomes a **slot**. You cannot pass on an image you can see, and no tool reads file paths,
  so do not try: write the image anyway, with a `src` nothing supplies yet and a `name`
  saying what goes there:

  ```vd
  image poster.logo x=40 y=24 w=120 h=40 src=logo fit=contain name="Your logo"
  ```

  The canvas shows it as a labelled box the person drops the file into, whenever they like.
  Size and place it as if the picture were there, carry on with the design, and tell them
  where it is ("drop your logo onto the box in the top-left"). Every image with the same
  `src` fills together. `vd_assets` lists the slots still waiting.

A `src` naming nothing reports `missing-asset`. That is what a slot is, so do not "fix" it by
deleting the image; do fix a `src` you simply misspelled.

## Looking at your work, and exporting

**Over MCP (desktop and CLI), `vd_export` is how you see what you made.** `vd_read` is text, and a layout that
reads fine can still look wrong: text overflowing, two shapes overlapping. After a build or
a large edit, export the frame as `png` with `save: false` and look at the picture that comes
back; fix what you see, then look again.

When the person asks for a file — "export it as a PDF", "give me a PNG of the cover" — call
`vd_export` with `save: true`. Formats: `png`, `jpg`, `webp`, `svg`, `pdf`, `ai` (Illustrator:
one artboard of the whole canvas, or `artboards: "frames"` for a file per frame), `html` and
`pptx` (PowerPoint: a slide per frame, with shapes and text still editable). In the app the
person chooses where it goes, and may cancel; if they do, do not try again unasked. Only
save when asked — a look is `save: false`.

**With no vDesign tools at all** — this skill loaded on its own, by an agent that can write
files — the design is a file. Write the document to `<title>.vd`, holding exactly the lines
the output contract describes, and give the person that file. It opens in the vDesign app,
at getv.design/app, and in the VS Code extension, where they can see it, keep editing it and
export it to any format above. You cannot look at it first, which is one more reason to
place everything by relationship and leave text room to breathe. Do not draw it some other
way to show them: a picture from anything but vDesign is not what the design looks like.

## Reference

Each file is named by its path in this skill. Installed as a folder, read them from beside
this file, never through `vd_skill`; in the flattened system prompt they follow below.

- `reference/grammar.md` — the expression language in full: edges, percentages, relative
  references, precedence; plus tokens, paint (colours, gradients, layers), fonts and the asset
  registry.
- `reference/nodes.md` — every node type and every property it accepts: `frame`,
  `canvas`, `rect`, `ellipse`, `vector`, `image`, `video`, `text`, `instance`, `connector`,
  `group`.
- `reference/edits.md` — the mutation dialect in full.
- `reference/motion.md` — motion: page transitions, reveals, buttons, timing, the camera, beats
  and music.
- `reference/video.md` — videos for social media and websites: sizes, storyboards, recipes,
  cutting to the beat.
- `reference/brand.md` — brands: a `kind brand` document's roles, logos, rules and guides, how
  a patch changes one, how one is made, and how a design uses one.
- `examples/`: complete documents. `diagram.vd`, `slide.vd`, `hero.vd` (a web page),
  `deck.vd` (three pages with motion), and `promo.vd`, a 9-second video storyboard.
Files in this package (12)
  • SKILL.md 15 KB
  • examples/deck.vd 2 KB
  • examples/diagram.vd 1 KB
  • examples/hero.vd 1 KB
  • examples/promo.vd 2 KB
  • examples/slide.vd 1 KB
  • reference/brand.md 7 KB
  • reference/edits.md 11 KB
  • reference/grammar.md 8 KB
  • reference/motion.md 11 KB
  • reference/nodes.md 21 KB
  • reference/video.md 5 KB

Versions

The database has no other skills named vdesign.

Database snapshot: 13.11.2026 · package version 7ace867f14ce (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90starrykit
    Create, inspect, refine, and export polished editable presentations, posters, social graphics, diagrams, and other visual documents with StarryKit. Use when the user explicitly chooses StarryKit, wants to work on an existing StarryKit document, or requests an editable…
  • 100signal-geometry
    Create Signal Geometry abstract illustrations and posters from concepts or briefs. Use when the user asks for sparse geometric visuals, editorial posters, spatial systems, or prompt-only image recipes.
  • 100show
    Create and review inline visual explanations, diagrams, interactive widgets, mockups, charts, and illustrations. Triggers on "/show", "show me", "draw", "diagram this", "visualize", "map this out", "make it interactive", or a request for a mockup, chart, or illustration.
  • 90ui-ux-pro
    World-class design intelligence for building, reviewing, or improving any design artifact — interfaces AND visual/marketing collateral. Use whenever the task involves designing, building, styling, or critiquing something visual: web pages, apps, dashboards, components, design…
  • 100gamma
    Create presentations, documents, social posts, and websites using Gamma's AI API. Use when asked to create slides, presentations, decks, documents, or web content via Gamma.
  • 95Art
    Complete visual content system. USE WHEN user wants to create visual content, illustrations, diagrams, OR mentions art, header images, visualizations, mermaid, flowchart, technical diagram, infographic, PAI icon, pack icon, or PAI pack icon.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.