FacetDocs

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.

card-start.json≈ 398 tokens
{
  "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"}
      ]
    }
  ]
}
What card-start.json builds

A kit and a card in one call. Every later call names @ink, title and chip without sending them again.

Built by the docs build with the real CLI.

  • Strings are texts. Containers pass font, style and color down to every text inside.
  • Kit colors are variables (the collection is named Kit; a kit has no name); rename one with facet variables rename brand accent and give one a value with facet 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 in title; 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}"}} inside member. A children parameter 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"}} brings chip, pill, badge, dot, button, button-quiet, toggle, toggle-off, segmented (of segment, segment-on), card, stat, legend, spark, bars, stack-bar, meter, code, steps (of step), window and phone, painted in your kit's accent, ink, line… Write them before you draw one by hand; facet guide basics lists 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, row or any other key. A preset and a part cannot share a name. {"kit": {"parts": {"chip": null}}} removes one.
  • Font shorthand: "Family Size/Line Weight" plus italic, tracking +0.4 or -2%, a case caps. Weights are 100 to 900 in hundreds, or light, medium, semibold, bold and 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

WriteFor
{"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": 260on 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": 1take 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.

WriteFor
"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+2060break only at soft hyphens you place; a word joiner keeps letters together
"columns": 2, "gap": 20lines 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 shapethe 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": 1one 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 spanssuperscripts, subscripts ("sub"), footnote marks; px for your own shift
{"text": "the guide", "link": "https://…"} in spansa 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 spansa 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

card-set.json≈ 283 tokens
{
  "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"
        }
      ]
    }
  ]
}
What card-set.json builds

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.

Built by the docs build with the real CLI · built after card-start.json.

  • "{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.
  • only keeps 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 plan checks 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 ofWrite
an x and y for each layera 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 framea column of the label and the frame; after follows it by the frame's name
round(size * 1.35) for a line heighta 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 lengthlet 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 scriptkit 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 heightfacet probe @block.json: sizes and each text's lines, nothing kept
pixel widths for the parts of a stacked bargrow 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 carda part in the kit: {"chip": "Evening"}
delete, then build againbuild --sync (layers keep their ids), --replace for a component set
reading tree text with a patterntree --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

ChangeDo
a value or twomodify NODE '{...}'; $nodes reaches named descendants: {"$nodes": {"Title": {"text": "Tue"}}}
a treeedit 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 setbuild @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 layerbuild @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 (null is 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 at keeps its own width; give it a width to 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 with connect, and keep at for 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.

Documentation for Facet 0.3.228-g032727de