A small, complete document
Save the following as hello.visualspec.json. The document declares the 1.0 format, identifies its purpose, selects the UI profile and places one text node in a scene.
{
"$schema": "https://visualspec.dev/schema/1.0/schema.json",
"visualSpec": "1.0",
"metadata": { "title": "Hello Visual Spec" },
"profiles": ["ui"],
"scenes": [{
"id": "scene.main",
"kind": "2d",
"nodes": [{
"id": "node.title",
"kind": "text",
"text": "Hello Visual Spec"
}]
}]
}
A profile expresses which kind of visual artifact this document describes. It does not select a framework. An ID identifies an object in the document; it is not a CSS selector or a file path.
Run the local tools
Clone the repository, install its dependencies, then validate your document:
npm install
npm run validate -- hello.visualspec.json
To run the documentation and interactive tools locally:
npm run dev
The CLI checks the document's structure and implemented semantic rules. A successful result does not prove that a renderer reproduced the intended appearance or accessibility behavior. Those require execution and evidence from the chosen target.
Make one change at a time
Open the playground, load the UI example and edit a text value. Then try an invalid value and inspect its location in the validation results. The live preview implements a documented 2D subset; unsupported profiles remain inspectable and validatable without implying a full renderer.
Explore examples for each profile. Use the generated reference for accepted property types, and the normative specification for the meaning of those properties.
Add evidence before detail
When you have a source design, identify the relevant region and the aspects it controls. Capture viewport, version or time range when those affect the result. This creates an auditable reference before you add layout, motion or component behavior.