visualspec.1.0 RC
GitHub
Module

Components

Reusable interface patterns

A component is a pattern with a meaning: a button, a dialog, a tab list. The definition describes anatomy (the named parts), variants, and behavior. An instance places that pattern in a scene. The kind is not a React component and not a Swift view.

Use this module when The same interface pattern appears more than once, or its behavior and parts need to stay stable across platforms.

Keep in mind. Platform mappings in the catalog are design guidance. This release does not ship those adapters.

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

mapping

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 component, package, version, variant, primitive, pattern, and props. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
componentstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
packagestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
versionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
variantstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
primitivestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
patternstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
propsobject
Exact constraints
type
object
additional properties
jsonValue
additionalPropertiesjsonValue

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

mappingJSON
{  "component": "example",  "package": "example",  "version": "example",  "variant": "example"}

behavior

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 overlay, modal, modality, placement, dismiss, focus, anchor, selection, orientation, activation, scrollLock, and loop. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
overlayboolean

Write true or false.

Exact constraints
type
boolean
modalboolean

Write true or false.

Exact constraints
type
boolean
modality"modal" | "non-modal"

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
  • "modal"
  • "non-modal"
placementstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
dismissarray<"escape" | "backdrop" | "swipe" | "outside-press" | "close-button"> | object

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 1array<"escape" | "backdrop" | "swipe" | "outside-press" | "close-button">

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"escape" | "backdrop" | "swipe" | "outside-press" | "close-button"

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
  • "escape"
  • "backdrop"
  • "swipe"
  • "outside-press"
  • "close-button"
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 outsidePress, escape, backdrop, and swipe. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
outsidePressboolean

Write true or false.

Exact constraints
type
boolean
escapeboolean

Write true or false.

Exact constraints
type
boolean
backdropboolean

Write true or false.

Exact constraints
type
boolean
swipeboolean

Write true or false.

Exact constraints
type
boolean
focusfocus

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

anchorobject

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 targetRef, target, placement, collision, and offset. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
targetRefid

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

targetstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
placement"top" | "bottom" | "left" | "right" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end" | "right-start" | "right-end"

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

Exact constraints
Allowed values
  • "top"
  • "bottom"
  • "left"
  • "right"
  • "top-start"
  • "top-end"
  • "bottom-start"
  • "bottom-end"
  • "left-start"
  • "left-end"
  • "right-start"
  • "right-end"
collision"flip" | "shift" | "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
  • "flip"
  • "shift"
  • "none"
offsetdimension

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

selection"none" | "single" | "multiple"

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"
  • "single"
  • "multiple"
orientation"horizontal" | "vertical"

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
  • "horizontal"
  • "vertical"
activation"automatic" | "manual"

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
  • "automatic"
  • "manual"
scrollLockboolean

Write true or false.

Exact constraints
type
boolean
loopboolean

Write true or false.

Exact constraints
type
boolean

Smallest example

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

behaviorJSON
{  "overlay": true,  "modal": true,  "modality": "modal",  "placement": "example"}

slot

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 description, semanticRole, required, multiple, allowedKinds, componentRef, states, and accessibility. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
descriptionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
semanticRoletaxonomy

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

requiredboolean

Write true or false.

Exact constraints
type
boolean
multipleboolean

Write true or false.

Exact constraints
type
boolean
allowedKindsarray<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.

componentRefid

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

statesarray<string>

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
itemsstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
accessibilityaccessibility

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

Smallest example

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

slotJSON
{  "description": "example",  "semanticRole": {    "$ref": "common#taxonomy"  },  "required": true,  "multiple": true}

composition

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 slot.

You may omit componentRef, nodeRef, and properties. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
slotrequiredstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
componentRefid

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

nodeRefid

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

propertiesobject
Exact constraints
type
object
additional properties
jsonValue
additionalPropertiesjsonValue

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

compositionJSON
{  "slot": "example"}

component

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

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.

You must include id.

24 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.

kindtaxonomy

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

componentRefid

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
descriptionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
familystring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
variantstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
variantsobject
Exact constraints
type
object
additional properties
object
additionalPropertiesobject

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 description, appearance, layout, and properties. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
descriptionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
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.

propertiesobject
Exact constraints
type
object
additional properties
jsonValue
additionalPropertiesjsonValue

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

anatomyobject

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 slots.

Exact constraints
type
object
additional properties
forbidden
slotsrequiredobject
Exact constraints
type
object
additional properties
slot
additionalPropertiesslot

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

propertiesobject
Exact constraints
type
object
additional properties
jsonValue
additionalPropertiesjsonValue

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

childrenarray<composition>

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

Exact constraints
type
array
itemscomposition

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

statesarray<string>

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
itemsstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
behaviorbehavior

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

accessibilityaccessibility

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

responsiveresponsive

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

motionobject
Exact constraints
type
object
additional properties
id
additionalPropertiesid

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

eventRefsarray<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.

stateRefsarray<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.

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.

referencesarray<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.

implementationMappingmapping

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

platformMappingsobject
Exact constraints
type
object
additional properties
mapping
additionalPropertiesmapping

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

anyOf 1-

You must include kind.

anyOf 2-

You must include componentRef.

Smallest example

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

componentJSON
""