yoshida yoshida DEV
Open the editor

Docs Format Expressions

Expressions: Names and References

On this page
NameTypeMeaning
a param namethe param's typeThe card's value, or the default
loop namesnumber / itemFrom repeat: the index, and the current item with each; also those of the repeated groups around the layer
a constantthe constant's typeFrom consts
canvas.w, canvas.hnumberCanvas size in pixels
pinumberThe circle constant, 3.14159…. A param or constant named pi takes its place
card.idtextThe card's id
render.indexnumber0-based position of the card in its set
render.datetextISO date YYYY-MM-DD in the project's time zone (utc_offset), chosen once by whoever starts the render (--date or --now on the CLI)
render.timetextTime HH:MM:SS in the same time zone
render.nowtextThe instant the render starts, in UTC, as YYYY-MM-DDTHH:MM:SSZ (--now on the CLI); not changed by utc_offset
@<layer_id>.<field>the field's typeAnother layer's evaluated field
@<layer_id>.bounds.<f>numberThe layer's final pixel bounds
@<layer_id>[n].<field>the field's typeIteration n of a repeated layer (or of the repeated group around it)
list[n], item.fieldIndexing (0-based) and field access
list.Key, list["Key"]Lookup by key

Reserved words that cannot be used as param, constant, function or loop names: canvas, render, card, true, false, and, or, not, in (error 1106). Built-in function names are not reserved: a param or constant may use one, because a bare name is a value and not a call. A design function with a built-in's name hides the built-in in that design, with warning 1113. See Functions.

Layer references

Layer references always start with @, so params and layer ids live in separate namespaces: a param background and a layer background can coexist.

"y": "@art.bounds.bottom + 90"
"w": "@art.bounds.w"
"fill": "@panel.stroke.color"

References between layers may point forward or backward. The core orders evaluation by dependency; a cycle is error 3004. Drawing order is always the array order, independent of references.

An unknown layer or field is error 3002 with a "did you mean" hint. A layer that uses repeat has no single position: read one iteration with @layer[n].field (without an index it is error 3005), see Repeat. Inside a repeated group, references between its layers mean the same iteration. A divider cannot be referenced at all (3002). Other layers inside groups can be referenced from anywhere.

Positions read from another layer (bounds.*, box.x, box.y, at.x, at.y) are given in the coordinate frame of the reading layer: inside a translated group they are relative to its origin.

Bounds

@layer.bounds.<f> is the final pixel bounds after anchor, size and layout, always of the unrotated layer:

FieldMeaning
left, top, right, bottomEdges
w, hWidth and height
cx, cyCentre

This is what makes layouts compose: put a text under an image with "y": "@art.bounds.bottom + 20", centre a badge number on its circle with @badge.bounds.cx / @badge.bounds.cy, size a frame to its content with @art.bounds.w. For text, the bounds include the effect of wrapping and auto-shrink. For a group, the bounds are the union of its visible layers.

Readable fields

These fields of a layer can be read (when the layer has them):

Field pathType
bounds.left, .top, .right, .bottom, .w, .h, .cx, .cynumber
box.x, box.y, box.w, box.hnumber
at.x, at.ynumber
stroke.width, stroke.colornumber, color (zero width / transparent when there is no stroke); also the outline of a text layer
opacity, rotatenumber
visiblebool
fill, colorcolor
radius, size, line_spacing, wrap, max_linesnumber (wrap and max_lines read 0 when unset)
text, srctext

@layer.size is the font size actually used after auto-shrink. @layer.rotate is the angle taken modulo 360 (bounds ignore rotation). A hidden layer (visible: false) is not drawn, but its values can still be read.

Params

A param name used in an expression gives the card's value, or the param's default when the card does not set it. An enum param reads as text, an image param as an image (usable in src templates and in avg_color), a list as a list.

Lists and items

ingredients[0] is the first item (an index out of range is error 3102). ing.name reads a field of an item, for example the loop item in repeat.each. len(list) gives the number of items. Items can also be found by key: List lookup by key.

Card and render values

  • card.id: the card's id as text (001, or whatever the card file says).
  • render.index: 0 for the first card of the set, 1 for the second, and so on.
  • render.date: for example 2026-10-08, the local date in the project's time zone. Use it for footers, and pass --now (or --date) when you need identical output on different days.
  • render.time: for example 14:05:09, the local time in the same zone.
  • render.now: for example 2026-10-08T12:05:09Z, the UTC instant of the render. Pass --now to pin it.
"text": "#{card.id} · {render.date}"

The date and time functions are on Dates and times, and the time zone is set with utc_offset in Project Layout and Manifest.

↑↓ to moveEnter to openEsc to close