FacetDocs

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).

raag-kit.json≈ 698 tokens
{
  "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}"
        }
      }
    }
  }
}

The kit behind the Raag examples: a default font, six colors, six type presets and four parts.

SectionHoldsUsed as
fontthe default font of every textnothing to write: texts start from it
colorsnamed colors, one value or one per mode@ink, @ink/40%
modesmode names for the colors (["Light", "Dark"])"mode": "Dark" on a layer
fallbackscharacters to the family accepted to draw them ({"✓◐": "Hiragino Sans"}, "*" for any)silences GLYPH_FALLBACK for those characters
typenamed text presets (a font or text keys){"title": "Today"}, "style": "title"
partsnodes 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.

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.

{
  "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 stats in a row) are matched in order by a sync. 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.

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:

{"kit": {"use": "../system/kit.json", "colors": {"accent": "#D9485F"}}}
use takesIt is
a path to a .json filea kit written as {"kit": {...}} or bare; facet --doc system.facet kit --json writes one from a file
a path to a .facet filethat design's own kit
"facet:NAME"a kit that ships with Facet
a list of theseread 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.

PartWriteParameters
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

$ 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.

Documentation for Facet 0.3.228-g032727de