visualspec.1.0 RC
GitHub
Module

Interaction

What happened, and what should change visually

Interaction records observable events (a press, a hover, a marker), the visual action they request, and the states a thing can be in. It does not contain business logic, network calls, or application code.

Use this module when A visual response depends on an event or on being in a named state.

Keep in mind. “Submit the order” is application behavior. “Show the pressed appearance” is a visual action. Only the second belongs here.

Raw schema:/schema/1.0/modules/interaction.schema.json · https://visualspec.dev/schema/1.0/modules/interaction.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.

event

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 id and type.

You may omit targetRef, key, modifiers, pointer, gesture, markerRef, externalName, actionRefs, once, debounce, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

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

typerequiredtaxonomy

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

targetRefid

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

keystring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
modifiersarray<"alt" | "ctrl" | "meta" | "shift">

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
items"alt" | "ctrl" | "meta" | "shift"

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

Exact constraints
Allowed values
  • "alt"
  • "ctrl"
  • "meta"
  • "shift"
pointer"mouse" | "touch" | "pen" | "any"

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

Exact constraints
Allowed values
  • "mouse"
  • "touch"
  • "pen"
  • "any"
gestureobject

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 type, axis, threshold, and direction. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
type"drag" | "swipe" | "pinch" | "rotate" | "long-press" | "tap"

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
  • "drag"
  • "swipe"
  • "pinch"
  • "rotate"
  • "long-press"
  • "tap"
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"
thresholdnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
direction"up" | "down" | "left" | "right" | "any"

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
  • "up"
  • "down"
  • "left"
  • "right"
  • "any"
markerRefid

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

externalNamestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
actionRefsarray<id>

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
itemsid

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

onceboolean

Write true or false.

Exact constraints
type
boolean
debounceduration

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

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.

eventJSON
{  "id": {    "$ref": "common#id"  },  "type": {    "$ref": "common#taxonomy"  }}

action

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 id and verb.

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

Exact constraints
type
object
additional properties
forbidden
idrequiredid

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

verbrequiredtaxonomy

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

targetRefid

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

targetRefsarray<id>

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
itemsid

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

intentstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
eventRefid

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

stateRefid

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

motionRefid

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

parametersobject

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 value, position, angle, scale, time, destination, materialRef, duration, property, and visible. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
valuestring | number | boolean | vector2 | vector3

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

anyOf 1string

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
anyOf 2number

Write a number. Decimals are allowed.

Exact constraints
type
number
anyOf 3boolean

Write true or false.

Exact constraints
type
boolean
anyOf 4vector2

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

anyOf 5vector3

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

positionvector2 | vector3

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 1vector2

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

anyOf 2vector3

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

anglenumber

Write a number. Decimals are allowed.

Exact constraints
type
number
scalenumber

Write a number. Decimals are allowed.

Exact constraints
type
number
timetime

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

destinationid

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

materialRefid

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

durationduration

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

propertystring

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
composition"sequence" | "parallel" | "conditional" | "stagger"

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

Exact constraints
Allowed values
  • "sequence"
  • "parallel"
  • "conditional"
  • "stagger"
actionRefsarray<id>

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
itemsid

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

conditioncondition

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

delayduration

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

staggerduration

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

onCompletearray<id>

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
itemsid

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

onCancelarray<id>

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
itemsid

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

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.

actionJSON
{  "id": {    "$ref": "common#id"  },  "verb": {    "$ref": "common#taxonomy"  }}

state

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 id and name.

You may omit targetRef, initial, appearance, layout, visible, variant, motionRef, accessibility, onEnter, onExit, transitions, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

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

namerequiredstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
targetRefid

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

initialboolean

Write true or false.

Exact constraints
type
boolean
appearanceappearance

This is not a new shape. It reuses appearance from the appearance 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.

visibleboolean

Write true or false.

Exact constraints
type
boolean
variantstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
motionRefid

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

accessibilityaccessibility

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

onEnterarray<id>

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
itemsid

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

onExitarray<id>

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
itemsid

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

transitionsarray<object>

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

Exact constraints
type
array
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 to.

You may omit eventRef, actionRef, motionRef, and condition. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
torequiredid

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

eventRefid

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

actionRefid

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

motionRefid

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

conditioncondition

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

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.

stateJSON
{  "id": {    "$ref": "common#id"  },  "name": "example"}

flow

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 id, initial, and states.

You may omit name, sceneRef, transitions, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

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

namestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
initialrequiredid

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

sceneRefid

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

statesrequiredarray<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 id and name.

You may omit sceneRef. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

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

namerequiredstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
sceneRefid

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

transitionsarray<object>

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

Exact constraints
type
array
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 from and to.

You may omit eventRef, motionRef, and condition. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
fromrequiredid

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

torequiredid

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

eventRefid

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

motionRefid

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

conditioncondition

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

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.

flowJSON
{  "id": {    "$ref": "common#id"  },  "initial": {    "$ref": "common#id"  },  "states": [    {      "id": {        "$ref": "common#id"      },      "name": "example"    }  ]}