# Facet: everything Every page of the documentation in reading order. Examples are build inputs: `facet --doc FILE build @NAME.json`. ## Contents - Facet: A Mac design app your AI can design in. Install it, connect your assistant in one click, and describe what you want. - Install Facet: Download Facet, drag it to Applications, open it once. Two minutes, no account. - Your first design: Open the sample, ask your AI to finish it, or build a first card yourself from the command line. - Connect your AI: Let Claude, ChatGPT, Cursor or VS Code design in Facet. One click from the app, or a few lines by hand. - The command line: Install the facet command, see what is connected, and use Facet from Terminal and scripts. - The language: What a build call can contain, how names resolve, and what containers pass down. - The loop: Build, look, read back with source, change with sync. The fewest calls and tokens per change. - Stream: A design written one layer per line, built while it is still being written, and changed with lines of the same kind. - Kit: Colors, type presets and parts said once, kept with the file and named everywhere after. - Layout: Rows, columns, grids, stacks and rings; sizes; and placing a layer by words, anchors or angles. - Text: Strings as texts, the font shorthand, presets, what containers pass down, and sentences with components in them. - Color: Kit colors, variables, tints, gradients and modes. - Repeat: One node per item of a list, or a count, with the item's fields substituted. - Drawing: Circles, lines, arcs, polygons and paths as data, with fills, gradient strokes and dashes. - React: Write a design in React with Facet's pieces and your own components; facet react builds it in place. - Components: Component sets with variants and properties, layers that belong to some variants, and instances. - Behavior: The states a component moves through, the scenarios that decide them, plays and looks, written beside its variants. - Changing designs: Read a design back with source, change it in place with sync, edit values with modify, replace a set. - Checks: What every write verifies, the warnings it reports, and expect for what must hold. - For agents: How an agent builds the most with the fewest tokens and round trips, and how to recover from mistakes. - Agent card: The language and the loop on one page, for agents: enough for most builds in a few thousand tokens. - Updates and uninstalling: Facet updates itself; uninstall removes the app, its settings and its connections, never your designs. - Troubleshooting: What to do when Facet will not open, an assistant cannot find it, or a command is missing. - Gallery: Complete designs built with the language, each with its source and token cost. - Keys: Every key a node can carry, with its forms and what it does. - Commands: Every command with its arguments, flags and an example. - Result codes: Every warning and error code a reply can carry, and what to do. - Font: The grammar of the font shorthand. - Chart: The compact behavior format, the full chart format it compiles to, and the commands that read them. --- # Design with your AI, in a real design app Facet is a design app for the Mac that your AI assistant can work in. Ask Claude, ChatGPT or Cursor for a screen, a component or a change, and watch it appear on the canvas: real layers with auto layout, text styles, color variables and components, that you can keep editing by hand. Every change is one undo step, with the assistant's name on it.
1. InstallDownload, drag to Applications, open. No account.2. Start a designOpen the sample or a new file.3. Connect your AIOne click for Claude, ChatGPT, Cursor or VS Code.
## What your assistant writes Behind every request, your assistant writes a short description in Facet's build language, and Facet turns it into layers, measures them, checks them and says what did not work. You can write it too. A whole phone screen in one call: a header, a dial drawn from shapes, a sentence with chips in it and tilted stickers. Everything named here (`phone`, `swara`, `deva`, `@saffron`) comes from a kit sent once per file. `raag-today.json` (after raag-kit.json, listed at the end): ```json { "phone": { "name": "Today", "children": [ { "row": [ { "draw": [ {"path": "M20 2v14", "stroke": "@ink", "weight": 2}, { "circle": [20, 30, 14], "fill": {"linear": ["@saffron", "@rose"], "angle": 160} } ], "size": [40, 46], "name": "Mark" }, { "column": [ {"title": "Raag"}, {"deva": "आज का रियाज़", "color": "@mute"} ] }, {"space": "fill"}, {"icon": "lucide:settings-2", "size": 22} ], "gap": 12, "align": "center", "width": "fill" }, { "stack": [ { "draw": [ { "circle": [150, 150, 144], "fill": {"radial": ["#FFFFFF00", "@rose/10%"]}, "stroke": "none" }, { "circle": [150, 150, 120], "stroke": "#1A142333", "dash": [2, 6] }, { "arc": [150, 150, 120, 270, 315], "stroke": {"linear": ["@saffron", "@rose"], "angle": 45}, "weight": 14 } ], "size": 300 }, { "ring": [ { "each": ["रात", "सुबह", "दोपहर", "शाम"], "do": {"deva": "{.}", "color": "@mute"} } ], "r": 86 }, { "column": [ {"deva-xl": "यमन"}, {"small": "Yaman's hour", "color": "@mute"} ], "align": "center" } ], "width": "fill" }, { "type": "paragraph", "width": "fill", "runs": [ "It's evening, so Yaman. Every note is shuddha except ", {"swara": {"note": "तीव्र म", "tone": "@rose"}}, ": sing it a touch sharp, and land on ", {"swara": "नि"}, " and ", {"swara": "ग"}, " more than on ", {"swara": {"note": "सा", "tone": "@mute"}}, "." ] }, { "row": [ {"sticker": {"label": "12 दिन लगातार", "turn": -4}}, { "sticker": { "label": "Tanpura in C♯", "tone": "#E3E7FA", "turn": 3 } }, {"sticker": {"label": "40 min", "tone": "#F9D7DD", "turn": -2}} ], "gap": 10, "align": "center" } ] } } ``` ## Why it is short Every key costs a model tokens and every call costs a round trip, so the language removes structure instead of abbreviating words.
≈ 788tokens for the whole screen above, its kit sent once before
9×fewer tokens to read a design back with source than tree --full
1 callfor a component set with its properties, states and behavior
- **Say it once.** Colors, type and reusable parts live in the file's [kit](kit.md) and are named everywhere after. - **Intent, not arithmetic.** Rows, columns and stacks place things; `at` names a place, an anchor or an angle. See [Layout](layout.md). - **Read what you write.** [`source`](update.md) prints any layer in the language, ready to edit and send back with `--sync`. - **Checked, not hoped for.** Every write verifies what it asked for and reports what it could not do, by layer, with the fix. See [Checks](checks.md). ## Where to go next
Your first designThe sample, your AI, or the command line.The languageNodes, names and the shapes a build takes.ComponentsSets, properties, variants and instances.For agentsThe loop that costs the fewest tokens.
--- # Install Facet Facet is a Mac app. It needs no account and no sign-up, and it keeps your designs as files on your Mac. **You need** a Mac with Apple silicon (M1 or later) and macOS 13 Ventura or later. ## Download and open 1. Download **Facet.dmg** from [faux.design](https://faux.design). 2. Open the downloaded file. A window shows the Facet icon and an Applications folder. 3. Drag **Facet** onto **Applications**. 4. Open **Facet** from your Applications folder, Launchpad or Spotlight (⌘ Space, type "Facet"). 5. macOS asks once whether you want to open an app downloaded from the internet. Click **Open**. Facet is signed and checked by Apple (notarized), so that is the only question macOS asks. > **Tip** If you open Facet straight from the downloaded window instead of Applications, Facet offers to move itself there. Say yes: Facet can only update itself, and AI apps can only find it, from Applications. ## What you see first A welcome screen with three choices: - **Start with a sample** opens a small, half-finished design you can explore, or ask your AI to finish. - **New design** starts an empty file. - **Open…** opens a design you already have. Beside them, **Let your AI design with you** connects Claude, ChatGPT, Cursor or another assistant in one click, and **Not now** closes the welcome. See [Connect your AI](connect.md). You can skip it and come back any time from **Facet › Connect AI Apps…**. **Help › Show Welcome** brings this screen back. ## With Homebrew If you already use Homebrew: ```sh brew install --cask uxfreak/tap/facet ``` This installs the app and the `facet` command together. Updates still arrive inside the app. ## Where your designs live Designs are ordinary files ending in `.facet`. New designs go to **Documents › Facet** unless you choose another folder. Double-click a `.facet` file in Finder to open it, or drop it on the Facet icon. Facet keeps its settings, recent files and design systems in a hidden folder in your home folder, `.facet`. ## What is inside Facet is built from open-source Rust crates and bundles open fonts and icons; their licenses are listed in `Facet.app/Contents/Resources/THIRD-PARTY.md`, with the font licenses in `Resources/Licenses` (right-click the app › **Show Package Contents**). ## Next - [Your first design](start.md) - [Connect your AI](connect.md) --- # Your first design The quickest start is the sample: a small screen left half-finished on purpose, so there is something to explore and something to ask for. ## With your AI 1. On the welcome screen, choose **Start with a sample**. Facet saves it as **Documents › Facet › Welcome.facet** and opens it. 2. If you have not yet, connect your assistant: **Facet › Connect AI Apps…** ([Connect your AI](connect.md)). 3. In Claude, ChatGPT or Cursor, ask for something on the open design, for example: > Use Facet to add a pricing card to my open Welcome design. Your assistant edits the file you have open. Its changes appear on the canvas as it works, with its name beside them, and every change it makes is one step you can undo with ⌘Z. > **Tip** Ask for what you want to see, not how to build it: "a settings screen for a meditation app, calm and dark" works better than a list of boxes. Ask for a change the same way: "make the header quieter", "add a second plan". ## By hand Everything an assistant does, you can do on the canvas: select, move, resize, edit text, change colors in the inspector on the right. **View › Command Palette** lists every action with its shortcut. ## From the command line The `facet` command builds designs from a short JSON description, the same way assistants do. Install it once with **Facet › Install Command Line Tool…** ([The command line](command-line.md)). A card is a `column` with two texts. The container's `font` reaches every text inside it, so the texts are plain strings. `hello.json`: ```json { "name": "Hello", "column": [ "Evening practice", {"text": "Twelve days in a row", "color": "#6F6879"} ], "font": "Inter 15/22", "padding": 20, "gap": 4, "fill": "#FFFFFF", "cornerRadius": 14, "width": 260 } ``` ```sh facet --doc practice.facet build @hello.json --preview hello.png ``` Every command takes `--doc FILE`. If Facet has the file open, the command edits it there and you see the change live; otherwise a helper in the background opens the file, saves after every change and stops when you run `facet --doc practice.facet close`. A command that changes the file creates it; one that only reads it, like `tree`, says at once when the file does not exist. `--preview` writes a picture of what was built. The reply lists every layer by name, and any warning names the layer and the fix. Three commands read what is there: `tree` lists layers with their sizes, `inspect NODE` shows one layer, and `shot NODE -o card.png --scale 2` renders it. ```sh facet open practice.facet ``` opens the file in the app as a tab. ## Next - [Connect your AI](connect.md) - [The loop](loop.md): build, look, read back, change in place. - [The language](language.md): what a build can contain. --- # Connect your AI Facet gives your assistant two things: the **Facet tools** (to open designs and build, change, check and render them) and the **Facet skill** (how to use them well, in a few thousand words). Once connected, you ask in plain words and watch the design change. ## One click 1. In Facet, choose **Facet › Connect AI Apps…** (or **Let your AI design with you** on the welcome screen). 2. Facet lists the assistants it finds on your Mac. Click **Connect** beside each one you use, or **Connect all**. 3. Do what Facet says to finish (the table below): usually, quit the app with ⌘Q and open it again. 4. Click **Try it** to open the app with a first request ready to send. If an app already has a `facet` entry of its own, Facet leaves it alone and offers **Replace…**, which keeps your entry to put back on **Disconnect**. Facet changes only its own entry in each app's settings, keeps a copy of each file it changes beside it (named like `claude_desktop_config.json.facet-backup-20261026-101500`), and remembers what it added: **Disconnect** removes exactly that. If you move Facet or an app stops finding it, click **Repair**. | App | What Connect does | To finish | |---|---|---| | Claude (desktop app) | adds the Facet tools to Claude's settings, and the skill | quit Claude (⌘Q) and open it again | | Claude Code | runs `claude mcp add` for you, and links the skill | start a new Claude Code session | | ChatGPT and Codex | adds the Facet tools to Codex's settings, and links the skill | quit the app and open it again | | Cursor | adds the Facet tools to Cursor's settings | Cursor turns them on in a moment (Settings › MCP) | | VS Code | opens VS Code's own install prompt | click **Install** there | | Another app | **Copy setup** copies the settings to paste into it | | ## Check it works Open a design in Facet, then ask your assistant: > Use Facet to list my open designs. It should name the file. If it says it has no Facet tools, see [Troubleshooting](troubleshoot.md). ## By hand The Facet tools are a local MCP server: the program inside Facet, started with the argument `mcp`. Every app below uses the same two values: - **command**: `/Applications/Facet.app/Contents/Helpers/facet` - **arguments**: `mcp` The tools act on the design that is in front in Facet (they open Facet if it is not running), and can list, open and create designs. ### Claude (desktop app) Open **Claude › Settings › Developer › Edit Config**, which opens `claude_desktop_config.json`, and add Facet under `mcpServers`: ```json {"mcpServers": {"facet": {"command": "/Applications/Facet.app/Contents/Helpers/facet", "args": ["mcp"]}}} ``` Keep any servers already there. Quit Claude (⌘Q) and open it again. To give Claude's chat the Facet skill as well, download **facet-skill.zip** from the release. In Claude, make sure code execution is on (**Settings › Capabilities**), then open **Customize › Skills**, click **+** and choose **Upload a skill**. ### Claude Code ```sh claude mcp add --scope user facet -- /Applications/Facet.app/Contents/Helpers/facet mcp ``` For the skill, link Facet's copy into Claude's skills folder (Facet's own **Connect** does this): ```sh mkdir -p ~/.claude/skills && ln -sfn /Applications/Facet.app/Contents/Resources/skill ~/.claude/skills/facet ``` ### ChatGPT and Codex Add to `~/.codex/config.toml`: ```toml [mcp_servers.facet] command = "/Applications/Facet.app/Contents/Helpers/facet" args = ["mcp"] ``` and the skill: ```sh mkdir -p ~/.agents/skills && ln -sfn /Applications/Facet.app/Contents/Resources/skill ~/.agents/skills/facet ``` Restart the ChatGPT app or Codex. ### Cursor In Cursor's settings, under MCP, add a new global server with the same command and arguments, or add to `~/.cursor/mcp.json`: ```json {"mcpServers": {"facet": {"command": "/Applications/Facet.app/Contents/Helpers/facet", "args": ["mcp"]}}} ``` Cursor reads the skill from `~/.claude/skills` or `~/.agents/skills`. ### VS Code Run **MCP: Add Server** from the command palette, choose **Command (stdio)**, and enter the command and arguments above. VS Code reads the skill from `~/.claude/skills` or `~/.agents/skills`. ## What your assistant can do Everything on the [For agents](agents.md) page and in the [agent card](card.md): build whole screens and component sets from a short description, change designs in place, check layout and text, render pictures, export assets and design tokens. Every change is one undo step in Facet, shown with the assistant's name. --- # 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](connect.md) 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: ```sh 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 ```sh 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: ```sh 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: ```sh 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: ```js 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](start.md) and [The loop](loop.md). Every command is on the [Commands](commands.md) 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](react.md). ## 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](https://github.com/uxfreak/facet/blob/main/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: ```json "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. --- # The language A build takes one of three shapes: | You send | Meaning | |---|---| | a node | build it | | a list of nodes | build each, as separate top-level layers | | `{"kit": {...}, "nodes": [...]}` | keep the kit with the file, then build the nodes (either part may be left out) | ## Nodes A node is an object, or a string, which is a text. Containers are written with the container as the key: ```json {"column": ["Title", {"row": ["Left", {"space": "fill"}, "Right"], "width": "fill"}], "padding": 16, "gap": 8} ``` | Container | What it does | |---|---| | `row`, `column` | auto layout along one axis | | `grid` | rows of `columns` | | `stack` | children overlap; each is placed with [`at`](layout.md) and centered by default | | `ring` | children spread around a circle of radius `r` | Any other node uses `type` (`text`, `rectangle`, `ellipse`, `vector`, `frame`), or one of the shorthands: `text`, `icon`, `draw`, `space`, `set`. ## Names A key that is not part of the language is a name, looked up in this order: 1. a **type preset** of the kit: `{"title": "Today"}` is a text in the preset `title`; 2. a **part** of the kit: `{"chip": "May 2027"}` builds the part with that argument; 3. a **component** in the file: `{"Button": {"Kind": "Primary", "Label": "Pay"}}` is an instance. A node uses at most one name. A name that matches nothing is reported with the nearest key, preset, part or component. Keys of the language come first, so a preset or part cannot be called `name`, `text`, `row`, `fill` or any other key on the [Keys](keys.md) page; the kit refuses such a name. A name is either a preset or a part, never both. A component set built earlier in the same call is already a name: one call can hold a set and the screen that uses it. ## Passing things down A container's `font`, `style` and `color` reach every text inside it that does not set its own. That is why most texts can be plain strings. A build into an existing layer (`--parent ID`) starts from what the texts already inside that layer share: their most common font and color. A row added to a card in Georgia comes out in Georgia without saying so. ## Names of layers Name every layer you will address later (`"name": "Price"`). A text nobody named is named after its content (its first 40 characters), and keeps following it when the text changes; instances nobody named are named after their variant (`State=Locked`). A name is one line: line breaks in it become spaces, with a note. The reply to every build lists the ids of the layers by name; a name several layers share (a component set's layers, one per variant, or repeated parts) lists their ids joined by `|`, in tree order. ## Long forms Every short form has a long form, and both work in one call: `{"row": [...]}` is `{"type": "row", "children": [...]}`, and `@ink` is `"@Kit/ink"`, and `{"set": "Plan", "variants": {...}}` is `{"type": "component-set", "name": "Plan", "variantMatrix": {...}}`. The long forms reach a few things the short ones do not name, such as `$nodes` overrides. The [Keys](keys.md) page lists every key. > **Why** One builder and one set of checks read every form, so nothing behaves differently depending on how it was written. --- # The loop Most work is four steps, and each is one call. 1. **Build** what you mean: `facet --doc f.facet build @screen.json --preview s.png`. 2. **Look** at the preview and read every warning. Warnings name the layer and the fix. 3. **Read back** what is there, in the language: `facet --doc f.facet source Screen`. 4. **Change** it in place: edit the JSON, then `build @screen.json --sync`. Layers keep their ids, instances stay linked, and the change is one undo step. **A generator on a loop.** When a script writes the JSON, `facet --doc f.facet build --watch --run 'python3 make.py'` runs it, syncs what it prints, and does both again each time a file changes: save the script and the design follows in the app, in well under a second. `--files 'recipes/*.py,kit.json'` names what to watch (`*` within a name, `**` across folders); without it, the files under the current folder, leaving out designs, pictures, hidden folders and build output. A script that writes a file instead of printing names it: `build --watch --run 'python3 make.py' @out.json`. A run that fails, or a build that is refused, is printed and the watch goes on; Ctrl-C stops it. It works for any language that can print JSON. From another shell (or when the watch runs in the background), `facet --doc f.facet build --watch --stop` ends it. ```sh $ facet source Hello {"font":"Inter 15/22","column":["Evening practice",{"text":"Twelve days in a row","color":"#6F6879"}],"gap":4,"padding":20,"fill":"#FFFFFF","name":"Hello","width":260,"at":[0,0],"cornerRadius":14} ``` `source` prints the shortest form that builds the layer again. Containers come back as `{"row": [...]}`, plain texts as strings, kit colors and text styles by name. It costs about a ninth of the tokens `tree --full` does, so reading before a change is cheap. When a layer looks wrong, `tree NODE` shows each layer's size and place, `inspect NODE` every property of one, and `shot NODE -o x.png --scale 2` a close look. > **Tip** Send the kit once per file. Later builds name its colors, presets and parts without sending them again; `facet kit` prints what the file holds. ## Small changes For one or two values, `modify` is shorter than a sync: ```sh facet --doc f.facet modify Hello '{"fill": "@paper", "font": "Inter 16/24"}' facet --doc f.facet modify Hello '{"$nodes": {"Evening practice": {"text": "Morning practice"}}}' ``` ## Undo Each call is one undo step, whatever it changed: `facet --doc f.facet undo`. --- # Stream A build is one JSON node, so nothing shows until all of it is written. The same design can be written as lines, one layer each. Every line that has arrived is a design that builds, so it appears as it is written: ```sh my-agent | facet --doc f.facet build --stream # lines on stdin facet --doc f.facet build --stream @card.sxl # or from a file facet build --stream @card.sxl --print # the JSON the lines stand for; no document ``` ## A line `kind#Name key=value key=value | text` ``` column#Card width=320 padding=[16,20] gap=12 fill=#FFFFFF cornerRadius=12 font="Inter 14 400" row#Header width=fill gap=8 align=center icon size=16 | lucide:bell text#Title font="Inter 16 700" | Reminders space | fill text#Count color=@muted | 3 text#Body width=fill | Call the bank before noon. Button#Done Kind=Quiet Label="Mark done" width=fill ``` - **kind** is a key of [the language](language.md) (`row`, `column`, `text`, `rectangle`, `icon`, `space`…) or a name: a preset, a part or a component. - **`#Name`** names the layer. A layer that is changed later needs one; a top-level layer without one is given one. A name with spaces is quoted: `text#"Due date"`. - **Indentation** puts a line inside the nearest line above it that is indented less. - **Keys** are the language's, written `key=value`. A value with spaces is quoted; a list or a map is written as JSON (`padding=[16,20]`); a number, `true` and `false` are themselves; a bare `key` is `key=true`. - **After ` | `** comes the text of a `text`, or the value of an `icon` or a `space`, to the end of the line. `\n` is a line break and `\|` a bar. - On a component, keys of the language sit beside it (`width=fill`) and every other key is one of its properties (`Kind=Quiet`). - A component set is `set#Name` with its `variants` (and `props`, `behavior`) as JSON values and one line inside it, which every variant starts from: `set#Switch variants={"State":{"Off":{},"On":{"fill":"#6E56CF"}}} behavior=toggle`. Lines after it use it by name, in the same stream. - A line that starts with `#` is a comment. ## Changes Change lines are not indented and name a layer by its name. They follow the design in the same stream, or come later in a stream of their own that starts with the design as it was written. | Line | Does | |---|---| | `PATCH Count color=#DC2626` | sets keys of a layer (a component's properties too) | | `REPLACE Body \| Call the bank at 3.` | replaces a text | | `TEXT Body \| Ask for Meera.` | adds to the end of a text | | `INSERT text#Note after=Body \| …` | a new layer after (or `before=`) a sibling, or the last one inside `parent=NAME`; lines indented under it go inside it | | `DELETE Count` | removes a layer and what is inside it | | `END` | nothing after it is read | ## What happens The stream writes what its lines changed and no more. Layers the document does not hold yet are built where they go (a new top-level layer on the page; a line under a layer that is already there, inside that layer, at its place); a `PATCH`, `REPLACE` or `TEXT` on a layer that is there changes that one layer; a `DELETE` removes it. So a page of thousands of layers takes one more card for the cost of the card. Lines that arrive while a write is under way are written together in the next. A change that is not a write to one layer (new text on a container's own line, a set changed after it was built, a layer the document knows only by a name several layers share) syncs its top-level layer whole by name, as [`build --sync`](update.md) does, and so does a stream run again over a page that already holds its layers. The builder, its warnings and its replies are the ones every build has; at the end the command says how many builds, changes, deletions and whole syncs it made. A line that cannot be read is noted with its number and a code, and left out; the stream goes on. What the builder warns about a batch is said when that batch is built, with the line it ends at. A set waits for its first line inside before it is built, and a component's name may be written with its spaces and no quotes (`Laptop card#Mac`). With `--strict` the command fails at that line. | Code | Means | |---|---| | `E_BAD_LINE` | not `kind#Name key=value \| text`, or a quote left open | | `E_DUPLICATE_ID` | the name was already there: the line takes the earlier layer's place, with what is written inside it (an author that starts a part over means the new one); `PATCH` changes a layer without writing it again | | `E_UNKNOWN_NODE` | a change names a layer that is not there | | `E_BAD_INSERT` | `INSERT` without one of `before=`, `after=`, `parent=` | | `E_IMMUTABLE` | a name does not change: `DELETE` the layer and write it again | | `E_NEEDS_VALUE` | an `icon` or a `space` without its value after the bar | > **Why** The lines are another way to write the same JSON, read in the command line only. One builder and one set of checks read every form. Each write is an undo step, so a stream leaves many. ## Hearing back A screen whose components have [behavior](behavior.md) can be used while its author still writes it: `facet act --follow` prints each event a person (the Use tool) or an agent (`facet act`) sends, one line each, and the author answers in the stream it already has open. The stream follows what its instances were moved to: a press that took `Save` to Saving is kept by the builds that come after, though its line first said `State=Idle`. ``` EVENT Save PRESS from=Idle to=Saving number=3 read from `facet act --follow` REPLACE Status | Saving your changes… written to `facet build --stream` ``` --- # Kit The kit holds what a file's designs share. Send it with any build, or alone; it merges into the file's kit by name and is saved with the file. What is written last wins: a later build whose kit says `"font"` again sets it again. Colours, presets and parts are live (every layer using one follows a change at once); `font` is the default written into each text when it is built, so after changing it, build the screens again with `--sync`, and leave the family out of a text's own font (`"15/22 600"`) if it should follow. A kit has no name: a file holds one, and its colors are the variable collection `Kit` (`@ink` is `@Kit/ink`). The kit behind the Raag examples: a default font, six colors, six type presets and four parts. `raag-kit.json`: ```json { "kit": { "font": "Inter 15/22", "colors": { "ink": "#1A1423", "paper": "#F6F1EA", "saffron": "#F29F05", "rose": "#D9485F", "mute": "#6F6879", "board": "#ECE6DD" }, "type": { "display": "Fraunces 40/44 600 -1", "title": "Fraunces 22/26 600", "deva": "Tiro Devanagari Hindi 14/20", "deva-xl": "Tiro Devanagari Hindi 40/44", "eyebrow": "Inter 12/16 700 +1.6 caps", "small": "Inter 13/18 500" }, "parts": { "swara": { "params": {"note": "", "tone": "@saffron"}, "node": { "row": [{"text": "{note}", "style": "deva"}], "padding": [2, 8], "cornerRadius": 8, "fill": "{tone}/20%" } }, "sticker": { "params": {"label": "", "tone": "#FBE3B5", "turn": 0}, "node": { "row": [{"text": "{label}", "font": "Inter 13/18 700"}], "padding": [6, 12], "cornerRadius": 14, "fill": "{tone}", "rotation": "{turn}" } }, "status": { "params": {"ink": "@ink"}, "node": { "row": [ {"text": "9:41", "font": "Inter 15/20 600", "color": "{ink}"}, {"space": "fill"}, {"icon": "lucide:signal", "size": 16, "color": "{ink}"}, {"icon": "lucide:battery-full", "size": 16, "color": "{ink}"} ], "gap": 6, "align": "center", "width": "fill", "padding": [16, 26, 6, 26] } }, "phone": { "params": {"name": "Phone", "bg": "@paper", "children": []}, "node": { "name": "{name}", "column": [ {"status": {}}, { "column": "{children}", "padding": [10, 22, 28, 22], "gap": 18, "width": "fill", "height": "fill" } ], "width": 390, "height": 844, "cornerRadius": 44, "fill": "{bg}" } } } } } ``` | Section | Holds | Used as | |---|---|---| | `font` | the default font of every text | nothing to write: texts start from it | | `colors` | named colors, one value or one per mode | `@ink`, `@ink/40%` | | `modes` | mode names for the colors (`["Light", "Dark"]`) | `"mode": "Dark"` on a layer | | `fallbacks` | characters to the family accepted to draw them (`{"✓◐": "Hiragino Sans"}`, `"*"` for any) | silences `GLYPH_FALLBACK` for those characters | | `type` | named text presets (a [font](font.md) or text keys) | `{"title": "Today"}`, `"style": "title"` | | `parts` | nodes with parameters | `{"chip": "May 2027"}` | ## Colors become variables Kit colors are variables in the collection `Kit`, so a layer painted `@ink` stays bound: change `ink` in the kit and every layer follows, and a layer shown in another mode takes that mode's value. A tint such as `@rose/20%` is a variable of its own (`Kit/rose-20`, made the first time it is used), so tints follow modes too. A later kit naming other modes adds them to the ones the file has (`["Light", "Sepia"]` to `Light` and `Dark` makes three): its colors give their values in the modes they name and keep the ones they had in the others, and a colour written once is that colour in every mode. See [Color](color.md). ## A spacing scale `"space"` names the kit's spacings: `{"kit": {"space": {"s": 8, "m": 16, "l": 24}}}`. Each is a number variable of the collection `Kit`, named in a layer as a colour is: `"gap": "@s"`, `"padding": "@m"`, `"padding": ["@s", "@l"]` (each side by name or by number), `"cornerRadius": "@s"`. Change the number in the kit and every layer using it follows; `source` prints the names. A spacing takes one number, or one for each mode (`[8, 12]`). A name cannot be both a colour and a spacing: `"@m"` means one thing. `facet tokens export --format css` writes them beside the colours (`--kit-m: 16px`). ## Presets become text styles Each preset is a text style of the same name. `{"title": "Today"}` makes a text that follows the style; send the preset again with new values and every text using it changes at once, with no rebuild. ## Parts A part is a node with parameters. Inside it, `{name}` stands for a parameter: a string that is only `{name}` takes the argument as it is (a number, a color, a list), and `{name}` inside longer text is replaced by its text. ```json {"kit": {"parts": {"chip": {"params": {"label": "", "tone": "@saffron"}, "node": {"row": [{"text": "{label}"}], "padding": [2, 8], "cornerRadius": 8, "fill": "{tone}/20%"}}}}} ``` - `{"chip": "May 2027"}` passes one value to the first parameter. - `{"chip": {"label": "May 2027", "tone": "@rose"}}` names them. - Keys beside the name apply to the part's root: `{"chip": "Late", "rotation": -4}`. - A parameter called `children` takes the children written at the use: put `"{children}"` where they go. - A list parameter whose default is `[]`, written alone among children (`"{status}"`), adds nothing when the use leaves it out and its items when it is given. - An argument may be a node or a list of nodes, not only text: `{"card": {"title": "Today", "children": [{"chip": "Late"}]}}`. - The part's root is named after the part unless its node names it: `"name": "{title}"` names each use by its argument. - Parts use presets, other parts and components. A part that uses itself is stopped at 24 levels. - Uses that share a name (four `stat`s in a row) are matched in order by a [sync](update.md). Give each a `"key"` (`{"stat": {...}, "key": "uptime"}`) so a reordered or removed one is matched by what it is. A key also keeps a layer through a rename: without one, a sync that removes a layer and adds another under the same parent notes `SYNC_SWAPPED`, since that is what a rename looks like. A part is not a component: it expands where it is used and leaves no link. When the same thing must stay in sync across a file, make it a [component](components.md). ## Sharing a kit: `use` A kit can take its parts, presets and colours from a library, so several files draw the same `chip` without each one resending it: ```json {"kit": {"use": "../system/kit.json", "colors": {"accent": "#D9485F"}}} ``` | `use` takes | It is | |---|---| | a path to a `.json` file | a kit written as `{"kit": {...}}` or bare; `facet --doc system.facet kit --json` writes one from a file | | a path to a `.facet` file | that design's own kit | | `"facet:NAME"` | a kit that ships with Facet | | a list of these | read in order; a later one lies over an earlier one | - **What the file writes itself wins.** A colour, preset or part in the file's own kit lies over the library's of the same name, and stays the file's own. - **The file follows its library.** Every build reads the library again. When it changed, the file takes the change (a `KIT_LIBRARY` note says what), and since kit colours are variables and presets are text styles, layers already built follow. - **The file stands on its own.** What the libraries gave is kept with the document, so it opens and builds on a Mac that does not have them. A library that cannot be read is a `KIT_LIBRARY` warning, and what it gave before stays. A library that cannot be read when it is first named is an error. - A path is read from the folder the build runs in and kept whole, so later builds from elsewhere read the same file. A library may use libraries of its own. `"use": null` stops using them. ## The kit that ships: `facet:basics` `{"kit": {"use": "facet:basics"}}` brings ordinary parts for the things most designs redraw by hand. They are parts like any you would write: `facet kit` prints them, a part of the same name in your kit replaces one, and a design that never uses them pays nothing. | Part | Write | Parameters | |---|---|---| | `chip`, `pill`, `badge` | `{"chip": "Open"}`, `{"chip": {"label": "Fixed", "tone": "@good"}}` | `label`, `tone` | | `dot` | `{"dot": {"tone": "@bad"}}` | `tone`, `size` | | `button`, `button-quiet` | `{"button": "Save"}` | `label`; `tone` on `button` | | `toggle`, `toggle-off` | `{"toggle": {}}` | `tone` on `toggle` | | `segmented` with `segment`, `segment-on` | `{"segmented": [{"segment-on": "Day"}, {"segment": "Week"}]}` | `label` | | `card` | `{"card": [children], "width": "fill"}` | its children | | `stat` | `{"stat": {"label": "Uptime", "value": "98.2%", "extra": [{"chip": "+0.4"}]}}` | `label`, `value`, `extra` | | `legend` | `{"legend": {"items": [{"label": "Open", "tone": "@bad"}]}}` | `items` | | `spark`, `bars` | `{"spark": {"values": [3, 5, 4, 8]}}`, `{"bars": {"values": [3, 5, 4, 8], "width": 280, "height": 72}}` | `values`, `tone`, `width`, `height` | | `stack-bar` | `{"stack-bar": {"items": [{"value": 62, "tone": "@good"}, {"value": 8, "tone": "@bad"}]}}` | `items`: the shares, as weights | | `meter` | `{"meter": {"percent": 62}}` | `percent`, `tone` | | `code` | `{"code": "facet build @screen.json"}` | `text` | | `steps` with `step` | `{"steps": [{"step": {"label": "Write", "note": "one call"}}]}` | `label`, `note`, `tone` | | `window` | `{"window": {"title": "Wake", "children": [...]}}` | `title`, its children | | `phone` | `{"phone": [children]}` | its children | **They take your look.** The parts are painted in kit colours the library also defines (`ink`, `mute`, `paper`, `surface`, `line`, `accent`, `good`, `warn`, `bad`) and set in the font they inherit. Write any of those colours in your own kit and every part follows: `{"kit": {"use": "facet:basics", "colors": {"accent": "#0A84FF"}}}`. Keys written at the use lie over the part's root (`"width": "fill"`, `"name"`), as with any part. `facet guide basics` prints this list from the kit itself, with each parameter's default. `phone` and `window` add no padding inside: put their content in a column with padding. `phone` clips its screen: content longer than it is cut, and the build says so (`PART_CLIPPED`). `stat` has no surface of its own (no fill, padding or border): put it in a `card` for a tile. `code` sets its own mono font; every other part takes the font it inherits. A switch is `toggle`, tabs are `segmented`, a progress bar is `meter`. A list given to a part that holds children is its children: `{"card": [...]}` is `{"card": {}, "children": [...]}`. ## Seeing and changing the kit ```sh $ facet kit {"font":"Inter 15/22","colors":{"ink":"#1A1423","paper":"#F6F1EA","saffron":"#F29F05","rose":"#D9485F","mute":"#6F6879","board":"#ECE6DD"},"type":{"display":{"fontFamily":"Fraunces","fontSize":40.0,"lineHeight":44.0,"fontWeight":600,"letterSpacing":-1.0},"title":{"fontFamily":"Fraunces","fontSize":22.0,"lineHeight":26.0,"fontWeight":600},"deva":{"fontFamily":"Tiro Devanagari Hindi","fontSize":14.0,"lineHeight":20.0},"deva-xl":{"fontFamily":"Tiro Devanagari Hindi","fontSize":40.0,"lineHeight":44.0},"eyebrow":{"fontFamily":"Inter","fontSize":12.0,"lineHeight":16.0,"fontWeight":700,"letterSpacing":1.6,"textCase":"upper"},"small":{"fontFamily":"Inter","fontSize":13.0,"lineHeight":18.0,"fontWeight":500}},"parts":{"swara":{"params":{"note":"","tone":"@saffron"},"node":{"row":[{"text":"{note}","style":"deva"}],"padding":[2,8],"cornerRadius":8,"fill":"{tone}/20%"}},"sticker":{"params":{"label":"","tone":"#FBE3B5","turn":0},"node":{"row":[{"text":"{label}","font":"Inter 13/18 700"}],"padding":[6,12],"cornerRadius":14,"fill":"{tone}","rotation":"{turn}"}},"status":{"params":{"ink":"@ink"},"node":{"row":[{"text":"9:41","font":"Inter 15/20 600","color":"{ink}"},{"space":"fill"},{"icon":"lucide:signal","size":16,"color":"{ink}"},{"icon":"lucide:battery-full","size":16,"color":"{ink}"}],"gap":6,"align":"center","width":"fill","padding":[16,26,6,26]}},"phone":{"params":{"name":"Phone","bg":"@paper","children":[]},"node":{"name":"{name}","column":[{"status":{}},{"column":"{children}","padding":[10,22,28,22],"gap":18,"width":"fill","height":"fill"}],"width":390,"height":844,"cornerRadius":44,"fill":"{bg}"}}}} ``` Send a kit section again to change it; names you send replace those entries and the rest stay. The reply names what changed ("Kit changed: type title; every layer using them follows."), with or without nodes in the same call. `null` removes an entry: `{"kit": {"parts": {"badge": null}}}`. A removed color keeps its variable, because layers may still use it; delete the variable with `facet call variables '{"delete": "Kit/rose"}'` once nothing does. A name lives in one section: a preset and a part cannot share it, because `{"badge": ...}` could mean either. The kit refuses the second one and says which to rename. --- # Layout Containers do the placing. You say how things flow and how they size; Facet does the arithmetic. Three rows in a column. The first pushes `40 min` right with a `space` that fills; the second wraps its chips, made with `each`; the third ends at the right with `justify`. `layout-flow.json`: ```json { "name": "Session", "font": "Inter 15/22", "width": 340, "padding": 20, "gap": 16, "fill": "#FFFFFF", "cornerRadius": 16, "column": [ { "row": [ {"text": "Riyaz session", "font": "17/22 700"}, {"space": "fill"}, {"text": "40 min", "color": "#6F6879"} ], "width": "fill", "align": "center" }, { "row": [ { "each": ["Sa", "Re", "Ga", "Ma", "Pa", "Dha", "Ni"], "do": { "row": [{"text": "{.}", "font": "13/16 600"}], "padding": [6, 10], "cornerRadius": 8, "fill": "#F3EFF7" } } ], "gap": 6, "wrap": true, "width": "fill" }, { "row": [ {"text": "Skip"}, { "row": [{"text": "Start", "color": "#FFFFFF", "font": "15/20 700"}], "padding": [10, 20], "cornerRadius": 12, "fill": "#1A1423" } ], "gap": 16, "justify": "end", "align": "center", "width": "fill" } ] } ``` ## Flow keys | Key | Forms | What it does | |---|---|---| | `gap` | number, `[row, column]`, `{"row", "column"}`, `"auto"` | space between children (a grid's between rows, then columns); `"auto"` spreads them. Negative in a row or column that does not wrap: each child lies over the one before by that much, later ones on top, and a frame that hugs is as long as what they cover (four avatars of 40 with `"gap": -8` are 136 wide). A row that wraps and a grid keep 0 or more | | `padding` | number, `[v, h]`, `[top, right, bottom, left]` | room inside the edge; a negative side is set to 0 with a note, and the frame keeps its auto layout | | `align` | `start`, `center`, `end`, `stretch`, `baseline` | across the flow (a grid's cells down their row); `stretch` is CSS's: a frame that hugs takes the line's size, the tallest child setting it (a fixed child keeps its size, a text keeps its lines, a text in a column wraps at its width, a shape spans the line); `baseline` is CSS's too, in a row: the first lines of its texts sit on one baseline (a title and the count beside it, a price and its unit), a frame's baseline is that of what it starts with, and a child without text sits on the line by its bottom edge. In a column or grid it places children at the start | | `justify` | `start`, `center`, `end`, `space-between`, `space-around`, `space-evenly` | along the flow (needs room). `space-between` puts the first and last child at the edges; `space-evenly` makes every space equal, the two ends included; `space-around` gives the ends half a space | | `wrap` | `true` | a row breaks into lines | | `columns` | number or tracks | a `grid`'s columns; a text given no width, as a cell or in a cell's column, wraps at the cell's width when it would run past it (a note names it), and keeps hugging its words when it fits | | `columnSpan`, `rowSpan` | number | a `grid` child covers that many columns, or rows: a card with `"rowSpan": 2` stands beside two rows of the cells after it, and both rows together are as tall as it is. A file with a row span needs Facet 0.3.212 or later to open | | `gridRows` | tracks or `"none"` | a `grid`'s rows, top to bottom, written as columns are: a height, a share `"1fr"` of the height left (at least the row's content, as CSS's `1fr`) or `"hug"`; rows past the list hug. Beside a card with `"rowSpan": 2`, `"gridRows": ["1fr", "hug"]` gives the first row what the card leaves and keeps the second as tall as what it holds. `"none"` removes them. A file with grid rows needs Facet 0.3.217 or later to open | ## Sizes `width` and `height` take a number, `"fill"` (the room the parent's flow leaves) or `"hug"` (the content; the default for containers). `size` is both at once: a number, or `[width, height]`. A percentage is read on the children of a row (`width`) or a column (`height`): shares that add up to 100% (`"30%"` and `"70%"`) share the room left after the gaps, as `grow` weights do, and other shares are taken of the parent's room inside its padding when its size there is a number. Anywhere else a percentage is not a size, and the build says so. `minWidth`, `maxWidth`, `minHeight` and `maxHeight` bound any of them. A child that hugs along a row keeps the width of what it holds however little room the row has, unless it says a `minWidth`: then it gives way when the row runs out of room, down to that width, as a CSS flex item does (`"minWidth": 0` on a chip that clips its label lets the row squeeze it; one with no `minWidth` overflows). A column's children keep their height. A container that hugs stops at its max, and a child that fills it then gets the room the max allows: a row with `"maxWidth": 320` and a text with `"width": "fill"` is 320 wide and the text wraps inside it. A text given no width wraps there too, in the room the max leaves it, and a short one keeps the row hugging: a chat bubble is `{"row": [{"text": "…"}], "maxWidth": 260, "padding": [8, 12]}`. `"maxWidth"` on a text itself does the same: longer words wrap at it, shorter ones keep their width. A child that fills across a parent that hugs that way takes the parent's size and never gives it: a clipped pattern with `"height": "fill"` in a row is as tall as the row's other children, however tall its content. To make cards in a row one height, the tallest setting it, use `"align": "stretch"` on the row instead. A text with `"width": "fill"` wraps at the width its row or column gives it and takes the height of its lines; when the parent resizes, the text measures its lines again. `"maxLines": 1` keeps it to one line with an ellipsis. ## Space A child that fills across with a `maxWidth` (or `maxHeight`) and an `alignSelf` fills up to its maximum and is then placed by its alignment, as CSS centres `width: 100%; max-width: 736px; margin: 0 auto`: `{"width": "fill", "maxWidth": 736, "alignSelf": "center"}` in a 1200 wide column is 736 wide at 232. `"grow": 1` on a child takes the room its row or column leaves, as `"fill"` along the flow does. A number shares that room by weight, as CSS's `flex-grow` does: in a 300 wide row, `"grow": 1` and `"grow": 2` come out 100 and 200 wide, so a stacked bar is its values as weights. `modify` changes a weight, `source` writes it back, and a `--sync` whose source fills without one puts it back to 1. A file with a weight needs Facet 0.3.147 or later to open. `"margin"` on a child of a row, column or grid is room of its own around it, beyond the parent's `gap`: `"margin": 8` on every side, `[vertical, horizontal]`, `[top, right, bottom, left]`, or sides by name (`{"top": 8}`). Along the flow it moves the child and what follows it; across the flow it insets the child, and a child that fills takes the width its side margins leave. A side may be negative: `{"margin": {"top": -4}}` stands a caption 4 px nearer the title than the gap, and `{"margin": {"left": -12}}` lays one avatar over the one before it. A frame that hugs is as large as its children with their margins; a negative margin across the flow moves the child out past the frame's edge. `{"space": 12}` is still a spacer between two children (it stands between two gaps), and a negative space takes that much room back. `modify` changes a margin, `source` writes it back in its shortest form, and a `--sync` whose source no longer writes one takes it away. A file with a margin needs Facet 0.3.181 or later to open. `"alignSelf"` on a child of a row or column puts it across the flow where it says, whatever the parent's `align` is: `"start"`, `"center"`, `"end"`, `"stretch"` or, in a row, `"baseline"` (`"auto"` follows the parent again). One item at the bottom of a row whose items sit at the top is `{"alignSelf": "end"}`. `source` writes it back and a `--sync` whose source no longer writes it lets it go. A file with a row or child aligned by baseline needs Facet 0.3.191 or later to open. `"inset"` on a child of a row, column or grid takes it out of the flow and pins it that far in from its container's edges, as in a stack: `"inset": 0` is a background behind the other children or an overlay over them (children are drawn in the order written), `[top, right, bottom, left]` pins each side, and a side that is `null` is left free, so `[0, null, 0, 0]` is a bar down the left edge as tall as the container. The pin is part of the layout, not a position worked out once: when the container grows or shrinks (a longer text, a `--sync`, a larger instance of a component whose main holds the pinned layer) the pinned child follows its edges, and a container that hugs is never sized by it. `source` writes it back as `inset`, `modify` changes it, and the inspector shows it under the layer's sizing. A file with a pinned child in a flow needs Facet 0.3.191 or later to open. `"dividers"` on a row or column draws a rule between each pair of its children, never after the last: `"dividers": "@line"` (a colour), `true` (the kit's `line` colour), or `{"color": "@line", "weight": 1, "inset": 12}` to keep it clear of both ends. In a column the rules lie across its width; in a row they stand its height. `"between"` puts any node there instead: `{"row": ["Home", "Docs", "API"], "between": "·"}`. Both lower to ordinary layers (the rules are named `Divider`), so each can be selected and restyled, `source` shows them as children, and a `--sync` that adds or drops a child adds or drops its rule. A layer placed with `at` is outside the flow and gets none. `"line"` on a row or column draws one rule behind its children, along the flow and as long as the container whatever it holds: a timeline's line through its dots, a stepper's line through its circles. `"line": true` runs it through the middle of what each child starts with; `{"x": 20, "color": "@line", "width": 2}` places it (`y` in a row; `"side": "right"` pins it to the far edge; `"inset": 8` shortens both ends). It is a layer named `Line`, placed after layout, so it is as long as the container again after every `--sync`. ## Connecting layers `{"connect": ["React", "JSON"]}` draws an arrow from the layer named `React` to the layer named `JSON`. Write it beside them, as one more child of the row, column or stack that holds both: it takes no room in the flow. The line is routed once everything is laid out, so the boxes stay in rows and columns and nothing is placed by hand: ```json {"row": [ {"name": "React", "padding": [10, 14], "fill": "@card", "row": ["React"]}, {"name": "JSON", "padding": [10, 14], "fill": "@card", "row": ["JSON"]}, {"connect": ["React", "JSON"], "stroke": "@facet", "label": "emits"} ], "gap": 120} ``` | Key | Takes | Default | |---|---|---| | `from`, `to` | the side the line leaves and enters by: `left`, `right`, `top`, `bottom`, `center` | the sides facing each other | | `curve` | `smooth`, `straight`, `elbow` (right angles) | `smooth` | | `arrow` | `end`, `start`, `both`, `none` | `end` | | `stroke`, `weight`, `dash` | as a `draw` shape: a color (a kit color stays bound), a width, `[dash, gap]` | the color texts take here, 1.5 | | `gap` | clear space between a box and the line's end | 4 | | `label` | a text beside the line's middle, clear of it (above a line that runs across, to the right of one that runs down, off a slanted one square to it), or any other node (a chip with a fill) centered on it | none | | `route` | `avoid`: around the layers beside it that it does not join; `direct`: the line `curve` draws, through whatever is in the way | `avoid` | The result is an ordinary drawing named `React → JSON` (give it a `name` to choose another): select it, restyle it, delete it. A `--sync` after the boxes move routes it again and keeps its layer. A name no layer has is reported (`NOT_APPLIED`) and nothing is drawn. Moving a box in the app does not move its connectors; build or sync again. `{"space": 12}` is a fixed gap in a row or column; `{"space": "fill"}` takes the free room, so whatever follows is pushed to the end. Lines that leave or enter one box by the same side are spread along that side, in the order of what they reach, so two arrows never start from one point or cross on the way out. **Around what is in the way.** Among other layers (cards in a map, steps in a flow) a connector is routed around the ones it does not join, as orthogonal connector routing does it: the path with the fewest turns for its length through the gaps between them, at least 8 px from each, each middle stretch centred in the gap it runs through, crossing and running along the lines already drawn beside it as little as it can, and set 6 px apart from one where they share a gap. Every line among other layers is routed this way, so a map's lines all run alike; `smooth` rounds their turns, `elbow` keeps them square. A background that holds other layers (a lane band behind a row of cards) is not in the way, nor is a layer that holds either end. A line with no clear way round is drawn through and says so (`CONNECTOR_CROSSES`); `"route": "direct"` draws the plain line. Moving a box in the app routes the lines that follow it the same way. **When a box moves.** A connector follows the layers it joins. Drag a box in the app, nudge it, resize it, change a row's gap or a padding in the inspector, edit a text that makes a box grow, or run any command (`modify`, `arrange`, `build --sync`): when the edit lands, the connectors whose ends moved are routed again, with their labels, in that edit's undo step, so one undo puts the box and its arrows back together. During a drag the arrow waits and is routed when you let go. Only connectors whose ends moved are touched, and a design without connectors does no work for them. The relation is kept with the document (which layers a connector joins, by layer, and how it runs), so it survives saving and reopening; a connector whose shapes you redraw by hand is left as you drew it. ## Tables: a grid written row by row A grid's columns can size themselves and place their cells, and a grid can be written a row at a time. Column widths are never worked out by hand: ```json {"name": "Incidents", "width": 520, "padding": 8, "fill": "@paper", "cornerRadius": 12, "columns": ["hug", "fill", "hug", {"width": "hug", "align": "end"}], "gap": {"column": 16, "row": 0}, "align": "center", "header": {"cells": ["Id", "What happened", "State", "Runs"], "style": "cap", "color": "@mute"}, "rows": {"padding": [10, 12], "cornerRadius": 8}, "dividers": "@line", "grid": [ ["INC-7", "Checkout total is wrong with a coupon", {"chip": "Open"}, "1,204"], {"cells": ["INC-12", "Search returns stale results", {"chip": "Fixed"}, "87"], "fill": "@green/6%"}, ["INC-103", "Login loop on Safari", {"chip": "Open"}, "9"] ]} ``` | Write | For | |---|---| | `"hug"` in `columns` | a column as wide as its widest cell (beside a number, `"fill"` and `"Nfr"`) | | `{"width": "hug", "align": "end"}` in `columns` | the same widths, with the column's cells at its `start`, `center` or `end`: numbers line up on the right | | `"grid": [[cells], [cells]]` | one list per row. Each row becomes a layer named `Row 1`, `Row 2`…, so it can be filled, rounded, given a height, selected and restyled like any layer | | `"rows": {...}` | what every row is given: `padding`, `fill`, `cornerRadius`, `height` | | `{"cells": [...], "fill": ...}` | one row with keys of its own (a highlighted row, a `name`, a `key`) | | `"header": [cells]` or `{"cells": [...], "style": "cap"}` | a first row named `Header`. It shares the rows' padding, so its cells sit over theirs, and takes its own keys | | `"dividers"` | a rule between rows, as in a column | | `"gap"` | a number for both, or `{"column": 16, "row": 0}`; unwritten, columns are 12 apart and rows touch | Without `columns`, a grid written row by row has as many equal columns as its longest row has cells. A row holds at most one line of cells. What it builds is ordinary layers: a column of grids that share the columns. In a flat grid (`"grid": [cells]`) a hugging column is live: it follows its cells when a text is edited in the app. Written row by row, every row is its own grid, so hugging columns are measured once the rows are laid out and each row keeps that width as a number; `build --sync` measures again. ## Stacks In a `stack` the children overlap. Each is centered unless it says otherwise with `at`, and the stack takes the size that covers its children, again after every `--sync`, unless it has a `width` or `height` of its own: its largest child, and as far as a child placed at a point (`"at": [3, 2]`, a drop shadow's offset) reaches. A child with `"inset": 0` fills the stack instead, whatever size the others give it: a scrim over a card, an outline around content of any size (`"inset": 8`, or `[top, right, bottom, left]`, keeps it that far in). It does not size the stack. A stack's `padding` (a number, `[v, h]`, `[t, r, b, l]`, `{"top": …}`, each a number or a spacing token such as `"@m"`) insets where its children are placed. Frames, stacks and component templates clip what reaches outside them unless they say `"overflow": "visible"`: a focus ring drawn outside a control needs it. An avatar: a gradient circle, initials centered on it, and a badge pinned to the top right corner. `layout-stack.json`: ```json { "name": "Avatar", "stack": [ { "type": "ellipse", "size": 72, "fill": {"linear": ["#F29F05", "#D9485F"], "angle": 135} }, {"text": "AK", "font": "Inter 24/28 700", "color": "#FFFFFF"}, { "row": [{"text": "3", "font": "Inter 11/14 700", "color": "#FFFFFF"}], "padding": [2, 6], "cornerRadius": 10, "fill": "#1A1423", "at": ["top right", -2, 2] } ] } ``` ## Placing a layer: `at` | Form | Places the layer | |---|---| | `[x, y]` | with its top left corner at x, y | | `[x, y, "center"]` | with that point of itself at x, y: any place word, `"top center"`, `"bottom left"`, `"right"`. A text anchored at its center grows up and down as it wraps; anchor it by its top (`"top center"`, `"top left"`) to grow down. A placed text that overlaps another text warns `LAYOUT_OCCLUDED`. | | `"bottom right"` | in its parent by words: `top`, `bottom`, `left`, `right`, `center`, or two of them | | `["bottom right", -16, -16]` | by words, then moved by an offset (x to the right, y down, so `-16` lifts it) | | `{"angle": 90, "r": 80}` | its center at that angle (degrees clockwise from the top) and distance from the parent's center | In a row or column, `at` takes the layer out of the flow. Places pin the layer with constraints, so it keeps its place when the parent changes size. ## Frames in a row: `after` A top-level layer without `x` and `y` goes right of everything on the page. For a sequence, slides or screens of a flow, `"after"` places it right of the top-level layer it names, 80 apart, tops aligned: `{"name": "Slide 2", "after": "Slide 1"}`. In a call that builds several, `"after": "previous"` follows the node before it in the same call; `{"node": "previous", "gap": 120}` sets the gap. A component set or the icon library parked to the side never breaks the sequence, and `export --pdf` takes the frames in reading order, so a deck is built and exported without computing an x. A PDF holds one page of the file (the page showing, or `--page NAME`); `--pages all` puts every page of the file in one PDF, page after page in the pages list's order, and `--pages Cover,Flows` those pages in that order. **Rows of frames.** `"after": {"node": "previous", "wrap": 4, "gap": [80, 120]}` starts a new row after every fourth frame: at the row's left edge, under its tallest frame, the gap's second number apart. The row is read from the page, so a later call that names the last frame continues it. No `x = index × step`. **A caption above a frame** is a column of the label and the frame: `{"name": "Checkout · captioned", "gap": 12, "column": [{"cap": "Checkout"}, {"name": "Checkout", ...}]}`. The label moves with the frame, the next frame clears both, and `"after": "Checkout"` still follows it by the frame's name. **Frames already on the page.** `facet arrange --columns 4 --gap 80,120` lays the page's top-level layers out in rows, in reading order, without touching what is inside them (`facet arrange "Slide 3" "Slide 1"` places those, in that order; `--at X,Y` chooses where). Columns are as wide as their widest frame and rows as tall as their tallest, so nothing overlaps after frames change size. It is one undo step. ## Rings A `ring` places its children around a circle of radius `r`, the first at `start` degrees (clockwise from the top), the rest evenly after it. A child may set its own `angle`. `"arrows": true` (or a color, or `{"color", "weight", "gap"}`) draws an arrow from each child to the next, clockwise along the circle, under the children and clear of them (`gap`: degrees left free on each side of a child), for a cycle diagram. A ring grows to cover its children, and a stack around it takes that size. A clock face: twelve numbers from `each` on a ring starting at 30°, over a circle and a center dot, all in one stack. `layout-ring.json`: ```json { "name": "Clock", "stack": [ { "type": "ellipse", "size": 220, "fill": "#F6F1EA", "stroke": "#1A142322" }, { "ring": [ { "each": 12, "do": { "text": "{#}", "font": "Inter 15/20 600", "color": "#1A1423" } } ], "r": 88, "start": 30 }, {"type": "ellipse", "size": 8, "fill": "#D9485F"} ] } ``` ## Rotation `rotation` turns a layer counterclockwise, in degrees, about its own top-left corner: that corner stays where `at`, `x` and `y` put it (`"at": [100, 100]` turns a 100 × 40 layer by 90 up from (100, 100)). With an anchor, `"at": [x, y, "center"]` puts the layer's centre at x, y first, so it looks turned about its centre. In a row, column or grid, a rotated layer keeps its own size and the flow makes room for its turned box. A layer turned less than 45° that fills (a tilted card, `"width": "fill"`) takes the room as its own width or height, so its content wraps at that width; its corners stand out a little past the room, on purpose, and no warning counts them. ## Skew and matrix `skew` slants a layer about its top-left corner, as CSS's `skew()` does: `"skew": -20` leans its verticals 20° (the top to the right), `[x, y]` slants both ways (each between -89 and 89). With `rotation` beside it, the layer is turned after the slant. `matrix` draws a layer through any CSS matrix `[a, b, c, d, e, f]` (x' = a x + c y + e, y' = b x + d y + f) about its top-left corner, which moves by (e, f): a skew, a scale (`[0.5, 0, 0, 0.5, 0, 0]`), a mirror (`[-1, 0, 0, 1, 140, 0]` flips a 140-wide layer in place) or a 3D turn seen flat. It replaces `rotation`; `"matrix": "none"` draws the layer upright. The layer keeps its own size, its contents lay out in its own axes and are drawn through it, and in a flow it takes the upright box around what is drawn, as a rotated layer does. `inspect` and `source` give the matrix when a layer is more than turned, to four decimals; a matrix that folds a layer flat (a d - b c = 0) is refused. Four cards: plain, skewed by -20°, mirrored in place, and scaled to half, each with its words drawn through it. `layout-skew.json`: ```json { "name": "Cards", "width": 660, "height": 140, "fill": "#FFFDF8", "font": "Inter 16/22 700", "color": "#FFFFFF", "stack": [ { "name": "Plain", "at": [20, 30], "width": 130, "height": 80, "fill": "#D9485F", "cornerRadius": 8, "padding": 12, "column": ["Plain"] }, { "name": "Skewed", "at": [190, 30], "width": 130, "height": 80, "fill": "#3B6FD9", "cornerRadius": 8, "padding": 12, "skew": -20, "column": ["Skewed"] }, { "name": "Mirrored", "at": [350, 30], "width": 130, "height": 80, "fill": "#2E9E6B", "cornerRadius": 8, "padding": 12, "matrix": [-1, 0, 0, 1, 130, 0], "column": ["Mirrored"] }, { "name": "Half", "at": [510, 30], "width": 130, "height": 80, "fill": "#7A4FD0", "cornerRadius": 8, "padding": 12, "matrix": [0.5, 0, 0, 0.5, 32.5, 20], "column": ["Half"] } ] } ``` --- # Text A string in a list of children is a text. It takes its font and color from the nearest container that sets them, or from the kit's `font`. One container sets `Inter 15/22`; each text changes only what differs. `17/26` keeps the family and changes the size; `italic` and a weight add to it. `text-fonts.json`: ```json { "name": "Type", "font": "Inter 15/22", "gap": 8, "width": 360, "padding": 20, "fill": "#FFFFFF", "column": [ {"text": "Practise the raga", "font": "Fraunces 36/40 600 -1"}, { "text": "Evening · first prahar", "font": "Inter 12/16 700 +1.6 caps", "color": "#D9485F" }, {"text": "Every note is shuddha except tivra Ma.", "font": "17/26"}, {"text": "यमन · कल्याण थाट", "font": "Tiro Devanagari Hindi 20/28"}, { "text": "Last riyaz 2 days ago", "font": "13/18 500 italic", "color": "#6F6879" } ] } ``` ## The font shorthand `"Family Size/LineHeight Weight"` and optional words, in any order after the size: `italic`, letter spacing with a sign (`+0.4`, `-2%`) and a case (`caps`, `lower`, `title`). Leave the family out to keep the inherited one. The full grammar is in [Font](font.md). | You write | Means | |---|---| | `"Inter 15/22"` | Inter, 15 px, 22 px line height | | `"Fraunces 44/1.1 600 -1"` | line height 1.1 × size, weight 600, letter spacing −1 px | | `"12/16 700 +1.6 caps"` | inherited family, uppercase, spaced | ## Presets A kit `type` preset is a text style. `{"title": "Today"}` is a text in it; `"style": "title"` on a container makes it the default for the texts inside. A text's own `font` replaces a preset. ## A text in a box `padding` on a text puts it in a box, as CSS does: `{"text": "Dismiss", "name": "Dismiss", "padding": [6, 8], "fill": "@paper", "cornerRadius": 6}` builds a hugging row with that padding named `Dismiss`, holding the text named `Dismiss text` (`Dismiss > Dismiss text`; `Label` when the text has no name), so overrides of a `Label` of your own never reach it. The box takes the keys of a box: `fill` (its background), `stroke`, `strokeWidth`, `cornerRadius`, `effects`, `opacity`, the name and key, and the place and size (`at`, `x`, `y`, `width`, `height`, `grow`). The text keeps the rest, so `color` is the text's. A box given a width gives the text the room across, and the text wraps in it. A text already built takes no padding through `modify`; build it in its box. `verticalAlign` places a text's lines in a box taller than they are: `{"text": "A", "font": "Fraunces 40", "width": 80, "height": 120, "verticalAlign": "center"}` keeps its 120 px box and sets the letter in its middle (`top` is the default, `bottom` sets the last line on the box's bottom; Figma's `textAlignVertical` reads as it). A text given a height with `center` or `bottom` keeps that height; otherwise a text's box follows its lines and there is no room to place them in. In the app, **Align** in the Text section does the same for a text whose box has a fixed size. ## A width as measured: `"fractional"` A text that hugs is as wide as the next whole unit past its words, so the layers beside it land on whole pixels: `Workflow` in Inter 11 measures 50.22 and takes 51. `"fractional": true` keeps the 50.22. A browser sizes text this way, so a row of labels read from a page with `facet react dom` is fractional: nine chips each rounded up ended the row four pixels from where the page has it. It is a text's own setting (`{"text": "Workflow", "fractional": true}`), a sentence gives it to its words, `source` writes it back, and a file that has one needs this version to open. A text with a width keeps that width either way. The inspector does not show it; `facet inspect` does. ## A size that fits: `"fontSize": "fit"` `{"title": "Lessons from Wake", "width": "fill", "fontSize": "fit"}` takes the largest whole size at which the text fits, measured by the engine that draws it once the layout is known. Nothing is guessed from the number of characters. | The text has | It fits | |---|---| | a width (a number or `"fill"`) | one line at that width | | a width and `"maxLines": 2` | that many lines | | a width and a `"height"` | every line inside that height (the text's box still follows its lines) | `{"fit": {"min": 12, "max": 64}}` bounds the size (8 to 400 otherwise). The line height scales with the size, so write the preset's as you would anyway. A `FONT_FIT` note names the size it took; when the text cannot fit even at the smallest, `TEXT_OVERFLOW` says so. `build --sync` fits again when the words or the width change. A text without a width has nothing to fit and is reported. To know a text's size without building it, `facet probe @block.json` lays nodes out on a scratch copy and returns each node's size and each text's lines; it leaves nothing in the document, and takes a root of thousands of layers. ## What wins From strongest to weakest: keys written on the text (`fontSize`, `color`), the text's own `font`, its own `style`, then what the nearest container passes down (`font` or `style`, and `color`), then the kit's `font`. A span's own keys win over all of these for its characters: a text in a preset with `{"text": "code", "fontFamily": "JetBrains Mono"}` among its `spans` sets that word in the mono font and the rest in the preset, which they keep following. `source` writes such a text as its `spans`. ## Sentences with components `"type": "paragraph"` with `runs` mixes text and nodes. It wraps like text: each word is a text in the paragraph's font, nodes stay in place, and punctuation that touches a node stays on its line. A run of styled text (`{"text": "GUARDRAIL span", "fontWeight": 600}`) is split into words the same way, in the paragraph's font with its own keys on top. It takes the paragraph's font even where the kit or the container says another. A line break (`"\n"`) in a run ends the line: the words after it start the next one. `textAlign` on a paragraph (`center`, `right`) sets each of its lines there. A chip part used twice inside a sentence. Words sit a space of their font apart and lines a line height apart, as in a text of the same style; `wordSpacing` and `lineGap` (added between lines) change that. `text-paragraph.json`: ```json { "kit": { "parts": { "tag": { "params": {"label": "", "tone": "#D9485F"}, "node": { "row": [{"text": "{label}", "font": "Inter 13/18 600"}], "padding": [1, 7], "cornerRadius": 6, "fill": "{tone}/18%" } } } }, "nodes": [ { "name": "Digest", "font": "Inter 16/24", "width": 340, "padding": 20, "fill": "#FFFFFF", "column": [ { "type": "paragraph", "width": "fill", "runs": [ "Checkout errors rose ", {"tag": "+38%"}, " on Saturday, the most since ", {"tag": {"label": "Tue 14 Oct", "tone": "#6F6879"}}, ". Two agents stopped sending traces overnight." ] } ] } ] } ``` ## Lists `{"list": ["Open the file", ["Check the name", "Check the size"], "Save it"], "marker": "number"}` builds one text, an item per paragraph. A list inside the list nests its items one level under the item before it. `marker` is `bullet` (the default: •, then ◦ and ▪ deeper), `number` (1., then a. and i. deeper, counting per level), `check`, or any characters (`"–"`, `"→"`). A check item written `"[x] Done"` is ticked and `"[ ] Todo"` is not; the brackets are not drawn. `indent` is the space per level (1.5 times the size, widened so the longest marker fits), `start` the first number, and `gap` the space between items. Each marker hangs before its item, ending a little before the text, so numbers line up on their periods. Lines that wrap start at the item's indent, not under the marker. On a text built another way, `"list": "bullet"` (or `{"marker", "indent", "start", "gap"}`) makes each paragraph an item. Its leading tabs are its level, and `"list": "none"` ends the list. In the app, the **List** menu of the **Text** section does the same. Tab anywhere in an item nests it one level, Shift-Tab brings it back out (with a selection, every item it touches moves), and Backspace at an item's start brings it out too. ## Columns and drop caps A text with a width sets its lines in `columns`, filled in turn, with `gap` between them (the line height when left out). A text whose height follows its content balances its columns; a text of fixed height fills each column to its height and hides the lines past the last, ending in an ellipsis when it truncates. `dropCap` sets the first letter large across that many lines, from the first line's capitals down to the last line's baseline, and the lines beside it start after it: write the lines alone (`"dropCap": 3`) or with its `font` (a family and a weight, `"Fraunces semibold"`; its size follows the lines), `color` and `gap` (the space before its lines, a quarter of the text's size unless set). `paragraphIndent` starts the first line of each paragraph that far in; as books set it, the text's first paragraph is not indented unless `{"size": 11, "first": true}`. One text in two balanced columns with a three-line drop cap in another face and color. Edits reflow it; it stays one layer. `text-columns.json`: ```json { "kit": { "colors": {"ink": "#1A1423", "rose": "#B8742A"}, "type": {"body": "Source Serif 4 15/23"} }, "nodes": [ { "name": "Article", "width": 600, "padding": 24, "gap": 12, "fill": "#FFFDF8", "color": "@ink", "column": [ {"text": "The hour before the lamp", "font": "Fraunces 26/30 600"}, { "name": "Body", "body": "The evening raga begins before the musician plays. It starts in the half light, when the tanpura settles and the room learns its own pitch. Yaman rises with a sharpened fourth that leans toward the fifth, a small tension that the whole evening resolves. Listen for the way the singer returns to the same phrase, each time a little wider, until the phrase is the room and the room is the hour.", "width": "fill", "columns": 2, "gap": 20, "dropCap": {"lines": 3, "font": "Fraunces 600", "color": "@rose"} } ] } ] } ``` The drop cap is the paragraph's first letter (with its accents), even in a face that joins it to the next one, such as a blackletter "Th": the ligature breaks there and the rest of the word stays in the text. A kit type preset can hold both (`"lede": {"font": "Source Serif 4 18/28", "dropCap": 3}`), and every text in it then has them; `source` writes them on a text only when its preset does not. Copying from an exported PDF reads the drop cap as the first letter and the columns in order. ## Flowing around a layer `textWrap` on any layer (a photo, a shape, a frame) makes the texts that share its parent flow around its box, the number keeping them that far clear. Set it on the obstacle, not on the text, as print does: a text never names what it flows around, and a layer placed with `at` still pushes its texts aside. Beside it, a line continues across to the other side while both sides hold a proper line (about twelve ems each), and otherwise takes the wider side (keeping to the side the line above took while that side is nearly as wide, so lines run down one side of a shape rather than zigzag across it), so a layer in the middle of a column has text on both sides and one at an edge has text beside it. `{"offset": 12, "side": "largest"}` always takes the wider side, `"both"` every side with room for a few words, `"left"` or `"right"` keeps lines to one side, `"neither"` passes them above and below only, and a line with too little room moves below it. The clearance holds on every side, below the box too: a line whose top is less than the offset under the box's bottom is still shortened (a 60-high initial with offset 7 shortens lines down to 67), so size a drop initial to the lines it should span. A text with a drop cap beside a wrap sets the cap where its first line starts, after the layer, and the lines the cap spans start after the cap and follow the layer's edge. A text whose height follows its content grows to the lines it needs; `"none"` stops it. A text in columns does not flow around anything yet. A story flowing through frames counts its layers too: a frame with a figure across its top takes only the lines that fit below it, and the next frame starts after them. A justified text in a stack with a block at its top right: the lines beside the block shorten, hyphenating where they must, and run the full width below it. `text-wrap.json`: ```json { "name": "Page", "width": 520, "padding": 24, "fill": "#FFFDF8", "color": "#1B1712", "stack": [ { "name": "Body", "width": 472, "font": "Source Serif 4 15/22", "textAlign": "justified", "at": [0, 0], "text": "The tanpura is not played so much as kept. Four strings, plucked in turn, never quite the same twice, and the room fills with overtones that the singer leans on. Every note is measured against it; the drone is the floor the evening stands on. Listen long enough and the drone stops being a sound and becomes the room itself, the way the rain outside stops being weather and becomes the hour." }, { "name": "Photo", "size": [160, 150], "fill": {"linear": ["#B8742A", "#5B3A1E"], "angle": 160}, "cornerRadius": 4, "at": "top right", "textWrap": 12 } ] } ``` `"around": "outline"` follows the layer's shape instead of its box: lines beside a circle end along its curve, lines beside a triangle step along its sides, and a path, a drawing or a group of shapes (an imported SVG, an icon) works the same way. The clearance stays the same distance all round the curve. A picture is wrapped by its opaque part, so a cut-out (a PNG with a transparent background) works like a drawn shape and an ordinary photo keeps to its box; a tiled picture, and a text, keep to their box. `"textWrap": "outline"` is the same with no clearance. A justified text beside a circle: each line ends where the circle, twelve clear, meets it, so the text's edge curves in and out with it. `text-wrap-outline.json`: ```json { "name": "Page", "width": 520, "padding": 24, "fill": "#FFFDF8", "color": "#1B1712", "stack": [ { "name": "Body", "width": 472, "font": "Source Serif 4 15/22", "textAlign": "justified", "at": [0, 0], "text": "The tanpura is not played so much as kept. Four strings, plucked in turn, never quite the same twice, and the room fills with overtones that the singer leans on. Every note is measured against it; the drone is the floor the evening stands on. Listen long enough and the drone stops being a sound and becomes the room itself, the way the rain outside stops being weather and becomes the hour, and the hour becomes the raga." }, { "name": "Moon", "draw": [ { "circle": [80, 80, 80], "fill": {"linear": ["#B8742A", "#5B3A1E"], "angle": 160} } ], "size": 160, "at": ["top right", 0, 20], "textWrap": {"offset": 12, "around": "outline"} } ] } ``` ## Flowing across frames `"flow": ["Col 1", "Col 2", "Col 3"]` on a text writes a story once and sets it through those frames in order: the text fills the first frame, and each later frame gets a text box filling it that starts where the box before runs out, so a longer text moves on into the next column and a shorter one pulls back. The frames are named layers on the text's page, or on another page with `{"frame": "Body", "page": "Page 2"}` (an entry can also be `{"frame": "Col 2"}`); write the text inside the first frame or anywhere in the call, and it moves there. `frames`, `thread` and `into` read as `flow`. Every box keeps the story's style; each box can have its own columns. A box that ends at a paragraph break starts the next box with the next paragraph, as a page in print does, never with an empty line. The last box shows what is left, so a story longer than all its boxes runs past the last one (`TEXT_TRUNCATED` names it), and the reply notes the frames a story fills and how many characters the last does not hold (`TEXT_FLOW`), and a last frame holding only one or two lines of the story warns `RUNT_FRAME`, naming it; a box whose story goes on is not truncated, and shows no ellipsis. `source` writes the story once, with its `flow`, and a sync keeps the boxes it flowed into. A story that goes on onto another page keeps flowing there as you edit it; double-clicking its box on that page shows the page where the story starts and edits it there. One story in three columns: it fills the first, goes on in the second where the first runs out, and ends in the third. Edits reflow it through all three. `text-flow.json`: ```json { "name": "Spread", "width": 764, "height": 300, "padding": 28, "gap": 24, "fill": "#FBF7F0", "color": "#2A2420", "row": [ { "name": "Col 1", "width": 220, "height": 244, "column": [ { "name": "Story", "font": "Source Serif 4 14/21", "textAlign": "justified", "flow": ["Col 1", "Col 2", "Col 3"], "text": "The evening raga begins before the musician plays. It starts in the half light, when the tanpura settles and the room learns its own pitch. Then a single phrase, held and released, tells the listener which evening this is.\nThe drone holds. The voice finds the fourth, leans on it, and the whole room leans with it until the phrase resolves. Nobody in the room is counting; the cycle counts for them, sixteen beats folded so that the first returns as a surprise every time.\nBy the third hour the phrases have grown long enough to lose the beginning before they reach the end, and that is the point: the raga is not a melody but a place, and the musician walks the listener through it, room by room, until the last note closes the door. Outside, the street has gone quiet." } ] }, {"name": "Col 2", "width": 220, "height": 244}, {"name": "Col 3", "width": 220, "height": 244} ] } ``` In the app, editing any box of a story edits the story, from the character you clicked. While you type, every box keeps showing its part and the story reflows through them; clicks, drags and the caret move between the boxes. The Text section's **Continues** menu links a selected box to the box it continues, and `text_continue` with `from` does the same from the command line (`null` unlinks it). ## Paragraphs in a story `"paragraph"` on a span gives the paragraphs its characters start settings of their own; on a text it gives them to every paragraph. A paragraph takes the settings of its first character, as a word processor keeps them on the paragraph's mark, so they travel with the text through edits, copies, `source` and the file. - `"heading"`: kept with the paragraph after it (a heading never ends a frame alone; it moves on with the first lines of what follows), not indented, and the paragraph after it starts flush, as books set it. - `"item"`: a list item written with its own marker (`"— "`, `"1. "`): its lines after the first start under its text, not under the marker. - `"quote"`: every line starts in by `inset`. - `"bullet"`, `"number"` or `"check"`: a list item whose marker Facet draws in the hanging space before it, so a story can mix body paragraphs and list items. Numbers count the items in a row (1., 2., then a., i. for deeper levels) and start over after a paragraph that is no item. `{"list": "→", "level": 1}` draws your own characters, one level in (levels 0 to 8, each a step further). A `list` on the whole text makes every paragraph an item instead (see Lists). - `{"role", "indent", "hang", "inset", "spaceBefore", "spaceAfter", "keepWithNext", "keepTogether", "list", "level"}` sets them one by one, in px: `indent` the first line's (in place of the story's `paragraphIndent`), `hang` how far the later lines start in from it, `inset` every line's, `spaceBefore` and `spaceAfter` the room above and below it (not at the top of a frame), `keepWithNext` the heading's keep without its other settings, `keepTogether` one frame or column for the whole paragraph unless it fills one alone. `"body"` is a plain paragraph; `"none"` removes the settings. On the text, `orphans` and `widows` (1 to 9) keep that many of a paragraph's lines together at the foot of a frame or column and at the head of the next; 1, the default, lets a paragraph break after any line. Keeps hold for a story across frames, for columns, and for a fixed box's last line. A chapter set across two pages: the heading has a line of space above it and keeps the 19 px grid, starts flush, and so does the paragraph after it; the bullets are drawn and their lines hang under the text; `widows: 2` keeps two lines of a paragraph together at the top of the right page. `text-paragraphs.json`: ```json { "name": "Pages", "width": 560, "height": 300, "padding": 28, "gap": 24, "fill": "#FBF7F0", "color": "#2A2420", "row": [ {"name": "Left", "width": 240, "height": 244}, { "name": "Right", "width": 240, "height": 244, "column": [ { "name": "Chapter", "font": "Source Serif 4 13/19", "textAlign": "justified", "paragraphIndent": 13, "widows": 2, "flow": ["Left", "Right"], "spans": [ "The evening raga begins before the musician plays. It starts in the half light, when the tanpura settles and the room learns its own pitch. Then a single phrase, held and released, tells the listener which evening this is.\nThe drone holds. The voice finds the fourth, leans on it, and the whole room leans with it until the phrase resolves.\n", { "text": "The third hour\n", "fontWeight": 600, "fontSize": 15, "paragraph": {"role": "heading", "spaceBefore": 19}, "lineHeight": "19px" }, "By now the phrases have grown long enough to lose the beginning before they reach the end, and that is the point.\n", { "text": "the raga is a place, not a melody, and the musician walks the listener through it;\nthe cycle counts, so nobody in the room has to.", "paragraph": "bullet" } ] } ] } ] } ``` ## OpenType features `fontFeatures` turns a font's OpenType features on or off, for a whole text or for a span: `{"tnum": true}` (tabular figures, which line up in a table's columns), `["smcp"]` (small capitals drawn by the font, not shrunk capitals), `{"onum": true}` (oldstyle figures for running text), `{"liga": false}` (no ligatures), `{"ss01": 1}` (a stylistic set), `{"cv11": 2}` (the second alternate of a character variant), `frac`, `sups`, `subs`. A list turns tags on; a number picks an alternate; CSS's `fontFeatureSettings` (`"\"tnum\" 1, \"smcp\""`) is read as it. A font without a feature ignores it, and the text keeps its metrics; the build warns `FONT_FEATURE_MISSING`, naming the layer, the family and the tag (small capitals in Inter or Fraunces, which have none). Features travel with copies, `source` writes them, and a sync that leaves them out returns the font's defaults. They need the Rust text engine (the default); with `CANVAS_SHAPER=coretext` they are kept but not drawn. ## Raised and lowered characters A span's `baselineShift` sets its characters above the line (a positive number of px) or below it (negative). `"super"` and `"sub"` do the usual thing for the text's size: up a third of it (or down a sixth) and set at 65% of it, unless the span gives its own size: `{"spans": ["E = mc", {"text": "2", "baselineShift": "super"}]}`, `H₂O` with `"sub"`, footnote marks. CSS's `verticalAlign: "super"` is read as it. The line keeps its height; a raised character reaching above it may touch the line before, as in print. ## Underlines and strikethroughs `"underline": true` draws the font's underline; `"strikethrough": true` its strikeout. Either takes a style word (`"dotted"`, `"dashed"`, `"double"`, `"wavy"`, `"solid"`) or an object: `{"underline": {"style": "dotted", "thickness": 1, "offset": 3}}`. The thickness is in px (the font's when left out), and the offset puts an underline's top that many px below the baseline (the font's position when left out). Dots are squares a thickness wide and a thickness apart; dashes are three thicknesses long with two between; a double line is two lines a thickness apart; a wave's period is six thicknesses, and a wavy underline hangs below the letters. The line takes the characters' color. CSS's forms read as these: `"textDecoration": "underline dotted 2px"`, `textDecorationStyle`, `textDecorationThickness` and `textUnderlineOffset`, so the email idiom `border-bottom: 1px dotted` on a link is `"underline": {"style": "dotted", "thickness": 1}`. Every output draws them: the canvas, PNG, SVG and PDF. `inspect` shows them as `"textDecoration": {"line", "style", "thickness", "offset"}`, which a build reads back. ## Highlights `"highlight"` on a span puts a fill behind its characters, a pill inside a sentence: `{"spans": ["Spend rose ", {"text": "12% this week", "highlight": {"fill": "@lilac", "radius": 6, "padding": [1, 6]}}, " across teams."]}`. A color alone is a highlight with square corners and no padding; `"none"` removes it. `padding` is `[vertical, horizontal]` px, or one number for both. The horizontal padding moves the words around the highlight apart, so the pill never touches them; the vertical padding only grows the fill. A highlight is drawn on each line it reaches, as CSS's inline backgrounds are: rounded where it starts and ends, square where a line breaks it. On a text, `highlight` covers all of it. In a span, CSS's `background` or `backgroundColor` with `borderRadius` and `padding` read as a highlight, so a captured `` keeps its pill. Every output draws it under the glyphs: the canvas, PNG, SVG and PDF. `inspect` shows a text's highlight. ## Links `"link"` on a span makes its characters a link: `{"spans": ["Read ", {"text": "the guide", "link": "https://faux.design/docs"}, "."]}`. On a text it covers all of it. Exported PDFs make those characters clickable, one area per line the link covers, so a link that wraps works on both lines. A link is an `https:`, `http:` or `mailto:` URL of at most 2048 bytes; anything else is refused with a note. `"href"` is read as it, and `""` removes a link. `inspect` and `tree` show a span's link, and `source` shows a text's. ## Scripts and symbols Devanagari and other scripts that reorder letters shape as written. Chinese and Japanese are set solid: a line ends between any two of their characters, keeping closing punctuation (`,。)`) with the character before it and opening punctuation with the one after, and a justified line is filled between the characters, since it has no word spaces to stretch. A web address (a word holding `://`) also breaks after `/`, `?`, `&` and `=`, so a long one fills its lines rather than leaving the line before it short. Arabic, Hebrew and other right-to-left scripts read right to left, joined, and a line mixing directions sets each run in its own direction (the Unicode bidirectional algorithm): lines break in reading order, then each line is set for display, and the caret, clicks and selection follow what you see. Alignment stays as set: `textAlign: "right"` sets a right-to-left paragraph against its right edge. Some symbols draw as color emoji by default (zodiac signs, ☕, ⚡, ⭐); put U+FE0E after one to get the font's glyph. A build notes each such symbol, and notes each character the font has no glyph for (`GLYPH_FALLBACK`, naming the font that draws it instead), so a ✖ in a monospace font or an accented letter a display face lacks does not quietly come from another family. Once you have seen it and are content, accept it in the kit: `{"kit": {"fallbacks": {"✓◐": "Hiragino Sans"}}}` silences the note for those characters drawn from that family (`"*"` for any family); the note itself says how. A character no font on the machine has is a `GLYPH_MISSING` warning instead: it shows as a missing-glyph box, never as Apple's LastResort placeholder passed off as a font. ## Where lines break Justified text (`"textAlign": "justified"`) chooses its line breaks for the whole paragraph at once, as book typesetting does (Knuth and Plass), so its spaces come out as even as the words allow rather than one line filled at a time leaving a loose one after it. When the words alone leave a line loose, it hyphenates as TeX does: at the points Liang's patterns find in words of five letters or more, two letters in and three before the end (English's; other languages keep their own), in the text's `"lang"` (`"de"`, `"pt-BR"`; English when absent; about fifty languages have patterns, and one without them for its letters breaks words only at soft hyphens), and never on two lines in a row when it can help it. To choose the breaks yourself, for a language the patterns don't know (romanized Hindi: `"keh\u00ADta"`), put soft hyphens (U+00AD) in a word: it then breaks only there, and they draw nothing where it doesn't. `"hyphenate": false` turns the patterns off for the whole text (CSS's `"hyphens": "manual"` is read as it), so only words holding soft hyphens break. A word joiner (U+2060) between two letters keeps them together. A line separator (U+2028, what a Markdown hard break or `
` becomes) starts a new line in the same paragraph: no paragraph spacing or indent before it, and the line it ends is not stretched when justified; `\n` starts a new paragraph. A hyphenated line ends in a hyphen; copied from a PDF it is a soft hyphen (U+00AD), so the word pastes and searches whole. Only word spaces stretch: an em space, a thin space or another fixed space keeps its width. A tab is as wide as four of the font's spaces and draws nothing, so code indented with tabs keeps its indent. A text with a width wraps after spaces and after a hyphen inside a word ("well-" / "known"). A hyphen that starts a word stays with it, so `--help` and `-5` never split; a word wider than the box breaks between letters. A heading or short paragraph with `"balance": true` breaks its lines evenly, as CSS's `text-wrap: balance` does: it keeps the number of lines it has at its width and breaks them at the narrowest width that still holds that many, so a two-line title does not leave one word alone on its second line. The box keeps its width and alignment; only the breaks move. It evens out paragraphs of two to six lines (a longer one breaks as usual, as browsers do), and justified text breaks optimally instead. `"textWrap": "balance"` on a text is read as it. `facet react dom` sets it from a page's `text-wrap: balance`, and the inspector's **Balance lines** switch sets it by hand. The same heading twice in a 300-wide box: filled line by line, its last line holds only "stands on"; with `"balance": true` its three lines come out nearly even. `text-balance.json`: ```json { "name": "Headings", "width": 340, "padding": 20, "gap": 20, "fill": "#FFFDF8", "color": "#1B1712", "font": "Inter 26/32 700", "column": [ { "name": "Greedy", "width": 300, "text": "The drone is the floor the whole evening stands on" }, { "name": "Balanced", "width": 300, "balance": true, "text": "The drone is the floor the whole evening stands on" } ] } ``` --- # Color Anywhere a color goes (`fill`, `stroke`, `color`, a gradient stop), you can write: | Form | Is | |---|---| | `#1A1423`, `#1A142380` | a color, optionally with alpha | | `oklch(0.92 0.004 286.32)`, `oklch(40% 0.185 27.7 / 0.5)` | CSS Color 4, as Tailwind v4 and shadcn write tokens: also `oklab()`, `lch()`, `lab()`, `hsl()`, `hwb()`, `rgb()` and `color(display-p3 1 0 0)`, `color(srgb …)`, `color(srgb-linear …)`, with percentages, `none` and `/ alpha` | | `color-mix(in srgb, #2563EB, black 20%)`, `color-mix(in oklch longer hue, red, blue 30%)` | CSS Color 5: two colors (hex, a name, a function, another `color-mix()`) mixed in `srgb`, `srgb-linear`, `oklab`, `oklch` or `hsl`, with either percentage or both, and `shorter`, `longer`, `increasing` or `decreasing` hue. The document keeps the mixed value | | `{"pattern": "dots", "size": 8, "color": "@ink", "background": "@paper"}` | a pattern fill: `dots`, `lines`, `grid`, `hatch`, `cross`, `checker`, `halftone` or `dither`, drawn as one small picture that tiles. `size` is the pitch (2 to 256, default 8); `weight` a dot's diameter or a line's thickness; `density` the share a halftone or dither covers (0 to 1; a halftone starts at 0.3, and from about 0.4 its dots touch and read as a checker); `angle` 0, 45, 90 or 135 for lines and a hatch; no `background` leaves the ground clear. Other words are read with a note: `stripes` and `diagonal-stripes` are a hatch (lines when the angle is 0 or 90), `spacing` is the pitch (a `size` beside it is then the mark's own size), and `stroke` and `strokeWidth` are the marks' colour and weight. The ground is the layer's own fill under the tile, so a kit colour there stays bound and follows a Dark copy; the marks are a picture in the colour they were built in and stay as they are (a note says so when the file has modes). Use it for a texture that repeats: thousands of vector marks cost megabytes, and a build that draws 200,000 path points or more says so (`VECTOR_HEAVY`) | | `@ink` | the kit color `ink`, bound to its variable | | `@Theme/surface` | a variable in another collection | | `@Theme/surface\|#FFFFFF` | a variable, painting the fallback until it exists | | `@app/ink/5%\|#0000140D` | a tint of a variable whose name has slashes: the last `/N%` is the tint, and the fallback is the tinted colour | | `@ink/40%`, `#1A1423/40%` | the color at 40% of its opacity | | `{"linear": [stops], "angle": 90}` | a linear gradient; angle 0 runs left to right, 90 top to bottom (the default, as in CSS; CSS counts its own angles from the top, so its `180deg` is 90 here) | | `{"radial": [stops]}` | a radial gradient from the center | Stops are colors spread evenly, or `[color, position]` pairs with positions from 0 to 1. A CSS Color 4 color is drawn in sRGB. One outside it (a vivid `display-p3` or `oklch` color) is brought in by CSS gamut mapping, which lowers its chroma and keeps its hue and lightness, and the build notes `OUT_OF_GAMUT` with the hex it draws. Kit colors, `call variables` and `tokens import` take the same forms; a DTCG file may write a color object in any of these spaces (`{"colorSpace": "oklch", "components": [0.92, 0.004, 286.32]}`). The document keeps the sRGB value, so `tokens export` writes hex. A linear gradient between two kit colors, a radial one with a stop placed at 0.6, a tint, and a stroke. `color-paints.json`: ```json { "kit": { "colors": {"saffron": "#F29F05", "rose": "#D9485F", "dusk": "#2B1E4A"} }, "nodes": [ { "name": "Paints", "gap": 16, "row": [ { "type": "rectangle", "size": 96, "cornerRadius": 20, "fill": {"linear": ["@saffron", "@rose"], "angle": 45} }, { "type": "ellipse", "size": 96, "fill": {"radial": ["@saffron", ["@rose", 0.6], "@dusk"]} }, { "type": "rectangle", "size": 96, "cornerRadius": 20, "fill": "@dusk/20%" }, { "type": "rectangle", "size": 96, "cornerRadius": 20, "fill": "@rose", "stroke": "@dusk", "strokeWidth": 3 } ] } ] } ``` ## Modes Give the kit `modes` and a value per mode for each color, as a list in the order of `modes`: `{"modes": ["Light", "Dark"], "colors": {"surface": ["#FFFFFF", "#0F172A"]}}`. A value per mode by name reads the same (`{"surface": {"Light": "#FFFFFF", "Dark": "#0F172A"}}`), and names the modes when the kit has none. A kit that started without modes gains them the same way, in a later call: its colours keep their value in every mode until one is given, so a file that began plain can still get a dark copy. A later call that gives colours a value per mode need not name the modes again. To move plain colours onto kit colours afterwards, `modify` each layer's `fill`, and set `"color": "@ink"` on a container: it goes to the texts inside that share the colour most of them have, and texts with a colour of their own keep it (`facet copy Card --name "Card Dark" --mode Dark`). `"mode": "Dark"` on any layer shows it, and everything inside it, in that mode. A layer that is already there takes it the same way: `facet modify Card '{"mode": "Dark"}'`, or the key added to your JSON and a `build --sync`. Instances inside take that mode too, wherever their main component is (on another page, or nested in another instance). A colour written on a layer as `{"light": "#FFFFFF", "dark": "#1F2937"}` is read as one of the two with a note (the dark one under a layer with `"appearance": "dark"`); only a kit colour follows the mode. A themed copy of a layer already built: `facet call duplicate '{"nodeIds": ["Login"], "name": "Login Dark", "mode": {"collectionName": "Kit", "modeName": "Dark"}}'`, or build it again with `"mode": "Dark"` and `"after": "previous"` to place it beside the first. The same card twice; the second says `"mode": "Dark"`. The tint `@accent/15%` follows the mode because it is a variable of its own. `color-modes.json`: ```json { "kit": { "modes": ["Light", "Dark"], "colors": { "bg": ["#FFFFFF", "#15121C"], "fg": ["#1A1423", "#F6F1EA"], "accent": ["#D9485F", "#FF7A8F"] } }, "nodes": [ { "name": "Light", "at": [0, 0], "color": "@fg", "fill": "@bg", "padding": 20, "gap": 10, "cornerRadius": 16, "column": [ {"text": "Evening practice", "font": "Inter 18/24 700"}, { "row": [{"text": "Yaman", "color": "@accent"}], "padding": [4, 10], "cornerRadius": 10, "fill": "@accent/15%" } ] }, { "name": "Dark", "mode": "Dark", "at": [220, 0], "color": "@fg", "fill": "@bg", "padding": 20, "gap": 10, "cornerRadius": 16, "column": [ {"text": "Evening practice", "font": "Inter 18/24 700"}, { "row": [{"text": "Yaman", "color": "@accent"}], "padding": [4, 10], "cornerRadius": 10, "fill": "@accent/15%" } ] } ] } ``` For a variable collection that is not the kit's, write `"mode": {"Theme": "Dark"}`. ## Exporting `facet --doc f.facet tokens export --format css` writes the variables as CSS custom properties, one block per mode (`:root` for the first, `[data-mode="dark"]` for the others; a mode named Dark or Light also gets a `prefers-color-scheme` block that applies while the page sets no `data-mode`); `--format dtcg` writes Design Tokens Community Group JSON. --- # Repeat `{"each": data, "do": node}` stands for one node per item, in place, wherever a child can go. Seven bars from seven objects. `"height": "{m}"` takes the number itself, so the bar heights are the data. `repeat-bars.json`: ```json { "name": "Week", "gap": 12, "padding": 20, "fill": "#FFFFFF", "cornerRadius": 16, "column": [ { "text": "Minutes practised", "font": "Inter 13/18 600", "color": "#6F6879" }, { "row": [ { "each": [ {"d": "M", "m": 40}, {"d": "T", "m": 25}, {"d": "W", "m": 55}, {"d": "T", "m": 30}, {"d": "F", "m": 60}, {"d": "S", "m": 15}, {"d": "S", "m": 45} ], "do": { "column": [ { "type": "rectangle", "width": 24, "height": "{m}", "cornerRadius": 6, "fill": "#F29F05" }, {"text": "{d}", "font": "Inter 12/16 600", "color": "#6F6879"} ], "gap": 6, "align": "center" } } ], "gap": 10, "align": "end" } ] } ``` ## What can be substituted | Write | Becomes | |---|---| | `{.}` | the item itself | | `{field}` | a field of an object item | | `{i}` | the index from 0 | | `{#}` | the number from 1 | | `{n}` | how many items there are | `data` may be a list or a count: `{"each": 12, "do": {"text": "{#}"}}` makes 1 to 12. A string that is only `{name}` keeps the value's type (a number stays a number, a list is spread into the list around it); inside longer text the value is written as text. ## With parts `each` and [parts](kit.md) combine: `{"each": ["Sa", "Re", "Ga"], "do": {"chip": "{.}"}}`. --- # Drawing `draw` lists shapes in a box of `size`, with coordinates from its top left corner, y down. Use it for what layout cannot express: dials, charts, marks. For symbols, use an [icon](#icons) first. A gauge: a track arc, a value arc with a gradient stroke, a needle and its hub. Arcs run clockwise from the top, as on a clock face. `drawing-gauge.json`: ```json { "name": "Gauge", "size": [200, 170], "draw": [ {"arc": [100, 100, 80, 225, 495], "stroke": "#ECE6DD", "weight": 14}, { "arc": [100, 100, 80, 225, 405], "stroke": {"linear": ["#F29F05", "#D9485F"], "angle": 0}, "weight": 14 }, {"line": [100, 100, 100, 40], "stroke": "#1A1423", "weight": 3}, {"circle": [100, 100, 6], "fill": "#1A1423"} ] } ``` ## Shapes | Shape | Numbers | |---|---| | `circle` | `[cx, cy, r]` | | `ellipse` | `[cx, cy, rx, ry]` | | `rect` | `[x, y, width, height]`, with `radius` (a number, or `[top left, top right, bottom right, bottom left]`) and `smoothing` (0 to 1: corners that ease into their sides, a squircle; 0.6 is the shape app icons are cut to) | | `line` | `[x1, y1, x2, y2]` | | `poly` | `[x1, y1, x2, y2, ...]`, with `"closed": true` for a polygon | | `arc` | `[cx, cy, r, from, to]` in degrees clockwise from the top: 0 is 12 o'clock, 90 is 3 o'clock, and `[cx, cy, r, 0, 360 * share]` is a progress ring from the top | | `path` | SVG path data; several subpaths make one shape, and one wound the other way is a hole (`fill-rule` even-odd from SVG is kept) | ## Shapes from data: `plot` and `bars` Two shapes are written as values, not coordinates, and are scaled into the drawing's size, up the page: | Shape | Takes | Draws | |---|---|---| | `plot` | `[3, 5, 4, 8]`, or `[[x, y], ...]` pairs | a line through the values, evenly spaced (or at their x) | | `bars` | `[3, 5, 4, 8]` | a bar for each value, standing on 0; `"gap": 0.25` is the share of each slot left free | ```json {"draw": [{"bars": [4, 7, 5, 9], "fill": "@line", "radius": 2}, {"plot": [3, 6, 6, 8], "stroke": "@accent", "weight": 2}], "size": [280, 60]} ``` The lowest and highest value of every such shape in the drawing (and 0, for bars) fill its height, so two series share one scale and nothing is divided by a maximum by hand. `"domain": [0, 100]` on the drawing sets the range. Beside bars, a line's points sit over the middles of the bars. They become an ordinary `poly` and `rect`s with the keys written beside them (`stroke`, `fill`, `radius`, `dash`), so they can be restyled like any shape; other shapes in the same drawing stay in its own units. Under a line, `"area": "@accent/12%"` beside `plot` fills down to the drawing's bottom, and `"dots": 3` puts a dot of that radius on each point (`true` sizes them from the line). A level across the chart is a second `plot` of two points on the same scale: `{"plot": [[0, 30], [11, 30]], "stroke": "@mute", "dash": [6, 4]}`. Written as a chart, `{"chart": "line", "data": [12, 18, 15, 22], "area": {"fill": "#2563EB", "opacity": 0.12}, "points": true, "target": {"value": 20}, "width": 480, "height": 240}` is read as that drawing. One bar in another colour: `"highlight": "@accent"` beside `bars` paints the tallest bar, and `"fills": [null, null, "@accent"]` gives a bar its own (a `null` keeps the shape's `fill`). A ring by its shares is written as a chart and read as a drawing of arcs: `{"chart": "donut", "segments": [{"value": 50, "fill": "@accent"}, {"value": 30, "fill": "@good"}, {"value": 20, "fill": "@line"}], "size": 160, "thickness": 20, "center": {"text": "$48.2k"}}`. `thickness` is the ring's width (`innerRadius` gives the hole instead: a share of the radius up to 1); `center` is a text over the middle, bold and sized to the ring unless it gives its own `font` or `style`. The note in the reply shows the stack of `draw` arcs it became, which is what `source` prints and what you restyle. For the common charts, the kit that ships has parts over these: `{"spark": {"values": [...]}}`, `{"bars": {"values": [...]}}`, `{"stack-bar": {"items": [{"value": 62, "tone": "@good"}, ...]}}` (shares by `grow` weights), `{"meter": {"percent": 62}}` and `legend`. See [the kit](kit.md). ## Paint A frame's own stroke has no caps. For a dotted or perforated border, draw the outline over the frame in a stack: `{"stack": [card, {"draw": [{"rect": [1, 1, 218, 88], "radius": 10, "stroke": "@line", "weight": 2, "dash": [0, 6]}], "size": [220, 90], "inset": 0}]}`; the rectangle sits half a weight inside the drawing so its dots are whole. A drawing with `"width": "fill"` (or `"height": "fill"`) in a row or column takes the room it leaves, and its shapes stretch with it from their `size`: a rule drawn 100 wide spans the column. The drawing's own `fill` (and `cornerRadius`) paints its box under the shapes. Each shape takes `fill` (none by default) and `stroke` (the node's `color` by default when there is no fill), with `weight` (1.5), `dash` (`[dash, gap]`; a dash of `0` with round caps is a dotted line: `"dash": [0, 6]`), `cap` (`round` by default; `none`, `square`), `join` and `opacity` (0 to 1, multiplying its fill and stroke). Colors and gradients read as anywhere else. A shape whose fill or stroke is a kit color alone (`"@rose"`, `"@rose/40%"`) stays bound to it: change the color in the kit, or show the drawing in another mode (`"mode": "Dark"`), and the shape follows. A kit color inside a gradient is written as its value. > **Note** A drawing becomes vector layers. Neighbouring shapes that paint alike (the same fill and stroke, no gradient) and don't touch become one layer, which draws exactly as separate layers would: a grain of 500 dots in one color is one vector, not 500. `"merge": false` keeps a layer per shape, for a drawing you mean to edit shape by shape. Read back with `source`, it comes back as paths. ## Icons `{"icon": "lucide:clock", "size": 16, "color": "@mute"}` draws an icon from the Iconify collections (`lucide`, `mdi`, `tabler`, `ph` and the rest), fetched once and cached. The first use of a name makes a component `Icons/lucide:clock` in a frame named `Icons` beside your work, and the build notes it; every use is an instance of it, so `color` and `size` are per use and one edit to the component changes them all. An icon at another size scales as a whole, its strokes with it, as the icon set draws it at that size. Swap an icon with `modify Icon '{"icon": "lucide:moon"}'`, or from an instance with `{"Icon": "lucide:moon"}`. `color` paints the shapes the icon draws in `currentColor`; an icon drawn in one colour of its own (one read from a page whose stylesheet set its stroke) is recoloured whole. A token stays bound either way, so the icon follows a mode, swapped or not. A nested instance swapped to another variant keeps an icon its component swapped inside it. A smooth-cornered shape that clips what is inside it is a mask: put the drawing first in a stack with `"mask": true`, and the layers after it show only inside its outline. ```json {"stack": [ {"size": [824, 824], "mask": true, "maskType": "vector", "draw": [{"rect": [0, 0, 824, 824], "radius": 185, "smoothing": 0.6, "fill": "#000000"}]}, {"name": "Art", "width": 824, "height": 824, "fill": {"linear": ["#3A2418", "#120A07"], "angle": 60}} ]} ``` --- # React A design can be written in React. `facet react` renders the file with your project's own React, without a browser or a dev server, and builds the result into a document the way `build --sync` does: run it again and only what changed changes. ```sh facet --doc design.facet react render screen.tsx --props data.json facet --doc design.facet react render screen.tsx --props data.json --watch # again on every save facet react render screen.tsx -o screen.json # the build JSON, to read ``` It needs Node.js 20 or later. The first run installs the tool's packages once. A component is rendered once everything it loads lazily has loaded (`React.lazy` behind `Suspense`: an editor, a chart), so the render shows the part itself, not its loading skeleton; with React 17 or earlier it is rendered at once. ## The pieces `@facet/react` gives the build language as components. A prop is a key of the language, written as the language writes it, so everything on the other pages applies: `gap`, `padding`, `fill`, `width="fill"`, `dividers`, `at`, `grow`. ```tsx import { Box, Column, Kit, Row, Span, Text, component } from "@facet/react"; const Switch = component("Switch", { variants: { State: ["Off", "On"] } }, ({ State }) => ( )); export default function Settings({ options }) { return ( Awake until 4:30 {options.map((option) => ( {option.title} ))} ); } ``` | Piece | Is | |---|---| | `Row`, `Column`, `Grid`, `Stack`, `Ring`, `Frame` | the containers | | `Text`, `Span` | a text; a `Span` styles part of it; a component among the words makes it a sentence that wraps around it | | `Icon`, `Box`, `Space` | an icon (`name="lucide:bell"`), a layer with no children, room in a flow: `` fills, `` is 12 px | | `Draw` with `Circle`, `Ellipse`, `Rect`, `Line`, `Poly`, `Arc`, `Path`, `Plot`, `Bars` | a drawing; shapes take `at` (or `d`, or `values`) and their paint | | `Connect` | `label`: an arrow between two named layers | | `Kit` | the file's kit, said in the code: colours with modes, type presets, the font, `use="facet:basics"` | | `Use` | a kit part, preset or component by name: `` | | `component(name, { props, variants }, render)` | a component of the design | | `Node` | any other node, as JSON | ## What React gives the design - **Components are components.** `component()` makes one master in Facet and an instance at every use. `props` are its text properties (`{ Label: "Draft" }`), `variants` its axes, the first value of each the default; a variant is stored as what differs from the default. A variant that adds or removes layers is reported (`VARIANT_SHAPE`). - **Tokens live in the code.** `` anywhere in the screen is sent with it; nothing is sent separately. - **Keys.** React's `key`, on a piece or on a component of yours that is mapped over data, is the layer's `key`: a reordered or renamed row is moved, not replaced. - **Types.** The package types every piece from Facet's own grammar (`facet guide types`), so a wrong value, a wrong word or a variant a component does not have is a compile error in your editor, when the project has the package's types: a project that installs `@facet/react`, or a `tsconfig.json` whose `paths` point `@facet/react` at the tool's copy (`~/.facet/react/BUILD/src/index.d.ts`). A render does not type-check: there a wrong prop is an `INPUT_IGNORED` warning with the nearest key and the line that wrote it. - **Source lines.** Every layer carries the line that wrote it. Facet's warnings about it end with `(source: screen.tsx:42)`, and `facet inspect` shows it. - **Your app's components** go in beside Facet's pieces and are read through their CSS (for a Tailwind project, `--css` names the stylesheet). What the reader does not understand is reported as `CSS_UNREAD`, never dropped silently. ## Options | Option | Does | |---|---| | `--project DIR` | the project whose React and packages the file uses (default: the current folder) | | `--props FILE` | JSON given to the component as its props | | `--export NAME` | render that export instead of the default one | | `--page NAME` | build into that page whatever is showing | | `--preview PNG` | write a picture of what was built | | `--watch` | render again when the file, the project's sources or the data change | | `-o FILE` | write the build JSON to a file and build nothing | `facet react stories button.stories.tsx` reads a Storybook stories file: the component as a set from its variant options, and each story. ## The way back An edit made in Facet to a rendered layer is overwritten by the next render, as with any generator: the source is the truth. To keep the edit, take it back: `facet --doc design.facet react source "Options"` (a layer's name, its id, or a selector such as `"List > Row"` when names repeat) prints that layer as Facet holds it now, written with the pieces, and `facet inspect` (or any warning about it) names the file and line it came from. Paste it there. ```tsx Keep the display on ``` A component or a kit part comes back as ``: swap in your own component's name. ## What of the app's CSS is read App components are read through the project's stylesheet the way a browser reads it: every rule whose selector matches an element counts, not only its own classes. That covers rules for elements (`h2`, `button`), children and siblings (`.card > p + p`, Tailwind's `space-y-2`, `divide-y`, `*:p-1`, `[&>svg]:size-4`), attributes (`data-[state=on]:…`, `aria-selected:…`), position (`first:`, `odd:`), what an element holds (`has-[>svg]:…`), a checked box beside it (`peer-checked:…`), ids, `@layer` and `!important`; the winner is the one a browser would pick. Breakpoints are answered for one page size, 1280 by 800 unless `--viewport` says another: ```sh facet react render screen.tsx --viewport 390 # a phone: `md:` rules do not apply facet react render screen.tsx --viewport 1440x900 ``` What only holds in a state (`hover:`, `focus:`, `group-hover:`) or in the dark scheme is not drawn. What could not be read is said, by rule: `CSS_RULE_UNREAD` for a pseudo-element (`::before`, `placeholder:`), a container query, or a pseudo-class it does not know. ## A page from a browser `facet react dom` reads a page the way a browser laid it out: it opens the URL or HTML file in headless Chrome (a profile of its own; a Chrome you have open is not touched), asks for every element's computed style and box, and builds from that through the same map. ```sh facet --doc design.facet react dom http://localhost:3000/orders --root main facet react dom page.html --viewport 390x844 --tree tree.json -o screen.json ``` `--root` is a selector for the elements to read (the page's body when left out). A page behind a login is read from a Chrome that is already signed in: start one with a debugging port (or allow remote debugging in `chrome://inspect/#remote-debugging`) and pass its DevTools address as `--attach ws://127.0.0.1:PORT/devtools/browser/…`; the page opens in a tab of its own, which is closed when it has been read, and no other tab is looked at. The reader waits until the page has fetched and drawn what it was going to, and takes entrances that are still playing to their end. `--shot page.png` writes the browser's own picture of what was read, and `--assets DIR` says where the pictures of its images go. Nothing of the project is needed: no source, no stylesheet. What it cannot know is where a colour came from, so the layers hold colours, not tokens. `render --html page.html` writes a render as such a page, to see what a browser makes of the same component. What only the browser knows is said in the tree, so the map needs no font and no stylesheet to place a layer where the page has it: | The tree says | So the build | |---|---| | each element's `box` | gives children the room the browser measured, sizes table cells and shares (`calc(100% + 2px)`, `min-height: 100%`) from it, and places a turned box by the upright box around it | | `words`: the box around an element's own text | fills a heading that its container stretched, where another line says how wide the container is | | `clipped`: its content is cut off at its edge | gives a truncated label, and a box that cuts what it holds, the width it was measured at (one line with an ellipsis) | | `::before`, `::after` and `::marker` as elements of their own | builds a dot, a rule, a badge in a corner, a bullet or a number where the browser drew it | | a shadow root's children and a slot's content | builds what a web component lays out | | `faces`: the fonts the browser drew symbols in | sets an arrow or a sign the page's face lacks in the face that drew it | | `picture`, alone on a clear ground | an `img`, a `canvas` or a `video` frame as a picture; with `flattened`, an element no layer can draw (a filter other than blur, a mask, a clip path, a perspective) as one picture, said with `CSS_FLATTENED` | | `painted` | a background no fill can be (a repeating or conic gradient, blended layers) as a picture of the box's own paint, its children still layers | | `backgrounds`: the pictures a background names | image fills that cover, contain, tile or sit where `background-position` puts them, with gradients over them as layers | | `font-size` as drawn | uses the size `font-size-adjust` left, not the one the stylesheet wrote | | an `svg`'s paint in its markup | draws a ring or an icon coloured by a class: `fill`, `stroke`, width and dashes are written where the stylesheet set them, a colour as sRGB, the text colour as `currentColor` | ### Who drew it, every state, and the data behind it A development build of a React app keeps a record on each element of the component that drew it, the props it was given and where in the code it was made. `--components` reads them and finds each file and line through the page's own source maps: every layer that a component of the app drew is named for it, and `--sources sources.json` writes, by layer name, the component, its props, the file that defines it (`source`) and the line that used it (`used`), so a change to the layer can go back to its code. A library's components and the framework's are left out. Nothing is added to the app; a production build has no such records and says `COMPONENTS_UNKNOWN`. `--states` puts each element a person can act on (links, buttons, fields, anything with a pointer cursor) in `hover`, `active` and `focus-visible` through DevTools and writes what changes, in it and in what it holds, as its `states`. `--record DIR` keeps every answer to the page's requests for data (not its scripts or pictures, and not the framework's own fetches of rendered components). `--replay DIR` answers those requests from the folder instead of the network, on any host, so a recording from a signed-in page renders the same on a local development server. `--patch patch.json` changes answers first: `[{"match": "/api/items", "set": {"items[id=a1].status": "done", "total": 0}}]` sets each path of the JSON of every answer whose URL holds `match` (`[3]` steps into a list by position, `[id=a1]` into each item whose `id` starts with `a1`). An entry with `"answer"` (and `"status"`) is the answer whole, recorded or not: the reply to a write. One recording and a few patches are every state of a page, read at its real URL, with the app untouched. A request is matched by what it sent (method, path, query and body); one whose body the recording does not hold is answered with the recorded request on that path most like it, field by field, and said (`REPLAY_LOOSE`): an answer to another request may be of another shape, so if the page shows an error, record it again on this build or answer it with a patch. A read the recording does not hold goes to the network and is said (`REPLAY_MISSED`); a write it does not hold is never sent: it gets an empty 200 and is said (`REPLAY_FAKED`). (A recording made before 0.3.189 kept each answer in place of what was sent; its requests match by path, said as `REPLAY_LOOSE`. Record again to match by body.) Before the page is read it is woken and held still: lazy pictures are asked for at once, the page is scrolled through a screen at a time and back (what fades in when it is seen is shown), the pictures are waited for (5 s at most), an entrance still playing is taken to its end, and what never ends (a spinner, a marquee, an SVG's own animation, a video) is held at its start, so two reads of a page agree. What a closed shadow root lays out is read as an open one's is; a frame is read through and clipped where the frame shows it, one of another origin through its own DevTools session; a drawing that uses a sprite's symbol or a gradient defined elsewhere in the page holds them; a drawing whose vectors cannot carry what it does (a filter, a picture inside it, words along a path, HTML inside it) is the browser's picture of it (`CSS_FLATTENED`), and its clip paths draw as masks; an image is its own file at its own size where Facet fits it as the page does (`object-fit: cover` is `fill`, `contain` is `fit`), else the browser's picture of it; and a closed `
` holds only its summary. The page's own faces come along: each family, weight and style it loaded is decoded from WOFF or WOFF2 into a font file, and goes into Facet's font cache (`FONT_SHIPPED`), so its words are drawn in the very files the page drew them in. A family Google Fonts does not offer keeps the page's name for it; one it does offer is often another version (blender.org's Inter sets 5% wider than today's), so the page's files go in renamed as the family and the page's host, `Inter (blender.org)`, and the texts the page set in it name that: no other document's Inter changes. `--theme dark` (or `light`) reads the page in that colour scheme, as its `prefers-color-scheme` media queries draw it. Without it a page is read light, whatever the Mac's appearance, so a capture comes out the same at any hour; with `--attach` it is read as the browser you attached to shows it. `--pick` brings the page's tab to the front with DevTools' own element picker: what you click is what is read (as `--root` would name it). `--absolute` gives up the page's own layout: every box stands where the browser measured it and is as large, as a capture that keeps geometry exactly does; a box drawn at a scale is its layers there, at the scale, not a picture; by default the rows, columns and grids are rebuilt as auto layout, so the design stretches and wraps as the page does. `--widths 1440,768,390` reads the page at each width in turn (its media queries answered for that width) and builds one screen for each, named `1440 wide`, `768 wide` and so on, side by side, each as wide as the width it was read at. `--open SELECTOR` opens what it names before the page is read (a menu, a popover, a dialog, a side sheet): pressed with the pointer as a person would. Only if that press changed nothing at all (no element, word or request) is it tried from the keyboard, then by script, so a control that does something is never pressed twice. `--click SELECTOR` presses once and lets the page settle, with no check: a tab, an action, a toggle. With `--each-step` the page is read as it opens and again after each step, one screen each, side by side and named for the step (`Start`, `Step 1 · click #more`): a flow. Each step's read does the steps before it again from the page as it opens, so every screen comes out the same however often it is read. Give each once for each thing to do, in order; `OPEN_FAILED`, `OPEN_MISSING` and `CLICK_MISSING` say what did not happen, and `CLICK_AMBIGUOUS` (or `OPEN_AMBIGUOUS`) names a selector that matched several elements and which one, the first, was pressed. `--tokens` names each element's colours by the page's own CSS variables: which declaration won, as DevTools has it, followed through a theme's aliases (`--color-muted: var(--muted)`) to the one that holds the colour, a tint as `muted/50%`, and a text colour no rule sets as its parent's. Each name's light and dark values are read too (the dark with the page's dark selector, such as `.dark`, on ``). The build refers to them (`@muted`) and defines them as kit colours with `Light` and `Dark` modes, so the page switches theme as the app does. The page's scripts are held still from the read until its colours are named (a page fed by a stream draws itself again), a declaration that names a variable is taken over a base reset listed after it, and each name is kept only where it is the colour the browser painted (a tint by its alpha), so a name is never wrong; what is left is a value. `--tokens-in PREFIX` refers instead to the document's own variables named `PREFIX` (`@app/muted`, with the page's colour as a fallback) and defines none: a design system that holds them as aliases to its roles restyles every captured screen when its mode changes. ```sh facet react dom https://app.example.com/orders --attach ws://… --record rec/ # once, signed in facet react dom http://localhost:3000/orders --attach ws://… --replay rec/ \ --patch shipped.json --components --states --sources orders.sources.json -o orders.json ``` `--assemble` (on `dom` or `map`) turns those records into components, the units a change goes back to. Every component of the app that drew a frame is one set, used once or many times, named after the component whose code drew the layer (a popover or tooltip that only passes on what another component wrote names nothing: the component that wrote it does). Its uses become instances of it: - A prop whose values tell their looks apart (`variant`, `size`, `isActive`; two together when one is not enough) is a variant property. A flag a use leaves out is `false`. - Where a prop decides the shape (a button with words, or an icon alone), the template holds every shape's layers, each kept to the values that have it (`only`); shapes no prop tells apart are told apart by a `Shape` property. - The states read with `--states` are a `State` property (`Default`, `Hover`, `Pressed`, `Focus`), for a control a person presses (a button, a link, a tab, a field). - Each drawing is an icon component (`Icons/page:NAME-N`), so a use that draws another icon swaps it, as it says its own words. - Each instance keeps its place and says its own words, icons and the variants of the instances inside it as overrides (a layer inside a nested instance by its path, `Settings > Icon`), and any fill, colour, stroke or size that differs as its layers' own keys (`$nodes`). - Uses whose own layer is another kind of container (a row in one place, a column in another) are a set each. A prop whose values are prose (a tip, a title) varies by whether it is given (`true`, `false`), not by its words. Components inside components are made first, so a set holds instances of the sets in it. A layer that looks like no variant of its set stays a layer. Each layer a component drew keeps that component's file and line as its `$source`, and each instance where it is used when the read knows it, so a change made in Facet goes back to its code: `facet where NODE` names the components a layer is in, innermost first, each with its file, and the layer as the innermost component's own layer. Stacking, effects and moves come across as a layer has them: `z-index` orders a box's children (one below zero goes behind the box its stacking starts at), `transform`, `rotate`, `scale` and `translate` (a turn, a skew, a scale, a mirror, or a 3D turn without a perspective, which the page shows flat) are the layer's `matrix`, its words and boxes inside it read upright and drawn through it, with margins that keep the room CSS gave it; only a perspective (or boxes turned in 3D together) is the browser's picture, and a back the page hides (`backface-visibility: hidden`) is left out; a relative box's offsets are margins that move nothing else, `filter: blur()` and `backdrop-filter: blur()` are blur effects, `mix-blend-mode` is `blendMode`, an `outline` is a stroke layer pinned outside the box, `visibility: hidden` is opacity 0, a box kept for a screen reader (`clip: rect(0 0 0 0)`) is left out, `-webkit-line-clamp` is `maxLines`, and `white-space: pre` keeps its spaces. Colours in a space wider than sRGB come as the sRGB the screen shows. Texts of a page read this way are `"fractional"` (see [Text](text.html)): as wide as the browser measured them. Rows and groups of a table draw no borders unless the table's borders collapse, a grid's `align-items` is its `align`, `width: max-content` with `min-width: 100%` hugs with a least width, and room an inline run keeps beside itself (`margin-left` on a span) is a space in its sentence. Checked on four screens of a running app at 1440 x 900: every layer's box is within 1.5 px of the browser's (185, 248, 620 and 228 boxes), and between 1.0% and 2.2% of pixels differ from the browser's own picture, nearly all of it the edges of letters, which the two rasterisers smooth differently. Colours are still values, not tokens, and nothing is a component yet. ## A component as a package to build from `facet --doc design.facet react handoff Chip --out handoff/` writes what a developer, or a smaller model, needs to build the component `Chip` (a set or a single component) so `verify` matches it: - `HANDOFF.md`, the brief. It covers the `data-part` contract, how a build is checked, the rules that keep a build exact (border-box, padding already inside the border, the app's CSS variables, paint order, copying each variant's values rather than deriving a rule), the properties with their defaults, the modes, and every variant's parts with a box and CSS each. - `handoff.json`, the same as data: variants, and parts in tree order. Each part has a box relative to the root, its parent part, its CSS, for a vector its path as SVG, and its code line (`source`) when the design records one (`$source`, as `dom --components` and `render` write it). The package names the component's code (`code`): the set's or a variant's own line, else the file most of its parts were written in. The file also holds the variables, each with its value in every mode. - `variables.css`: every variable on `:root`, and each other mode of its collection under `[data-mode="NAME"]`. A build that imports it and uses the variables draws every mode. - A picture of each variant at 2×, named after it (`state-idle.png`), and `icons/` with each icon as SVG in `currentColor` (each icon part's `color` says what it is drawn in). - `behavior.json`, when a statechart is bound to the component: its events, views and plays; `slots`, the layers its events act on (`{"Label": ["PRESS"]}`: a press on the part `Label` sends `PRESS`); and `scenarios`, the chart as a table a build can run as it is: each state names the view it shows (a value of the variant property) and where each event leads (`"Saving": {"view": "Saving", "on": {"DONE": "Saved", "FAIL": "Idle"}}`), with guards and variables already worked out per scenario. A component built on a headless behaviour library takes its state from the table, binds each slot's press to its events, and keeps the look from the variants. Values bound to variables are written as `var(--name, fallback)`: colours, and also sizes, radii, gaps, padding and opacity, so a mode that changes density changes the build too. A variable is named after the token (`@Kit/line` is `--kit-line`); `--css-prefix app/` names the tokens under `app/` after the app's own variables (`@app/text-primary` is `--text-primary`), which is how `dom --tokens-in app/` names them. An instance inside the component is one part, named after its layer; its insides are its own component's handoff. How the CSS keeps the design's geometry: - **Hugging.** A layer that hugs its content across a row or column is `fit-content`, because `auto` stretches there. - **Placement.** A layer placed by `at`, or inside a frame without auto layout, is `position: absolute`. Its `left` and `top` (or its `inset`, when it is pinned to the parent's edges) are measured as Facet measures them, from the parent's outer edge. - **Paint order.** Beside such a layer, every child has a `z-index` in Facet's paint order, so a background placed under a label stays under it. **Part names.** A layer the design tool named by itself (`Frame 1233`) has a different number in every variant. Its part is named by its place instead: `Lead › Frame 2`, its parent's part and then its place among such siblings. That name is the same in every variant, and `verify` looks for the same name. ## A built component against its design `facet --doc design.facet react verify URL --component "Composer/State=Idle, Mode=Light"` measures a component a developer (or an agent) built against the component in the document, part by part. **The contract is one name per part.** Each layer of the component has a name, and the built markup marks the same part with `data-part="Name"`; the root takes the component's root layer name. Parts pair by that name alone, never by order or class, so the markup can be structured any way. A name used several times pairs the nth with the nth. **What it measures.** Every part's x, y, width and height are taken relative to its own root on each side, then compared. A part is within `--tolerance` px (0.5 by default) or it is reported with its deltas, worst first. Parts the build does not mark are listed, and so are marked parts the design does not have. Boxes are outer boxes on both sides: a Facet stroke is inside its box, as a CSS border is with `box-sizing: border-box`, so a bordered box's CSS padding is the Facet padding less the stroke. **Looks and pixels.** Each part's fonts, colours and spacing are compared with what the browser computed, a stroke outside the box as an outline. A vector's paint is left to the pixels. `--pixels` also compares the root's picture with the design's (an isolated shot on `--background`, `#ECECEC` by default): at most `--pixel-share` (2%) of pixels may differ by more than `--pixel-threshold` (48), after both pictures are softened over 3×3 so edge smoothing does not count. **Modes.** `--mode Kit=Dark` checks the variant in a mode of the design's variables. The design is switched to that mode while it is read and drawn, then put back, and the page should set `data-mode` to match. **Output.** `--json FILE` (or `--report FILE`) writes the whole comparison for an eval to score, with both pictures beside it. The command exits 3 when anything is off, missing, or the root is unmarked. The page is read as `dom` reads it, so `--viewport`, `--attach` (a signed-in Chrome), `--open` and `--click` work the same; a Storybook story's iframe URL reads one story. ## The trees between the render and the build A render becomes a design in steps, and each step hands the next one file. The cascade finds the CSS in effect on every element and writes the **declared tree**: the elements, their attributes, and their styles as the stylesheet wrote them. The **computed tree** is the same elements with every `var()` replaced, every shorthand taken apart into longhands, lengths in px and each colour's token named. The map reads only the computed tree. `--tree tree.json` writes the tree beside the result (the declared one from `render`, the computed one from `dom`), and `facet react map tree.json` builds from either alone, with no project, no React, no stylesheet and no Node at hand. `--computed computed.json` on `map` writes the computed tree it mapped: ```sh facet react render screen.tsx --tree tree.json -o screen.json facet --doc design.facet react map tree.json ``` So a design that comes out wrong can be looked at in halves: is the tree what the app's CSS says, and is the build what that tree means. `tools/facet-react/CONTRACT.md` in Facet's source describes every field of both trees. ## What it does not do yet Hover and focus states are not drawn. A component's behavior is passed through as the build language writes it (`component(name, { behavior }, render)`); React state and effects are not read. Rendering needs Node (the first run installs the tool's packages; a lone file needs no project of its own): Facet does not run React by itself. Everything after the render is Facet's own: what the CSS means is worked out and mapped inside `facet`, the same way for any tree. --- # Components A set is a component with variants. `set` names it; `variants` lists each variant property and its values; `template` is the node every variant starts from. Write a set this way: `"type": "component-set"` with a `name` is its long spelling and `variantMatrix` that of `variants`, read by the same reader, so they build the same set, but `set` is the one form the examples use. Three variants of a card. `{Name}`, `{Hour}` and `{Last}` bind texts to the set's properties; `only` keeps a layer to the variants that use it; the Locked variant sets its own `Last`. `raga-card.json` (after raag-kit.json, listed at the end): ```json { "set": "Raga/Card", "props": { "Name": "राग भैरव", "Hour": "MORNING", "Last": "Last riyaz 2 days ago · 25 min" }, "variants": { "State": { "Learning": {}, "New": {}, "Locked": { "fill": "#F3EFF7", "props": {"Last": "Opens after 21 days of Yaman"} } } }, "template": { "width": 300, "padding": 18, "gap": 8, "fill": "#FFFFFF", "cornerRadius": 20, "column": [ {"eyebrow": "{Hour}", "color": "@mute"}, {"deva-xl": "{Name}", "font": "Tiro Devanagari Hindi 24/30"}, { "row": [{"swara": "रे॒"}, {"swara": "ध॒"}], "gap": 6, "only": "Learning" }, {"small": "{Last}", "color": "@mute", "only": ["Learning", "Locked"]}, { "name": "Progress", "only": "Learning", "stack": [ { "type": "rectangle", "width": 264, "height": 6, "cornerRadius": 3, "fill": "@ink/8%" }, { "type": "rectangle", "width": 180, "height": 6, "cornerRadius": 3, "fill": "@saffron", "at": "left" } ] }, { "row": [ { "text": "Start learning", "font": "Inter 14/20 700", "color": "#FFFFFF" } ], "padding": [8, 14], "cornerRadius": 16, "fill": "@ink", "only": "New" } ] }, "behavior": { "axes": { "history": ["fresh", "practised"], "streak": { "values": ["short", "long"], "when": {"history": ["practised"]} } }, "start": "Loading", "states": { "Loading": {"LOADED": "route"}, "route": [ "history == 'fresh' -> New", "streak == 'long' -> Learning", "Locked" ], "New": {"START": "Learning"}, "Learning": {"PAUSE": "Locked"}, "Locked": {"UNLOCK": "Learning"} }, "plays": {"Begin a new raga": ["LOADED", "START"]}, "targets": {"START": "Start learning"} } } ``` ## Variants ```json "variants": {"State": ["Learning", "New", "Locked"]} "variants": {"State": {"Learning": {}, "Locked": {"fill": "#F3EFF7"}}} ``` The first value of each property is the default. A value's map changes that variant: keys for the root, `$nodes` for named layers, and `props` for its own property values. A `$nodes` entry for a nested instance is written as the instance is: `{"$nodes": {"Nav alerts": {"State": "Active", "Label": "Alerts"}}}` puts the sidebar's Alerts item in its Active state in that variant only (`$variant` works too). A text that names a variant property shows each variant's own value: `{"text": "{Tier} plan"}` reads "Free plan" in `Tier=Free` and "Pro plan" in `Tier=Pro`. No property needs declaring for it, and a text can name several (`"{Lead} · {State}"`). The set lays its variants out as a grid: the last property's values run across and the other properties' down, so `Lead` (7) × `State` (2) × `Density` (2) is 2 columns of 14 rows. `"columns": "State"` (or a list of properties) picks what runs across. The set is drawn with a dashed purple outline around its variants in the app and in previews; each variant is a component of its own inside it. Without `variants`, a set is one component that only has properties: `{"set": "Date tile", "props": {"Month": "OCT", "Day": "30"}, "template": {...}}` makes the template a component, and instances set `Month` and `Day` as with any set. There is no variant property to choose, so no dummy axis is needed. ## Properties `props` declares the set's properties once, with their defaults. A text written `"{Name}"` follows `Name`, and a property sets a whole text, so `"{Action} →"` is refused: give the arrow a text of its own. a layer with `"visible": "{Show retry}"` shows or hides with a boolean. Instances set them by name. A nested instance's property can follow the set's: `{"Pill": {"Label": "{Count}"}}` in the template has the set's `Count` drive the pill's `Label`, so `{"Badge": {"Count": "5"}}` shows 5 in its pill, and the set's own variants show `Count`'s default. The pill stays an instance of `Pill`. A variant that sets its own value (`"props": {"Last": "Opens after 21 days of Yaman"}`) keeps that text; the property's value applies in the other variants. When every value of a variant property sets its own, no instance can change it, and the build warns `INPUT_IGNORED`: write the text in each variant instead, or leave one variant to follow the property. A part's argument can be a property: `{"chip": "{Hour}"}` inside a template binds the chip's text to `Hour`. ## Layers in some variants: `only` `"only": "Learning"`, `"only": ["Learning", "Locked"]`, or `"only": {"State": ["Learning"]}`. In a set with several properties a plain value names the property that has it, and values of different properties must all hold (`["Ready", "Bad"]` is State=Ready and Tone=Bad); a value two properties share needs the map form. Other variants leave the layer out instead of hiding it, so a set with many views stays small. A layer only some variants hold can make those variants larger; the set gives each column and row the room of its largest variant, so that is fine. ## Instances Use a component by its name. Keys that name a variant property choose the variant; the rest set properties, or override a layer's text by name. `name` beside the component names the instance, which matters when a screen holds several: `{"Plan": {"Tier": "Pro"}, "name": "Pro card"}`. An override (`$override`) names a layer of the instance, and reaches every layer of that name below it. When the instance holds instances that each have a layer of one name (a menu of items, each with an `Icon`), a path names one of them: `{"$instance": "Menu", "$override": {"Settings > Icon": "lucide:settings", "Settings > Label": "Settings"}}`, as `find` reads ` > `. An override of a nested instance takes the same form as the instance: `{"Nav alerts": {"State": "Active", "Label": "Alerts"}}` chooses its variant and then sets its properties, and a variant chosen this way keeps the values the component gave that instance (its label and its count stay). An override of a text says its words and their look; how the text sizes (to its words, to its lines, or fixed) stays the main component's, so changing the main's resize changes every instance's, overridden or not. Three instances; each chooses its State and sets the raga's name and hour. `raga-library.json` (after raag-kit.json, raga-card.json, listed at the end): ```json { "name": "Library", "gap": 20, "align": "start", "row": [ {"Raga/Card": {"State": "Learning"}}, { "Raga/Card": { "State": "New", "Name": "राग भीमपलासी", "Hour": "AFTERNOON" } }, { "Raga/Card": { "State": "Locked", "Name": "राग मालकौंस", "Hour": "LATE NIGHT" } } ] } ``` A bare value sets a component's only text property: `{"Button": "Pay now"}`. ## Changing a set Build it again with `--replace`: the set changes in place, so each variant keeps its identity and instances on every page follow, keeping what they set. When its variant properties change, a new set takes the old one's place and this page's instances move to the variants with the same names. `facet find '[component=Plan]'` lists a set's uses on the page showing, wherever the set itself is (a library page beside the screens), and `facet components` counts them and lists the components from other pages that the page uses. [`--sync`](update.md) changes it in place too, and is all that adding a value to a variant property needs (`"Tone": ["Info", "Warn"]` gaining `"Bad"`): the new variant is added and every instance stays as it was. Use `--replace` when a property is added, removed or renamed. --- # Behavior A set can say how it behaves: which state shows first, which events move it on, and what decides the way in each scenario. One build stores the set, its statechart, the binding of states to variants and its design axes, as a feature named after the set in lower case with dashes (`Raga card` is `raga-card`). The build's reply names it; every chart command takes that name. The [raga card](components.md) above carries this behavior: ```json "behavior": { "axes": {"history": ["fresh", "practised"], "streak": {"values": ["short", "long"], "when": {"history": ["practised"]}}}, "start": "Loading", "states": { "Loading": {"LOADED": "route"}, "route": ["history == 'fresh' -> New", "streak == 'long' -> Learning", "Locked"], "New": {"START": "Learning"}, "Learning": {"PAUSE": "Locked"}, "Locked": {"UNLOCK": "Learning"} }, "plays": {"Begin a new raga": ["LOADED", "START"]}, "targets": {"START": "Start learning"} } ``` ## States - A state named like a value of the set's variant property **shows that variant** (`New`, `Learning`, `Locked`). - A set with several variant properties names the one its states show: `"property": "State"` beside `start`. The other properties (`Kind`, `Size`) stay design dimensions; each state keeps the instance's values of them. - `{"EVENT": "Target"}` moves on when the event happens. A target may be `"guard -> Target"`, a list of those (the first whose guard holds wins), or `{"target", "guard", "assign"}`. - A state written as a **list** moves on at once: `route` picks the next state by the scenario. It is never on screen, so it needs no variant. - `note`, nested `states`, `initial` and `type` (`parallel`, `final`) are written as in the full chart format. ## Behaviors by name The common ones ship, so a set need not write them: `"behavior": "toggle"`. | Name | Moves through | Events | |---|---|---| | `toggle` | off, on | `TOGGLE` | | `press` | rest, pressed | `PRESS`, `RELEASE` | | `disclosure` | closed, open | `OPEN`, `CLOSE`, `TOGGLE`, `DISMISS` (closes) | | `task` | idle, busy, done, failed | `START`, `DONE`, `FAIL`, `RESET` | Their states are roles. A set whose variant values carry those names (in any case: `Off`, `On`) needs nothing more; another says which value plays each role, and adds what is its own beside it: the layers events act on, plays, and states or moves of its own, which lie over the named ones. ```json "behavior": {"use": "toggle", "as": {"off": "Unchecked", "on": "Checked"}, "targets": {"TOGGLE": "Box"}, "states": {"Unchecked": {"DISABLE": "Disabled"}, "Disabled": {"ENABLE": "Unchecked"}}} ``` A role left without a value is refused, with the set's values to choose from. ## Scenarios `axes` name what varies between situations. Every combination is a scenario; guards read the axis values. An axis with `when` applies only where earlier axes take those values and keeps its first value elsewhere, so `streak` does not double the fresh scenarios. ```sh $ facet chart raga-card 3 scenarios over history (fresh, practised) × streak (short, long): 3 to 4 configurations each Views: New reachable where history is fresh, streak is short Learning reachable in every scenario Locked reachable in every scenario Coverage: 4/10 transitions over every scenario untested in 3 scenario(s): Learning --PAUSE--> Locked untested in 3 scenario(s): Locked --UNLOCK--> Learning Play skeletons (shortest paths to what no play reaches): Covers Learning --PAUSE--> Locked: LOADED → START → PAUSE Covers Locked --UNLOCK--> Learning: LOADED → START → PAUSE → UNLOCK Reaches Locked: LOADED → START → PAUSE Covers Locked --UNLOCK--> Learning: LOADED → UNLOCK Covers Learning --PAUSE--> Locked: LOADED → UNLOCK → PAUSE Reaches Learning: LOADED → UNLOCK Covers Learning --PAUSE--> Locked: LOADED → PAUSE Covers Locked --UNLOCK--> Learning: LOADED → PAUSE → UNLOCK Reaches Locked: LOADED → PAUSE ``` `facet chart` says where each view is reachable by axis values, what is not covered, and the shortest event sequences to reach what no play reaches (`--full` lists every scenario). Its words: | Word | Means | |---|---| | scenario | one combination of axis values; an axis with `when` adds values only where it applies | | configuration | the set of states active at once; a chart has a few per scenario | | transition | one event moving one state to another, counted once per scenario where it can happen | | coverage | the transitions the plays take, of all transitions | | reachable in every scenario | some event sequence shows the view whatever the axis values | | play skeleton | the shortest event sequence to a view or transition no play reaches; name it under `plays` to keep it | ## Plays and targets `plays` name event sequences to replay on the canvas: `facet plays run raga-card "Begin a new raga"` runs one in every scenario and says where it ends. `targets` name the layer each event acts on, so replays click the right thing; they are optional, and events without one replay without a click. ## Using an instance `facet act` lists every instance on the page whose component has a statechart: the view it shows and the events it takes now, each with the layer it acts on. `facet act NODE EVENT` sends one event to one instance (its id or its layer name). Its chart moves from the view the instance shows, and the instance shows the view it reaches: ```sh facet --doc f.facet act # "Save" (25), save-button: shows Idle; takes PRESS (on "Label") # "Wifi" (18), switch: shows Off; takes TOGGLE (on "Knob") facet --doc f.facet act Wifi TOGGLE # Wifi took TOGGLE: Off -> On; takes TOGGLE (on "Knob") facet --doc f.facet act Save PRESS # Save took PRESS: Idle -> Saving; takes DONE, FAIL facet --doc f.facet act --at 260,69 # a press at a point of the page: the event whose target layer holds it ``` Each instance has its own place in the chart, variables included, kept while the document stays open: a chart that counts wrong codes locks the instance that had three, not its neighbour. An instance changed by hand goes on from the view it shows. An event the view does not take fails, and the message lists the ones it takes. In the app the **Use** tool (**U**) does the same with clicks: a click on a layer an event acts on sends that event. Each event is one undo step; `--scenario k=v` chooses the axis values the guards read. `facet act --follow` prints every event an instance takes, from the command line or from clicks with the Use tool, as it happens: `EVENT Save PRESS from=Idle to=Saving number=3`. An author that wrote the screen as a [stream](stream.md) reads these and answers with change lines, so the screen is used and rewritten in one loop; `facet act --after 3` prints what came after event 3 and ends. > **Why** A design made of components that know their states can be used, not only looked at: an agent reads what a screen takes and acts on it in one call each way, with no pictures and no clicks to aim. ## Looks `looks` are design axes: `{"Look": {"Light": "Kit/Light", "Dark": "Kit/Dark"}}` shows each option in a mode of the kit's variables. Lattice views (`facet lattice`) cross them with the scenarios. The full chart format, for what the compact one does not cover, is in [Chart](chart.md). --- # Changing designs Three ways to change what is there, from smallest to largest. | Change | Use | Keeps | |---|---|---| | a few values | `modify NODE '{...}'` | everything else | | a tree, by writing it again | `build @tree.json --sync` | ids, instances, comments of every layer that still matches | | a component set | `build @set.json --replace` | its instances and what they set | ## Read it back first `source` prints a layer as you would write it: the shortest form, with containers as `{"row": [...]}`, plain texts as strings, the font and color a container passes down lifted back to it, kit colors and styles by name, instances as `{"Component": {...}}`. ```sh $ facet source Library {"row":[{"Raga/Card":{}},{"Raga/Card":{"State":"New","Hour":"AFTERNOON","Name":"राग भीमपलासी"}},{"Raga/Card":{"State":"Locked","Hour":"LATE NIGHT","Name":"राग मालकौंस"}}],"gap":20,"name":"Library","at":[1020,0]} ``` `--depth N` stops after N levels and counts the children it left out. `source` prints what is there. Parts come back expanded, because a part leaves no link, and values equal to their defaults are left out. So for a screen you built from parts, keep editing your own JSON and send it with `--sync`; read with `source` what you did not write, or what someone changed by hand. A kit tint prints as you write it (`@rose/20%`). Variable bindings print as their variables, numbers and strings as well as colors (`"width": "@Probe/size"`, `"gap": "@Probe/gap"`, `"text": "@Probe/label"`), and a layer that sets a mode prints it (`"mode": {"Probe": "B"}`), so what `source` prints builds a tree that still follows its modes. A layer in a plain frame or a stack that is pinned other than to the top left prints its place (`"at": "center"`, or `["bottom right", -8, -8]` when it sits off it), which keeps both its spot and how it follows the frame's size. ## Sync `build --sync` matches what you write against the existing tree and changes only what differs: - a written node matches the existing child with the same `key` or name (unnamed nodes match the next unnamed child of the same kind; several children with the same name match in order, so give repeated parts a `key`: inside `each`, `"key": "{id}"` is filled per item like any other text, and the layer keeps its key with the document, so a sync finds it after its name, text or order changed); - a match of the same kind is updated in place; a match of another kind, and anything new, is built; - existing children that nothing matches are deleted; - children end in the written order. Keys you write are applied. A key you leave out keeps its value; write `"none"` to clear a fill or stroke. The whole sync is one undo step, and the reply counts what it did: `Synced: 2 changed, 1 added, 0 removed; 14 other layers were already as written.` `--preview` renders the synced tree as it does a build. To add one child, `build @child.json --parent ID` appends it last in its parent. To put it anywhere else, sync the parent with the child where it belongs. > **Tip** Give layers you will change a `name` or a `key`. Matching by name keeps a layer's id even when it moves to another place in the list. ## Modify `modify` takes the same keys as a node, for one layer and, with `$nodes`, its named descendants: ```sh facet --doc f.facet modify Card '{"fill": "@paper", "$nodes": {"Title": {"text": "Tuesday", "font": "Inter 20/26 700"}}}' ``` On an instance, `"props"` or `"properties"` sets its component properties. On any other layer, the layer's own keys inside them apply as if given directly (`{"properties": {"gap": 12}}` sets a row's gap), keys given directly win, and anything else is reported. A layer whose size changes (a row gaining a child, a bound size, a mode switch) keeps the point its constraints pin: a centered row stays centered, where a fresh build puts it. ## Replace a set `build @set.json --replace` builds the set again in the old one's place. Instances move to the new variants with the same names and keep the properties they set. ## Replays A script that animates a design by syncing it again and again (a step every second or two) is not followed by the agent's cursor or the outlines of what changed: a sync that repeats the same agent's sync of the same layers within five seconds shows neither, so the cursor does not sit over what the replay shows. Its first step, and any one-off edit, show them as usual. `--quiet` (`"presence": false`) hides them for one call; `"presence": true` shows them for a call that would otherwise be quiet. ## Copying to another file `source` writes an instance by its component's name (`{"Chip": {"Label": "Shipped"}}`), which builds only in a file that has that component. `facet --doc A.facet source Row --detach` writes each instance as the layers it shows instead, so `facet --doc B.facet build` of that source shows the same layers in a file without the components (as plain layers, no longer linked to them). --- # 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](codes.md) 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. The headline is meant to fit on one line in a 240 px card. It takes three, and the build says so. `checks-expect.json`: ```json { "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} } ] } ``` | Key | Holds when | |---|---| | `lines` | a text has exactly this many lines, or within `{"min", "max"}` | | `maxLines` | a text has at most this many | | `fits` | nothing in the layer is clipped or cut short | | `width`, `height` | the layer is this size, or within `{"min", "max"}` | | `noOverlap` | the 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. --- # For agents The language was measured against real agent sessions. These habits keep both tokens and round trips low. ## The cheapest loop 1. **Kit first, once per file.** Colors, type presets and every repeated shape as parts. Later calls send only nodes. 2. **Build whole screens in one call.** A list of nodes builds several top-level layers at once. 3. **Read the reply, not a screenshot.** Warnings and `expect` misses name the layer and the fix. Ask for `--preview` when you need to see the result, not after every call. 4. **Read back with `source`, change with `--sync`.** Never rebuild from scratch to change a value. ## Budget | Task | Typical cost | |---|---| | A kit for an app | 600 to 1,000 tokens, once | | A phone screen using the kit | 600 to 1,000 tokens | | Reading a screen back (`source`) | 1,500 to 2,000 tokens | | A component set with states and behavior | 800 to 1,500 tokens | ## When something goes wrong | Reply says | Do | |---|---| | `INPUT_IGNORED` with a suggestion | fix the key it names; for a key the language says another way (`arrow`, `table`, `sparkline`, `check`), the warning gives that way with an example | | `"x" is not a key, a kit preset or part, or a component` | check `facet kit` and `facet components` | | `NOT_APPLIED: width "fill" needs an auto-layout parent` | put the layer in a row or column, or give a number | | `LAYOUT_OVERFLOW` | let the frame hug, make it larger, let a child wrap or shrink, or say `"overflow": "hidden"` (or `"clip": true`) if the clipping is meant; a drawing that bleeds past a frame clipping on purpose is not reported | | `EXPECT_FAILED` | change the layout until the expectation holds | | `Outcome unknown` after a long build | the host may still be working: wait, then `find` before retrying | ## Machine-readable documentation - [llms.txt](llms.txt) lists every page with a one-line summary. - [llms-full.txt](llms-full.txt) is all of it in one file, examples included. - `facet guide` prints the whole reference; `facet guide reference` prints it as JSON. ## MCP `facet mcp` serves the same tools over MCP on stdio, acting on the design in front in Facet (and opening Facet if it is not running); `facet --doc f.facet mcp` serves one file instead. [Connect your AI](connect.md) sets it up in each app. --- # Agent card Everything most builds need, in the order you need it. The other pages go deeper, and [the full documentation](llms-full.txt) holds all of them in one file. ## Commands ```sh 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. A kit and a card in one call. Every later call names `@ink`, `title` and `chip` without sending them again. `card-start.json`: ```json { "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"} ] } ] } ``` - **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 | 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](text.md) 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 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. `card-set.json` (after card-start.json, listed at the end): ```json { "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" } ] } ] } ``` - `"{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](behavior.md). ## 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: ``, ``, ``, ``, ``, ``, ``, `` with ``, ``, ``. `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](react.md). ## 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 (`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. --- # Updates and uninstalling ## Updates Facet checks for a new version once a day. When there is one, it shows what changed and offers **Install Update**; Facet restarts in a few seconds with your files reopened. Choose **Facet › Check for Updates…** to check now. The `facet` command and the skill your assistants use live inside the app, so they update with it. With Homebrew, updates still arrive inside the app; `brew upgrade --cask --greedy facet` also works. ### Beta builds Choose **Facet › Receive Beta Builds** to get beta builds before they become releases, as well as every release; a check mark shows it is on, and choosing it again goes back to releases only. From Terminal: `facet setup channel beta`, `facet setup channel stable`, or `facet setup channel` to see which you are on. Going back to releases does not undo a beta you installed: you move on at the next release. ## Uninstall Choose **Facet › Uninstall Facet…**. It removes: - the `facet` command it installed (and a `facet` or `canvas` link an earlier version left on your PATH), - the Facet entries it added to your AI apps (with a backup of each file it changes) and the skill links, - Facet's settings, recent files, thumbnails, logs and session (`~/.facet`), - its caches, downloaded fonts among them (`~/Library/Caches/design.faux.facet`), and its preferences and saved window state in `~/Library`, - the app itself, once Facet quits. It never touches your designs (`.facet` files stay where they are, in Documents › Facet or wherever you saved them) or your design systems. **Keep Settings and Uninstall** also keeps settings and recent files for a later reinstall. From Terminal, `facet uninstall` does the same; `facet uninstall --dry-run` lists what it would remove and removes nothing, and `facet uninstall --keep-data` keeps settings and recent files. `facet uninstall --yes` runs without the question, for scripts; `--json` prints what it removed. If you installed with Homebrew: ```sh brew uninstall --cask facet # the app and the command brew uninstall --zap --cask facet # also settings, caches and skill links ``` > **Note** A skill you uploaded to Claude's chat lives in your Claude account: remove it in Claude under **Settings › Capabilities › Skills**. --- # Troubleshooting ## "Facet can't be opened" Facet is notarized by Apple, so a downloaded copy asks once and opens. If macOS refuses instead, open **System Settings › Privacy & Security**, scroll to the message about Facet and click **Open Anyway**. Download Facet again from [faux.design](https://faux.design) if the message says the file is damaged: the download was cut short. ## Facet asks to move to Applications Facet is running from the download window or the Downloads folder. Click **Move to Applications**: from anywhere else it cannot update itself, and your AI apps cannot find it. ## Connect says Facet must be in Applications AI apps remember where Facet is, so Facet connects them only from the Applications folder (or your own Applications folder in your home folder). Move Facet there, open it from there, and connect again. ## My assistant says it has no Facet tools 1. In Facet, open **Facet › Connect AI Apps…**. If the app shows **Repair**, click it; if it shows **Connect**, click it. 2. Quit the assistant completely (⌘Q, not just closing its window) and open it again. Claude, ChatGPT and Codex read their tools only at startup. 3. In Terminal, `facet setup` shows what Facet set up for each app. 4. Claude (desktop app) writes what went wrong to its logs folder, `~/Library/Logs/Claude/` (the file with `facet` in its name). ## My assistant edits the wrong design The Facet tools act on the design in front in Facet. Click the design's tab, or name the file in your request ("in Welcome.facet, …"); assistants can list your open designs and open others. ## macOS asks whether an app may access a folder When an assistant opens a design in Documents, Desktop or Downloads for the first time, macOS asks whether that app (for example Claude) may access the folder. Allow it, or keep designs in **Documents › Facet** and allow it once. ## "facet: command not found" The command is not installed, or Terminal was open before it was. Choose **Facet › Install Command Line Tool…**, then open a new Terminal window. The command always works by its full path: `/Applications/Facet.app/Contents/Helpers/facet`. ## Text shows in a different font Facet downloads Google Fonts the first time a design uses them; until then, and offline, it uses a stand-in and the design shows a font warning. Reconnect to the internet and reopen the design. Fonts that are not on Google Fonts must be installed on your Mac (double-click the font file). ## "Opened read-only; update Facet to edit" The file was saved by a newer Facet. This build shows it (a **Read-only** chip sits beside its name) and exports it, but will not write it, so nothing you change by hand or from an assistant is saved: update Facet (**Facet › Check for Updates…**), or save a copy in this build's format with `facet --doc f.facet save --to copy.facet`, which opens editable and leaves the original as it was. An assistant's change is refused with `READ_ONLY`. A file holding a part this build cannot read at all is refused with the part's name and both versions. ## Facet quit unexpectedly macOS keeps a crash report under **Console › Crash Reports** (`~/Library/Logs/DiagnosticReports/Facet-*.ips`). Attach it to an issue at github.com/uxfreak/facet; every release keeps the symbols that turn it into function names and lines, so nothing else is needed. ## Start over `facet setup disconnect all` removes Facet from every assistant; **Facet › Connect AI Apps…** connects them again. To reset Facet completely, [uninstall](updates.md) and install again; your designs are never removed. --- # Gallery Each of these is built by the docs build from the source beside it. ## A phone screen Raag's Today screen. With the kit sent once, the screen itself is about 900 tokens. `raag-today.json` (after raag-kit.json, listed at the end): ```json { "phone": { "name": "Today", "children": [ { "row": [ { "draw": [ {"path": "M20 2v14", "stroke": "@ink", "weight": 2}, { "circle": [20, 30, 14], "fill": {"linear": ["@saffron", "@rose"], "angle": 160} } ], "size": [40, 46], "name": "Mark" }, { "column": [ {"title": "Raag"}, {"deva": "आज का रियाज़", "color": "@mute"} ] }, {"space": "fill"}, {"icon": "lucide:settings-2", "size": 22} ], "gap": 12, "align": "center", "width": "fill" }, { "stack": [ { "draw": [ { "circle": [150, 150, 144], "fill": {"radial": ["#FFFFFF00", "@rose/10%"]}, "stroke": "none" }, { "circle": [150, 150, 120], "stroke": "#1A142333", "dash": [2, 6] }, { "arc": [150, 150, 120, 270, 315], "stroke": {"linear": ["@saffron", "@rose"], "angle": 45}, "weight": 14 } ], "size": 300 }, { "ring": [ { "each": ["रात", "सुबह", "दोपहर", "शाम"], "do": {"deva": "{.}", "color": "@mute"} } ], "r": 86 }, { "column": [ {"deva-xl": "यमन"}, {"small": "Yaman's hour", "color": "@mute"} ], "align": "center" } ], "width": "fill" }, { "type": "paragraph", "width": "fill", "runs": [ "It's evening, so Yaman. Every note is shuddha except ", {"swara": {"note": "तीव्र म", "tone": "@rose"}}, ": sing it a touch sharp, and land on ", {"swara": "नि"}, " and ", {"swara": "ग"}, " more than on ", {"swara": {"note": "सा", "tone": "@mute"}}, "." ] }, { "row": [ {"sticker": {"label": "12 दिन लगातार", "turn": -4}}, { "sticker": { "label": "Tanpura in C♯", "tone": "#E3E7FA", "turn": 3 } }, {"sticker": {"label": "40 min", "tone": "#F9D7DD", "turn": -2}} ], "gap": 10, "align": "center" } ] } } ``` ## A component library Three instances of a set whose states, properties and behavior come from one build. `raga-library.json` (after raag-kit.json, raga-card.json, listed at the end): ```json { "name": "Library", "gap": 20, "align": "start", "row": [ {"Raga/Card": {"State": "Learning"}}, { "Raga/Card": { "State": "New", "Name": "राग भीमपलासी", "Hour": "AFTERNOON" } }, { "Raga/Card": { "State": "Locked", "Name": "राग मालकौंस", "Hour": "LATE NIGHT" } } ] } ``` ## Metrics Three metric cards from one part. Each sparkline is a `poly` drawn in the part, with its points passed as a parameter. `gallery-metrics.json`: ```json { "kit": { "font": "Inter 14/20", "colors": { "ink": "#14161B", "muted": "#5B606B", "line": "#E3E5EA", "good": "#1E7A55", "bad": "#C2306F", "cobalt": "#2B4ACB" }, "type": { "kpi": "Schibsted Grotesk 30/34 800 -0.5", "label": "Inter 12/16 600 +0.6 caps" }, "parts": { "metric": { "params": { "label": "", "value": "", "delta": "", "tone": "@good", "points": [0, 0] }, "node": { "column": [ {"label": "{label}", "color": "@muted"}, {"kpi": "{value}"}, { "row": [ {"text": "{delta}", "font": "13/18 600", "color": "{tone}"}, {"space": "fill"}, { "draw": [ {"poly": "{points}", "stroke": "{tone}", "weight": 2} ], "size": [80, 28] } ], "width": "fill", "align": "center" } ], "width": 220, "padding": 16, "gap": 6, "fill": "#FFFFFF", "stroke": "@line", "cornerRadius": 14 } } } }, "nodes": [ { "name": "Metrics", "gap": 12, "color": "@ink", "row": [ { "metric": { "label": "Traces today", "value": "48,210", "delta": "+12% vs Sat", "points": [0, 22, 13, 18, 27, 20, 40, 12, 53, 14, 67, 8, 80, 4] } }, { "metric": { "label": "Error rate", "value": "2.4%", "delta": "+0.9 pts", "tone": "@bad", "points": [0, 20, 13, 21, 27, 18, 40, 16, 53, 10, 67, 9, 80, 3] } }, { "metric": { "label": "p95 latency", "value": "812 ms", "delta": "−40 ms", "points": [0, 6, 13, 9, 27, 8, 40, 14, 53, 16, 67, 20, 80, 22] } } ] } ] } ``` ## Settings A settings list from two parts. The third row passes its own control in place of the toggle. `gallery-settings.json`: ```json { "kit": { "parts": { "toggle": { "params": {"on": "#2B4ACB", "at": "right"}, "node": { "stack": [ { "type": "rectangle", "width": 44, "height": 26, "cornerRadius": 13, "fill": "{on}" }, { "type": "ellipse", "size": 20, "fill": "#FFFFFF", "at": ["{at}", 0, 0] } ], "width": 44, "height": 26, "padding": 3 } }, "setting": { "params": {"title": "", "detail": "", "control": {"toggle": {}}}, "node": { "row": [ { "column": [ {"text": "{title}", "font": "15/20 600"}, {"text": "{detail}", "color": "#5B606B"} ], "width": "fill", "gap": 2 }, "{control}" ], "width": "fill", "align": "center", "gap": 16, "padding": [14, 0] } } } }, "nodes": [ { "name": "Settings", "font": "Inter 14/20", "color": "#14161B", "width": 380, "padding": [8, 20], "fill": "#FFFFFF", "cornerRadius": 16, "column": [ { "setting": { "title": "Daily digest", "detail": "Email and Slack at 09:00" } }, { "setting": { "title": "Only when something changed", "detail": "Skip quiet days", "control": {"toggle": {"on": "#C9CDD6", "at": "left"}} } }, { "setting": { "title": "Time zone", "detail": "Asia/Kolkata", "control": { "row": [ {"text": "Change", "font": "14/20 600", "color": "#2B4ACB"} ] } } } ] } ] } ``` --- # 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) | Key | Forms | What 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 | | `style` | `preset or text style name` | on a text or a container; {"preset": "text"} is a text in that preset | | `color` | `@name \| @name/40% \| #hex` | on 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) | | `inset` | `px \| [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] | | `each` | `list \| count` | with "do": NODE, one node per item; {.} is the item, {i} its index, {#} its number, {field} a field | | `space` | `number \| "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) | | `set` | `name` | a 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 | | `only` | `value \| [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 | | `$source` | `string` | where 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 | | `key` | `string` | what 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 | Key | Forms | What 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) | | `name` | `string` | layer name; results return ids by name, and $nodes/$override address layers by it | | `children` | `[NODE, ...]` | child nodes, in order | ## Size and place | Key | Forms | What it does | |---|---|---| | `width` | `number \| "fill" \| "hug"` | "fill" takes the free room of an auto layout parent; "hug" fits the content ("100%" and "auto" also work) | | `height` | `number \| "fill" \| "hug"` | as width | | `minWidth` | `number` | also maxWidth, minHeight, maxHeight; a hugging container stops at its max, and a child that fills it gets the max | | `x` | `number` | position in the parent; ignored inside auto layout unless "position": "absolute" | | `y` | `number` | as x | | `position` | `"absolute" \| "auto"` | absolute takes a child out of its parent's flow (pinned bars, badges) | | `skew` | `degrees \| [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 | | `rotation` | `degrees` | counterclockwise, 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 | Key | Forms | What it does | |---|---|---| | `gap` | `number \| {"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) | | `dividers` | `color \| 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) | | `between` | `NODE` | on a row or column: that node repeated between each pair of children (a dot, an arrow icon) | | `padding` | `number \| [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 | | `wrap` | `bool` | rows 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 | | `margin` | `number \| [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 | | `grow` | `1 \| weight` | fill 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) | | `columns` | `number \| [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 | | `columnSpan` | `number` | grid 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 | | `rowSpan` | `number` | grid child: rows it spans (a tall card beside two short ones) | ## Look | Key | Forms | What 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, ...] \| null` | fills 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 | | `stroke` | `color \| gradient \| [paint, ...]` | border; with strokeWidth (default 1) and strokeAlign (inside, center, outside) | | `strokeWidth` | `number \| [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 | | `cornerRadius` | `number \| {"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 | | `opacity` | `0..1` | layer opacity | | `blendMode` | `"pass-through" \| "normal" \| "multiply" \| "screen" \| "overlay" \| ...` | layer blend mode (18 modes) | | `clip` | `bool` | clip 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 | | `visible` | `bool` | false hides the layer ("hidden": true also works) | | `locked` | `bool` | lock against pointer edits | ## Text | Key | Forms | What it does | |---|---|---| | `text` | `string` | the 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 | | `fontSize` | `number \| "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 | | `fontWeight` | `100..900 \| "Regular" \| "Medium" \| "Semi Bold" \| "Bold" \| ...` | weight | | `fontFamily` | `string` | family name; one this machine lacks is fetched from Google Fonts, otherwise substituted with a warning | | `color` | `color \| "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 | | `lineHeight` | `number \| "150%" \| "auto" \| {"unit":"PIXELS"\|"PERCENT"\|"AUTO","value"}` | line height | | `letterSpacing` | `number \| "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) | | `fractional` | `true \| false` | a 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 | | `underline` | `true \| "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 | | `highlight` | `color \| {"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 | | `columns` | `1..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 | | `dropCap` | `2..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 | | `paragraphIndent` | `number \| {"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 | | `orphans` | `1..9` | on 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 | | `widows` | `1..9` | on a text: fewest lines of a paragraph carried alone to the head of the next frame or column (see orphans) | | `balance` | `bool` | on 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 | | `hyphenate` | `bool` | on 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 | | `lang` | `language 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) | | `baselineShift` | `px \| "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) | | `link` | `URL \| ""` | on a text or a span: an https:, http: or mailto: link; exported PDFs make those characters clickable; "" removes it (href reads as it) | | `textWrap` | `px \| {"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 | | `$textStyle` | `style name` | follow a text style; a new name creates the style from this layer | ## Components | Key | Forms | What it does | |---|---|---| | `$instance` | `component or set name` | an 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 | | `scale` | `number (0.01 to 100)` | with $instance: show the component scaled, strokes, radii, effects, spacing and text included (a live thumbnail) | | `template` | `NODE` | in 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) | | `$clone` | `node id` | copy 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} | | `$exposeInstance` | `true` | with 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 | Key | Forms | What it does | |---|---|---| | `$image` | `file 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 | | `tileScale` | `number (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) | | `svgPath` | `SVG path data` | vector: 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` | ` markup` | vector 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 and become text layers placed by baseline and text-anchor (a or turned text is not, SVG_TEXT_DROPPED); a (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 | | `merge` | `bool (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`). --- # Commands Every command, with its arguments. Each runs against a file with `facet --doc FILE COMMAND` (add `--headless` for a host of your own, without the app), or against the open window without `--doc`. `facet guide TOOL` prints the same for one command. The table names each argument as `facet call TOOL '{json}'` takes it; the flag beside it is the command-line form. ## build Create a whole tree in one call: frames with auto layout, text, images, vectors, instances with variants and overrides, component sets and variable references. Returns every node id by layer name. From a generator: facet build --watch --run 'python3 make.py' [--files 'recipes/*.py'] runs it, syncs the JSON it prints (or the @file it writes) and does both again whenever a watched file changes: without --files, the source files under the current folder (the generator among them); with --files, only the files those patterns match, so name the generator's own file too. As lines: facet build --stream reads one layer per line (`kind#Name key=value | text`, two spaces of indentation to go inside the line above; then PATCH NAME key=value, REPLACE NAME | text, INSERT kind#Name after=SIBLING, DELETE NAME) from stdin or @file.sxl and syncs what each batch of lines changed, so a design shows while it is still being written; --print writes the JSON the lines stand for. ```sh facet build @screen.json [--sync] [--replace] [--again] [--strict] [--parent NODE [--index N | --before SIBLING]] [--component] [--preview out.png] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `schema` | | NODE | required | the tree to build (see the grammar below); a bare node also works | | `parentId` | `--parent` | id / name | | build inside this frame instead of on the page | | `index` | `--index` | number | | with parentId: where the new layer goes among the parent's children, 0 first (default: last) | | `before` | `--before` | id / name | | with parentId: the child of the parent the new layer goes before | | `position` | | {x, y} | | page position of the root (default: right of existing content) | | `convertToComponent` | `--component` | bool | | make the root a main component | | `replace` | `--replace` | bool | | replace the top-level node of the same name: the new one takes its place, its instances move to the new components with the same names (else the variants keeping their values), and the old one is deleted (one undo step) | | `again` | `--again` | bool | | add a second top-level layer of a name that is already there; without it (and without sync or replace) such a build is refused, since it is nearly always a build run again where a sync was meant | | `sync` | `--sync` | bool | | change the top-level node of the same name in place to match: layers that still match keep their ids, instances and comments; the rest are added or deleted; gap, padding, fill, stroke, cornerRadius, opacity, effects, rotation and a text's width and maxLines an earlier source wrote and this one leaves out go back to their defaults (one undo step) | | `presence` | | bool | | whether the app shows this call: its agent cursor and the outlines of what it changed. Left out, a sync that repeats the same agent's sync of the same layers within a few seconds (a replay) shows neither and other calls show both; false hides them (CLI --quiet), true shows them | | `prune` | | bool | | with sync: delete the page's top-level layers this call does not write (main components, component sets and the Icons frame stay), so a source that writes fewer frames than before leaves none behind; the reply names them (SYNC_PRUNED) | | `preview` | `--preview` | path | | write a PNG of the result (the written node, or the page) | ```sh facet build '{"name": "Card", "width": 320, "padding": 16, "gap": 8, "fill": "#FFFFFF", "cornerRadius": 12, "column": [{"text": "Hello", "font": "Inter 20 700"}, "Plain text"]}' ``` ## source A layer written in the build language, shortest form first: what you would write to build it, ready to edit and send back with build --sync. Variable bindings print as their variables (@Collection/name), a layer's mode as "mode", and a pinned layer in a frame by its place ("at": "center"). It names the kit's colours, presets and parts; the kit itself is `facet kit`, and a new file needs it first ({"kit": …, "nodes": [source]}). ```sh facet source NODE [--depth N] [--detach] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id / name / selector | required | the layer | | `depth` | `--depth` | number | | levels of children to include (all by default) | | `detach` | `--detach` | bool | | write instances as the layers they show, not by their component's name, so the source builds in another file that lacks the components (CLI --detach) | ```sh facet source Card ``` ## kit The document's kit: its font, colors, type presets and parts, as you would write it. ```sh facet kit ``` ## pages The document's pages; "add" makes a page and shows it (with "show": false, keeps the page showing), "show" shows one, "rename", "move" and "delete" change them; pages are named by name or id. Every tool works on the page showing, or on the page its "page" argument names (name or id) without showing it. Ids in later commands are those of the page showing: pass --page NAME, or show the page first. ```sh facet page [list | add NAME [--keep] | copy PAGE NAME | show PAGE | rename [PAGE] NAME | move PAGE N | delete PAGE] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `add` | | name | | add a page with this name and show it | | `copy` | | {page: name} | | a new page holding a copy of every top-level layer of the page named, each where it was; component sets and main components stay where they are and the copies' instances follow them (one undo step) | | `show` | | name / id / false | | show this page; with "add", false keeps the page showing | | `rename` | | name / {page: name} | | rename the page showing, or each page named (one undo step) | | `move` | | {page: position} | | move each page to a position in the page order, 0 first (one undo step) | | `delete` | | page / [pages] | | delete pages with their layers; the last page stays (one undo step) | ```sh facet call pages '{"add": "Flows"}' ``` ## modify Change an existing node with the same keys as build; edit named descendants with "$nodes", an instance's layers with "$override" and its variant with "$variant". ```sh facet modify NODE @props.json [--preview out.png] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id / name / selector | required | the node to change: its id, or a layer name or selector that matches exactly one node (a name a top-level layer shares with layers inside others means the top-level one) | | `schema` | | props | required | keys to set, e.g. {"fill": "#000", "$nodes": {"Title": {"text": "Hi"}}} | | `all` | | bool | | change every layer nodeId matches (a name several layers share, a selector, "A, B"), in one undo step | | `preview` | `--preview` | path | | write a PNG of the result (the written node, or the page) | ```sh facet modify 12 '{"$nodes":{"Title":{"text":"Welcome back"}},"fill":"#F8FAFC"}' ``` ## tree The page structure: ids, names, types, positions and sizes, nested. ```sh facet tree [NODE] [--depth N|all] [--full] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id | | start here instead of the page | | `depth` | `--depth` | number / "all" | | levels to expand (default 4); a node cut off below that has "truncated": true and its childCount | | `detail` | `--full` | "full" | | every node with all its properties, as inspect shows them | ```sh facet tree --depth 2 ``` ## inspect Everything about one node in grammar keys: position, size, sizing, layout, look, text, component facts, children. ```sh facet inspect NODE ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id | required | the node | ```sh facet inspect 12 ``` ## where Where a layer is in code: the components it 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. From the $source a generator wrote (facet react dom --components writes the app's files). ```sh facet where NODE ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id | required | the node | ```sh facet where 12 ``` ## probe Lays nodes out as build would, without keeping them: returns each node's size and place and, for texts, the lines they take, the line height and where each line starts in the content (to paginate or split text). A list, or a kit with nodes, answers one result per node, in the kit's styles. It builds on a scratch copy: the document and its undo history are never touched. ```sh facet probe JSON ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `schema` | | node / [nodes] / {kit, nodes} | required | what to measure, as build takes it | ```sh facet --doc f.facet probe @block.json ``` ## reveal Brings a layer into view in the window showing the file: centered at the same zoom when it fits, else framed whole (--fit always frames it). It changes only the view, never the document, and does not bring the window forward. ```sh facet reveal NODE [--fit] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id / name / selector | required | the layer | | `fit` | `--fit` | bool | | frame the layer whole even when it already fits | ```sh facet reveal "Pricing card" --fit ``` ## find Nodes matching a selector: Name, "[name^=Card]", "[type=text]", "[component=Button]" (the instances of a component or a set), "[fill=#2563EB]" (layers of that colour; a text by the colour of its words; "[fill=@brand]": bound to that variable), "[fontSize>20]" (texts by size: =, >, >=, <, <=), "[font=Inter]" (texts in a family), "[cornerRadius=8]" (a layer's own numbers: cornerRadius, width, height, opacity, with the same comparisons), "#12", "Card Title" (descendant), "Card > Title" (child), "A, B". Names may contain spaces ("Card Coil > Photo"); [name="..."] matches one name exactly. ```sh facet find SELECTOR [--in NODE] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `selector` | | string | required | what to match | | `scope` | | id | | search inside this node only | ```sh facet find '[type=text]' --in 12 ``` ## components Component sets (with their variant properties and values in order, first is the default) and main components. ```sh facet components ``` ## variables Create a variable collection with any number of modes, in the document's variables (saved with the file, shown in the Variables window); a value may be {"alias": "Collection/name"}. Reference variables in builds as "@Collection/name|fallback": fills, strokes, gradient stop colors and positions, radius, stroke width, size, gap, padding, opacity (percent), font size, letter spacing, text and visibility stay bound, and set_mode switches a subtree's mode. ```sh facet call variables @tokens.json ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `collectionName` | | string | required | e.g. Theme | | `modes` | | [string] | | e.g. ["Light", "Dark"] (default one mode) | | `variables` | | [{name, type, value / values}] | required | type: color, number, string, boolean; values: {Mode: value or {"alias": "Collection/name"}} | ```sh facet call variables '{"collectionName":"Theme","modes":["Light","Dark"],"variables":[{"name":"surface","type":"color","values":{"Light":"#FFFFFF","Dark":"#0F172A"}}]}' ``` ## set_mode Show a subtree in another mode of a collection: every property bound to that collection's variables takes the mode's value. ```sh facet call set_mode '{"nodeId":ID,"collectionName":C,"modeName":M}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id | required | subtree root | | `collectionName` | | string | required | the collection | | `modeName` | | string | required | the mode | ```sh facet call set_mode '{"nodeId":"12","collectionName":"Theme","modeName":"Dark"}' ``` ## design_system Variables with their modes, components, and the colors and text styles in use. ```sh facet call design_system ``` ## package Save the design and write it with what it needs into one folder (default: " package" beside it): the .facet document, the project's DESIGN.md, the system it follows at that version, fonts.json naming every family, and a README. Never overwrites a folder. ```sh facet --doc F call package '{"out":"/abs/folder"}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `out` | | string | | the package folder (absolute) | ## systems Design systems in the library (~/.facet/systems): each one's name, version, and absolute paths to its tokens.json (DTCG), DESIGN.md (rules) and folder. They are plain files; read and edit them directly. ```sh facet call systems ``` ## system One system (default: the one this file's project follows, named in the header of the DESIGN.md beside it): version, file paths, rules, published versions. ```sh facet call system '{"name":"Acme"}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `name` | | string | | system name | ## system_create Make a system from this file: its tokens as tokens.json, the project's DESIGN.md (or a starter) as the system's rules, version 1.0.0; the project then follows it. ```sh facet call system_create '{"name":"Acme","description":"..."}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `name` | | string | required | system name | | `description` | | string | | one line about it | ```sh facet call system_create '{"name":"Acme"}' ``` ## system_use Bring a system's tokens into this file (collections, modes, aliases, text, paint and shadow styles; existing ones update) and make the project follow it. Run it again after editing the system's files to take the changes. ```sh facet call system_use '{"name":"Acme","version":"1.2.0"}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `name` | | string | | system (default: the one followed) | | `version` | | string | | a published version (default: the files as they are) | ```sh facet call system_use '{"name":"Acme"}' ``` ## system_save Write this file's tokens to its system's tokens.json (unpublished until system_publish). ```sh facet call system_save ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `name` | | string | | system (default: the one followed) | ## system_publish Record the system's files as a new version (major, minor, patch or an explicit 1.2.0) under versions/; a project that follows it moves to that version. ```sh facet call system_publish '{"bump":"minor"}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `name` | | string | | system (default: the one followed) | | `bump` | | string | | major, minor (default), patch or a version | ```sh facet call system_publish '{"bump":"patch"}' ``` ## lint Check the page against the design rules in DESIGN.md beside the file (colors, radii and spacing from tokens, text styles, fonts): the rules file's path, its rules and every layer that breaks one (main components and instance overrides; what instances show unchanged is not reported twice). Run it after edits. ```sh facet call lint ``` ## duplicate Copy nodes; a copy sits right of its source, past any layer already there. Optional "name" and "mode": {collectionName, modeName} for a themed copy. ```sh facet copy NODE [NODE…] [--name NAME] [--mode Dark] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeIds` | | [id] | required | nodes to copy | | `name` | `--name` | string | | name of the copy | | `mode` | `--mode` | {collectionName, modeName} | | show the copy in this mode | | `preview` | | path | | write a PNG of the result (the written node, or the page) | ```sh facet call duplicate '{"nodeIds":["12"],"name":"Login Dark","mode":{"collectionName":"Theme","modeName":"Dark"}}' ``` ## delete Delete nodes and their children. ```sh facet delete NODE [NODE…] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeIds` | | [id] | required | nodes to delete | ```sh facet delete 14 ``` ## detach Turn instances into ordinary layers that keep what they showed (their overrides and names); instances nested inside stay instances. One undo step. ```sh facet detach NODE [NODE…] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeIds` | | [id] | required | the instances to detach | ```sh facet detach "Pro card" ``` ## componentize Make an existing frame, row or column a component, where it is; its uses are then written by its name ({"Card": {}}). ```sh facet component NODE ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id / name / selector | required | the frame to make a component | ```sh facet component Card ``` ## group Put layers of one parent in one layer of their own, in place. In a row or column they go into a row or column with the same gap, which lays out, takes new layers and copies like any other; placed freely (on the page, in a stack) they become a group, which moves its layers as one. ```sh facet group NODE NODE… [--name NAME] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeIds` | | [id] | required | the layers to group | | `name` | `--name` | string | | the group's name | ```sh facet group A B --name Pair ``` ## replace Replace words in every text of the page showing (or under one layer): each text that holds OLD exactly, capitals included, gets NEW in its place, in one undo step. A text with styled runs, and one inside an instance (set through the instance's property), is left and counted, so nothing loses its styling. ```sh facet replace OLD NEW [--in NODE] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `find` | `--in` | text | required | the words to look for | | `with` | | text | required | the words to put in their place | | `scope` | | id / name | | only the texts under this layer | ```sh facet replace "Sign up" "Join" ``` ## arrange Lay top-level layers out in rows without touching what is inside them: the layers named, in that order, or every top-level layer of the page in reading order. With columns, a row holds that many and each column is as wide as its widest layer; without, one row. Rows are as tall as their tallest layer, gap apart (80 by default; [across, down]). It starts at the layers' top-left corner, or at "at". One undo step. ```sh facet arrange [NODE ...] [--columns N] [--gap G | ACROSS,DOWN] [--at X,Y] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeIds` | | [id] | | top-level layers, in the order to place them (default: all, in reading order) | | `columns` | `--columns` | number | | layers per row (default: one row) | | `gap` | `--gap` | number / [across, down] | | space between layers (default 80) | | `at` | `--at` | [x, y] | | where the first layer's top-left corner goes (default: where the layers' corner is now) | ```sh facet arrange --columns 4 --gap 80,120 ``` ## move Move layers into another frame (or onto the page with "parentId": null) at a child index (default: last, on top). Layers keep their place on the canvas unless the new parent's auto layout places them; absolute layers stay absolute. With "toPage" they move to another page at the same place, keeping their ids, names and component links. ```sh facet move NODE [NODE…] --into PARENT [--index N] | --to-page NAME ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeIds` | | [id] | required | layers to move, in order | | `parentId` | | id / null | | the new parent frame (default and null: the page) | | `index` | `--index` | number | | child index in the new parent (0 is the bottom of the stack and the start of a flow) | | `toPage` | `--to-page` | name / id | | move the layers (top-level or not) onto this page instead, one undo step; instances stay linked | | `within` | | bool | | keep the parent it has: last among its children, or at index (0 first) | ```sh facet call move '{"nodeIds":["14"],"parentId":"12","index":0}' ``` ## script Run JavaScript (the body of an async function) over the same tools, as ONE call: canvas.build({...}), canvas.find({selector}), canvas.call(TOOL, args) and plugin-style nodes (facet.currentPage.findOne(...), node.fills = [...], facet.createFrame()). If it throws, everything it did is rolled back; otherwise it is one undo step. --read-only always rolls back. No file, network or clock access; timers run instantly in order. `facet guide script` lists the API. Each script runs in its own process: if the engine crashes or runs past its limit, that call fails with the reason and nothing it did is kept; the app keeps running. ```sh facet script @file.js [--read-only] [--input JSON] [--timeout-ms N] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `script` | | string | required | the code; `return` gives the result, `await` works | | `readOnly` | `--read-only` | bool | | roll back every change at the end (inspections and measurements) | | `input` | `--input` | any JSON | | a value the script reads as canvas.input | | `timeoutMs` | `--timeout-ms` | number | | time limit (default 30000, at most 120000) | ```sh facet script 'const card = facet.currentPage.findOne(n => n.name === "Card"); card.resize(320, card.height); return card.width;' ``` ## paint_styles Create paint styles: each one solid color, bound to a color variable when given as "@Collection/name|#fallback". Apply with "$fillStyle" or "$strokeStyle". A name that exists is kept ("reused": true); "update": true gives it the new color instead. ```sh facet call paint_styles '{"styles":[{"name":"Brand/Accent","fill":"@Brand/accent|#2563EB"}]}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `styles` | | list | required | [{"name", "fill"}] | | `update` | | bool | | redefine styles that exist (layers using them update) | ```sh facet call paint_styles '{"styles":[{"name":"Brand/Accent","fill":"#2563EB"}]}' ``` ## effect_styles Create effect styles from "effects" lists (drop-shadow, inner-shadow, blur, background-blur, as in build). Apply with "$effectStyle". A name that exists is kept; "update": true redefines it and every layer following it updates. ```sh facet call effect_styles '{"styles":[{"name":"Elevation/Card","effects":[...]}]}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `styles` | | list | required | [{"name", "effects"}] | | `update` | | bool | | redefine styles that exist (layers using them update) | ```sh facet call effect_styles '{"styles":[{"name":"Elevation/Card","effects":[{"type":"drop-shadow","y":4,"blur":12,"color":"#0000001A"}]}]}' ``` ## text_styles Create text styles from text keys (fontFamily, fontWeight or fontStyle, fontSize, lineHeight, letterSpacing). Apply with "$textStyle". A name that exists is kept; "update": true redefines it and every text following it updates. ```sh facet call text_styles '{"styles":[{"name":"Body/Strong","fontFamily":"Inter","fontWeight":600,"fontSize":14}]}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `styles` | | list | required | [{"name", "fontFamily", "fontWeight", "fontSize", ...}] | | `update` | | bool | | redefine styles that exist (texts following them update) | ## photos Search openly licensed photos (Wikimedia Commons, then Openverse): title, web-sized thumbnail URL, size, license, author and page. Place one with "$image": URL, or the best match directly with "$image": "photo:masala chai". Results and photos are cached. ```sh facet call photos '{"query":"masala chai","limit":6}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `query` | | string | required | what the photo shows | | `limit` | | number | | results (default 6, at most 20) | | `sheet` | | path | | also write a contact sheet PNG: the results' thumbnails in a numbered grid with their titles and sources, to choose by looking | ```sh facet call photos '{"query":"masala chai","limit":6,"sheet":"chai.png"}' ``` ## fonts Every font family a document can name: those installed here and every Google Fonts family (styles, weights, italics, variable axes, subsets, license, whether it renders here now). Name any of them as fontFamily: one not installed is downloaded and cached before the write measures (FONT_INSTALLED); text in it shows a metric-close stand-in only while it loads. Runs without a host too. ```sh facet fonts list|search QUERY|info FAMILY|used [--json] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `action` | | list / search / info / used | | default: info with family, search with query, else list; used: the families the page showing uses, with their weights, how many texts each sets and whether this machine has each | | `missing` | | bool | | used: only the families this machine lacks | | `query` | | string | | search: part of a family name | | `family` | | string | | info: the family | | `category` | | string | | list: sans-serif, serif, display, handwriting or monospace | | `installed` | | bool | | list: only families that render here now | | `google` | | bool | | list: only Google Fonts families | | `limit` | | number | | families returned (list 200, search 20) | ```sh facet fonts search 'playfair' && facet fonts info 'Playfair Display' ``` ## refresh_images Re-read and decode every image under a node (or the page) from the document: how many were refreshed, and which layers miss their image. ```sh facet call refresh_images '{"nodeId":ID}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id | | subtree (default: the page) | ```sh facet call refresh_images '{"nodeId":"12"}' ``` ## project Create a project (a folder beside the served document), or reuse the one with that name ("reused": true). ```sh facet call project '{"name":"Checkout"}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `name` | | string | required | project name | ## file Create an empty document in a project (or reuse it); the reply gives its path. Work on it with `facet --doc PATH`. ```sh facet call file '{"projectId":"Checkout","title":"Cart"}' ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `projectId` | | string | required | project name | | `title` | | string | required | file name (without .facet) | ## projects Projects beside the served document, with their files. ```sh facet call projects ``` ## undo Revert the latest write call as a whole (however many engine steps it took). If the document changed since, revert one step. ```sh facet undo ``` ## redo Replay the call undo reverted. ```sh facet redo ``` ## audit Layout findings: content a fixed frame clips or that shows past a frame's edge (LAYOUT_OVERFLOW) and content an edge-pinned bar covers (LAYOUT_OCCLUDED). Every write runs it on what it wrote. ```sh facet audit [NODE] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id | | audit this subtree (default: the page) | ```sh facet audit 12 ``` ## shot Render nodes (or the page) to PNG, text included. LOOK at it after every write. The PNG is transparent outside the layers (so is --preview's); --background '#FFFFFF' fills it. ```sh facet shot [NODE...] -o out.png [--scale 2] [--padding 0] [--background #FFFFFF] [--region x,y,w,h] [--isolate] [--span] [--props JSON | --each @sets.json] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeIds` | | [id] | | layers to frame, each by name, selector or id (default: the page) | | `output` | | path | required | PNG file to write | | `scale` | `--scale` | number | | pixels per unit (default 1) | | `padding` | `--padding` | number | | margin in units (default 0) | | `background` | `--background` | color | | color under the content (default transparent) | | `region` | `--region` | [number] | | render this world rectangle, [x, y, w, h] with w and h above 0 (CLI --region x,y,w,h), instead of the area the layers span; --scale applies, --padding does not (default: the layers or the page) | | `isolate` | `--isolate` | bool | | only the named layers and what they hold, without the layers beside or over them (default: everything in the frame, as the canvas shows it) | | `sheet` | | bool | | several layers that don't touch are set side by side in a contact sheet, 24 units apart, in the order named (default); false (CLI --span) renders the whole area they span | | `props` | `--props` | object | | render one instance with these properties without keeping them: {"Month": "FEB", "Day": "29"} | | `each` | `--each` | [object] | | a PNG per set of the instance's properties, in one call, none kept; output names each with {Property} or {#}: tiles/{Month}-{Day}.png | ```sh facet shot Card -o card.png --scale 2; facet shot Tile --each @dates.json -o 'tiles/{Month}-{Day}.png' ``` ## spec Handoff: what a node is, its structure, every string, colors, typography, spacing, radii, shadows, instances, images, bound variables and component states. ```sh facet spec NODE ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id | required | the node | ```sh facet spec 12 ``` ## measure Handoff: layout as data (redlines): sizes, sizing modes, padding, gaps, insets and the space between siblings. With a second layer: the distance between the two, across and down (negative where they overlap), and between their centers. ```sh facet measure NODE [--depth N] | facet measure NODE OTHER ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id | required | the node | | `depth` | `--depth` | number | | levels of children (default 1) | | `to` | | id | | another layer: reply with the distance between the two instead | ```sh facet measure 12 --depth 2 ``` ## swiftui Handoff: a layer as a SwiftUI view. Rows and columns are HStack and VStack with their spacing, padding and alignment; a frame without auto layout is a ZStack with each child at its place; fills (colours and linear gradients), strokes, corner radii, clipping, shadows (the radius is the deviation Facet draws the blur with, 0.42 of it), opacity and rotation are written as modifiers; texts carry their font, size, weight, tracking, case and colour. Icons, vectors and pictures are written as Image("name") and listed in assets, to export with assets export. notes says what SwiftUI cannot say the same way (a wrapping row, a radial fill, a shadow's spread, line height as line spacing). ```sh facet swiftui NODE [--name ViewName] [-o View.swift] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id / name | required | the layer | | `name` | `--name` | string | | the view's type name (default: the layer's name as a type name) | | `output` | | path | | where to write the Swift file (default: the code is in the reply) | ```sh facet swiftui "Popover" -o Popover.swift ``` ## compare Handoff: how far a picture of the built thing (an app's own screenshot of a state) is from a design frame. The frame is rendered as shot renders it (from the command line: as export draws it whenever the two pictures differ, so a frame and its own export are the same), on white (the picture's transparent parts go on the same ground), at the picture's scale (worked out from its width unless given), and compared pixel by pixel: the share of pixels differing by more than the tolerance in any channel, the mean difference, and the box of the largest differing patch in the frame's units. output writes the picture greyed with the differing pixels in magenta. With failOver, the call fails when more than that percentage differ, so a test stops an implementation drifting from its design. ```sh facet compare FRAME built.png [--scale 2] [--tolerance 8] [--fail-over 1] [-o diff.png] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `nodeId` | | id / name | required | the design frame | | `image` | | path | required | a PNG of the built thing | | `scale` | `--scale` | number | | pixels per unit of the picture (default: its width over the frame's) | | `tolerance` | `--tolerance` | 0..255 | | how far a channel may be off before a pixel differs (default 8) | | `failOver` | `--fail-over` | percent | | fail when more than this share of pixels differ | | `output` | | path | | where to write the difference picture | | `background` | | color | | what the frame is rendered on (default white) | | `design` | | path | | a PNG of the frame to compare with in place of rendering it here: the frame's own export at this scale. The command line passes it by itself when the pictures differ, so a frame and its own export are 0% apart | ```sh facet compare "Popover" build/popover@2x.png --fail-over 1 -o diff.png ``` ## tokens Handoff: variables, or (when there are none) the colors, spacing, radii, shadows and text styles in use, as CSS custom properties, a TypeScript module or JSON. With include metrics: also a metrics group with the layout values of each layer under the node, named by layer and property (popover-width, popover-padding-top, popover-radius, popover-shadow-blur, title-font-size, title-line-height), for a generator to write an app's metrics from. ```sh facet tokens export --format css|ts|json|dtcg [--mode M] [--node ID] [--include metrics] [-o FILE] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `format` | `--format` | css / ts / json / dtcg | required | output format | | `mode` | `--mode` | string | | one mode of each collection | | `nodeId` | `--node` | id | | infer from, and take metrics from, this subtree only | | `include` | `--include` | "metrics" | | also export each layer's sizes, spacing, radii, type and shadows | ```sh facet tokens export --format css -o tokens.css ``` ## assets Handoff: image files, vectors as SVG and the font families in use, with a manifest.json. With set: one file for each layer directly inside that frame, named after the layer (the Icons frame's lucide:monitor is monitor.svg): svg, or png at a scale on a clear ground, ready for an asset catalogue. ```sh facet assets export [NODE] --out DIR | facet assets export --set FRAME [--format svg|png] [--size 15] [--scale 3] [--color current|drawn] --out DIR ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `output` | `--out` | dir | required | folder to write | | `nodeId` | | id | | export from this subtree only | | `set` | `--set` | id / name | | a frame: export each layer directly inside it as a file named after it | | `format` | `--format` | svg / png | | with set: the file format (default svg) | | `size` | `--size` | number | | with set: the width each file is drawn for, in points, whatever size the layer has (15 for a 15 pt icon) | | `scale` | `--scale` | number | | with set and png: pixels per point (3 for @3x) | | `color` | `--color` | current / drawn | | with set and svg: "current" (default) writes an icon of one colour in currentColor, so it takes the colour of the text around it; "drawn" keeps the colours in the design | ```sh facet assets export 12 --out assets/ ``` ## guide This page. Topics: tools, grammar, results, or a tool name. ```sh facet guide [TOPIC] ``` | Argument | Flag | Type | | About | |---|---|---|---|---| | `topic` | | string | | tools, grammar, results or a tool name | ```sh facet guide build ``` ## Everything else Files, hosts, the app window and behavior charts, as `facet --help` prints them: ``` facet: design by command, and drive the visible app Agents: read `facet guide` first: it opens with a first screen in five steps (write JSON, build --preview, look, shot), then every tool, the grammar and the result codes. `facet --version` names this build. facet --doc FILE build @screen.json [--preview s.png] one call builds a whole tree facet --doc FILE build --watch --run 'python3 make.py' run a generator again when its files change, and sync facet --doc FILE build --watch --stop end that watch from another shell facet --doc FILE build --stream [@design.sxl | -] a design written as lines, built while it is written facet --doc FILE react render screen.tsx [--watch] a design written in React, built in place facet --doc FILE modify NODE @props.json [--all] change a node (and named layers); --all: every layer NODE matches facet --doc FILE delete NODE [NODE…] remove layers (ids, names or selectors) facet --doc FILE rename NODE NAME name a layer facet --doc FILE move NODE… --into PARENT [--index N] put layers inside another (or --to-page NAME; --end / --start: among its own parent's children) facet --doc FILE copy NODE… [--name NAME] [--mode Dark] copy layers, right of their source facet --doc FILE detach NODE… | group NODE NODE… [--name NAME] an instance as ordinary layers; layers in one layer of their own facet --doc FILE component NODE make a frame a component, where it is facet --doc FILE page add NAME [--keep] add a page (--keep: without showing it); also page show NAME, rename [OLD] NEW, move NAME N, delete NAME, list facet --doc FILE tree | inspect NODE | find SELECTOR | components | audit [NODE] facet --doc FILE where NODE the components a layer is in and their files facet --doc FILE spec NODE | measure NODE | shot [NODE] -o x.png facet --doc FILE arrange [NODE ...] [--columns N] [--gap G] top-level frames into rows, contents untouched facet --doc FILE compare FRAME built.png [--fail-over 1] [-o diff.png] an app's screenshot against its design facet --doc FILE swiftui NODE [--name ViewName] [-o View.swift] a layer as a SwiftUI view facet --doc FILE tokens export --format css|ts|json|dtcg | assets export [NODE] --out DIR facet --doc FILE undo | redo whole calls facet --doc FILE call lint layers breaking the rules in DESIGN.md beside FILE facet --doc FILE call package ['{"out":DIR}'] FILE with its DESIGN.md, system and fonts in one folder facet [--doc FILE] call systems | system | system_create | system_use | system_save | system_publish design systems: plain files in ~/.facet/systems/NAME (tokens.json as DTCG, DESIGN.md); see `facet guide` facet [--doc FILE] history [list|version NAME|restore REF|diff FROM [TO]] operation log and versions (also `version save NAME`) facet --doc FILE chart import @chart.json | chart FEATURE [--explore] | chart bind|design FEATURE @f.json facet --doc FILE states COMPONENT | states apply NODE VIEW | plays list|run | replay FEATURE PLAY --at MS facet --doc FILE act | act NODE EVENT what each instance's statechart takes now; send one event facet --doc FILE lattice FEATURE matrix|flow|designs|replay [--scenario k=v] facet --doc FILE shot NODE --state VIEW [--scenario k=v] [--design k=v] -o x.png facet --doc FILE call TOOL '{json}' any tool (variables, set_mode, duplicate, delete, ...) facet --doc FILE script @file.js [--read-only] JavaScript over the tools as one call (facet guide script) facet close --doc FILE save and stop the document's host facet --doc FILE --headless COMMAND own headless host even when the app has FILE open facet --doc FILE --page NAME COMMAND work on another page without showing it facet serve FILE [--socket PATH] [--font FILE] run a headless host in the foreground facet [--doc FILE] mcp the tools as an MCP server on stdio (facet mcp --help) Set up (AI apps, Terminal, the skill; facet setup --help): facet setup [--json] each AI app (installed, connected), facet on PATH, the skill links facet setup connect CLIENT|all|skills add Facet to Claude, Claude Code, Codex, Cursor or VS Code facet setup disconnect CLIENT|all|skills remove only what Facet added (backups beside each changed file) facet setup cli [--user] | repair facet on PATH; point everything at this copy after a move facet setup channel [beta|stable] receive beta builds too, or stable releases only (the default) facet uninstall [--keep-data] [--yes] [--dry-run] remove what Facet added, its data and the app; never your designs Open files (registry ~/.facet/docs, app socket ~/.facet/app.sock; --doc FILE uses the app's host when the app has FILE open): facet files [--json] [--no-ping] [--front] every open file: path, kind app|headless, pid, build, socket, lock holder, ping health (ms), the front tab; --front prints its path only facet app restart [--bundle PATH] save every file, restart the app on the new build (default: its own bundle), reopen every tab and headless host on the same sockets with the same view; prints both builds facet open FILE [--socket PATH] [--focus] [--new-window | --no-window] open FILE in the running app (a tab in the current window, own socket; --new-window: own window, closed with the file; --no-window: headless host), or start the app facet focus FILE select FILE's tab and bring its app window to the front facet close FILE [--no-save] close FILE's app window (saves unless --no-save) or stop its headless host Without --doc (or CANVAS_DOC) commands drive the running app over its control socket: facet capabilities [--json] | schema [OP] | demo list|open CASE|step|reset|close facet tour [CASE] [--delay-ms N] | whats-new [--grep TEXT] [--since VERSION] [--titles] [--json] | try [FEATURE] [--json] facet inspect | select ID | drag HANDLE DX DY | zoom FACTOR | pan DX DY facet duplicate | undo | redo | fit | save | reopen facet front bring the window to the front (no other command does) facet send '{"op":"mask","enabled":true,"mode":"outline"}' facet export --out DIR [--frames] [--settings JSON] [--wait] background job; export status|cancel [JOB] facet export --pdf OUT.pdf [--page PAGE] [--paper a4|letter|WxH] [--dpi N] [--text text|outlines] [--wait] every top-level frame, a page each facet variables [list] [--type color] [--json] | variables rename OLD NEW | variables set NAME VALUE [--mode MODE] | tokens [--mode NAME] [-o OUT.json] | tokens import FILE.json [--json] facet renderer exact|tiles draw every frame exactly, or compose in tiles Without any host: facet render DOC -o OUT.png [--view content|saved] [--node ID] [--zoom Z] [--scale S] [--padding P] [--background #RRGGBB[AA]] facet export DOC --out DIR [--page P] [--node ID]... [--frames] [--format png|jpg|svg|pdf] [--size 2x|512w|512h] [--suffix S] [--text outlines|text] facet export DOC --pdf OUT.pdf [--page P] [--paper a4|letter|WxH] [--dpi N] [--text text|outlines] frames fitted to paper; selectable text facet pdf IN.md [-o OUT.pdf] [--style STYLE.mdstyle.json] [--stats] Markdown as paginated PDF pages facet tokens DOC [--mode NAME] [-o OUT.json] facet chart CHART.json|DIR [--explore] [--json] a chart file's report (scr-kit interchange) facet guide [TOPIC] [--json] facet fonts list|search QUERY|info FAMILY|fetch FAMILY...|refresh [--json] installed and Google Fonts families Developer commands (measuring and debugging Facet itself) are under `facet dev --help`. Global: --doc FILE, --socket PATH, --headless, --json; every command takes --help. Agent results print on stdout, then `facet: warning:` and `facet: note:` lines on stderr, a write's closed by their count. Exit 0 = completed, 2 = invalid input or unavailable, 3 = failed or unknown outcome (nothing changed for agent tools). No automatic retries. Coordinates for drag, pan and pointer commands are canvas-local logical screen pixels; drag handles: south_east, east, north_west, north, north_east, south, south_west, west, rotate. ``` --- # Result codes Every reply lists what did not happen as asked. Each warning names the layer and the fix; the app shows the same warnings as badges on the canvas. | Code | Meaning | |---|---| | `INPUT_ALIASED` | note: a key or value was read in its canonical form | | `INPUT_IGNORED` | a key was not understood and did nothing; fix the spelling it names | | `NOT_APPLIED` | asked for X, got Y; change the request or the parent | | `NOT_SUPPORTED` | the engine cannot do this yet; the rest of the call was applied | | `SVG_TEXT_DROPPED` | part of an $svg's text (a , a turned group, per-letter positions) is not mapped to its text layers | | `SVG_FEATURE_IGNORED` | an $svg's filter, image, or a mask or clip path inside a masked element is not applied; its shapes draw without it | | `LAYOUT_TIGHT` | a note: content overflows by 2 px or less (scaled type, a turned corner); reported apart so real overflow stands out | | `PREVIEW_WIDER` | a note: layers reach past the frame a build made (a connector looping outside it), so its preview shows more than the frame | | `PART_CLIPPED` | a note: a kit part clips by its own definition (a phone's screen) and the content given to it is larger, so part of it does not show | | `FONT_FEATURE_MISSING` | a fontFeatures tag the text's font does not have (small capitals in Inter): the text draws without it | | `ROW_UNEVEN` | a note: boxes in a row hug their content and come out different heights; "align": "stretch" on the row makes them one height (center or end silences it) | | `OUT_OF_GAMUT` | a note: a CSS Color 4 color (oklch, lab, display-p3…) lies outside sRGB; it is drawn as the hex the note names, by CSS gamut mapping | | `LAYOUT_OVERFLOW` | content is clipped by a fixed-size frame (also content spilling out of a filled child), shows past the edge of a frame that neither hugs nor clips it, or is pushed into a fixed frame's end padding along its flow | | `EXPECT_FAILED` | a layer's expect (lines, fits, size, noOverlap) did not hold | | `LAYOUT_OCCLUDED` | an edge-pinned bar or overlay covers content | | `FRAMES_OVERLAP` | two top-level frames on the page overlap; move one below or right of the other | | `VECTOR_HEAVY` | one call drew 200,000 path points or more: a repeating texture is a pattern fill ({"fill": {"pattern": "halftone"}}), one small tiled picture | | `TEXT_UNREADABLE` | a text is the colour of the fill behind it, so its words cannot be seen | | `NO_ROOM` | a note: justify or a filling child has no room to work with, because the container hugs its content on that axis | | `TEXT_TRUNCATED` | text does not fit its fixed box | | `TEXT_OVERFLOW` | a one-line text runs past the width its frame gives it; give it "width": "fill" or a fixed width | | `FONT_ALIASED` | a note: a CSS font list, a system keyword or a vendor's renamed family read as the family it stands for (Slack-Lato as Lato) | | `FONT_SUBSTITUTED` | a requested font family is not installed; another one draws the text | | `IMAGE_UNREADABLE` | an image file's data past its header is damaged or cut short; the layer draws what of it decodes, or nothing | | `TOKEN_FALLBACK` | a variable was not found; its fallback value was used | | `OVERRIDE_UNMATCHED` | an instance override names no property or layer | | `FONT_INSTALLED` | note: a font family missing on this machine was installed from Google Fonts for this host | | `IMAGE_SOURCE` | note: where a fetched photo came from: title, author, license and page | | `HISTORY_EMPTY` | note: undo or redo found nothing to step | | `GLYPH_FALLBACK` | note: a font has no glyph for a character, so another font draws it | | `FONT_STYLE_MISSING` | note: a family has no italic, so italic text in it shows upright | | `NAME_TAKEN` | a build with again added a top-level layer under a name another one already has; later calls naming it match both | | `GLYPH_MISSING` | no font here has a character, so it shows as a missing-glyph box | | `TEXT_FLOW` | note: the frames a story flows through, and how much of it the last does not hold | | `RUNT_FRAME` | a story's last frame holds only a line or two of it | | `HEAD_AT_FOOT` | a heading is the last line of a frame, its text in the next | | `GRID_DRIFT` | a story's lines leave its baseline grid, so facing frames' baselines stop lining up | | `STRAIGHT_QUOTES` | running text uses straight quotes or apostrophes where typographic ones belong | | `SPLIT_UNIT` | a line breaks between a number and its unit | | `HYPHEN_LADDER` | more than two lines in a row end in a hyphen | | `LOOSE_LINE` | note: justified lines stretch their word spaces past twice a normal space | | `CLIPPED_BY_PARENT` | content the layout pushed out of a frame is hidden by an ancestor that clips on purpose | | `TEXT_CELL_WRAP` | note: a text given no width would run past its grid cell, so it wraps at the cell's width; give it a width to choose another | | `KIT_LIBRARY` | a kit's library (kit.use): a note of what the file took from it when it changed, or a warning that it could not be read and what it gave before is kept | | `ICON_COMPONENT` | a note: an icon became a component in the Icons frame, and every use of it is an instance; one line for all the icons of a call | | `REPLACED` | a note: what build --replace swapped, and where instances went | | `BEHAVIOR_STORED` | a note: a set's behavior was stored as a feature; `facet chart NAME` checks it | | `INSTANCE_PROPS` | a note: keys of a modify were set as an instance's properties | | `NO_MATCH` | a note: a selector matched nothing, with the nearest layer name or the form to write | | `LAYOUT_ADJUSTED` | a note: the build changed a layout value so the result shows (a hugging row with a filling child fills; a shape with no paint gets a stroke) | | `INFO` | a note for the reader, nothing to fix: where a file was written, which document was used | | `VARIANTS_ALIKE` | a note: every variant of a component set looks the same, so its variant property changes nothing | | `MANY_MATCHED` | a note: a name in $nodes matched several layers and all were changed | | `NO_RULES` | a note: lint checked nothing, because the file has no DESIGN.md rules and no design system | | `ICON_SET` | a note: the design has an Icons frame; assets export --set Icons writes one named file per icon | | `FONT_FIT` | note: the size a text with fontSize "fit" took: the largest at which it fits its box, its maxLines or one line | | `TEXT_ELLIPSIS` | note: a maxLines text ends in an ellipsis, so part of it is not shown | | `SYNC_SWAPPED` | note: a sync removed a layer and added another under one parent, which is what a rename looks like; a key on the layer keeps it | | `SYNC_RESET` | note: a sync set a key back to its default because the source no longer writes it | | `CONNECTOR_CROSSES` | warning: a connector's line passes through a layer it does not join; route it with sides or an elbow, or move the layers | | `SYNC_PRUNED` | note: a sync with prune removed the page's top-level layers the call no longer writes | | `SYNC_REBUILT` | note: a sync built a layer again because the source writes it as another kind (a row as a column): it and its children have new ids | | `SCRIPT_LOG` | note: a line a script wrote with console.log | | `SCRIPT_ERROR` | error: a script threw or ran out of time; everything it did was rolled back | | `INVALID_INPUT` | error: nothing changed; the message says what to fix | | `NOT_FOUND` | error: a node, component or variable does not exist | | `FILE_NOT_FOUND` | error: a "file" argument names a file other than the one this host serves | | `UNKNOWN_TOOL` | error: no tool has that name; the message suggests one | | `ENGINE_ERROR` | error: the engine refused a step; nothing changed | | `READ_ONLY` | error: the file was made by a newer Facet and opened read-only; nothing changed (save --to COPY.facet writes a copy you can edit) | --- # Font ``` font = [family] size ["/" line] [word ...] family = every word before the first number or keyword ("Instrument Sans"), a Google Fonts family named with a keyword in it ("Archivo Black"), a number ending it when a size follows ("Source Serif 4 16/26"), a known family with a number inside ("M PLUS 1 Code 13/20"), or quoted ("\"Source Serif 4\" 16/26") size = number, in pixels line = number of pixels | number "%" | multiple of the size, up to 4 ("1.4") word = weight | "italic" | spacing | case weight = 100 … 900 in hundreds | thin | extralight | light | regular | medium | semibold | bold | extrabold | black spacing= "+" or "-" then pixels ("+0.4") or a percentage ("-2%") case = caps | upper | lower | title ``` | Font | fontFamily | fontSize | lineHeight | fontWeight | other | |---|---|---|---|---|---| | `Inter 15/22` | Inter | 15 | 22 | | | | `Fraunces 44/1.1 600 -1` | Fraunces | 44 | 110% | 600 | letterSpacing −1 | | `12/16 700 +1.6 caps` | inherited | 12 | 16 | 700 | letterSpacing 1.6, upper case | | `Tiro Devanagari Hindi 20/28` | Tiro Devanagari Hindi | 20 | 28 | | | On a Mac, Apple's own families are written by their plain names: `SF Pro` (the system font), `New York` (its serif), `SF Mono`, `SF Compact` and `SF Pro Rounded`; they exist on Macs only, so a file that must draw the same elsewhere uses a Google Fonts family. PingFang SC is the exception: recent macOS keeps its outlines in a format Facet's text engine does not read, so a text naming it is drawn in another family and the build warns `FONT_SUBSTITUTED`; for Chinese, name Hiragino Sans GB, Songti SC or Noto Sans SC. The first number after the family is the size, so write a weight after it. A weight with no size (`"Fraunces 600"`, `"Inter 100 italic"`) changes the family and weight and keeps the size, as `"600"` alone changes only the weight; a size of a whole hundred is written with its line height (`"Fraunces 200/200"`). A family whose name ends in a number keeps it when a size follows (`"Source Serif 4 16/26"`), and a Google Fonts family whose name holds a weight or case word keeps it whole (`"Archivo Black 18/20"`, `"Black Ops One 24"`), as does one with a number inside its name (`"M PLUS 1 Code 13/20"`), while `"Inter Bold 16"` is Inter in bold; quote a family to be sure (`"\"Noto Serif Display 2\" 40"`). A family from Google Fonts is downloaded the first time a build names it. Italic asked of a family without an italic face shows upright, and the build notes it (`FONT_STYLE_MISSING`). Tracking (`+1.6`, `letterSpacing`) is not applied to scripts whose letters join (Arabic, Syriac, N'Ko, Mongolian, Devanagari, Bengali, Gurmukhi), as browsers do, so a tracked heading in several scripts keeps them whole. --- # Chart The `behavior` of a set compiles to a feature: a statechart, the binding of its states to the set's variants, and design axes. This page lists both forms side by side. | Compact (on a set) | Full chart | |---|---| | `"start": "Loading"` | `"initial": "Loading"` | | `"Loading": {"LOADED": "route"}` | `"Loading": {"view": "Loading", "on": {"LOADED": {"target": "route"}}}` | | `"route": ["a == 'x' -> Failed", "Ready"]` | `"route": {"always": [{"target": "Failed", "guard": "a == 'x'"}, {"target": "Ready"}]}` | | `"plays": {"Retry": ["FAIL", "RETRY"]}` | `"plays": [{"name": "Retry", "events": ["FAIL", "RETRY"]}]` | | `"targets": {"RETRY": "Retry"}` | `"binding": {"targets": {"RETRY": "Retry"}}` | | `"looks": {"Look": {"Dark": "Kit/Dark"}}` | `"designAxes": [{"name": "Look", "values": {"Dark": [{"mode": {"collection": "Kit", "mode": "Dark"}}]}}]` | ## Guards Guards are expressions over the scenario's axis values and the chart's context: numbers, quoted strings, `true`, `false`, `null`; `!`, `-`, `+`, `*`, `/`, `%`; `<`, `<=`, `>`, `>=`, `==`, `!=`, `===`, `!==`; `&&`, `||`, `??`; `c ? a : b`; parentheses; `.length`; and `in('state.path')`, true while that state is active. An unknown name is an error, not a value. ## Axes ```json "axes": {"traffic": ["steady", "idle", "stopped"], "rhythm": {"values": ["daily", "weekly"], "when": {"traffic": ["idle", "stopped"]}}} ``` Every combination of axis values is a scenario; an axis with `when` varies only where the earlier axes it names take those values. ## Commands | Command | Shows | |---|---| | `facet chart FEATURE` | where each view is reachable, coverage, play skeletons (`--full` per scenario) | | `facet states COMPONENT` | each view's variant and where it is reachable | | `facet plays list` / `run` | plays and their runs per scenario | | `facet lattice FEATURE matrix` | every state of a component in every scenario, as live instances | | `facet chart import @chart.json` | stores a full-format chart (or `{"chart", "binding", "designAxes"}`) | --- # Example files the examples build on ## card-start.json ```json { "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"} ] } ] } ``` ## hello.json ```json { "name": "Hello", "column": [ "Evening practice", {"text": "Twelve days in a row", "color": "#6F6879"} ], "font": "Inter 15/22", "padding": 20, "gap": 4, "fill": "#FFFFFF", "cornerRadius": 14, "width": 260 } ``` ## raag-kit.json ```json { "kit": { "font": "Inter 15/22", "colors": { "ink": "#1A1423", "paper": "#F6F1EA", "saffron": "#F29F05", "rose": "#D9485F", "mute": "#6F6879", "board": "#ECE6DD" }, "type": { "display": "Fraunces 40/44 600 -1", "title": "Fraunces 22/26 600", "deva": "Tiro Devanagari Hindi 14/20", "deva-xl": "Tiro Devanagari Hindi 40/44", "eyebrow": "Inter 12/16 700 +1.6 caps", "small": "Inter 13/18 500" }, "parts": { "swara": { "params": {"note": "", "tone": "@saffron"}, "node": { "row": [{"text": "{note}", "style": "deva"}], "padding": [2, 8], "cornerRadius": 8, "fill": "{tone}/20%" } }, "sticker": { "params": {"label": "", "tone": "#FBE3B5", "turn": 0}, "node": { "row": [{"text": "{label}", "font": "Inter 13/18 700"}], "padding": [6, 12], "cornerRadius": 14, "fill": "{tone}", "rotation": "{turn}" } }, "status": { "params": {"ink": "@ink"}, "node": { "row": [ {"text": "9:41", "font": "Inter 15/20 600", "color": "{ink}"}, {"space": "fill"}, {"icon": "lucide:signal", "size": 16, "color": "{ink}"}, {"icon": "lucide:battery-full", "size": 16, "color": "{ink}"} ], "gap": 6, "align": "center", "width": "fill", "padding": [16, 26, 6, 26] } }, "phone": { "params": {"name": "Phone", "bg": "@paper", "children": []}, "node": { "name": "{name}", "column": [ {"status": {}}, { "column": "{children}", "padding": [10, 22, 28, 22], "gap": 18, "width": "fill", "height": "fill" } ], "width": 390, "height": 844, "cornerRadius": 44, "fill": "{bg}" } } } } } ``` ## raga-card.json ```json { "set": "Raga/Card", "props": { "Name": "राग भैरव", "Hour": "MORNING", "Last": "Last riyaz 2 days ago · 25 min" }, "variants": { "State": { "Learning": {}, "New": {}, "Locked": { "fill": "#F3EFF7", "props": {"Last": "Opens after 21 days of Yaman"} } } }, "template": { "width": 300, "padding": 18, "gap": 8, "fill": "#FFFFFF", "cornerRadius": 20, "column": [ {"eyebrow": "{Hour}", "color": "@mute"}, {"deva-xl": "{Name}", "font": "Tiro Devanagari Hindi 24/30"}, { "row": [{"swara": "रे॒"}, {"swara": "ध॒"}], "gap": 6, "only": "Learning" }, {"small": "{Last}", "color": "@mute", "only": ["Learning", "Locked"]}, { "name": "Progress", "only": "Learning", "stack": [ { "type": "rectangle", "width": 264, "height": 6, "cornerRadius": 3, "fill": "@ink/8%" }, { "type": "rectangle", "width": 180, "height": 6, "cornerRadius": 3, "fill": "@saffron", "at": "left" } ] }, { "row": [ { "text": "Start learning", "font": "Inter 14/20 700", "color": "#FFFFFF" } ], "padding": [8, 14], "cornerRadius": 16, "fill": "@ink", "only": "New" } ] }, "behavior": { "axes": { "history": ["fresh", "practised"], "streak": { "values": ["short", "long"], "when": {"history": ["practised"]} } }, "start": "Loading", "states": { "Loading": {"LOADED": "route"}, "route": [ "history == 'fresh' -> New", "streak == 'long' -> Learning", "Locked" ], "New": {"START": "Learning"}, "Learning": {"PAUSE": "Locked"}, "Locked": {"UNLOCK": "Learning"} }, "plays": {"Begin a new raga": ["LOADED", "START"]}, "targets": {"START": "Start learning"} } } ``` ## raga-library.json ```json { "name": "Library", "gap": 20, "align": "start", "row": [ {"Raga/Card": {"State": "Learning"}}, { "Raga/Card": { "State": "New", "Name": "राग भीमपलासी", "Hour": "AFTERNOON" } }, { "Raga/Card": { "State": "Locked", "Name": "राग मालकौंस", "Hour": "LATE NIGHT" } } ] } ```