visualspec.1.0 RC
GitHub
Module

Appearance

How it looks

Appearance is the visual surface: color, paint, stroke, shadow, type, and filters. It describes what a person sees, not which CSS property or which renderer produced it.

Use this module when You are specifying fill, stroke, type, shadow, or a filter and you want every adapter to read the same intent.

Keep in mind. Prefer a token reference when the value belongs to a design system. A raw color is a decision; a token is a decision you can change in one place.

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

color

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

anyOf 1string

Write a text value.

The text must match the pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$. That pattern is the contract for which characters are allowed.

Exact constraints
type
string
pattern
^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
anyOf 2"transparent" | "currentColor" | "black" | "white"

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
  • "transparent"
  • "currentColor"
  • "black"
  • "white"
anyOf 3tokenRef

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

anyOf 4object

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 space and channels.

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

Exact constraints
type
object
additional properties
forbidden
spacerequired"srgb" | "srgb-linear" | "display-p3" | "rec2020" | "lab" | "lch" | "oklab" | "oklch" | "xyz-d50" | "xyz-d65"

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
  • "srgb"
  • "srgb-linear"
  • "display-p3"
  • "rec2020"
  • "lab"
  • "lch"
  • "oklab"
  • "oklch"
  • "xyz-d50"
  • "xyz-d65"
channelsrequiredarray<number>

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

The list needs at least 3 items.

The list allows at most 3 items.

Exact constraints
type
array
min items
3
max items
3
itemsnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
alphanumber

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

Smallest example

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

colorJSON
""

gradient

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

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

Exact constraints
type
object
additional properties
forbidden
typerequired"linear" | "radial" | "conic"

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
  • "linear"
  • "radial"
  • "conic"
anglenumber

Write a number. Decimals are allowed.

Exact constraints
type
number
centervector2

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

stopsrequiredarray<object>

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

The list needs at least 2 items.

Exact constraints
type
array
min items
2
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 offset and color.

Exact constraints
type
object
additional properties
forbidden
offsetrequirednumber

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
colorrequiredcolor

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

Smallest example

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

gradientJSON
{  "type": "linear",  "stops": [    {      "offset": 0,      "color": {        "$ref": "appearance#color"      }    },    {      "offset": 0,      "color": {        "$ref": "appearance#color"      }    }  ]}

paint

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

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

You may omit color, gradient, assetRef, scale, repeat, and opacity. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
typerequired"solid" | "gradient" | "image" | "pattern"

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
  • "solid"
  • "gradient"
  • "image"
  • "pattern"
colorcolor

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

gradientgradient

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

assetRefid

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

scalenumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
repeat"none" | "x" | "y" | "both"

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
  • "none"
  • "x"
  • "y"
  • "both"
opacitynumber

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

Smallest example

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

paintJSON
{  "$ref": "appearance#color"}

stroke

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 alignment, dash, cap, and join. 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.

alignment"inside" | "center" | "outside"

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
  • "inside"
  • "center"
  • "outside"
dasharray<number>

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

Exact constraints
type
array
itemsnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
cap"butt" | "round" | "square"

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
  • "butt"
  • "round"
  • "square"
join"miter" | "round" | "bevel"

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
  • "miter"
  • "round"
  • "bevel"

Smallest example

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

strokeJSON
{  "color": {    "$ref": "appearance#color"  },  "width": {    "$ref": "common#size"  }}

shadow

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, x, y, and blur.

You may omit spread and inset. 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.

xrequireddimension

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

yrequireddimension

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

blurrequiredsize

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

spreaddimension

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

insetboolean

Write true or false.

Exact constraints
type
boolean

Smallest example

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

shadowJSON
{  "color": {    "$ref": "appearance#color"  },  "x": {    "$ref": "common#dimension"  },  "y": {    "$ref": "common#dimension"  },  "blur": {    "$ref": "common#size"  }}

typography

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
fontFamilystring | array<string>

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

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
anyOf 2array<string>

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
itemsstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
fontAssetRefid

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

fontSizesize

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

fontWeightinteger | "normal" | "bold"

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 sit between 1 and 1000, including both ends.

Exact constraints
type
integer
minimum
1
maximum
1000
anyOf 2"normal" | "bold"

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
  • "normal"
  • "bold"
fontStyle"normal" | "italic" | "oblique"

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
  • "normal"
  • "italic"
  • "oblique"
lineHeightnumber | dimension

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

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
anyOf 2dimension

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

letterSpacingdimension

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

textAlign"start" | "end" | "left" | "right" | "center" | "justify"

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"
  • "left"
  • "right"
  • "center"
  • "justify"
textTransform"none" | "uppercase" | "lowercase" | "capitalize"

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
  • "none"
  • "uppercase"
  • "lowercase"
  • "capitalize"
textDecoration"none" | "underline" | "line-through" | "overline"

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
  • "none"
  • "underline"
  • "line-through"
  • "overline"
direction"ltr" | "rtl" | "auto"

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
  • "ltr"
  • "rtl"
  • "auto"
fontFeaturesobject
Exact constraints
type
object
additional properties
boolean
additionalPropertiesboolean

Write true or false.

Exact constraints
type
boolean
fontVariationsobject
Exact constraints
type
object
additional properties
number
additionalPropertiesnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
maxLinesinteger

Write a whole number.

The number must be at least 1.

Exact constraints
type
integer
minimum
1
overflow"clip" | "ellipsis" | "wrap"

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
  • "clip"
  • "ellipsis"
  • "wrap"

Smallest example

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

typographyJSON
{  "fontFamily": "example",  "fontAssetRef": {    "$ref": "common#id"  },  "fontSize": {    "$ref": "common#size"  },  "fontWeight": 1}

filter

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

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

Exact constraints
type
object
additional properties
forbidden
typerequired"blur" | "brightness" | "contrast" | "grayscale" | "hue-rotate" | "invert" | "saturate" | "sepia" | "custom"

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
  • "blur"
  • "brightness"
  • "contrast"
  • "grayscale"
  • "hue-rotate"
  • "invert"
  • "saturate"
  • "sepia"
  • "custom"
amountnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
assetRefid

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

filterJSON
{  "type": "blur"}

appearance

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

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

Exact constraints
type
object
additional properties
forbidden
fillpaint | array<paint>

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

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

anyOf 2array<paint>

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

Exact constraints
type
array
itemspaint

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

backgroundpaint

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

colorcolor

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

strokestroke | array<stroke>

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

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

anyOf 2array<stroke>

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

Exact constraints
type
array
itemsstroke

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

opacitynumber

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
blend"normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "color" | "luminosity"

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

Exact constraints
Allowed values
  • "normal"
  • "multiply"
  • "screen"
  • "overlay"
  • "darken"
  • "lighten"
  • "color-dodge"
  • "color-burn"
  • "hard-light"
  • "soft-light"
  • "difference"
  • "exclusion"
  • "hue"
  • "saturation"
  • "color"
  • "luminosity"
radiussize | 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 1size

This is not a new shape. It reuses size 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 topLeft, topRight, bottomRight, and bottomLeft. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
topLeftsize

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

topRightsize

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

bottomRightsize

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

bottomLeftsize

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

shadowsarray<shadow>

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

Exact constraints
type
array
itemsshadow

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

blursize

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

filtersarray<filter>

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

Exact constraints
type
array
itemsfilter

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

maskRefid

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

clipRefid

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.

textureRefid

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

typographytypography

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

visibleboolean

Write true or false.

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

appearanceJSON
{  "fill": {    "$ref": "appearance#paint"  },  "background": {    "$ref": "appearance#paint"  },  "color": {    "$ref": "appearance#color"  },  "stroke": {    "$ref": "appearance#stroke"  }}