FacetDocs

Keys

Every key a node can carry, grouped as facet guide prints them. This page is generated from the same table the builder reads, so it lists exactly what is applied.

Language (write these first)

KeyFormsWhat it does
kit{"font", "modes", "colors", "type", "parts"}beside "nodes" (or alone): say colors, type presets and parts once; kept with the file and named everywhere after. A kit has no name and no other keys: a file holds one, and its colors are the variable collection Kit (@ink is @Kit/ink). A color with modes is a LIST in the order of "modes", not a map: {"modes": ["Light", "Dark"], "colors": {"ink": ["#111827", "#F9FAFB"], "surface": ["#FFFFFF", "#0F172A"]}, "type": {"title": "Inter 22/28 700"}}
nodes[NODE, ...]several top-level nodes in one call (a bare node or a list also works)
row[NODE, ...]also column, grid, stack (children overlap, placed with at) and ring (children around a circle, "r")
font"Family Size/Line Weight italic +0.4 caps" | "Family 600" (family and weight; the size kept)on a text; on a container it is the font of every text inside
stylepreset or text style nameon a text or a container; {"preset": "text"} is a text in that preset
color@name | @name/40% | #hexon a container: the color of every text inside; @name is a kit color, /40% a tint (its own variable); "contrast" lets each text pick the ink that reads on its own background
at[x, y] | [x, y, "center"] | "bottom right" | [place, dx, dy] | {"angle", "r"}place a layer: absolute, anchored, by words in its parent, or around the parent's center (degrees from the top)
insetpx | [vertical, horizontal] | [top, right, bottom, left]on a child of a stack, row, column or grid: out of the flow and pinned this far in from the container's edges (0 covers it): an overlay, a scrim, a background behind the other children, an outline around content of any size; a side that is null is left free
after"Slide 3" | "previous" | {"node", "gap", "wrap"}a top-level layer placed right of the one named ("previous": built before it in this call), a gap apart (80 by default), tops aligned: slides and other sequences without computing x. "wrap": 4 starts a new row after every fourth frame, under the row's tallest; "gap": [across, down]
eachlist | countwith "do": NODE, one node per item; {.} is the item, {i} its index, {#} its number, {field} a field
spacenumber | "fill"an empty gap in a row or column
icon"set:name"an icon (same as $icon); size sets both sides
draw[{"circle"|"ellipse"|"rect"|"line"|"poly"|"arc"|"path"|"plot"|"bars": ...}]shapes as data in a box of "size"; fill, stroke, weight, dash, cap per shape. Two are written from data and scaled into the size: {"plot": [3, 5, 4]} is a line through the values and {"bars": [3, 5, 4]} a bar each, the lowest and highest value filling the height ("domain": [low, high] on the drawing sets the range)
setnamea component set: "variants", "template", "props" (bound with "{Prop}"), "behavior" (a statechart) and "looks"; the one way to write a set ("type": "component-set" with "name" reads the same): {"set": "Plan", "props": {"Price": "$0"}, "variants": {"Tier": ["Free", "Pro"]}, "template": {"column": [{"text": "{Tier} plan"}, {"text": "{Price}"}]}}
variants{Property: [values]} | {Property: {Value: {keys, "$nodes", "props"}}}in a set: its variant properties; the first value is the default; a value's map changes that variant; without it the set is one component with only properties
props{Name: default}in a set: its properties; a layer binds with "text": "{Name}" or "visible": "{Name}"; a text naming a variant property ("{Tier} plan") shows each variant's value; set at build: change them with build --sync (or --replace) of the set, not modify
behavior{"start", "states", "axes", "plays", "targets"} | "toggle" | {"use": name, "as": {role: value}, ...}in a set: the states it moves through, stored as a feature named after the set
looks{Axis: {Option: "Collection/Mode"}}in a set with behavior: design axes shown in variable modes
onlyvalue | [values] | {Property: [values]}in a set's template: the layer exists only in those variants
expect{"lines", "maxLines", "fits", "width", "height", "noOverlap"}what must hold after layout; a miss is EXPECT_FAILED
$sourcestringwhere a generator wrote the node ("make.py:118", "Card.tsx:42"). Facet keeps it with the document, inspect shows it, and every warning about the layer ends with it; on a set it is kept on the set and on each variant without its own; it is never read
keystringwhat build --sync matches the layer by, kept with the document (else its name); inside each, filled per item: "{id}"
mode"Dark" | {"Collection": "Mode"}show this layer and everything in it in a mode of the kit's (or a collection's) variables. A themed copy of a built layer: facet call duplicate '{"nodeIds": ["Login"], "name": "Login Dark", "mode": {"collectionName": "Kit", "modeName": "Dark"}}', or build it again with "mode": "Dark"

Structure

KeyFormsWhat it does
type"frame" | "row" | "column" | "grid" | "text" | "rectangle" | "ellipse" | "vector" | "line" | "component-set"what to build; omitted means "column" (a frame with vertical auto layout); "component-set" is the long spelling of "set" (write "set": NAME)
namestringlayer name; results return ids by name, and $nodes/$override address layers by it
children[NODE, ...]child nodes, in order

Size and place

KeyFormsWhat it does
widthnumber | "fill" | "hug""fill" takes the free room of an auto layout parent; "hug" fits the content ("100%" and "auto" also work)
heightnumber | "fill" | "hug"as width
minWidthnumberalso maxWidth, minHeight, maxHeight; a hugging container stops at its max, and a child that fills it gets the max
xnumberposition in the parent; ignored inside auto layout unless "position": "absolute"
ynumberas x
position"absolute" | "auto"absolute takes a child out of its parent's flow (pinned bars, badges)
skewdegrees | [x, y]slants the layer about its top-left corner, as CSS's skew(): x leans its verticals, y its horizontals (each between -89 and 89); with rotation, turned after the slant
matrix[a, b, c, d, e, f] | "none"draws the layer through a CSS matrix about its top-left corner (x' = a x + c y + e, y' = b x + d y + f): a skew, a scale, a mirror or a flat 3D turn; its own box keeps its size and place in a flow; replaces rotation; inspect and source show it when it is more than a turn
rotationdegreescounterclockwise, about the layer's top-left corner (where at, x and y put it); an anchor such as at [x, y, "center"] places that point at x, y
constraints{"horizontal": "left"|"right"|"center"|"left-right"|"scale", "vertical": "top"|"bottom"|"center"|"top-bottom"|"scale"}how a child follows a resized fixed frame

Auto layout

KeyFormsWhat it does
gapnumber | {"row", "column"} | "auto"space between children; "auto" spreads them (space-between); negative in a row or column that does not wrap: each child lies over the one before by that much (a row of avatars, "gap": -8)
dividerscolor | true | {"color", "weight", "inset"}on a row or column: a rule between each pair of children, never after the last (true: the kit's line colour); they are ordinary layers named Divider
connect["From", "To"]an arrow between two named layers, routed after layout and drawn as an ordinary drawing beside them; "from"/"to" (sides: left, right, top, bottom, center), "curve" (smooth, straight, elbow), "arrow" (end, start, both, none), "stroke", "weight", "dash", "gap", "label", "route" (avoid, the default: around the layers beside it that it does not join, apart from the lines beside it; direct: straight through them)
betweenNODEon a row or column: that node repeated between each pair of children (a dot, an arrow icon)
paddingnumber | [vertical, horizontal] | [top, right, bottom, left] | {"top","right","bottom","left","horizontal","vertical"}inner space
justify"start" | "center" | "end" | "space-between" | "space-around" | "space-evenly"along the flow; needs room (a number or "fill" size). space-between puts the first and last at the edges; space-evenly makes every space equal, the ends included; space-around gives the ends half a space
align"start" | "center" | "end" | "stretch"across the flow; stretch (as CSS): frames that hug take the line's size, the tallest setting it
wrapboolrows wrap onto new lines
alignSelf"start" | "center" | "end" | "stretch" | "auto"on a child of a row or column: where it sits across the flow when that is not where the parent's "align" puts its children (one item at the bottom of a centred row); "auto" follows the parent
marginnumber | [vertical, horizontal] | [top, right, bottom, left] | {"top","right","bottom","left","horizontal","vertical"}on a child of a row, column or grid: room of its own around it, beyond the parent's gap (as CSS's margin). A negative side pulls it toward its neighbour, or over it; a frame that hugs is as large as its children with their margins
grow1 | weightfill the free room along the parent's flow; a weight shares it as CSS's flex-grow does (a child with 2 takes twice the room of one with 1)
columnsnumber | [number | "fill" | "Nfr" | "hug" | {"width", "align"}, ...]grid: column count (equal shares) or tracks: widths, shares of the free width, and "hug" (as wide as the column's widest cell); {"width": "hug", "align": "end"} also puts the column's cells at its start, center or end. A grid written row by row ({"grid": [[cells], [cells]]}) makes each row a layer: "header": [cells] adds a first row, "rows": {padding, fill, height} styles every row, {"cells": [...], "fill": ...} one row, "dividers" rules them off, and the columns still line up
columnSpannumbergrid child: columns it spans
gridRows[number | "Nfr" | "hug", ...] | "none"grid: its rows, top to bottom: heights, shares of the height left (at least the row's content, as CSS's 1fr: a hero row that takes what a tall cell beside it leaves) and "hug"; rows past the list hug; "none" removes them
rowSpannumbergrid child: rows it spans (a tall card beside two short ones)

Look

KeyFormsWhat it does
fill"#RRGGBB[AA]" | "rgb(...)" | color name | "@Collection/name|#fallback" | {"type":"linear"|"radial"|"angular"|"diamond","stops":[{"position","color"}],"angle"} | {"type":"image","url":...} | {"pattern":"dots"|"lines"|"grid"|"hatch"|"cross"|"checker"|"halftone"|"dither","size","weight","color","background","density","angle"} | [paint, ...] | nullfills of frames and shapes, bottom first; a pattern is a small tiled picture drawn from its words (size: the pitch, weight: a dot's diameter or a line's thickness, density: the share a halftone or dither covers, angle: 0, 45, 90 or 135 for lines and a hatch); each paint object may add opacity, visible and blendMode; a lone token color stays bound to its variable; text uses color
strokecolor | gradient | [paint, ...]border; with strokeWidth (default 1) and strokeAlign (inside, center, outside)
strokeWidthnumber | [top, right, bottom, left] | {"top","right","bottom","left"}border width; per side on frames and rectangles
strokeDash[dash, gap] | "none"dashed border; strokeCap (none, round, square) and strokeJoin (miter, bevel, round) shape vector strokes
strokeAlign"inside" | "center" | "outside"border position
cornerRadiusnumber | {"topLeft","topRight","bottomRight","bottomLeft"} | [tl, tr, br, bl]rounded corners, one radius or one per corner
effects{"type":"drop-shadow","x","y","blur","spread","color"} | {"type":"blur","blur"} | [...]drop-shadow and inner-shadow (several of each, bottom first), one blur (layer blur) and one background-blur; a text takes one drop-shadow and one blur, drawn from its glyphs
opacity0..1layer opacity
blendMode"pass-through" | "normal" | "multiply" | "screen" | "overlay" | ...layer blend mode (18 modes)
clipboolclip children to the frame (default: fixed-size or rounded frames clip); written as true it is meant, as "overflow": "hidden" is, and the audit does not flag what it cuts
overflow"hidden" | "vertical" | "horizontal"content beyond the frame is expected: clipped on purpose (hidden) or scrolled; the audit does not flag it
visibleboolfalse hides the layer ("hidden": true also works)
lockedboollock against pointer edits

Text

KeyFormsWhat it does
textstringthe characters; \n starts a paragraph
runs["text", NODE, ...]with type "paragraph": a sentence with components in it (chips, icons), wrapping like text; text keys style every word; wordSpacing and lineGap tune the spacing
fontSizenumber | "fit" | {"fit": {"min", "max"}}size in px (default 16). "fit": the largest whole size at which the text fits what it was given, measured after layout: its maxLines at its width; else, with a height, that box; else one line at its width. The line height scales with it; FONT_FIT notes the size
fontWeight100..900 | "Regular" | "Medium" | "Semi Bold" | "Bold" | ...weight
fontFamilystringfamily name; one this machine lacks is fetched from Google Fonts, otherwise substituted with a warning
colorcolor | "contrast" | {"contrast": [color, color, ...]}text color (also on $icon); "contrast" picks the ink that reads best on the fill behind the text (near-black or white), or the best of the colors given
lineHeightnumber | "150%" | "auto" | {"unit":"PIXELS"|"PERCENT"|"AUTO","value"}line height
letterSpacingnumber | "5%"tracking (not applied to joined scripts: Arabic, Devanagari…)
textAlign"left" | "center" | "right" | "justified"a text that fills its row needs center to look centered
resize"width" | "height" | "none" | "truncate"auto width (one line), wrap at the width (auto height), fixed box, or fixed with an ellipsis
spans["plain text" | {"text", ...character keys}, ...]mixed styles in one layer: each span sets fontWeight, fontSize, fontFamily, italic, color, underline, strikethrough, textDecoration, textCase, letterSpacing or lineHeight for its text; a string is plain text
textDecoration"none" | "underline" | "strikethrough"decoration; also textCase (original, upper, lower, title), italic (bool), paragraphSpacing (px) and maxLines (truncates with an ellipsis)
fractionaltrue | falsea text that hugs keeps its measured width (54.3) instead of the next whole unit (55), as a browser sizes text; for rows read from a page, where rounding each text would add up
underlinetrue | "dotted" | {"style", "thickness", "offset"}an underline and how it is drawn: style solid, double, dotted, dashed or wavy; thickness px (0: the font's); offset px below the baseline. strikethrough takes the same; textDecoration also reads CSS's "underline dotted 2px" and textDecorationStyle, textDecorationThickness, textUnderlineOffset
highlightcolor | {"fill", "radius", "padding"} | "none"on a text or a span: a fill behind the characters, drawn per line with rounded ends (a pill inside a sentence); padding [vertical, horizontal] px, the horizontal moving the words around it apart. In a span, CSS's background or backgroundColor with borderRadius and padding read as it
columns1..12 (on a text)on a text with a width: columns its lines fill in turn, balanced when its height follows the content; "gap" (px, default the line height) is the space between them
dropCap2..10 | {"lines", "font", "color", "gap"}the first character set large across that many lines, the lines beside it starting after it; its size follows the lines, "font" takes a family and weight ("Fraunces semibold")
list"bullet" | "number" | "check" | CHARS | "none" | {"marker", "indent", "start"}each paragraph an item of a list, its leading tabs its level, a check item's leading [x] its box; a marker hangs before each item and wrapped lines align at its indent. As a node, {"list": ["a", ["nested"], "b"], "marker": "number"} builds one text
paragraphIndentnumber | {"size", "first"}the first line of each paragraph starts this far in; as books set it, not the text's first paragraph unless "first": true
verticalAlign"top" | "center" | "bottom"on a text with a height: where its lines sit in the box (a height with center or bottom keeps the box fixed); Figma's textAlignVertical reads as it
paragraph"heading" | "item" | "quote" | "body" | "bullet" | "number" | "check" | "none" | {"role", "indent", "hang", "inset", "spaceBefore", "spaceAfter", "keepWithNext", "keepTogether", "list", "level"}on a span or a text: the settings of the paragraphs its characters start. bullet/number/check (or list: CHARS, level 0..8): a list item whose marker Facet draws in the hanging space, numbers counting the items in a row. heading: kept with the next paragraph, not indented, and the paragraph after it starts flush; item: lines after the first start under the text after its marker ("— ", "1. "); quote: lines start in by inset. spaceBefore/After px, keepWithNext moves it on to the next frame with what follows, keepTogether keeps it in one frame
quotes"smart" | "straight"on a text: "smart" sets its straight quotes and apostrophes as typographic ones (“ ” ‘ ’) as it builds, spans included; a quote after a digit stays a prime. Running text left with straight ones warns STRAIGHT_QUOTES
orphans1..9on a text: fewest lines of a paragraph left alone at the foot of a frame or column; widows (1..9): fewest carried alone to the next one's head; 1 (the default) lets a paragraph break anywhere
widows1..9on a text: fewest lines of a paragraph carried alone to the head of the next frame or column (see orphans)
balanceboolon a text: true breaks its lines evenly (CSS text-wrap: balance), at the narrowest width that keeps the line count, for a paragraph of up to six lines; "textWrap": "balance" is read as it
hyphenateboolon justified text: false breaks words only at their soft hyphens (U+00AD), for a language English hyphenation points get wrong; true (the default) also at those points
langlanguage tag ("de", "pt-BR")on a text: its language, which chooses justified text's hyphenation patterns (English when absent; one without patterns for its letters breaks words only at soft hyphens)
fontFeatures{"tnum": true, "ss01": 1, "liga": false} | ["smcp", "onum"]OpenType features of a text or a span: tnum tabular figures, onum/lnum oldstyle/lining figures, smcp/c2sc small caps, liga/dlig ligatures, ss01-ss20 stylistic sets, cv01 character variants, frac, sups/subs; a font without one ignores it (Rust text engine)
baselineShiftpx | "super" | "sub"on a span: raised (positive) or lowered from the baseline; super and sub raise or lower by a third of the text's size and set it at 65% (x², H₂O, footnote marks)
linkURL | ""on a text or a span: an https:, http: or mailto: link; exported PDFs make those characters clickable; "" removes it (href reads as it)
textWrappx | {"offset", "side": "auto" | "largest" | "both" | "left" | "right" | "neither", "around": "box" | "outline"} | "outline" | "none"on any layer: texts sharing its parent flow around its box (or with around outline, its shape: a circle's curve, a triangle's sides, a path, a group's, a picture's opaque part) that far clear (also when it is placed with at); a text with columns does not
flow[frame name | {"frame", "page"}, ...]on a text: the story flows through these frames in order, the text filling the first and a linked box filling each next one, each starting where the box before runs out; a frame on another page names its page
$textStylestyle namefollow a text style; a new name creates the style from this layer

Components

KeyFormsWhat it does
$instancecomponent or set namean instance; a set gives its first variant; "scale": 0.5 scales everything it shows (sizes, text, strokes, radii)
$variant{"Property": "Value"}choose a variant
$override{"Layer": "text" | bool | {props} | {"Property": "Value"}}per-instance text, visibility, fill, color, stroke, image, width and height, a nested instance's variant, or an icon swap ("Icon": "lucide:moon"); a layer name reaches every layer of that name below the instance, and a path reaches one: "Settings > Icon" is the Icon inside the layer named Settings; layout follows the component
scalenumber (0.01 to 100)with $instance: show the component scaled, strokes, radii, effects, spacing and text included (a live thumbnail)
templateNODEin a set: the node every variant starts from
variantMatrix{"Property": {"Value": {props, "$nodes": {...}}} | ["Value", ...]}the long spelling of "variants" (write "variants"): one variant per combination, in written order
$nodes{"Layer": {props}}edit named descendants (variantMatrix entries, instances and modify)
$clonenode idcopy an existing node (placed beside it)
$alias{"Label": {"name": "Count", "default": "0"}}on a nested instance in a component being built: the component's property Count (added with the default when new) drives the instance's own property Label; written by the language for {"Pill": {"Label": "{Count}"}} in a set template
$expose{"characters": "Name"} | {"visible": "Name"}with convertToComponent: the layer's text or visibility becomes a component property; instances set it with $override {"Name": value}
$exposeInstancetruewith convertToComponent: a nested instance shows its properties on the component's instances
$variants{"Property": ["Value", ...]}inside a component-set template: the layer exists only in variants with those values (other variants leave it out instead of hiding it)

Media

KeyFormsWhat it does
$imagefile path | file:// | data: URL | https:// URL | "photo:QUERY" | "hash:HEX"an image fill (with scaleMode fill, fit, crop or tile); URLs and photo searches are fetched once and cached; hash: reuses an image in the document; {"src": source, "crop": [x, y, w, h]} keeps that part of the image, in its own pixels
scaleMode"fill" | "fit" | "crop" | "tile"how $image fits; tile repeats it from the top-left corner at one unit per image pixel
tileScalenumber (above 0, up to 1000)with scaleMode tile: the tiles at this multiple of the image's natural size (0.5 halves them)
focus[x, y] from 0 to 1 | "top" | "bottom left" | ...the point of a filling image kept in view: the crop centers on it as far as the image covers the layer ([0.5, 0.5], the center, by default)
svgPathSVG path datavector: one or more subpaths (M, L, H, V, C, S, Q, T, Z), filled together by the nonzero rule (a hole winds the other way); the layer is the path's own bounds, its top-left corner at x, y (a path starting at 40,40 is not offset by 40); to keep a path's coordinates, use draw with a path shape in a drawing of a set size
$svg<svg> markupvector layers from every shape (one per subpath, with fill and stroke), scaled to width/height; currentColor takes "color" (alpha included), and "fill" (a color or gradient) paints what currentColor fills; its <text> and <tspan> become text layers placed by baseline and text-anchor (a <textPath> or turned text is not, SVG_TEXT_DROPPED); a <mask> (luminance or alpha), or a clip path (by its shapes), becomes a "Masked" group with a Facet mask layer "Mask" first; a mask or clip inside a masked element, a filter or image is not applied (SVG_FEATURE_IGNORED)
marks[{"box": [x, y, w, h], "pin": 1, "side": "left" | "right" | "top" | "bottom" | "top left", "color"}]on an image: outlined boxes with numbered pins over parts of it, in the image's own pixels and scaled as it is shown (annotated screenshots); "markColor" colors them all; without a height the image keeps its proportions
mergebool (default true)with $svg or draw: neighbouring shapes that paint alike and don't touch become one layer (500 dots of one color are one vector); false keeps a layer per shape
$icon"set:name" (Iconify: lucide, mdi, tabler, ...)an icon: an instance of the component "Icons/set:name" (made on first use in the "Icons" frame), with size and color; $override {"Icon": "lucide:moon"} or modify {"$icon": ...} swaps it

Node types

frame, row, column, grid, text, rectangle, ellipse, vector, line, paragraph, component-set, plus the containers of the language (row, column, grid, stack, ring).

Documentation for Facet 0.3.228-g032727de