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.
{
"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
}
]
}
]
}

A linear gradient between two kit colors, a radial one with a stop placed at 0.6, a tint, and a stroke.
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.
{
"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%"
}
]
}
]
}

The same card twice; the second says "mode": "Dark". The tint @accent/15% follows the mode because it is a variable of its own.
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.