FacetDocs

Checks

Every write checks what it asked for and reports what it could not do. Each warning names the layer and the top-level frame it is in ("Photo" in "Artist · Night"), what it asked, what it got and the fix; a mistake in the input itself, before any layer exists, names its place in the input instead. The build's summary counts what was not applied in each frame it built. The app shows the same warnings as badges on the canvas. A key a layer or a span does not read is INPUT_IGNORED, naming the nearest key ("weight" in a span: fontWeight), and a build that adds a top-level layer under a name another one has is NAME_TAKEN (use --sync to change the one there, or --replace), since later calls naming it would match both.

**From a generator: $source.** A script that writes the JSON can say where each node came from: {"name": "Card", "$source": "make.py:118", ...} (a React adapter writes Card.tsx:42). Facet keeps it with the document and never reads it. inspect shows it as source, and every warning or note about that layer, or about a layer inside it that has none of its own, ends with it: … (source: make.py:118). Fixing a warning then starts at the line that wrote the layer, not at a search for its name. facet where NODE walks the other way, through components: the components a layer is in, innermost first, each with the file that defines it and, for an instance, where it is used, and the layer as the innermost component's own layer, with that layer's source. In Python, inspect.stack()[1] gives the caller's file and line for a helper to fill in.

  • Verification. Sizes and text a node asked for are compared with what was built (NOT_APPLIED).
  • Layout audit. Content a fixed frame clips (LAYOUT_OVERFLOW), content its layout puts before its top or left edge (a column set to its end holding more than it has room for), which is clipped however its ancestors clip (CLIPPED_BY_PARENT), including content spilling out of a child that fills it, auto layout content that shows past a frame that neither hugs nor clips it (over the layer beside it), content an edge-pinned layer covers (LAYOUT_OCCLUDED, also for a placed text that overlaps another text), and top-level frames left overlapping on the page (FRAMES_OVERLAP, with a clear position below or beside). "overflow": "hidden" marks clipping as intended, and the document keeps it. A kit part that clips by its own definition (a phone's screen) says what it cut in a PART_CLIPPED note, since the clip is the part's and not the author's. Overflow of 2 px or less (scaled type, a turned corner) is a LAYOUT_TIGHT note instead, with the amount, so the overflows that show stand out. Boxes in a row (frames with their own fill, stroke or shadow, hugging their content) that come out different heights while the row aligns them at the top get a ROW_UNEVEN note: "align": "stretch" makes them one height, and an explicit center or end keeps the row quiet.
  • Text. A text box its content outgrows (TEXT_TRUNCATED), a story whose last frame holds only a line or two of it (RUNT_FRAME), a heading left as a frame's last line with its text in the next (HEAD_AT_FOOT; "paragraph": "heading" keeps it with what follows), a story's lines leaving its baseline grid so facing frames stop lining up (GRID_DRIFT), running text with straight quotes or apostrophes where typographic ones belong (STRAIGHT_QUOTES; "quotes": "smart" on a text sets them as it builds), a line that breaks between a number and its unit (SPLIT_UNIT; a no-break space keeps them together), more than two hyphenated line ends in a row (HYPHEN_LADDER), and, as a note, justified lines stretched past twice a normal word space (LOOSE_LINE), a one-line text running past the width its frame gives it (TEXT_OVERFLOW; not inside a frame that clips on purpose with "overflow": "hidden"), a font that had to be substituted (FONT_SUBSTITUTED), a fontFeatures tag the font does not have (FONT_FEATURE_MISSING).
  • Images. An image file whose data is damaged or cut short past its header (IMAGE_UNREADABLE, on the build that places it and in the audit): placing reads the header alone, so the layer draws what of it decodes, or nothing.

The Result codes page lists every code.

A design system's rules are a separate check: facet --doc f.facet call lint lists every layer that breaks the DESIGN.md beside the file. With no DESIGN.md it checks nothing, and says exists: false.

Saying what must hold: expect

expect on any node states what must be true after layout. A miss is an EXPECT_FAILED warning, so a build can be trusted without a screenshot. It is checked each time the JSON that holds it is built or synced, and on a modify that writes one (modify Title '{"text": "…", "expect": {"lines": 1}}'); it lives in your JSON, not on the layer, so keep it there. The warning names the layer's id, which tells same-named layers apart. A miss is a warning and the command still succeeds; add --strict (facet build @screen.json --sync --strict) and it exits 3 instead, so a script or a build step stops on it.

checks-expect.json≈ 85 tokens
{
  "name": "Headline",
  "width": 240,
  "padding": 16,
  "fill": "#FFFFFF",
  "column": [
    {
      "text": "Checkout errors rose on Saturday after the release",
      "font": "Inter 18/24 700",
      "width": "fill",
      "expect": {"lines": 1}
    }
  ]
}
What checks-expect.json builds

The headline is meant to fit on one line in a 240 px card. It takes three, and the build says so.

Built by the docs build with the real CLI.

  • EXPECT_FAILED: "Checkout errors rose on Saturday after t" in "Headline" (layer 2): "Checkout errors rose on Saturday after t" has 3 line(s); expected 1
KeyHolds when
linesa text has exactly this many lines, or within {"min", "max"}
maxLinesa text has at most this many
fitsnothing in the layer is clipped or cut short
width, heightthe layer is this size, or within {"min", "max"}
noOverlapthe children in a container's flow do not overlap

Previews

--preview out.png on any write renders what that call wrote: each top-level layer it built or synced, whole, or the layer it modified, not the page (a component set shows every variant). Layers that reach past the frame built, with nothing clipping them (a connector looping over its row, a badge hung on a corner), are in the picture, and a PREVIEW_WIDER note names them. facet shot NODE -o out.png --scale 2 renders any layer at any time, framing what the canvas shows there (a layer beside or over it included); --isolate renders only the named layers and what they hold, each at its own opacity. Several layers that don't touch (facet shot Cover Page-3 Page-9) come out as a contact sheet: each rendered on its own, side by side in a grid 24 units apart, in the order named; --span renders the whole area they span instead, and layers that touch always render as one area. On an instance, --props '{"Day": "29"}' renders it with those properties without keeping them, and --each @sets.json -o 'tiles/{Month}-{Day}.png' writes a PNG per set of properties in one call ({#} is the set's number), none of them kept: 366 date tiles take seconds, not minutes of modify and shot pairs. Previews draw in layer order, so scrims and sheets cover what is under them, as on the canvas. The PNG is transparent outside the layers; --background '#FFFFFF' fills it.

Documentation for Facet 0.3.228-g032727de