Agent card
Everything most builds need, in the order you need it. The other pages go deeper, and the full documentation holds all of them in one file.
Commands
facet --doc f.facet build @screen.json --preview s.png # build, then read every warning
facet --doc f.facet source Screen # a layer, in the language
facet --doc f.facet build @screen.json --sync # change in place
facet --doc f.facet modify Card '{"fill": "@paper"}' # one or two values
facet --doc f.facet tree Screen # ids, sizes, places (no name: the whole page)
facet --doc f.facet inspect 42 # every property of one layer
facet --doc f.facet shot Screen -o s.png --scale 2 # render any layer (transparent; --background '#FFFFFF')
facet --doc f.facet shot -o part.png --region 80,30,30,40 # render a world rectangle
facet --doc f.facet export --out out --node 42 --format pdf --wait # one layer as a file, by its id (Card.pdf)
facet --doc f.facet export --pdf deck.pdf --wait # the page showing, a frame a PDF page; --pages all for every page of the file (look at a page with shot FRAME)
facet --doc f.facet rename "Frame 12" Header # name a layer
facet --doc f.facet replace "Sign up" "Join" # new words in every text of the page (--in NODE: under one layer)
facet --doc f.facet hide Debug # also show, lock (for the hand: commands still change a locked layer), unlock (several layers, or --all for every layer of a name); resize Card --width 400
facet --doc f.facet move Badge --into Card # put a layer inside another
facet --doc f.facet component Card # make a frame a component, where it is; move Footer --end: last among its parent's children
facet --doc f.facet detach "Pro card" # an instance as ordinary layers; group A B --name Pair: layers in a row, column or group of their own
facet --doc f.facet modify "[font=Inter]" '{"fontFamily": "Roboto"}' --all # every layer a name or selector matches, in one step
facet --doc f.facet copy Home --name "Home v2" # a copy: right of a top-level frame, after a child in its flow (--mode Dark: themed)
facet --doc f.facet page copy Home "Home v2" # a whole page: its layers where they were, on a new page
facet --doc f.facet find --text "Submit" # the texts that say it
facet --doc f.facet find --fill "#2563EB" # layers of a colour (or of a variable: --fill @brand); --type text --min-size 20: texts by size
facet --doc f.facet variables rename accent brand # a variable's name; layers that use it follow
facet --doc f.facet history version "Before redesign" # a named version; history restore NAME, history diff NAME (layers by id, variables by name: `renamed Kit/brand to Kit/accent`); `history export NAME -o old.facet` writes a version as a file of its own, to look at (`facet --doc old.facet shot`) without restoring it
facet --doc f.facet page add Flows # also page show, rename, delete, list
facet --doc f.facet delete Card # remove a layer
facet --doc f.facet undo # each call is one undo step
facet --doc f.facet close # save and stop the host
--doc and the path are two arguments; to say the file once, export CANVAS_DOC=/abs/path/f.facet and write facet COMMAND (a shell variable holding facet --doc f.facet is run by zsh as one command name, and fails). A file the app has open is edited live in the app; add --headless after the path for a host of your own. @file.json reads a file; inline JSON works too.
A build call
A node, a list of nodes, or {"kit": {...}, "nodes": [...]}. Send the kit once per file; it is saved with the file and every later call names it. Several files share one kit with {"kit": {"use": "../system/kit.json"}}: its parts, presets and colours come from that file and follow it when it changes.
{
"kit": {
"font": "Inter 15/22",
"colors": {
"ink": "#1A1423",
"paper": "#FBF7F0",
"rose": "#D9485F",
"mute": "#6B6470"
},
"type": {"title": "Inter 22/28 700", "cap": "Inter 12/16 600 +0.4 caps"},
"parts": {
"chip": {
"params": {"label": "", "tone": "@rose"},
"node": {
"row": [{"text": "{label}", "color": "{tone}"}],
"padding": [2, 8],
"cornerRadius": 8,
"fill": "{tone}/12%"
}
}
}
},
"nodes": [
{
"name": "Card",
"width": 360,
"padding": 16,
"gap": 8,
"fill": "@paper",
"color": "@ink",
"cornerRadius": 16,
"column": [
{"title": "Today"},
{
"row": [
{"cap": "Raag Yaman"},
{"space": "fill"},
{"chip": "Evening"}
],
"width": "fill",
"align": "center"
},
{
"text": "Long text wraps at the card’s width and takes the height of its lines.",
"width": "fill",
"color": "@mute"
},
{"icon": "lucide:clock", "size": 16, "color": "@mute"}
]
}
]
}

A kit and a card in one call. Every later call names @ink, title and chip without sending them again.
- Strings are texts. Containers pass
font,styleandcolordown to every text inside. - Kit colors are variables (the collection is named
Kit; a kit has no name); rename one withfacet variables rename brand accentand give one a value withfacet variables set paper '#000000' --mode Dark, and the kit follows):@ink, a tint@ink/40%, one value per mode with"modes": ["Light", "Dark"]as a list in that order,"surface": ["#FFFFFF", "#0F172A"], and"mode": "Dark"on a layer. A Dark copy of a built layer:facet call duplicate '{"nodeIds": ["Login"], "name": "Login Dark", "mode": {"collectionName": "Kit", "modeName": "Dark"}}'. - Kit spacings are number variables:
"space": {"s": 8, "m": 16}in the kit, then"gap": "@s","padding": ["@s", "@m"]. Change one in the kit and the layers follow. - Type presets are text styles:
{"title": "Today"}is a text intitle; so is{"text": "Today", "style": "title"};"style": "cap"sets a container's default. - Parts take parameters:
{"chip": "Evening"}(first parameter) or{"chip": {"label": "Late", "tone": "@mute"}}.{param}alone takes the value as it is (a node, a list); inside longer text it is text. Parts use parts and pass their parameters on:{"avatar": {"initials": "{initials}"}}insidemember. Achildrenparameter takes the children written at the use ("{children}"). A list parameter defaulting to[], written alone among children ({"row": [{"text": "{who}"}, {"space": "fill"}, "{badges}"]}), adds nothing when left out and its nodes when given:{"member": {"who": "Ben", "badges": [{"chip": "Blocked"}]}}. - Ready parts:
{"kit": {"use": "facet:basics"}}bringschip,pill,badge,dot,button,button-quiet,toggle,toggle-off,segmented(ofsegment,segment-on),card,stat,legend,spark,bars,stack-bar,meter,code,steps(ofstep),windowandphone, painted in your kit'saccent,ink,line… Write them before you draw one by hand;facet guide basicslists each with its parameters. - Names: a key that is not a language key is a preset, then a part, then a component. Keys win, so never name a preset or part
name,text,size,rowor any other key. A preset and a part cannot share a name.{"kit": {"parts": {"chip": null}}}removes one. - Font shorthand:
"Family Size/Line Weight"plusitalic, tracking+0.4or-2%, a casecaps. Weights are 100 to 900 in hundreds, orlight,medium,semibold,boldand the rest; a weight between them after a size ("Inter 15/22 650") is read as written, drawn exactly by a font that varies by weight and by the nearest weight otherwise, with a note."17/26"keeps the family;"600"or"semibold"changes only the weight, and"Fraunces 600"the family and weight; a size of a whole hundred takes its line height ("200/200"). Any Google Font downloads on first use. Change a preset in the kit and every text in it follows at once.
Layout
| Write | For |
|---|---|
{"row": [...]}, {"column": [...]} | auto layout; gap (negative lays each child over the one before: a row of avatars is "gap": -8), padding (number, [v, h], [t, r, b, l]), align (cross: start, center, end, stretch, baseline: a row's texts on one baseline), justify (start, center, end, space-between, space-around, space-evenly) |
{"grid": [...], "columns": 2} | rows of columns ("columns": [120, "fill", "hug"] sizes them: a width, a share, the widest cell; {"width": "hug", "align": "end"} also right-aligns the column); a cell that holds layers fills its column unless given a width, and a text given no width that would run past its cell wraps at the cell's width (TEXT_CELL_WRAP notes it) |
{"stack": [...]} | children overlap, centered; place each with at, or "inset": 0 to fill the stack (an overlay, an outline) |
{"ring": [...], "r": 80} | children around a circle; "arrows": true draws a cycle from each to the next |
"width", "height" | a number, "fill" (the room the flow leaves), "hug" (default for containers); "size": 40, [w, h] or "fill" (both ways) |
{"space": "fill"}, {"space": 12} | push siblings apart, or a fixed gap |
{"grid": [[cells], [cells]], "header": [cells], "rows": {"padding": [8, 12]}, "dividers": true} | a table: each list is a row and a layer of its own (fill it, round it), columns line up; {"cells": [...], "fill": ...} restyles one row |
{"connect": ["A", "B"]} | an arrow from layer A to layer B, routed after layout; curve, arrow, stroke, label; beside them in their container. ["CEO", "A", "B", "C"] joins the first to each of the rest (an org chart); a decision is {"shape": "diamond", "text": "Valid?"}. A connector that names a layer that is not there is said once and not built |
"dividers": "@line", "between": "·" | on a row or column: a rule, or any node, between each pair of children (never after the last) |
"at" | [x, y], [x, y, "center"] or [x, y, "top center"] (that point of the layer at x, y; anchor a text that may wrap by its top so it grows down), "bottom right", ["top right", -8, 8] (x right, y down), {"angle": 90, "r": 60}; takes the layer out of the flow |
"maxWidth": 260 | on a text, or on the row or column holding it: longer words wrap there, shorter ones keep their width (a chat bubble) |
"margin": 8, [v, h], [t, r, b, l], {"top": -4} | on a child of a row, column or grid: room of its own beyond the gap; a negative side pulls it toward its neighbour, or over it |
"alignSelf": "end" | on a child of a row or column: its own place across the flow (start, center, end, stretch, baseline), whatever the parent's align |
"inset": 0, [t, r, b, l] | on a child of a stack, row, column or grid: out of the flow and pinned to the container's edges (a background, an overlay); null leaves a side free |
"grow": 1 | take the leftover room along the flow, over any width or height given along it; a weight shares it ("grow": 2 takes twice the room of "grow": 1) |
{"row": [{"text": "Email", "color": "@muted"}], "width": "fill", "height": 44, "padding": [0, 12], "align": "center", "stroke": "@border", "cornerRadius": 8} | a text field with its placeholder: an input is a bordered row |
{"button": "Sign in"}, {"toggle": true, "on": true}, {"input": "email", "placeholder": "you@example.com"} (or a stroked box with a placeholder), {"divider": true}, {"triangle": "down"} | controls written as a key are read as the layers that draw them (a row holding the label, a track and knob, a bordered row, a 1 px rule, a drawn triangle), with a note; a kit part, preset or component of that name comes first |
Never compute positions: at with a place word, an anchor or an angle does it.
Look
fill (a color: hex, oklch(), lab(), hsl(), color(display-p3 …) and every CSS Color 4 form, color-mix(in srgb, #2563EB, black 20%), "none", or a gradient {"linear": ["@rose", "@ink"], "angle": 90}: 90 runs top to bottom, 0 left to right, and no angle is top to bottom; or a pattern {"pattern": "dots", "size": 8, "color": "@ink"}: dots, lines, grid, hatch, cross, checker, halftone or dither, one small tiled picture, with weight, background, density and angle), "$image": "photo:latte art" (the best match; facet call photos '{"query": "latte art", "sheet": "pick.png"}' draws the candidates numbered, to choose one by looking and pass its thumbnail) or a path for a picture ("focus": "top" or [x, y] keeps that part in view when it crops; {"src": "shot.png", "crop": [x, y, w, h]} cuts it to that rectangle of its own pixels first; "scaleMode": "tile" repeats it from the top-left corner at one unit per image pixel, and "tileScale": 0.5 halves the tiles; "marks": [{"box": [x, y, w, h], "pin": 1, "side": "left"}] outlines parts of a screenshot with numbered pins, the boxes in the screenshot's own pixels, and "markColor" colors them), stroke and strokeWidth (a number, or per side on frames and rectangles: {"bottom": 1} with sides left out 0, or a list as padding takes it, [0, 0, 1, 0]), cornerRadius (number, [tl, tr, br, bl] or a side: {"top": 16}), opacity (0 to 1; 40 and "40%" are read as 0.4), blendMode ("multiply" for an overprint, "screen", "overlay" and the rest, on shapes, frames and texts), effects ({"type": "drop-shadow", "x": 0, "y": 4, "blur": 12, "color": "#0000001A"}, {"type": "blur", "blur": 8} (a layer blur: on a frame or a drawing, the frame and everything in it blur together), or "none"), overflow: "hidden", rotation (degrees counterclockwise, about the layer's top-left corner, which stays where at, x and y put it; what is inside turns with it, and at with an anchor puts the turned layer's own anchor point there). Texts: text, font, style, color ("contrast" picks near-black or white, whichever reads best on the fill behind the text; {"contrast": ["@ink", "@paper"]} picks among your colors), textAlign, maxLines: 1 (one line with an ellipsis), "type": "paragraph" with "runs": ["Due ", {"chip": "Fri"}, " at noon."] for chips inside a sentence; padding on a text puts it in a box named after it, the text named after it too (Count holds Count text; Label when unnamed), and there fill, stroke, cornerRadius and effects are the box's (a text with a fill beside its color, or with a fill and a cornerRadius, is the same box: a number on a round blue square); a text takes one drop shadow and a layer blur, drawn from its glyphs (white type on a photo). Editorial typography is below.
{"icon": "lucide:bell", "size": 20, "color": "@mute"}: any Iconify set; each name becomes a component in an Icons frame, every use an instance. {"draw": [{"circle": [20, 20, 18], "stroke": "@rose", "weight": 3}], "size": 40} draws shapes (circle, ellipse, rect, line, poly, arc, path; points flat or as [x, y] pairs); an arc [cx, cy, r, from, to] runs clockwise from 12 o'clock in degrees.
Typography
Book-quality setting, all on one text layer that stays editable. facet guide typography prints every text key; Text has the details and live examples.
| Write | For |
|---|---|
"font": "Fraunces 40/44 600 italic -1%" | family, size/line, weight, italic, tracking; caps for capitals; a kit type preset is a text style and can hold dropCap, columns and paragraphIndent |
"textAlign": "justified" | whole-paragraph line breaking (Knuth–Plass), even spaces, and hyphenation at Liang's points in the text's "lang" ("de", "pt-BR"; about fifty languages) |
"hyphenate": false, U+00AD, U+2060 | break only at soft hyphens you place; a word joiner keeps letters together |
"columns": 2, "gap": 20 | lines in columns, balanced when the height follows the content |
"dropCap": 3 or {"lines": 3, "font": "Fraunces semibold", "color": "@rose", "gap": 6} | a large first letter across three lines |
{"list": ["a", ["nested"], "b"], "marker": "number"} | a list in one text: bullet, number, check ("[x] Done") or any marker; wrapped lines align at the indent |
"paragraphIndent": 12 or {"size": 12, "first": true} | each paragraph's first line indented, as books set it |
"paragraph": "heading" on a span (or "bullet", "number", "item", "quote", {"spaceBefore": 8, "keepTogether": true}) | the paragraph it starts: a heading stays with what follows and starts flush, an item hangs under its text; "widows": 2 / "orphans": 2 on the text keep lines together across frames |
"textWrap": 12 on a photo or shape | the texts beside it flow around it, 12 clear; {"offset": 12, "around": "outline", "side": "largest"} follows its shape |
"flow": ["Col 1", "Col 2", {"frame": "Body", "page": "Page 2"}] | one story set through frames in order, across pages; edits reflow it through every box |
"spans": [...], "type": "paragraph" with "runs" | mixed styles in one text; components (chips, icons) inside a sentence. Spans are the text: "spans": [{"text": "$29", "fontSize": 48}, {"text": "/month", "fontSize": 16}] is a big price and a small unit on one baseline (a span reads character keys: fontSize, fontWeight, color, italic). With a "text" beside them, spans that are parts of it restyle those parts |
"maxLines": 1 | one line ending in an ellipsis (TEXT_ELLIPSIS notes it) |
"fontSize": "fit" | the largest size at which the text fits its width on one line (its maxLines, or its height, when given); {"fit": {"min": 12, "max": 64}} bounds it |
{"text": "2", "baselineShift": "super"} in spans | superscripts, subscripts ("sub"), footnote marks; px for your own shift |
{"text": "the guide", "link": "https://…"} in spans | a link, clickable in exported PDFs; on a text it covers all of it |
"underline": "dotted", {"style": "wavy", "thickness": 1.5, "offset": 3} | underline style (solid, double, dotted, dashed, wavy), thickness, offset; strikethrough the same |
{"text": "12%", "highlight": {"fill": "@lilac", "radius": 6, "padding": [1, 6]}} in spans | a pill behind part of a sentence, drawn per line; highlight on a text covers all of it |
"fontFeatures": {"tnum": true} or ["smcp", "onum"] | OpenType features on a text or a span: tabular or oldstyle figures, true small caps, ligatures, stylistic sets (ss01), character variants |
Right-to-left and mixed-direction lines, Devanagari and other reordering scripts shape as written. PDFs keep text selectable and copy it in reading order; a hyphenation point's hyphen copies as a soft hyphen, so the word pastes whole.
Repeat
{"each": ["Mon", "Tue", "Wed"], "do": {"chip": "{.}"}}: {.} the item, {field} a field of an object item, {i} its index, {#} its number. {"each": 5, "do": ...} repeats a count. each goes wherever a child can go: in a grid list each item is a cell.
Components
{
"nodes": [
{
"set": "Plan",
"props": {"Price": "$0", "Note": "Billed monthly"},
"variants": {"Tier": ["Free", "Pro"]},
"template": {
"name": "Plan",
"width": 240,
"padding": 16,
"gap": 6,
"fill": "#FFFFFF",
"column": [
{"title": "{Tier} plan"},
{"text": "{Price}", "name": "Price"},
{"text": "{Note}", "name": "Note", "width": "fill"},
{"chip": "Popular", "only": "Pro"}
]
},
"x": 440,
"y": 0
},
{
"name": "Plans",
"x": 440,
"y": 260,
"gap": 12,
"row": [
{"Plan": {"Tier": "Free"}},
{
"Plan": {"Tier": "Pro", "Note": "Billed yearly"},
"name": "Pro card"
}
]
}
]
}

A set with a property per text, a variant property shown in a text, a layer only one variant holds, and two instances in the same call.
"{Prop}"binds a text to a property;"visible": "{Show}"binds visibility to a boolean one."{Tier} plan"names a variant property, so each variant shows its own value.- Variants sit in a grid, the last property across;
"columns": "State"on the set picks another. onlykeeps a layer to some variants. A variant's map, written under"variants", changes it:"variants": {"Tier": {"Free": {}, "Pro": {"fill": "#F3EFF7", "props": {"Price": "$12"}, "$nodes": {"Title": {"color": "#7C3AED"}}}}}. A text with a colour of its own is restyled by name under"$nodes".- A prop every variant sets for itself cannot be set by instances; the build warns.
- Give exposed texts
"width": "fill"(or a number) so longer values wrap rather than widen the component. - A set is built on the page, at the top level of the call: written inside a frame it is lifted out, with a note.
- A component written the way other tools write one,
{"component": "Button", "variants": {"Size": ["Small", "Large"]}, "props": {"Label": "Save"}, "row": [...]}, is read as a set when no component has that name (the rest is its template), and{"use": "Button", "Size": "Small"}as an instance. - A layer of one instance:
{"Card": {"Title": "Pasta"}, "$nodes": {"Photo": {"$image": "pasta.jpg"}}}sets keys on the instance's own layers by name (a picture, a fill), where a property does not reach. - Instances:
{"Plan": {"Tier": "Pro", "Note": "Billed yearly"}, "name": "Pro card"}. Variant property keys choose the variant; the rest set properties. The set may be written before or after the screens that use it. One call can hold the set and the screen that uses it. - Behavior on a set (
"behavior": {"start", "states", "axes", "plays", "targets"}) is stored as a feature named after the set (plan);facet chart planchecks it. See Behavior.
Writing a generator
A script (Python, a shell loop, React) that writes the JSON is fine, and facet --doc f.facet build --watch --run 'python3 make.py' runs it again and syncs each time you save. Before you hand-place anything (an x or y, a column width, a font size, a text height, an arrow's path), check that the language doesn't already do it. Each row below is arithmetic that generators kept writing by hand:
| Instead of | Write |
|---|---|
| an x and y for each layer | a row, column or grid; at with a place word ("bottom right", ["top right", -8, 8]) for the one layer that overlaps |
| an x for each top-level frame | "after": "previous" (or a frame's name); it sets the gap and aligns the tops. {"node": "previous", "wrap": 4, "gap": [80, 120]} makes rows of four. On a sync a frame keeps its place, unless the frame it follows has grown over it: then it and the frames after it move clear. For frames already there: facet arrange --columns 4 |
a caption placed at y - 70 above a frame | a column of the label and the frame; after follows it by the frame's name |
round(size * 1.35) for a line height | a ratio in the font: "Inter 16/1.35" |
a font size guessed from the length of a title (len * 0.62) | "fontSize": "fit" on a text with a width |
| a guess at a text's height from its length | let it size itself: a text with a width (or "width": "fill") takes the height of its lines, and the column below it moves down |
| column widths so rows line up, or a width guessed for the longest label | "columns": ["hug", "fill", {"width": "hug", "align": "end"}], and "grid": [[cells], [cells]] with header and rows for a table |
| coordinates for an arrow between two boxes | {"connect": ["A", "B"]}, which follows the boxes |
| a rule after every row but the last | "dividers": "@line" on the column |
| a search for the line that wrote a layer a warning names | "$source": "make.py:118" on the nodes a helper writes; warnings about them end with it |
| hex colours repeated through the script | kit colours, sent once: @ink, @ink/40%, with a Dark value if the design has one |
a build, then tree parsed to learn a text's height | facet probe @block.json: sizes and each text's lines, nothing kept |
| pixel widths for the parts of a stacked bar | grow weights: {"grow": 3} beside {"grow": 1} |
value / max * height for a bar chart or a sparkline | {"draw": [{"bars": [3, 5, 4]}, {"plot": [3, 5, 4]}], "size": [280, 60]}, or the kit's spark, bars, stack-bar and meter parts; a ring by its shares is {"chart": "donut", "segments": [{"value": 50, "fill": "@accent"}, {"value": 50, "fill": "@line"}], "size": 120, "thickness": 16, "center": {"text": "50%"}}, read as a drawing of arcs under its text |
| a helper function for a chip or a card | a part in the kit: {"chip": "Evening"} |
| delete, then build again | build --sync (layers keep their ids), --replace for a component set |
reading tree text with a pattern | tree --json, find --json (result.nodes[].id) |
| looking at the picture to check a rule | "expect": {"fits": true}, {"lines": 1}, {"noOverlap": true} |
A loop in the script's own language is as good as each; give each repeated row a key (an id from the data), so --sync matches a row to its layer when rows are added, removed or reordered. The current language writes the kind as a key ({"row": [...]}); the older {"type": "row", "children": [...]} still builds, and source prints any layer in the current form.
In React
facet --doc f.facet react render screen.tsx --props data.json [--watch] builds a design written in React, in place. The pieces come from @facet/react and take the language's keys as props: <Row gap={8}>, <Column>, <Grid columns={2}>, <Text style="title">, <Span>, <Icon name="lucide:bell">, <Box>, <Draw> with <Circle at={[20, 20, 18]}>, <Connect from="A" to="B">, <Kit colors={{…}}>. component("Switch", { variants: { State: ["Off", "On"] }, props: { Label: "Wi-Fi" } }, render) is one master with instances. React's key is the layer's key; warnings end with the source line; facet react source LAYER prints a layer back as JSX. Types come from the grammar, so wrong keys fail to compile. See React.
Changing what is there
| Change | Do |
|---|---|
| a value or two | modify NODE '{...}'; $nodes reaches named descendants: {"$nodes": {"Title": {"text": "Tue"}}} |
| a tree | edit the JSON you built it from, then build --sync: matched layers keep ids and instances; gap, padding, fill, stroke, cornerRadius, opacity, effects, rotation and a text's width and maxLines the JSON no longer writes go back to their defaults; the reply counts what changed. The JSON is the source: a value or a name changed since with modify or rename goes back to what the JSON says, so make that change in the JSON too. A sync leaves the page's other top-level layers alone (a page can hold several sources' layers); --sync --prune deletes those this call does not write (a source that now writes fewer frames), except main components, sets and the Icons frame |
| a component set | build @set.json --sync: variants still written keep their ids, so instances on every page follow and keep what they set (--replace rebuilds it: every layer in what it rebuilds gets a new id, so read ids again after it) |
| add one layer | build @row.json --parent ID (or the parent's name) appends it last (--index 0 or --first puts it first, --before "Compose" before that child); it takes the font and color most of the parent's texts share, and the kit's when they differ. A later --sync of the parent's JSON removes it unless it is added there too |
Running the same build again does not change a design: a top-level name that is already there is refused (nothing is built), and the reply names the three ways on: --sync to change it in place, --replace to swap it, --again for a second copy on purpose.
Name the layers you will change, or give repeated ones a key (inside each: "key": "{id}", filled per item): sync matches by key or name, and same-named siblings in order. source prints a layer in the language with parts expanded; for a screen built from parts, keep editing your own JSON. It names the kit's colours, presets and parts: facet kit prints the kit, and a new file needs it first ({"kit": …, "nodes": [the source]}). A picture is printed as "$image": "hash:…", the image this document holds: it builds in this document, and another file needs the picture given again (a path, a URL or photo:).
Checks
Every write verifies itself and reports, by layer, what did not happen: NOT_APPLIED, INPUT_IGNORED (a key not read, with the nearest one, or the way to say what it meant: arrow answers with connect), LAYOUT_OVERFLOW, LAYOUT_OCCLUDED, FRAMES_OVERLAP, TEXT_TRUNCATED, TEXT_OVERFLOW, TEXT_UNREADABLE (words the colour of what is behind them), FONT_SUBSTITUTED, TOKEN_FALLBACK. Fix each one; the app shows them as badges. A build that read every key says so ("every key read"; keysIgnored in JSON). Overflow of 2 px or less is a LAYOUT_TIGHT note. Boxes in a row (fill, stroke or shadow) that come out different heights get a ROW_UNEVEN note. A maxLines text cut short by its ellipsis gets a TEXT_ELLIPSIS note, and a character its font lacks a GLYPH_FALLBACK note naming the font that draws it (a GLYPH_MISSING warning when no font here has it, so it shows as a box). State what must hold instead of looking: "expect": {"lines": 1}, {"fits": true}, {"noOverlap": true}, {"width": {"max": 320}}; a miss is EXPECT_FAILED.
Look at the --preview PNG when the result matters visually. It renders the top-level layers the call built or synced, whole, not the page.
Every command works on the page showing, and ids in later commands are those of the page showing: pass --page NAME or show the page first. To work on another page without moving the person's view, give it the page: facet --doc f.facet --page "Flows" build @screen.json (any tool takes "page": a name or id), and add pages with facet call pages '{"add": "Flows", "show": false}' ("rename", "move" and "delete" change them, by name or id). Components on one page (a "Components" page) are used by name from every other page. facet call move '{"nodeIds": ["Card"], "toPage": "Flows"}' moves layers to another page, keeping their ids and component links.
Traps
- Frames have no fill until you give one;
"fill": "none"removes one (nullis not a value). "fill"width needs a row, column or grid parent; a top-level layer gets a number. A row that hugs its width leaves a child that fills it no room, so such a row fills its parent's width (give the row a width to choose another).- A text in a stack or with
atkeeps its own width; give it awidthto wrap. - Overlapping top-level frames hide each other: put component sets to the side (
"x": 1400). For slides or a flow,"after": "previous"(or a frame's name) places each frame right of the one before. - A board placed by hand (a stack of layers each with
at: [x, y]) breaks when a text wraps or a label changes. Build it from rows and columns, join boxes withconnect, and keepatfor the few layers that overlap on purpose. - Cards in a row hug their own heights:
"align": "stretch"on the row makes them one height. "♈︎"draws a symbol as text; without U+FE0E some symbols draw as color emoji.- A call nests at most 32,768 levels of JSON, about 16,000 frames inside each other; a document nests as deep as you build it.