Variables

Variables are named values, such as colors and sizes, that layers reference instead of repeating them. A variable can hold one value per theme.

What variables are

Variables belong to the document, not to a page. Each one has a type and a value. The type is one of color, number, string or boolean.

"variables": {
  "accent": {"type": "color", "value": "#3B82F6"},
  "space-md": {"type": "number", "value": 16}
}

Referencing a variable

A layer uses a variable by giving a property the variable's name with a $ in front. Change the variable and every layer that references it changes too. Here card is a frame saved by an earlier call.

Insert(card, {type: "frame", name: "Badge", padding: [4, 10], gap: "$space-md", fill: "$accent"})

The name itself never starts with $; only the reference does. Text styles can reference variables the same way, for example fontSize: "$h1-size".

The Variables panel

Open the Variables tab in the left sidebar. It lists the document's color variables and how many layers use each one.

• New variable adds a color variable.
• Edit a name to rename it. Layers that use it follow the new name. Names use letters, digits, dots, dashes and underscores.
• Edit the color to change it everywhere.
• The minus button removes a variable. Its layers keep the color as a plain value.

To use a variable on a layer, click the swatch-book button next to any color field in the Inspector and pick it. The same menu has Detach variable, which keeps the color as a plain value.

The panel edits plain color variables. Number, string and boolean variables, and the values of themed variables, are set by agents for now. A themed variable that layers still use cannot be removed from the panel.

Themes

A themed variable holds a list of values, each with the theme it belongs to. A theme is an axis and a value, such as {mode: "dark"}. When an agent sets themed values, Potlot records the axis and its values in the document's themes.

SetVariables({
  bg: {type: "color", value: [
    {value: "#FAFAF7", theme: {mode: "light"}},
    {value: "#141414", theme: {mode: "dark"}}
  ]}
})

The canvas draws the first value in the list. An agent picks another theme when it reads or exports: Get(id, {resolveVariables: true, theme: {mode: "dark"}}), or the theme option of Export.

For agents

• GetVariables() returns the variables and the themes.
• SetVariables(variables, replace?) merges definitions, or replaces them all when replace is true. Each definition must be {type, value}; a bare value fails.
• DeleteVariables(names) removes variables and returns how many went. Layers that still name one keep the reference, so rewrite them first.

Something unclear, missing or broken? Write to feedback@anaknegeri.dev.