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).
{
"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.
| 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 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.
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
childrentakes 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 notesSYNC_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 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_LIBRARYnote 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_LIBRARYwarning, 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": nullstops 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
$ 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.