Write Your First Spec
A spec page is where requirements live. It is a rich-text document with structure, context, and embedded requirement cards — not a ticket, not a slideshow, not an email thread.
Creating a page
Section titled “Creating a page”In the left sidebar of your project, click the + button next to “Specs”. Name the page after the feature or area it covers (for example: “Order Management”, “User Onboarding Flow”, “Search & Filtering”).
What goes in a spec
Section titled “What goes in a spec”A good spec page typically contains:
- Context — why this feature is needed, what business problem it solves
- Scope — what is in and out of scope for this piece of work
- Functional description — how the feature should behave from a user’s perspective
- Requirement cards — individual, trackable items embedded in the text
- Open questions — decisions still to be made, flagged for discussion
You don’t need a rigid template. Write the way that makes the most sense for the feature — prose, bullet points, tables, or a combination.
Formatting
Section titled “Formatting”The editor supports:
| Element | How to insert |
|---|---|
| Headings (H1–H3) | Type #, ##, or ### at the start of a line |
| Bullet list | Type - or * at the start of a line |
| Numbered list | Type 1. at the start of a line |
| Table | Type / and select Table |
| Code block | Type ``` |
| Divider | Type --- |
| Requirement card | Type / and select the card type |
Embedding a requirement card
Section titled “Embedding a requirement card”Requirement cards are the structured elements within a spec. To add one:
- Place your cursor where the card should appear
- Type
/to open the block menu - Select the card type (Requirement, Basic, or Simple)
Write the requirement as a clear, testable statement inside the card. A well-written requirement answers: “What should the system do, and for whom?”
Saving and sharing
Section titled “Saving and sharing”Vanillaround auto-saves everything as you type. There is no save button. To share a page with someone who is already a project member, use @mention to notify them — they’ll receive a link directly to the page.
Organising with sub-pages
Section titled “Organising with sub-pages”If a feature is complex, break it into sub-pages. Hover over a page in the sidebar and click the + icon that appears next to it to create a child page. Use this to create a hierarchy: a top-level page for a major feature area, with sub-pages for each component or flow.
See Page Hierarchy for more detail.