yoshida yoshida
Open the editor

Docs Format

Expressions

On this page

Almost every value in a design can be an expression: a small formula that reads params, other layers and the canvas. Expressions have no assignments, no loops and no side effects, and are checked for types when the design loads, before anything is drawn.

"box": { "x": "50% + (i - (level - 1) / 2) * 56", "y": "@title.bounds.bottom + 50", "w": 48, "h": "auto" }
"fill": "foil ? #F5C542 : accent"
"text": "{upper(title)} · {fmt(cost, 1)} pts"

Value kinds

Every field has one of these kinds. The kind decides how a JSON value in that field is read.

KindJSON numberJSON boolJSON string means
numberliteralerrorexpression yielding a number
boolerrorliteralexpression yielding a bool
colorerrorerrorexpression yielding a color (a hex literal is a valid expression)
texterrorerrortemplate
patherrorerrortemplate; the result must be a project path or https:// URL
enum(...)errorerrorone of the listed words, literal only
identerrorerroran identifier [a-z_][a-z0-9_]*, literal only

A wrong JSON type is error 1103. A number field accepts a plain JSON number (120) as well as a string expression ("120 + 10").

Types

Expressions have the types number, bool, text, color, image, list and list item. There is no implicit conversion: '5' + 1 is a type error (3003).

The pages

PageCovers
Literals and unitsnumbers, strings, booleans, colors, %, vw, vh
Names and referencesparams, loop names, canvas, card, render, @layer references
Operatorsprecedence, arithmetic, comparison, logic, in, ? :
Functionsmin, clamp, round, fmt, mix, avg_color, match, ...
Templates{expression} holes in text and path fields
List lookup by keystats.Speed, stats["Speed"]
Constants and functionsconsts and functions of a design: named values and formulas

Determinism

The same project, card data and render clock (render.now with utc_offset, or render.date) always produce the same pixels in every build (WebAssembly, CLI, server). Expressions have no clock of their own, no network and no file access. Seeded random functions give the same values for the same seeds.

Errors

  • Syntax errors are 3001, unknown names or functions 3002 (with a "did you mean" hint), type mismatches and wrong function arguments 3003, reference cycles 3004, references to repeated layers without an iteration index 3005, units in the wrong place 3006.
  • Math errors (3103), invalid date text (3105), a list or iteration index out of range (3102), a list key that does not exist (3104) and a negative width or height (3101) can only be found while evaluating a specific card, so they are reported with the card's id, by yoshida check (which evaluates every card) and when rendering.

See Diagnostics. In the editor, expression fields are small code editors with highlighting, completion and a reference: Builder: Expression editor.

In this section

↑↓ to moveEnter to openEsc to close