Protocol
Layout
The protocol defines its own layout rules. The widget and this site follow the same rules. You can see what happens when content does not fit before the widget is on a Home Screen.
A node is the size of its content unless a field sets its size. A stack shares its space between its children. Nothing is drawn outside the widget. The rest of this page describes these three rules in detail.
Sizes
By default, a node is the size of its content. A text is as wide as its words. A stack is as big as its children. Two values change the size, on either axis:
"w": 120makes a node 120 points wide.-
"w": "fill"makes a node take all the width that its parent offers. A node that contains a filling child also fills. This continues outwards until a node that has a number for its size.
minW, maxW, minH and maxH then limit
the result. The root always fills the widget, so a bg on the root covers the
whole widget.
Sharing a row
A stack first gives every child the size it asks for. If the children fit, the space that remains goes to the children that can grow. These are spacers, nodes that fill, and content that stretches, such as shapes and bars. If the children do not fit, the stack cuts the longest children first, towards a common length. Short children keep their full length. No child is cut to less than an ellipsis.
hstack: [ "Wolverhampton Wanderers" (115 pt), spacer, "12:00" (25 pt) ]
in 120 pt:
bases: 115 + 0 + 25 = 140 → 20 pt short
cut: both towards a common length, never below "…"
→ name 95 pt, time 25 pt (already shorter than 95, so untouched)
result: "Wolverhampton Wand…" then "12:00" {
"v": 1,
"view": {
"type": "vstack",
"align": "leading",
"spacing": 10,
"padding": 14,
"bg": "#151A21",
"text": {"color": "white"},
"children": [
{
"type": "text",
"text": "A long name and a time",
"style": "caption2",
"color": "#6D7786"
},
{
"type": "hstack",
"children": [
{
"type": "text",
"text": "Wolverhampton Wanderers",
"style": "headline",
"lines": 1
},
{"type": "spacer"},
{
"type": "text",
"text": "12:00–20:45",
"style": "headline",
"monoDigits": true
}
]
},
{
"type": "text",
"text": "Two long texts side by side",
"style": "caption2",
"color": "#6D7786"
},
{
"type": "hstack",
"children": [
{
"type": "text",
"text": "Design review with Priya and Sam",
"style": "subheadline",
"lines": 1
},
{
"type": "text",
"text": "Conference room 4B, second floor",
"style": "subheadline",
"color": "#9AA4B2",
"lines": 1
}
]
},
{
"type": "text",
"text": "The same, with priority: 1 on the room",
"style": "caption2",
"color": "#6D7786"
},
{
"type": "hstack",
"children": [
{
"type": "text",
"text": "Design review with Priya and Sam",
"style": "subheadline",
"lines": 1
},
{
"type": "text",
"text": "Conference room 4B, second floor",
"style": "subheadline",
"color": "#9AA4B2",
"lines": 1,
"priority": 1
}
]
}
]
}
} priority sets the order in which children are cut. The stack cuts children
with a lower priority first, as far as possible, before it cuts any child with a higher
priority. The default priority is 0. To protect one node, such as the time, the price or
the status, give that node a higher priority. In most rows, one such node is enough. A node
with a number for its own w is never cut.
Filling
Children with "w": "fill" share the remaining space equally. Their content
does not change the share, so two tiles that fill are always the same width. A bar gauge
fills its row without a w. A column that contains a bar gauge takes the rest
of its row. This puts a progress line between two airport codes, and the payload contains
no width.
{
"v": 1,
"view": {
"type": "vstack",
"spacing": 10,
"padding": 14,
"bg": "#151A21",
"text": {"color": "white"},
"children": [
{
"type": "hstack",
"spacing": 8,
"children": [
{
"type": "text",
"text": "Lamp",
"style": "footnote",
"weight": "semibold",
"w": "fill",
"padding": 10,
"bg": "#2A3340",
"corner": 10
},
{
"type": "text",
"text": "Living room thermostat",
"style": "footnote",
"weight": "semibold",
"w": "fill",
"padding": 10,
"bg": "#2A3340",
"corner": 10,
"lines": 1
}
]
},
{
"type": "hstack",
"spacing": 10,
"children": [
{"type": "text", "text": "LHR", "style": "title3", "weight": "bold"},
{
"type": "vstack",
"spacing": 2,
"children": [
{
"type": "symbol",
"name": "airplane",
"style": "caption",
"color": "cyan"
},
{"type": "gauge", "value": 0.42, "tint": "cyan", "thickness": 4}
]
},
{"type": "text", "text": "JFK", "style": "title3", "weight": "bold"}
]
}
]
}
} Stretching
Shapes, images, gauges and dividers have no size of their own. They stretch to fill the
space they are given. Across a stack, they match the size of their siblings. A thin
rect beside a block of text is as tall as the text. A capsule
behind a label in a zstack is as big as the label. For a pill, you can also
put a bg and a corner on the label. This gives the same result in
one node.
{
"v": 1,
"view": {
"type": "vstack",
"align": "leading",
"spacing": 12,
"padding": 14,
"bg": "#151A21",
"text": {"color": "white"},
"children": [
{
"type": "hstack",
"spacing": 8,
"children": [
{"type": "rect", "w": 4, "fill": "purple", "corner": 2},
{
"type": "vstack",
"align": "leading",
"spacing": 1,
"children": [
{
"type": "text",
"text": "Design review",
"style": "subheadline",
"weight": "semibold"
},
{
"type": "text",
"text": "15:00 – 16:00 · Room 4B",
"style": "caption",
"color": "#9AA4B2"
}
]
}
]
},
{
"type": "hstack",
"spacing": 8,
"children": [
{
"type": "zstack",
"children": [
{"type": "capsule", "fill": "green/25"},
{
"type": "text",
"text": "On time",
"style": "caption",
"weight": "semibold",
"color": "green",
"padding": {"leading": 8, "trailing": 8, "top": 3, "bottom": 3}
}
]
},
{
"type": "text",
"text": "Delayed 12 min",
"style": "caption",
"weight": "semibold",
"color": "orange",
"padding": {"leading": 8, "trailing": 8, "top": 3, "bottom": 3},
"bg": "orange/20",
"corner": 9
}
]
}
]
}
} When it does not fit
Text does not shrink unless you set minScale. A text that
does not fit wraps at spaces, stops at lines, and truncates the last line with
an ellipsis. If you set minScale, the text shrinks first. With
0.8, the text shrinks to 80% of its size before the ellipsis appears.
Lists can drop whole rows. With "overflow": "drop", a stack or
grid that does not have enough space leaves out whole children. It leaves out the lowest
priority first, and starts from the end. It shows more in their place, with
{count} filled in. Your server sends every row. The phone decides how many
rows fit at the reader's text size.
{
"v": 1,
"view": {
"type": "vstack",
"align": "leading",
"spacing": 6,
"padding": 14,
"bg": "#151A21",
"text": {"color": "white"},
"children": [
{"type": "text", "text": "Today", "style": "headline"},
{
"type": "vstack",
"align": "leading",
"spacing": 4,
"overflow": "drop",
"more": {
"type": "text",
"text": "+{count} more",
"style": "caption",
"color": "#9AA4B2"
},
"text": {"style": "subheadline"},
"children": [
{"type": "text", "text": "09:00 Standup"},
{"type": "text", "text": "11:30 Design review"},
{"type": "text", "text": "14:00 1:1 with Alex"},
{"type": "text", "text": "15:30 Interview"},
{"type": "text", "text": "16:30 Retro"},
{"type": "text", "text": "18:00 Climbing"}
]
}
]
}
} Content that is still too big starts at the top. Content larger than its space starts at the top-leading corner and runs off the bottom and trailing edges. The end of a list is cut, and the heading is not.
The exact rules
The full specification is in the protocol document, and it covers every case. Both renderers are built from that document. Both are tested against the same set of layouts, frame by frame. If the preview and the phone differ, that is a bug. Tell us at contact.