visualspec.1.0 RC
GitHub
Module

Layout

Where things sit

Layout places content without choosing a framework. It covers insets, constraints, flow, and rules that change when the viewport changes. The same document can describe a column on a phone and a row on a desk.

Use this module when Position, spacing, alignment, or a responsive change is part of the contract, not an accident of one implementation.

Keep in mind. Layout does not encode product logic. “Show the pay button when the form is valid” belongs to interaction and state, not to a media query.

Raw schema:/schema/1.0/modules/layout.schema.json · https://visualspec.dev/schema/1.0/modules/layout.schema.json

How to read a definition.The paragraphs say what to write and why. “Exact constraints” opens the schema keywords (type, pattern, bounds) for people checking a validator. A sample at the bottom of each definition is the smallest JSON that shows the required shape. Values such as $ref inside a sample point at another definition. They are not fields you copy into a document.

insets

More than one shape is accepted. Use exactly one of the 2 alternatives below. They are different ways to say the same kind of value.

anyOf 1dimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

anyOf 2object

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You may omit top, right, bottom, left, start, and end. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
topdimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

rightdimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

bottomdimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

leftdimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

startdimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

enddimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

insetsJSON
{  "$ref": "common#dimension"}

constraint

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include attribute and relation.

You may omit targetRef, targetAttribute, constant, multiplier, and priority. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
attributerequired"left" | "right" | "top" | "bottom" | "width" | "height" | "center-x" | "center-y" | "baseline" | "aspect-ratio"

Pick one of the 10 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "left"
  • "right"
  • "top"
  • "bottom"
  • "width"
  • "height"
  • "center-x"
  • "center-y"
  • "baseline"
  • "aspect-ratio"
relationrequired"equal" | "less-than-or-equal" | "greater-than-or-equal"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "equal"
  • "less-than-or-equal"
  • "greater-than-or-equal"
targetRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

targetAttribute"left" | "right" | "top" | "bottom" | "width" | "height" | "center-x" | "center-y" | "baseline"

Pick one of the 9 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "left"
  • "right"
  • "top"
  • "bottom"
  • "width"
  • "height"
  • "center-x"
  • "center-y"
  • "baseline"
constantdimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

multipliernumber

Write a number. Decimals are allowed.

Exact constraints
type
number
priorityinteger

Write a whole number.

The number must sit between 0 and 1000, including both ends.

Exact constraints
type
integer
minimum
0
maximum
1000

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

constraintJSON
{  "attribute": "left",  "relation": "equal"}

layout

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

36 other fields are optional. Include one only when you have a real value for it.

Exact constraints
type
object
additional properties
forbidden
type"stack" | "row" | "column" | "grid" | "overlay" | "flow" | "absolute" | "constraint-based"

Pick one of the 8 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "stack"
  • "row"
  • "column"
  • "grid"
  • "overlay"
  • "flow"
  • "absolute"
  • "constraint-based"
widthsize

This is not a new shape. It reuses size from the common module. Open that definition for the fields you can write.

heightsize

This is not a new shape. It reuses size from the common module. Open that definition for the fields you can write.

minWidthsize

This is not a new shape. It reuses size from the common module. Open that definition for the fields you can write.

maxWidthsize

This is not a new shape. It reuses size from the common module. Open that definition for the fields you can write.

minHeightsize

This is not a new shape. It reuses size from the common module. Open that definition for the fields you can write.

maxHeightsize

This is not a new shape. It reuses size from the common module. Open that definition for the fields you can write.

gapdimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

rowGapdimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

columnGapdimension

This is not a new shape. It reuses dimension from the common module. Open that definition for the fields you can write.

paddinginsets

This is not a new shape. It reuses insets from the layout module. Open that definition for the fields you can write.

margininsets

This is not a new shape. It reuses insets from the layout module. Open that definition for the fields you can write.

align"start" | "end" | "center" | "stretch" | "baseline"

Pick one of the 5 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "start"
  • "end"
  • "center"
  • "stretch"
  • "baseline"
justify"start" | "end" | "center" | "space-between" | "space-around" | "space-evenly"

Pick one of the 6 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "start"
  • "end"
  • "center"
  • "space-between"
  • "space-around"
  • "space-evenly"
alignSelf"auto" | "start" | "end" | "center" | "stretch" | "baseline"

Pick one of the 6 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "auto"
  • "start"
  • "end"
  • "center"
  • "stretch"
  • "baseline"
wrap"none" | "wrap" | "reverse"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "none"
  • "wrap"
  • "reverse"
columnsinteger | array<size>

More than one shape is accepted. Use exactly one of the 2 alternatives below. They are different ways to say the same kind of value.

anyOf 1integer

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
anyOf 2array<size>

Write a list. Each item follows the shape described under items.

The list needs at least 1 item.

Exact constraints
type
array
min items
1
itemssize

This is not a new shape. It reuses size from the common module. Open that definition for the fields you can write.

rowsinteger | array<size>

More than one shape is accepted. Use exactly one of the 2 alternatives below. They are different ways to say the same kind of value.

anyOf 1integer

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
anyOf 2array<size>

Write a list. Each item follows the shape described under items.

The list needs at least 1 item.

Exact constraints
type
array
min items
1
itemssize

This is not a new shape. It reuses size from the common module. Open that definition for the fields you can write.

columninteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
rowinteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
columnSpaninteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
rowSpaninteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
grownumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
shrinknumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
basissize

This is not a new shape. It reuses size from the common module. Open that definition for the fields you can write.

aspectRationumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
position"flow" | "relative" | "absolute" | "fixed" | "sticky"

Pick one of the 5 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "flow"
  • "relative"
  • "absolute"
  • "fixed"
  • "sticky"
insetinsets

This is not a new shape. It reuses insets from the layout module. Open that definition for the fields you can write.

zIndexinteger

Write a whole number.

Exact constraints
type
integer
clipboolean

Write true or false.

Exact constraints
type
boolean
overflow"visible" | "hidden" | "clip" | "scroll" | "auto"

Pick one of the 5 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "visible"
  • "hidden"
  • "clip"
  • "scroll"
  • "auto"
scrollobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You may omit axis, snap, snapAlign, and overscroll. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
axis"x" | "y" | "both"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "x"
  • "y"
  • "both"
snap"none" | "mandatory" | "proximity"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "none"
  • "mandatory"
  • "proximity"
snapAlign"start" | "center" | "end"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "start"
  • "center"
  • "end"
overscroll"auto" | "contain" | "none"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "auto"
  • "contain"
  • "none"
constraintsarray<constraint>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsconstraint

This is not a new shape. It reuses constraint from the layout module. Open that definition for the fields you can write.

safeAreaboolean

Write true or false.

Exact constraints
type
boolean
direction"ltr" | "rtl"

Pick one of the 2 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "ltr"
  • "rtl"
extensionsextensions

This is not a new shape. It reuses extensions from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

layoutJSON
{  "type": "stack",  "width": {    "$ref": "common#size"  },  "height": {    "$ref": "common#size"  },  "minWidth": {    "$ref": "common#size"  }}

query

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

14 other fields are optional. Include one only when you have a real value for it.

Exact constraints
type
object
additional properties
forbidden
minWidthnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
maxWidthnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
minHeightnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
maxHeightnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
orientation"portrait" | "landscape"

Pick one of the 2 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "portrait"
  • "landscape"
minAspectRationumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
maxAspectRationumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
pixelDensitynumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
inputModality"pointer" | "touch" | "keyboard" | "voice" | "gamepad" | "spatial"

Pick one of the 6 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "pointer"
  • "touch"
  • "keyboard"
  • "voice"
  • "gamepad"
  • "spatial"
windowClass"compact" | "medium" | "expanded"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "compact"
  • "medium"
  • "expanded"
platformtaxonomy

This is not a new shape. It reuses taxonomy from the common module. Open that definition for the fields you can write.

capabilitiesarray<taxonomy>

Write a list. Each item follows the shape described under items.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemstaxonomy

This is not a new shape. It reuses taxonomy from the common module. Open that definition for the fields you can write.

containerRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

safeAreaboolean

Write true or false.

Exact constraints
type
boolean

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

queryJSON
{  "minWidth": 0,  "maxWidth": 0,  "minHeight": 0,  "maxHeight": 0}

responsive

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include strategy and rules.

Exact constraints
type
object
additional properties
forbidden
strategyrequired"responsive" | "adaptive"

Pick one of the 2 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "responsive"
  • "adaptive"
rulesrequiredarray<object>

Write a list. Each item follows the shape described under items.

The list needs at least 1 item.

Exact constraints
type
array
min items
1
itemsobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include when.

You may omit layout, appearance, variant, visible, componentRef, and priority. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
whenrequiredquery

This is not a new shape. It reuses query from the layout module. Open that definition for the fields you can write.

layoutlayout

This is not a new shape. It reuses layout from the layout module. Open that definition for the fields you can write.

appearanceappearance

This is not a new shape. It reuses appearance from the appearance module. Open that definition for the fields you can write.

variantstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
visibleboolean

Write true or false.

Exact constraints
type
boolean
componentRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

priorityinteger

Write a whole number.

The number must sit between 0 and 1000, including both ends.

Exact constraints
type
integer
minimum
0
maximum
1000

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

responsiveJSON
{  "strategy": "responsive",  "rules": [    {      "when": {        "$ref": "layout#query"      }    }  ]}