FacetDocs

The command line

Facet includes a command, facet, that does everything an assistant does: build, change, check, render and export designs, with or without the app open. You only need it to use Facet from Terminal or scripts; assistants connected through Connect your AI do not.

Install it

Choose Facet › Install Command Line Tool…. Facet adds facet to the folder Terminal looks in:

  • If you use Homebrew, Facet links it into Homebrew's folder, with no password.
  • Otherwise Facet asks for your Mac password once, to create /usr/local/bin/facet, the standard place for commands every app can use.
  • Without a password, facet setup cli --user puts it in ~/.local/bin instead and adds that folder to Terminal's search path (a line in ~/.zprofile).

Open a new Terminal window and check:

facet --help

The command lives inside the app (/Applications/Facet.app/Contents/Helpers/facet), so it updates with Facet and is always the same version as the app. If you installed Facet with Homebrew, facet is already installed.

See what is set up

facet setup

lists each assistant Facet found and whether it is connected, whether the skill is installed, and where facet is. The same command connects and disconnects them:

facet setup connect claude-code     # or claude-desktop, codex, cursor, vscode, skills, all
facet setup disconnect all
facet setup repair                  # after moving Facet
facet setup connect codex --replace # replace an entry of your own (Disconnect puts it back)
facet setup cli                     # the same as Install Command Line Tool…

Add --json to any of them for output a script can read.

Markdown as a PDF

facet pdf writes a Markdown file as a PDF, with no app open and no document:

facet pdf notes.md -o notes.pdf
facet pdf report.md -o report.pdf --style report.mdstyle.json --stats

Input paths beginning with - must use an explicit ./ prefix, such as facet pdf ./-sample.md -o out.pdf or facet export ./-sample.facet --pdf out.pdf. Only facet pdf - reads standard input; export has no stdin input. Mistaken option names are rejected before opening a file.

Without --style, the pages use a plain built-in style that draws headings, paragraphs, lists, bold and italic, code, rules, GitHub tables and front matter's title, subtitle, author and date as a title block (with a front-matter title, the body's first # stays a section unless it repeats the title; without one, a leading # is the title); give a style for footnotes, alerts, definition lists, math and contents. A style file (.mdstyle.json) gives the fonts and colors, a template for each kind of block, and the page frames. Facet lays every block out at the column width and then fills the pages:

  • A paragraph breaks between lines and keeps at least two on each page.
  • A table repeats its header on the next page.
  • A heading stays with what follows it.

On dark pages, body text with no explicit color inherits the style's light ink; explicit colors are retained. Missing masthead fields and their separators are omitted; supplied values remain.

Table columns are sized to their content. Display math is written as text. With a style, add --direct for long documents (it needs --style): the pages are laid out and drawn without building a design, many times faster and in little memory. PDF has no blur, so each blur or soft shadow becomes one small image, made once and reused wherever the same blur recurs. Add --watch (with --direct and -o) to keep it running: each time you save the Markdown, the PDF is written again, drawing only the pages your edit moved. --stats prints how long each stage took and how many pages a second that makes. The --direct engine needs nothing from macOS: built as WebAssembly it writes the same PDF, byte for byte, given the same fonts. facet pdf --help lists every option.

In a browser

The same engine runs in a web page or in Node, with no server: crates/facet-pdf-web builds it as a WebAssembly module for JavaScript. Build it with cargo build --release --target wasm32-unknown-unknown -p facet-pdf-web, then wasm-bindgen --target web (or --target nodejs) of the .wasm, with wasm-bindgen-cli 0.2.129. It exports two functions:

import init, { pdf, version } from "./pkg/facet_pdf_web.js";
await init();
const bytes = pdf(markdown, styleJson, fonts, "report"); // a Uint8Array
  • markdown is the document's text and styleJson a style file's text.
  • fonts is an array of {family, bytes}, bytes a font file's contents as a Uint8Array. The page has these fonts and no others: a family the style names that is not given is missing.
  • A font given a family is that family. Give a family's files in name order, as Facet's font cache lists them.
  • A font given the family "" stands in for the computer's fonts: it draws characters no family in the style has. These are tried in the order given and the first that has a character draws it, so to match a PDF made on a Mac, give them in the order the Mac lists its fonts.
  • The last argument, optional, is the document's name, as facet pdf takes it from the file name (report for report.md). A page frame or title can show it; without it the name is page.

Given the same fonts it writes the same PDF as facet pdf --direct, byte for byte. It runs on one thread and takes about four times as long: 80 pages in about 0.43 s against 0.1 s. crates/facet-pdf-web/www/index.html is a small page that writes the sample report and downloads it.

Use it

Start with Your first design and The loop. Every command is on the Commands page; facet guide prints the same reference, and facet COMMAND --help explains one.

A design written in React

facet --doc design.facet react render screen.tsx --props data.json renders a React file with your project's own React and builds it in place; --watch does it again on every save. See React.

A schema and types for the build language

The keys of the build language are generated from the grammar Facet itself reads, in two forms an editor or a typed generator can use:

  • facet guide schema prints a JSON Schema (docs/schema/build.schema.json in the repository). Point a .json file at it with "$schema", or map it in your editor, and keys complete with their meaning and the simple ones are checked ("wrap": "yes" is flagged).
  • facet guide types prints TypeScript types (FacetNode, FacetKit, FacetBuild, FacetKey). A typed generator builds against them, so a key that Facet renames fails that build instead of changing designs quietly.

A node also takes the names your kit gives presets and parts as keys, so a key the schema does not know is allowed; the build's own INPUT_IGNORED warning is what catches a misspelt one. Forms too rich to type (a font shorthand, at) are described, not checked.

Handing a design to code

These commands write what an app's code needs from a design, so nothing is copied by hand.

  • Colours and variables: facet --doc f.facet tokens export --format css|ts|json|dtcg [-o FILE]. json is a plain tree of {$type, $value} with a value per mode; dtcg is the W3C Design Tokens form, the one other tools read. facet tokens FILE.facet -o tokens.json writes that same dtcg form from a saved file with no host, and facet tokens import reads one back.
  • A layer as a file: facet --doc f.facet export --node Home --format png --size 2x --out . --wait writes Home@2x.png; --format svg writes an icon as SVG. The same written as export --frame Home --png --scale 2 is read as it, with a note.
  • Layout metrics: add --node FRAME --include metrics to tokens export and the export gains a metrics group: each layer's width and height, gap and padding, radius, border width, shadow offsets, blur and colour, and each text's size, line height in px, weight and family. Tokens are named by layer and property (popover-padding-top, title-line-height); layers that share a name take their parent's (row-label), then a number. A layer with no name of its own is named by what it is under its parent (card-row, then card-row-2), never by its id, so the names hold when the design is built again; name the layers whose numbers the app reads. A script reads them to write an app's metrics file the way it writes its colours, so a changed gap in the design changes the app.
  • An icon set: facet --doc f.facet assets export --set Icons --out icons/ writes one SVG for each layer directly inside the Icons frame, named after it (monitor.svg, moon.svg). --format png --size 15 --scale 3 writes 45 px images on a clear ground for 15 pt icons at @3x, whatever size the components are drawn at; there is no scale to work out. An icon in one colour is written in currentColor, so it takes the colour of the text around it where it is used; --color drawn keeps the colours in the design.
  • Does the app match? facet --doc f.facet compare "Popover" build/popover@2x.png --fail-over 1 -o diff.png renders the frame as shot does, at the picture's scale, and sets it against the app's own screenshot of that state. It prints the share of pixels that differ, the mean difference and where the largest differing patch is in the frame, writes a picture with the differences in magenta, and with --fail-over exits with a failure when more than that percentage differ, so a test stops an implementation drifting from its design. --tolerance (8 of 255 by default) allows for antialiasing. When the two differ, the frame is drawn as export draws it and counted against that, so a frame and its own PNG export are 0% apart.
  • A layer as SwiftUI: facet --doc f.facet swiftui "Popover" -o Popover.swift writes a view (struct Popover: View; --name names it; without -o the code is printed). A row is an HStack and a column a VStack with the gap as spacing and the alignment across; "space": "fill" is a Spacer; padding, fixed sizes and fill (maxWidth: .infinity) are frames; a frame with no auto layout is a ZStack with each child at its offset. Fills, strokes, corner radii, clipping, shadows, opacity and rotation are modifiers, and a text carries its font, size, weight, tracking, case and colour. Icons, vectors and pictures are written as Image("name") and listed, to export with assets export. What SwiftUI cannot say the same way (a wrapping row, a radial fill, a shadow's spread) is listed as notes, not dropped in silence. Checked against SwiftUI itself: a card with a gradient, a stroke, a shadow, a chip, a wrapped text, a badge and a turned shape, generated and drawn by SwiftUI at 2x, comes out the size the design has and within 2% of its pixels (the edges of letters).

How the look maps, to SwiftUI and to CSS:

| Facet | SwiftUI | CSS | |---|---|---| | "effects": [{"type": "drop-shadow", "x": 0, "y": 4, "blur": 12, "color": C}] | .shadow(color: C, radius: 5.09, x: 0, y: 4): SwiftUI's radius is the Gaussian's standard deviation, and Facet draws a blur of b with a deviation of 0.4207 b + 0.039 | for the same picture, box-shadow: 0 4px 10.2px C (filter: drop-shadow(...) on a text or a shape): CSS blurs with a deviation of half its blur, so the blur to write is twice Facet's deviation, 0.84 b + 0.08. The blur copied as it is (12px) draws about a fifth wider in a browser. The handoff writes the CSS number for you: spec's shadows and its CSS are in CSS's blur, and tokens export --include metrics gives shadow-blur-css beside the design's own shadow-blur. Coming the other way, a shadow written with "cssBlur": 12 is drawn as a browser draws 12px (the React route writes shadows this way) | | "fill": {"linear": [A, B], "angle": 90} (90 runs top to bottom, 0 left to right) | LinearGradient(stops:, startPoint: UnitPoint(x: 0.5, y: 0), endPoint: UnitPoint(x: 0.5, y: 1)): the gradient's two handles, as unit points of the box | linear-gradient(180deg, A, B): CSS counts from the top, clockwise, so its angle is Facet's plus 90 | | "stroke": C, "strokeWidth": 1 (inside the box) | .overlay(shape.strokeBorder(C, lineWidth: 1)) | border: 1px solid C with box-sizing: border-box | | "cornerRadius": 16, [tl, tr, br, bl] | RoundedRectangle(cornerRadius: 16), UnevenRoundedRectangle(...) | border-radius: 16px, four values in the same order | | "rotation": 10 (counterclockwise, about the top-left corner) | .rotationEffect(.degrees(-10), anchor: .topLeading) | transform: rotate(-10deg); transform-origin: top left | | "matrix": [a, b, c, d, 0, 0] (or "skew": about the top-left corner) | .transformEffect(CGAffineTransform(a: a, b: b, c: c, d: d, tx: 0, ty: 0)) | transform: matrix(a, b, c, d, 0, 0); transform-origin: top left | | a text's line height 28 at size 22 | .frame(height: 28) on a one-line text, so it and what follows sit exactly; .lineSpacing(1.6) between the lines of a wrapped one (the line height less 1.2 of the size: close, not exact) | line-height: 28px | | a shadow on a frame that holds layers | .compositingGroup() before .shadow(...): SwiftUI otherwise shadows each view inside on its own | box-shadow on the element | | tracking +0.4 | .tracking(0.4) | letter-spacing: 0.4px |

  • Everything else in a subtree: facet assets export [NODE] --out DIR (images, vectors, fonts, a manifest), spec NODE and measure NODE.

Input recording diagnostics

New trackpad recordings preserve independent contact and momentum phases, including cancellation and combined phase flags. Older recordings leave these details unknown. This adds diagnostic fidelity; camera motion is unchanged.

The version-1 JSON-lines format adds optional native_phases, for example:

"native_phases":{"contact":{"state":"known","bits":0,"unknown_bits":0},"momentum":{"state":"known","bits":4,"unknown_bits":0}}

This means known contact None and momentum Ended. Semantic flags are Began=1, Changed=2, Ended=4, Cancelled=8, MayBegin=16 and Stationary=32; combinations retain every flag. unknown_bits preserves opaque source bits, without interpreting them. {"state":"unknown"} means unavailable; known bits=0 means known-empty. An absent field preserves legacy bytes and means unavailable. Explicit unknown axes retain their supplied provenance. New readers accept old records; old binaries that reject unknown fields are not promised to read extended records. Legacy phase continues to determine motion behavior, including cancellation projected to ended; native metadata independently retains cancellation. A combined scroll+pinch step supplies its metadata to both handlers; one native event ordinarily has one motion kind.

Separately, replay currently sorts by source at_ms: source inversions are reordered. This change does not repair file delivery order or establish native queue timing. Old recordings cannot reconstruct discarded phase distinctions. The original native hitch cause remains unknown; no continuation policy is implemented.

Documentation for Facet 0.3.228-g032727de