Layout, text and tokens

Every page in Zvessa is built from the same small set of layout and text blocks. A block never holds a size, font or colour. It names a text role, a size step or a colour role, and the space's style says what those look like. Change a token once and every page follows.

The AI and MCP clients use these blocks through propose_change, like any other block. People add them by hand in the page editor (Page header, Section, Grid, Shelf, List rows, Space, Badge, Tags).

How a page is put together #

A calm page usually reads top to bottom like this:

1. header: the page's title, with an optional small line over it, a line under it, a mark or logo, and one or two action buttons. When it is the first block it is the page title, and the bar at the top shows its title once you scroll (the iPhone large-title behaviour).
2. section blocks, each with a small uppercase title and an optional "See all" link.
3. Inside a section: a grid of cards or stats, a scroll shelf people swipe sideways, a row of buttons or badges, or a group of item rows.
4. An item (or a section with open: true) that holds blocks opens them as their own screen, so a settings page can live inside one page.

Defaults are quiet: no extra lines or frames unless the style asks for them, small uppercase labels over groups, one icon per row.

Example #

[
  { "id": "top", "kind": "header", "props": { "title": "Studio", "eyebrow": "Today", "subtitle": "Everything happening in your space", "mark": "S" },
    "children": [{ "id": "top-search", "kind": "button", "props": { "icon": "search", "href": "#search" } }] },
  { "id": "glance", "kind": "section", "props": { "title": "At a glance", "action": "See all", "href": "#stats" }, "children": [
    { "id": "glance-grid", "kind": "grid", "props": { "columns": 2 }, "children": [
      { "id": "members", "kind": "stat", "props": { "label": "Members", "value": "128", "change": "12%", "trend": "up" } },
      { "id": "bookings", "kind": "stat", "props": { "label": "Bookings", "value": "24" } } ] } ] },
  { "id": "settings", "kind": "group", "props": { "title": "Your space" }, "children": [
    { "id": "people", "kind": "item", "props": { "title": "People & invites", "icon": "users", "href": "#people" } },
    { "id": "alerts", "kind": "item", "props": { "title": "Notifications", "icon": "bell", "value": "On", "href": "#alerts" } } ] }
]

Designing a header #

Everything about a header is a setting on the block:

Text roles (tokens) #

Each role is a token in the style at type.roles.<role> with these settings: size (8-96 px, before type.scale), weight (400-800), font (body, display, mono or a font name), case (none or upper), tracking (-2 to 6 px), leading (1-2, line height as a multiple of size) and tone (a colour role). display, title and headline also follow the style's headingCase and tracking when they don't set their own.

Values below read: size · weight · font · case · tracking · leading · colour. A dash means the style's default.

To change one for a whole space, change the look, for example:

{ "op": "add", "path": "/look/changes/type/roles/title", "value": { "size": 32, "font": "serif" } }

A page's own look (/pages/N/look) can do the same for that page only.

Other tokens the blocks read #

Cards #

Variants: default (the style's card), outline, filled (a soft tint), accent (solid colour, or a lit edge in outlined styles), glass, plain (no frame).

Every layout and text block #

header #

The page's header (app bar), first on a page: a small line over the title (eyebrow), the title, a subtitle, an optional mark or logo, and its action buttons (children: button blocks, icon-only when they have an icon and no label). size 'large' is the phone's big title, 'inline' a compact bar title, 'hero' a tall picture band with the title on it. When it is the first block it replaces the page's own title, and the bar shows its title as you scroll.

Holds child blocks.

heading #

A title for a part of a page, with an optional small line over it and a line under it.

text #

Words in one of the style's text roles. variant picks the role: display, title, headline, subtitle, body, callout, caption, label, overline, number, quote, code. body is a paragraph, callout a bigger quiet intro, caption small print, label and overline small capitals, number a big figure, quote a pulled quote, code fixed-width.

list #

A list of short lines: bullets, numbers or ticks.

badge #

A small pill with a word or a count: New, Live, 3, Beta, Sold out.

chips #

A row of small tags that wraps: topics, skills, opening days, filters to read.

card #

A framed box: a picture or icon, a small line over the title, the title, a line under it, text, a badge, and child blocks. size 'sm' (a small square for grids and shelves), 'md' (default), 'lg' (big, a picture on top), 'wide' (picture or icon on the left, words on the right) or 'hero' (tall, the picture fills it with the words on top). With href the whole card opens it.

Holds child blocks.

stat #

A big number with a label, and optionally its change (+12%) and a note.

image #

A picture from a URL, in a shape you pick, with an optional caption.

button #

A button that opens a page, a conversation, a link or the AI. With an icon and no label it is a round icon button (header actions).

section #

A part of a page with a small title, an optional line under it and a link on the right (See all), holding child blocks. variant 'card' puts the children on one card. With open true it shows as one row that opens its children as their own screen (a settings page inside a page).

Holds child blocks.

stack #

Lays out child blocks in a column (or a row).

Holds child blocks.

row #

Child blocks side by side, wrapping onto the next line when they don't fit: buttons, badges, small cards, stats.

Holds child blocks.

grid #

Child blocks in columns of equal width: cards, stats, pictures. A child can span more columns with props.span.

Holds child blocks.

scroll #

A shelf of child blocks people swipe sideways: cards, pictures, stats. Each child is as wide as its size (cards) or itemSize.

Holds child blocks.

group #

Grouped list rows on one card with thin lines between them (a settings list, a menu, a contact card). Its children are usually item blocks.

Holds child blocks.

item #

One list row: an icon or picture, a title, a line under it, a value on the right, a badge, and an arrow when it opens something. Opens href, or, when it holds child blocks, opens them as their own screen titled by the row.

Holds child blocks.

divider #

A thin line between parts, optionally with a word in the middle.

spacer #

Empty space between parts.