visualspec.1.0 RC
GitHub
Module

Tokens

Named decisions

Tokens name reusable visual decisions: a brand color, a type ramp, a radius, a duration. Modes (light, dark, compact) can change the value without changing the name. Aliases point at other tokens. Cycles are invalid and are caught by semantic validation, not by the shape alone.

Use this module when The same decision should survive a theme change or be shared by many components.

Keep in mind. A token is data. It is not a CSS variable until an adapter maps it.

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

token

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 may omit type, value, description, modes, confidence, provenance, extensions, $type, and $value. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
type"color" | "dimension" | "spacing" | "radius" | "border" | "shadow" | "typography" | "font" | "gradient" | "opacity" | "duration" | "easing" | "motion" | "material" | "breakpoint" | "z-index" | "number" | "string"

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

Exact constraints
Allowed values
  • "color"
  • "dimension"
  • "spacing"
  • "radius"
  • "border"
  • "shadow"
  • "typography"
  • "font"
  • "gradient"
  • "opacity"
  • "duration"
  • "easing"
  • "motion"
  • "material"
  • "breakpoint"
  • "z-index"
  • "number"
  • "string"
valuestring | number | boolean | array<jsonValue> | object | typography | gradient | shadow | color | spring

More than one shape is accepted. Use exactly one of the 10 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 4array<jsonValue>

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

Exact constraints
type
array
itemsjsonValue

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

anyOf 5object

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 color and width.

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

Exact constraints
type
object
additional properties
forbidden
colorrequiredcolor

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

widthrequiredsize

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

style"solid" | "dashed" | "dotted"

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
  • "solid"
  • "dashed"
  • "dotted"
anyOf 6typography

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

anyOf 7gradient

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

anyOf 8shadow

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

anyOf 9color

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

anyOf 10spring

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

descriptionstring

Write a text value.

An empty string is not allowed.

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

confidencenumber

Write a number. Decimals are allowed.

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

Exact constraints
type
number
minimum
0
maximum
1
provenanceprovenance

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

$type"color" | "dimension" | "spacing" | "radius" | "border" | "shadow" | "typography" | "font" | "gradient" | "opacity" | "duration" | "easing" | "motion" | "material" | "breakpoint" | "z-index" | "number" | "string"

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

Exact constraints
Allowed values
  • "color"
  • "dimension"
  • "spacing"
  • "radius"
  • "border"
  • "shadow"
  • "typography"
  • "font"
  • "gradient"
  • "opacity"
  • "duration"
  • "easing"
  • "motion"
  • "material"
  • "breakpoint"
  • "z-index"
  • "number"
  • "string"
$valuestring | number | boolean | array<jsonValue> | object | typography | gradient | shadow | color | spring

More than one shape is accepted. Use exactly one of the 10 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 4array<jsonValue>

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

Exact constraints
type
array
itemsjsonValue

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

anyOf 5object

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 color and width.

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

Exact constraints
type
object
additional properties
forbidden
colorrequiredcolor

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

widthrequiredsize

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

style"solid" | "dashed" | "dotted"

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
  • "solid"
  • "dashed"
  • "dotted"
anyOf 6typography

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

anyOf 7gradient

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

anyOf 8shadow

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

anyOf 9color

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

anyOf 10spring

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

anyOf 1-

You must include value.

anyOf 2-

You must include $value.

Smallest example

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

tokenJSON
""

tokenRegistry

Exact constraints
type
object
additional properties
token
additionalPropertiestoken

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

Smallest example

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

tokenRegistryJSON
{}

visualLanguage

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

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

Exact constraints
type
object
additional properties
forbidden
personalityarray<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
principlesarray<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
paletteobject
Exact constraints
type
object
additional properties
color
additionalPropertiescolor

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

typographyobject
Exact constraints
type
object
additional properties
typography
additionalPropertiestypography

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

spacingobject
Exact constraints
type
object
additional properties
dimension
additionalPropertiesdimension

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

density"compact" | "comfortable" | "spacious"

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"
  • "comfortable"
  • "spacious"
geometryobject

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 radius, strokeWidth, and shape. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
radiussize

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

strokeWidthsize

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

shapetaxonomy

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

surfaceappearance

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

iconographyobject

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 style, strokeWidth, and assetRefs. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
stylestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
strokeWidthsize

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

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

photographyobject

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 style, referenceRefs, and composition. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
stylestring

Write a text value.

An empty string is not allowed.

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

compositionstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
illustrationobject

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 style, referenceRefs, and technique. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
stylestring

Write a text value.

An empty string is not allowed.

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

techniquestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
motionobject

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 duration, easing, and reducedMotion. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
durationduration

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

easingeasing

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

reducedMotion"remove" | "reduce" | "substitute"

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
  • "remove"
  • "reduce"
  • "substitute"
compositionobject

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 principles and preferredLayout. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
principlesarray<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
preferredLayouttaxonomy

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

externalTokensarray<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 uri and format.

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

Exact constraints
type
object
additional properties
forbidden
urirequireduri

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

formatrequired"dtcg" | "visualspec" | "custom"

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
  • "dtcg"
  • "visualspec"
  • "custom"
namespacestring

Write a text value.

An empty string is not allowed.

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

visualLanguageJSON
{  "personality": [],  "principles": [],  "palette": {},  "typography": {}}