Theme your site

How a space's look is set over the API: every key, what each one changes, which reader surfaces honour it, and which CSS variables are safe to target.

The console's Look area writes the same object this document describes. Anything you can do in the console you can do here, and vice versa.

The endpoints

When a write shows up. A theme, preset or reader-theme write evicts the reader's caches for the whole space — our data cache, the rendered pages, the CDN and the CSP origin lists the reader's policy is built from — so it is visible within a couple of seconds, like publishing a page. A new font or image origin is allowed on the same request as the CSS that loads it (Crossly CU-33); if the eviction call itself fails, the origin lists refresh within one minute. Saving a theme DRAFT deliberately does not: the caches hold the published theme, and a preview swaps the draft in per request.

The body of PUT/PATCH .../theme is the theme object itself, not { theme: … }. GET wraps it; the writes do not.

PATCH is the one to reach for. PUT with a partial body is the most common way to lose a theme: it is a replace, so PUT {"primaryColor": "#ff00aa"} deletes the custom font, the chrome and the custom CSS that were there a second ago.

Unknown keys are refused

These routes answer 422 naming any key they do not recognise, with its full path:

{
  "error": {
    "code": "validation.failed",
    "details": {
      "_": [
        "Unrecognised: chrome.footerColumns.0.title. Not fields we have — they would be ignored, so they are reported here."
      ]
    }
  }
}

This is deliberately stricter than the rest of the API, where an unrecognised body field is reported on the X-Unrecognized-Fields response header and otherwise dropped. On a theme there is nothing else to notice: the write answers 200, the read-back echoes what your client sent, and the only symptom is a page that looks wrong. So a key we do not honour is an error here, not a shrug.

The same goes for what is inside a document you send — a front page, a page's content: a block's attributes are checked, and so are the keys of an attribute that is itself an object. A section's padding takes top, bottom and x, so "padding": {"left": 24} is named as doc.content[0].attrs.padding.left (a 422 on a front page, the X-Unrecognized-Fields header on page content) instead of vanishing.

Who can write it

space.update. Reading the private theme needs space.read; the public /chrome read needs nothing beyond the space being public (or a valid share token).

Which surfaces honour which keys

Every reader surface is wrapped in one .forumulate-reader shell, and the space's theme is compiled into one <style> scoped to it — so colours, fonts, widths, custom CSS and custom JS apply to all of them: docs (/p/), blog (/b/), forum (/f/), roadmap (/r/), changelog (/c/), events (/e/), courses (/co/), status (/st/), FAQ (/faq/), jobs (/jobs/), legal (/legal/), contact (/contact/), and every one of those on a custom domain.

One shell, one stylesheet. The class is on exactly one element per page, so a rule written with the child combinator — .forumulate-reader > div — means one thing. (It used to be on the page's own root as well, nested inside the shell, which made that selector match at two levels and put the same stylesheet in the document twice.)

faviconUrl is universal too. It is not CSS, so it is not in that <style> — every reader page's metadata names it instead, which puts the brand's icon in the browser tab on all of the surfaces above, not just the docs reader.

The keys that are not universal:

If a space belongs to a site, the site theme is the base and the space theme is layered over it, key by key — so a site sets the shared look and one space can still override contentWidth or a palette slot without repeating the rest.

The keys

Colour

Palette slots

{ "palette": { "background": "#101014", "surface": "#18181f", "primary": "#e9e5db" } }

background, surface, header_background and header_primary are wired to the tokens our own stylesheet paints with, so setting them repaints the page — the two header slots paint [data-fx-header], and header_primary also rebinds --ink and --muted inside the bar so the links in it follow the brand rather than staying our grey. The rest are the Discourse colour-scheme names, published so an imported scheme maps across one-to-one and so a theme author can build on them from customCss. info, warning, danger and success paint the callouts of the same name (each falls back to today's colour when unset), and paletteDark re-tints them. highlight, love, tertiary and quaternary are not read by our components; to use one, read it in customCss: .doc-callout { border-color: var(--reader-highlight) }.

{ "primaryColor": "#5e6ad2", "palette": { "tint": true, "info": "#2563eb", "warning": "#d97706" } }

Text colours: ink, headings, secondary text, rules

ink, heading, muted and line are the four colours a page of text is made of, and the four tokens every reader surface reads (--ink, --ink-heading, --muted, --line). Before these slots existed the only way to a near-black body under pure-black headings was customCss against those internal names; now it is two keys, light and dark:

{
  "palette": { "ink": "#1d1d1f", "heading": "#000000", "muted": "#6e6e73", "line": "#d2d2d7" },
  "paletteDark": { "ink": "#e8e8ed", "heading": "#ffffff", "muted": "#a1a1a6", "line": "#424245" }
}

• heading colours every heading and page title through a weightless rule, so a heading that carries a colour of its own (a level colour from typography.levels, a card title in the brand) still wins. A section painted in a scheme of its own starts from that scheme's ink.

• palette applies in every mode, like every palette slot. For a TEXT slot that is how a near-black ink would have stayed near-black on the dark board — so a palette.ink, heading or muted that does not read on our dark paper, and that paletteDark leaves unset, is moved along its own hue until it does, in dark mode only. Set the paletteDark slot to choose the dark colour yourself.

• footer_background and footer_primary paint the footer the way the two header slots paint the header: the band's fill, and its text — --ink, --muted and --line are rebound inside the footer so its links follow.

secondary and primary are read as the page and the text when background / ink are not set — the meaning Discourse gives them, and the one our own Midnight, Editorial and Terminal presets were drawn with. tertiary and quaternary are published as --reader-tertiary / --reader-quaternary for your CSS only. Prefer background/ink/heading/muted: they always win.

Every colour is a full six-digit hex with the leading #. A bare 0b835b or a three-digit #0b8 is accepted and normalised (and the normalisation is reported on X-Field-Warnings). Anything else is a 422.

A section in its own scheme

A page is in one mode, but a band of it does not have to be. A section block can carry scheme: "dark" (or "light") and is then painted in that scheme whatever the page is in — a dark hero on a light page, a light pricing table on a dark one. It wears your palette for that scheme, not ours: in a dark section your paletteDark slots apply over palette, and the brand and accent inks are the ones chosen for the dark board; in a light section on a dark page the dark-only slots step aside. Nothing changes for a section without the key. The block side — backgrounds, spacing, the video background — is in Authoring: sections, video and block hooks.

Type

{
  "customFontUrl": "https://cdn.example.com/geist.css",
  "customFontFamily": "Geist"
}

That rebinds --font-display and --font-body inside .forumulate-reader, so it reaches paragraphs, article headings, page titles, card headings and the chrome. It does not change the console: those variables are also set on <html>, and the theme's copy is scoped to the reader subtree.

The type scale (typography)

The family keys say which face. typography says how big, how tight and how heavy — the type system a design file states, as keys, so it no longer has to be customCss against .forumulate-prose h2.

{
  "typography": {
    "scale": "major-third",
    "baseSize": 17,
    "fluid": { "minViewport": 360, "maxViewport": 1280, "minScale": 0.8 },
    "levels": {
      "h1": { "lineHeight": 1.1, "tracking": -0.02, "weight": 700 },
      "body": { "lineHeight": 1.65 },
      "code": { "size": 14 }
    },
    "headingTransform": "none",
    "variation": { "heading": "\"wght\" 650, \"opsz\" 48" },
    "features": { "body": "\"ss01\", \"tnum\" 1" },
    "opticalSizing": "auto",
    "headingWrap": "balance",
    "bodyWrap": "pretty"
  }
}

One heading, not a level. levels.h2.weight / .tracking set every h2. A single heading that differs — a hero at 800 and −0.03em — takes its own block keys, weight (100–900) and tracking (em, −0.2–0.5), from the block's look panel, the API or markdown (## Ship {weight=800 tracking=-0.03}); they outweigh the level's. See theming-advanced for the block look table.

How a size is decided. A level's own levels.<level>.size wins. Otherwise, with a scale, it is baseSize × ratio^step: h1 is four steps up, h2 three, h3 two, h4 one, h5 half a step, h6 and body sit on the base, small is one step down and code half a step down (a monospace face runs wide). With no scale, only the levels you sized explicitly change — and baseSize on its own sizes the body. A level you did not size keeps our stylesheet's size.

Fluid. With fluid present, every size becomes a clamp() that grows linearly from minViewport to maxViewport: headings start at minScale of their size, body text at bodyMinScale (default 1, so text does not shrink). Sizes are emitted in rem, so a reader who raised their browser's text size still gets larger text.

Settings strings are a closed vocabulary: quoted four-letter OpenType tags, comma-separated, each with a number (variation) or an optional number or on/off (features) — "wght" 650, "opsz" 32 or "ss01", "liga" off — or normal. Anything else is a 422 naming the key.

What it emits. One custom property per value your settings produce, on .forumulate-reader, and rules that apply them to the prose, its headings and the page title ([data-fx-page-title] takes h1):

<level> is h1–h6, body, small or code. Read them from your own CSS — a custom block that wants the h2 size uses var(--reader-fs-h2) instead of restating it. Unset, nothing is emitted: a theme with no typography compiles to exactly the stylesheet it did before the key existed.

mobile.fontScale multiplies the scale on phones: the sized levels' tokens are redefined under the phone media query, so every level scales together.

The studio inspector's per-element rules take font-variation-settings, font-feature-settings and font-optical-sizing too, for one element.

Colour per level, the standfirst and entry titles

Every level takes color and colorDark beside its size and weight — a brand-coloured h3 under black h2s:

{
  "typography": {
    "levels": { "h1": { "color": "#000000", "colorDark": "#ffffff" }, "h3": { "color": "#0066cc" } }
  }
}

A level colour outweighs palette.heading. Two more levels are carried by a documented hook rather than a prose element, and are sized only when you size them (a scale alone never touches them):

{
  "typography": {
    "levels": {
      "lede": { "size": 22, "lineHeight": 1.4 },
      "entryTitle": { "size": 28, "weight": 600 }
    }
  }
}

They publish --reader-fs-lede, --reader-fs-entry-title and the matching -lh-, -tracking- and -fw- tokens.

One size per screen size

Every size-like key in a theme — a level's size here, a level's spaceBefore, components.image.margin, a block's size, the spacer's height, and the feed, post and chrome keys that say they take one — accepts one value, or one per screen size:

{ "typography": { "levels": { "h1": { "size": { "lg": 56, "md": 44, "sm": 32 } } } } }

lg is the desktop and holds at every width nothing smaller overrides; md takes over at 1024px and below, sm at 640px and below — the same breakpoints elementStyles and mobile use. A step you leave out falls through to the next larger one, and a value with no lg leaves the desktop at the key's own default, so {"sm": 28} changes phones and nothing else. A misspelt step ({"phone": 28}) is a 422 that names it.

A length is px as a number, a unit string (px, rem, em, ch, vh, svh, dvh, vw, %), unitless 0, or clamp() / min() / max() of those with at most one + or - per argument — the shape every fluid formula takes: "clamp(2rem, 1.2rem + 3vw, 4rem)". A level size given as a number is still px, and still goes fluid with fluid and scales with mobile.fontScale; a length or a per-size object is used exactly as written (mobile.fontScale still reaches one that has no sm step). fluid and mobile.fontScale reach the hook levels below too.

More per level: face, case, a rule, space above, gradient text

rule and spaceBefore reach the prose headings only, not an index entry that wears a level (data-type-level). Two more hook levels:

{
  "typography": {
    "levels": {
      "eyebrow": {
        "color": "#c2410c",
        "colorDark": "#fdba74",
        "size": 12,
        "tracking": 0.14,
        "case": "upper"
      },
      "h2": {
        "rule": { "color": "#111111", "width": 2 },
        "spaceBefore": { "lg": "3.5rem", "sm": "2.5rem" }
      },
      "h1": { "gradient": { "stops": ["#7c3aed", "#db2777"], "angle": 120 } },
      "lede": { "font": "heading", "size": 22 }
    }
  }
}

Round-4 keys (2026-10): per-screen leading, per-level OpenType, captions

Top-level (not under typography):

{ "headingAnchors": "hover" }

The eyebrow level replaces the elementStyles recipe this guide used to give (h2[data-variant="eyebrow"]). That recipe works too now — an element rule is as heavy as our own eyebrow rule and comes after it — but the level is the setting we keep working.

Your own font files (fonts.faces)

customCss cannot @import — the sanitiser strips it, so what the policy allows and what the sheet loads agree. A face hand-written as @font-face in customCss works, but fonts.faces is the structured form, and its file's origin is added to the reader's font-src automatically, exactly like customFontUrl's:

{
  "fonts": {
    "faces": [
      {
        "family": "Brand Sans",
        "src": "https://cdn.example.com/fonts/brand-sans.woff2",
        "format": "woff2",
        "weight": "100 900",
        "style": "normal",
        "display": "swap"
      }
    ]
  },
  "headingFontFamily": "Brand Sans",
  "bodyFontFamily": "Brand Sans"
}

Up to 24 faces. Declaring a face does not apply it — name its family in headingFontFamily, bodyFontFamily or monoFontFamily.

When a font arrives late (fonts.display)

fonts.display is the font-display for the theme's own fonts: the faces of customFontUrl's stylesheet and every fonts.faces entry that sets no display of its own. Unset it is optional: the face is preloaded and used whenever it is there for the first paint (and from the cache on every page after), and a face that arrives later than that is skipped for this view, so the words never re-wrap under the reader. swap always shows the face, at the cost of the page jumping when it lands on a slow first load.

{ "fonts": { "display": "swap" } }

Uploading the file instead of hosting it. A font can be uploaded to your asset library like an image: .woff2, .woff, .ttf and .otf are accepted, recognised from the file's own bytes rather than its name. An uploaded font is always handed out at an absolute https address on our API (https://<api host>/api/assets/<id>), never at the CDN bucket's, and is served with Access-Control-Allow-Origin: * — @font-face always fetches in CORS mode, so without that header the face would load as nothing on your own domain. Put that absolute URL in src. A bare /api/assets/<id> path is refused, because src must start with https://. The font-face fields in the console's theme editor have an upload button that does all of this for you and fills in src and format.

Layout

What contentWidth actually sets

Four variables, one per kind of surface, all on .forumulate-reader:

The index width was 48rem until October 2026. Under a header running the full shell, a 48rem status page or blog index at 1440px was a 720px strip with ~355px of nothing each side; 56rem (896px) is the band a Statuspage/Instatus status page or a Stripe-style index runs at. The events and courses catalogues moved from the one-piece width to the index width at the same time. A legal document keeps a 46rem measure inside the index width when you set no layout.measure, so terms never run past ~90 characters a line.

A space that sets no contentWidth emits none of the four variables, and every surface falls back to the value in the "unset" column. For these four, unset and wide give the same widths. (contentWidth used to set --reader-max alone, which only the shell and the docs article read, so full gave a full-width header over a 672px blog post. Every surface reads one of the four now.)

The docs article column: where unset and wide differ

The docs article column has its own rule, because a page can set its own width. The page's layout wins. When a page names no layout, the column follows contentWidth, and this is the one place where unset is not the same as wide:

A page's own layout gives narrow 42rem, default 56rem, wide 72rem or full with no cap, whatever contentWidth says. Two more take the page out of the docs frame: center (no tree, no rail, the article centred at the default width) and custom (no tree, no rail, no cap, the title kept for screen readers only and no page chrome). A documentation space can set its default article width once with theme.docs.articleWidth (narrow | default | wide | full, or a measure like "52rem") — between a page's own layout and contentWidth; see the docs theme guide. So on a docs space, setting wide explicitly makes every article that names no layout 16rem wider than it is with the key unset. The other surfaces don't change. The row around the article (nav, article and rail) reads --reader-max like any other shell. Running text inside the column still stops at a readable measure; images, tables and other wide blocks use the extra room.

To move one surface without moving the rest, set its token in customCss rather than guessing at a class name — main.max-w-3xl is a Tailwind build artefact and changes under you on any release:

.forumulate-reader {
  --reader-list: 60rem;
}

The long-form measure (layout.measure)

A width is how far a surface may grow; a measure is how long a line of text may get inside it. They used to be the same number, so widening the indexes also widened every document set in the index width — a privacy policy at contentWidth: "full" ran edge to edge, and the only way to hold it back was CSS aimed at our page structure (main:not(#main-content) > article). The measure is its own key:

{ "contentWidth": "full", "layout": { "measure": "52rem" } }

It is published as --reader-measure on .forumulate-reader, and read by every element carrying [data-reader-measure]:

The measure only ever narrows: on a surface already narrower than it, it changes nothing, and with no layout.measure the elements have no cap of their own and render exactly as before. The column stays where it was — the text keeps the left edge the page heading sits on. "ch" is the typographer's unit (65–75 characters is the classic range); rem matches the width tokens above.

To clear it, PATCH {"layout": {"measure": null}} — or {"layout": null} for the whole layer. A wrong spelling (maxWidth, measures, a top-level measure) is a 422 that names the key, not a 200 that renders nothing. Target [data-reader-measure] in customCss if you need more than a length; never the max-w-[…] class beside it, which is a build artefact.

The header and footer frame (layout.frame)

The header and the footer are page-spanning bars, and their inner row — the logo, the links, the footer columns — runs to --reader-max whatever the page between them is. That is deliberate: the chrome is the site's, and it stays put while a reader moves from the docs to the blog to the status page. layout.frame decides the inner row:

{ "layout": { "frame": "column" } }

Why content changed. It matched each page's column, which on a real site put a 768px header — the nav wrapped onto two rows, the search box under the logo — over the blog, status and legal pages, and the full shell over the docs and forum one click away. Chrome that jumps width between pages of one site reads as broken, so content keeps one frame now, and the per-page match is there under its own name for a design that wants it.

The bars themselves (background, border) always span the window; only the row inside moves. It is published as --reader-frame on .forumulate-reader and read by every element carrying [data-reader-frame] — the header's <nav>, the footer's rows and the footer slot. Under column the reader also publishes --reader-column, the width of the current page's column, so customCss can line something else up with it.

Getting every edge on one line, on every page. The header row, the footer row and the page's column are all centred and pad their contents by the same gutter, so once their widths agree their contents start and end at the same x:

1. Make the widths equal — layout.widths with list and text (and board, if you have a board) all one length, or --reader-list / --reader-text in customCss.

2. Set "layout": { "frame": "column" }. Header and footer now take that one width on every page, and never move.

With unequal widths column still lines each page up, but the chrome moves between pages. A docs page keeps the shell because its column is the shell row; the "on this page" rail on a one-column page lives in the right-hand margin and never moves the column (it folds away when the margin is too narrow for it). To clear the key, PATCH {"layout": {"frame": null}}. A misspelling ("frame": "contents", "layout": {"frames": …}) is a 422 naming it.

Each surface's width (layout.widths)

contentWidth is three presets that move all four surface widths at once. A design that says "1080px shell, 980px index, 680px post" needs each one on its own, and layout.widths is that — one length per surface, the same vocabulary and bounds as layout.measure (px, rem or ch):

{ "layout": { "widths": { "max": "1080px", "list": "980px", "text": "680px", "media": "1200px" } } }

Each key wins over contentWidth for its surface alone, so {"contentWidth": "wide", "layout": {"widths": {"max": "1080px"}}} is a 1080px shell over the wide preset's index and post widths. Unset keeps the preset. The console offers the shells design files use (960–1280px) and your own length.

Background guides (layout.guides)

The hairline column rules a design-system site draws behind its content:

{
  "layout": {
    "guides": {
      "columns": 12,
      "width": "1080px",
      "color": "#eeeeee",
      "style": "dashed",
      "outer": "solid"
    }
  }
}

columns (1–24) rules sit between the two outer ones, across width (default the shell) centred on the page; style is the inner rules, outer the two at the edges (solid or dashed), color defaults to the theme's hairline. They are painted on [data-fx-main], so a section with its own background covers them, exactly as it covers the page.

The index title bar (layout.indexHeader)

Every index — blog, changelog, forum, roadmap, status, FAQ, jobs, events, courses — opens with a generated title bar: the space's name, and on a blog its Archive and RSS links. A composed front page usually has a hero of its own, and the bar above it could not be removed.

{ "layout": { "indexHeader": "hide-title" } }

show (default) is today's page; hide-title drops the heading and keeps the row's links; hide drops the whole row. The hooks are [data-fx-index-header] (the row) and [data-fx-index-title] (the heading).

The page gutter (layout.gutter)

The side padding between every reader page's content and the screen's edge — 16px on a phone, 24px from 768px and 32px from 1025px, unset (the desktop step was 24px until October 2026, which put a full-width header's logo 24px off the window's edge). Every page shell takes the same steps, the changelog, events, courses and contact pages included — they used to hold 16px at every width.

{ "layout": { "gutter": { "sm": 24, "lg": 32 } } }

px as a number (0–96), any length ("1.5rem", "clamp(1rem, 4vw, 2rem)"), or one per screen size. A bare value is every width; sm is below 768px, md 768–1024px, lg above, each falling back to the next larger step. Published as --reader-gutter-sm/-md/-lg on .forumulate-reader; a full-width section's side padding follows the same tokens (its unset value stays 1rem), so a band's words line up with the page around it.

What onThisPage actually does

The rail used to be a side effect of the width: wide and full removed it, standard kept it. Six of the eight built-in presets set wide or full, so picking one of those silently deleted it. Width and navigation are two decisions, so they are two keys.

Unset is the same as auto. onThisPage is a key of the space theme, so you set it with PATCH /orgs/{orgId}/spaces/{spaceId}/theme and the body {"onThisPage": "always"}.

The rail is hidden below 1280px on every surface — at narrower widths it would take the room the words need — and it renders nothing for a document with fewer than two headings. contentWidth has no effect on it either way.

Which surfaces it reaches. These are all of them. A surface that is not in this list (the forum, roadmap, status, events, a site's front door, the indexes) has no rail at any setting:

Legal documents, inline and page-backed alike. A legal document written as a page reads the theme of the space that page is in. One posted straight at POST /orgs/{orgId}/legal with an inline body belongs to no space, so it reads the theme of the org's legal space instead. That is the space whose header and footer already appear around it. Both kinds answer auto, always and never the same way. An org with no legal space has no theme to ask, so only the document's own setting (below) applies. The rail never appears inside an embed (?embed=1), because the embed is one frame of somebody else's page.

Per-piece override

A single page, post, release, lesson or legal document can set its own onThisPage, using the same three values. The piece wins over the space, and the space wins over the surface default:

1. the piece's own onThisPage, when it has one;

2. otherwise the space theme's onThisPage;

3. otherwise the surface default in the auto column above.

A piece's auto is not the same as leaving it unset. auto asks for the surface's own default even when the space says always or never. Send null to clear a piece's value so the space decides again. The FAQ is one page per space with no pieces, so only the space key reaches it.

The value you set is returned where you would expect to find it: in a page's metadata.onThisPage, in onThisPage on a post or release, and in onThisPage on each document from GET /public/orgs/{orgId}/legal. Changing it never bumps a legal document's version, so nobody is asked to accept it again over a layout change.

# One long release gets the rail; the rest of the changelog stays as it is.
curl -X PATCH "$API/orgs/$ORG/spaces/$SPACE/changelog/$RELEASE" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"onThisPage": "always"}'

# One short docs page drops the rail the guide preset gives every page.
curl -X PATCH "$API/orgs/$ORG/spaces/$SPACE/pages/$PAGE/metadata" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"onThisPage": "never"}'

Both in the console

The studio's Look panel has a picker for each, next to the colours and the font: Content width (Default, Standard, Wide, Full) and On this page (Default, Auto, Always, Never). Each starts at Default, which writes nothing — an unset theme renders exactly as it did before these keys existed. Choosing Default again removes a value a preset or an API call pinned. Pinning Auto renders the same as Default; the only difference is that a later change to the default would not reach you. Pinning Wide does not render the same as Default on a docs space: it widens every docs article that names no layout from 56rem to 72rem, as the table above shows. On every other surface, Wide and Default give the same widths.

Brand assets

What the brand lockup shows

The header, the footer and the docs sidebar all render the same lockup, in this order: the square logoMark, then the logoUrl image, then the name.

brandName decides the name, and only brandName:

"" is unset. It used to mean "no brand at all": clearing the field removed the name and suppressed the mark, which left an empty header.

In the header, chrome.brandText decides whether those words are SHOWN (2026-10-12). auto (default), show or hide:

{ "chrome": { "brandText": "show" }, "brandName": "Acme Docs" }

This replaces the rule above for the header only: a set brandName used to print beside the wordmark too, so a wordmark spelling "Acme" was followed by "Acme". The footer and the docs sidebar keep the table above. The shape is read from the image itself, once, when a page first renders it.

The docs sidebar uses the same lockup and the same rule, with one difference. When brandName is unset, the fallback name there is the space's name, not the site's or the organization's. So a space with only a logoMark shows the mark and then the space name at the top of its rail. A space with a logoUrl shows the mark (if set) and the wordmark image, and no name unless brandName is set. A phone shows mobile.logoUrl in place of the wordmark when you set one. The sidebar lockup is not a link. To remove it, set chrome.sidebarBrand: "hide" (see below). whiteLabel is read off the theme of whatever renders the footer it appears in, and inside a site that is the site. A space's own whiteLabel is therefore ignored while the space belongs to a site — set it in the site's config.theme — and is honoured on a space that belongs to no site. Same rule as chrome in the table above, for the same reason: a site has one footer, and one line at the bottom of it.

Header and footer (chrome)

Only for a space that belongs to no site. A site's own header/footer is configured on the site.

{
  "chrome": {
    "cta": { "label": "Start free", "href": "https://example.com/signup" },
    "headerLinks": [
      { "label": "Pricing", "href": "/pricing", "highlight": true },
      { "label": "Docs", "href": "/docs", "children": [{ "label": "Guides", "href": "/guides" }] }
    ],
    "navMenu": { "trigger": "hover", "animation": "fade" },
    "footerDescription": "Everything we ship, as we ship it.",
    "footerColumns": [{ "heading": "Product", "links": [{ "label": "Docs", "href": "/docs" }] }],
    "socialLinks": [{ "platform": "github", "href": "https://github.com/example" }],
    "footerLinks": [{ "label": "Privacy", "href": "/legal/privacy" }],
    "copyright": "© 2026 Example Ltd",
    "footer": { "logo": "https://cdn.example.com/footer.svg", "cookieLinkPlacement": "columns" },
    "mobileNav": "menu",
    "sticky": true,
    "height": "compact",
    "align": "split",
    "ctaStyle": "pill",
    "showSignIn": false,
    "themeToggle": { "show": true, "style": "icon", "position": "end" },
    "sidebarBrand": "show"
  }
}

chrome.sidebarBrand controls the top of the docs reader's left rail ([data-fx-sidebar-logo]):

• show (or unset) renders the lockup described under What the brand lockup shows: logoMark, then logoUrl, then the name. The name is brandName, or, when that is unset, the space's name, shown only when no logoUrl is set. With no logo keys at all, show is just the space name as text.

• hide removes the lockup. Use it when the header above already carries the brand. Search, the version and language switchers and the page tree stay.

Inside a site, a site's config.sidebarBrand is the default for every space in it, and a space's own theme.chrome.sidebarBrand still beats it, because the docs rail belongs to the space. So: set it once on the site, and override it on the one space that differs.

Docs header keys (October 2026)

Every key here is optional, and unset renders the header exactly as before.

A header link with style: "outline" or "button" now takes components.button.radius like the header's buttons. For a pale outline on a header button use ctas[i].border: "#ebebeb".

Ask AI's launcher, the search scope and the docs frame are theme.docs keys — see Theme a documentation space.

The footer's own lockup (chrome.footer)

The footer rendered the header's lockup with no way to say otherwise, and "Cookie settings" was injected into its bottom row wherever that row happened to be. Both are settings:

{
  "chrome": {
    "footer": {
      "logo": "https://cdn.example.com/footer.svg",
      "logoMark": false,
      "cookieLinkPlacement": "columns"
    }
  }
}

The three-way rule is brandName's, deliberately: a string is used verbatim, false shows nothing in that slot, and unset or "" keeps the header's. To go back to the header's lockup after setting one, send null — {"chrome":{"footer":{"logo":null}}} removes the key and {"chrome":{"footer":null}} takes the whole layer off.

The footer carries no phone-only logo whatever mobile.logoUrl says: a footer is one column on a phone, so there is room for the wordmark.

Inside a site this is the site's config.footer, exactly like whiteLabel and the rest of the chrome — see Sites.

cookieLinkPlacement moves the consent control; it cannot remove it. Withdrawing consent has to stay as easy as giving it (GDPR Art. 7(3)), and consent here is per-organization bring-your-own-CMP, so your reader may carry the only trigger a visitor can reach. There is no value that hides it: "none", "hide" and false earn a 422 that says so, rather than a 200 that changes nothing. The control renders nothing at all when there is nothing to consent to: an organization with no consent provider configured gets it only on pages that load an analytics tag (analytics.*) or a chat widget in an opt-in category, where a visitor must be able to withdraw. Configure a provider to have it on every page.

brand and columns need the part of the footer they name to be rendered: a footer with no columns has nowhere to put a column link. Each falls back to bottom rather than dropping the control. The reader 404 renders the same footer, so it lands in the same place there.

The control is [data-fx-cookie-settings] wherever it lands, so you can style it without reaching for the utility class it shares with your footer links.

Markup we have no setting for goes in chrome.footer.html (with its own scoped chrome.footer.css) — see Your own footer HTML, and a newsletter row. It is sanitised by the same function as a header nav panel's HTML: no inline script or on* handler ever runs from it and form controls are stripped. An external <script src="https://…"> in it is loaded only on your own custom domain, the same rule as customHead — see Scripts in an HTML panel or the footer HTML. On our platform origin a script in your footer would be same-origin with /api/* and with every other tenant's storage, so there it is dropped.

socialLinks platforms

x · github · linkedin · youtube · discord · mastodon · instagram · facebook · bluesky · website · behance · devto · dribbble · gitlab · hackernews · matrix · medium · patreon · pinterest · producthunt · reddit · rss · slack · spotify · stackoverflow · substack · telegram · threads · tiktok · twitch · vimeo · whatsapp

href is an https URL. A platform outside the list is a 422 naming the key — the list is the gate, so widening it is how a missing network gets in. Tell us and we will add it.

Marks: a faithful brand mark where we have one, the standard feed glyph for rss, a globe for website, and otherwise a neutral monogram badge carrying the platform's own name as its accessible label. A logo traced approximately is wrong on your brand's page and nobody can tell us so, which is why the icon set is allowed to lag the list above rather than guess.

chrome.themeToggle

{ "chrome": { "themeToggle": { "show": true, "style": "icon", "position": "end" } } }

A rounded control with a brand-filled active state, with no CSS:

{ "chrome": { "themeToggle": { "style": "mono", "radius": 999, "activeColor": "brand" } } }

radius shapes the outline and the active segment (one pixel less, so it sits inside the border) on mono and icon, and the track and thumb on switch. The text on the active fill stays readable on its own: brand uses the brand's own --signal-fg, accent the page colour, and a hex near-black or near-white by luminance. The same settings reach every copy of the control — the header, the phone menu and the reader 404 — and a site takes the same object at config.themeToggle.

Both are published as custom properties on [data-fx-theme-toggle], so a theme that wants a value the settings do not offer can still set one in customCss:

Clear either with null: PATCH {"chrome": {"themeToggle": {"activeColor": null}}}. A near-miss spelling (activeColour, borderRadius, shape) is a 422 that names it.

The control is [data-fx-theme-toggle] in every shape. Do not target [role=group][aria-label=Theme]: the label is translated, so that selector stops matching the moment a reader switches interface language.

The switch shape flips between light and dark and never returns to system — a viewer who has touched a two-state switch has expressed a preference. system is still the default, and mono and icon can go back to it.

A second button (chrome.secondaryCta)

The pair every marketing header carries — "Sign in" beside "Get started" — is cta plus secondaryCta:

{
  "chrome": {
    "cta": { "label": "Get started", "href": "/signup" },
    "secondaryCta": { "label": "Sign in", "href": "/login", "style": "outline" }
  }
}

Same {label, href} rules as cta (a path or a safe absolute URL), plus style: outline (default — two solid buttons side by side are two primaries), link or solid. It renders immediately before the primary in every copy of the header — the desktop row, the phone menu and the 404 — and its hook is [data-fx-cta-secondary], carrying data-cta-style like the primary. In a header painted with palette.header_background an unfilled secondary gets the same readable-ink correction as an unfilled primary. A site takes it in its config like every other chrome key.

The header's appearance (chrome.header)

{
  "chrome": {
    "header": {
      "overlay": true,
      "overlayInk": "#ffffff",
      "height": 72,
      "border": "none",
      "shadow": "sm",
      "blur": 12,
      "opacity": 0.85,
      "logoHeight": 32,
      "navGap": 28,
      "navWeight": 500,
      "navSize": 14,
      "navCase": "uppercase",
      "navTracking": 0.06
    }
  }
}

The nav keys style every top-level header item, [data-fx-nav-item] — your headerLinks and, on a site, the section links in the bar.

overlay and motion. theme.motion.header.behavior: "transparent-until-scroll" is the moving half of a transparent header: sticky, transparent until the reader scrolls. overlay is the static half: the header leaves the flow so the first section runs under it. On its own the header is absolutely positioned and scrolls away with the hero. With chrome.sticky or any moving motion.header.behavior it is fixed instead, and is painted back in (and loses overlayInk) once the reader has scrolled — so white text never ends up on a light bar over body text. Set both keys for the classic landing-page header; neither duplicates the other. The dropdowns and the phone menu keep the page's ink, since they sit on the page's surface.

The nav's colour and face, a floating header, a gradient

Three more chrome.header keys:

{
  "chrome": {
    "header": {
      "navInk": "#6e6e73",
      "navInkDark": "#a1a1a6",
      "navFont": "mono",
      "floating": { "inset": 12, "radius": 999, "maxWidth": "1080px" },
      "background": {
        "gradient": {
          "type": "linear",
          "angle": 90,
          "stops": [{ "color": "#0b0b10" }, { "color": "brand", "at": 100 }]
        }
      }
    }
  }
}

• navInk / navInkDark colour the nav items at rest — a muted nav beside a full-ink brand — and leave the hover to the brand. navFont sets them in the heading, body or mono face.

• floating lifts the bar off the edges into a rounded pill: inset px from the viewport edge (default 12), radius px (default 16; 999 is a pill), and maxWidth as a length (default the shell). A sticky floating header stays inset below the top. floating.phone decides the pill on a phone (below 768px): full spans the screen inset to inset, the brand at one end and the menu at the other; pill (and unset) keeps today's pill, as wide as what it holds. From 768px up the pill fills up to maxWidth (it used to shrink to its contents, so a 1204px cap drew a 975px pill).

On a phone, a header with a menu button keeps the brand, the search and the menu on ONE row: the brand gives way — its name ends in an ellipsis and a wordmark scales down — rather than the menu dropping to a second line. A header without a phone menu (mobileNav: "bar") wraps as it always did.

• background.gradient (and gradientDark for dark mode) is the same shape a section background's gradient takes: linear at an angle or radial, two to four stops, each a hex or one of the reader's roles — bg, surface, panel, ink, muted, brand, accent — with an optional at percentage. It paints over palette.header_background.

Buttons: colours, size, a third one

chrome.cta takes background, ink, size (sm, md, lg) and showOnPhone (keep it in the phone header row instead of the menu); chrome.secondaryCta takes ink, background and underline: false; and ctaStyle / secondaryCta.style gain subtle — a soft wash of the brand behind brand ink.

{
  "chrome": {
    "cta": {
      "label": "Get started",
      "href": "/start",
      "background": "#000000",
      "ink": "#ffffff",
      "size": "lg",
      "showOnPhone": true
    },
    "secondaryCta": {
      "label": "Sign in",
      "href": "/login",
      "style": "link",
      "ink": "#6e6e73",
      "underline": false
    }
  }
}

A header with THREE buttons uses chrome.ctas — up to three, in order, each {label, href, style, background, ink, underline}. When it is set it replaces cta and secondaryCta; the first is [data-fx-cta], the others [data-fx-cta-secondary], and each carries [data-cta-index].

{
  "chrome": {
    "ctas": [
      { "label": "Contact sales", "href": "/contact", "style": "link", "underline": false },
      { "label": "Sign in", "href": "/login", "style": "outline" },
      { "label": "Start free", "href": "/start" }
    ]
  }
}

The buttons' own inks are written with no weight at all, so an elementStyles colour on [data-fx-cta] now wins over them — and over the readable-ink correction a painted header applies, which used to leave white on white.

Rows above and below the header

{
  "chrome": {
    "topBar": {
      "links": [
        { "label": "Status", "href": "/status" },
        { "label": "Contact", "href": "/contact" }
      ],
      "background": "#f5f5f7",
      "ink": "#1d1d1f",
      "height": 32,
      "align": "end"
    },
    "subnav": {
      "links": [
        { "label": "Overview", "href": "/" },
        { "label": "Guides", "href": "/guides", "divider": true }
      ],
      "navSize": 13,
      "navWeight": 500
    }
  }
}

topBar is a utility row ABOVE the header row — plain links (up to eight), its own fill, ink and minimum height, links at the end (default) or start. subnav is a section row BELOW it, and its items are header items: a dropdown or a mega menu works there exactly as in the main row. Both line up with the header's frame. Hooks: [data-fx-top-bar], [data-fx-subnav].

Header search, the desktop menu, dividers

• chrome.search: none (default), icon (a magnifier) or pill (a field-shaped button). Either opens a small box that searches this space's posts — or its pages, on a space that has no posts. Hook: [data-fx-header-search].

• chrome.desktopNav: "menu" puts the header links behind the menu button on a wide screen too; the buttons and controls stay in the bar.

• headerLinks[].divider: true draws a hairline before that item — grouping "Product · Pricing | Docs · Blog". On the phone menu it is a rule. Hook: [data-fx-nav-divider].

• chrome.themeToggle.position: "footer" moves the light/dark control out of the header into the footer's bottom row.

Where the links sit, a separator, the rows on a phone

{
  "chrome": {
    "align": "left",
    "header": {
      "linksAlign": "start",
      "controlsAlign": "end",
      "brandSize": 18,
      "navSeparator": "·"
    },
    "topBar": {
      "links": [{ "label": "Status", "href": "/status" }],
      "style": "tab",
      "phone": "hide"
    },
    "subnav": {
      "links": [
        { "label": "Overview", "href": "/" },
        { "label": "Guides", "href": "/guides" }
      ],
      "phone": "menu",
      "justify": "between"
    }
  }
}

Round-4 keys (2026-10-11)

With chrome.align: "left" or "center", the phone menu button still ends the phone row — it no longer sits mid-row after the brand.

scroll suits a row of plain links; an item that opens a dropdown is better served by menu on a phone, where the dropdown becomes an accordion.

The top bar's row runs the full width of the frame, so align: "end" (the default) puts its links — or its tab — at the far end. It used to shrink to its links and sit in the middle of the page.

Round-5 keys (2026-10-11)

Header, top bar, theme control and footer. Every key is optional and unset renders as before, except the cycle toggle's outline (see themeToggle.border).

Wave-6 keys (2026-10-11)

The bottom row's rule now runs the width of its words, inside the gutter, as the columns above it do — it used to overhang by the gutter at each end. The row's frame and gutter sit on [data-footer-bottom-frame]; [data-footer-bottom] is the row inside it.

With themeToggle.phone: "row" (or topBar.phone: "row") on a packed header (align: "left" or "center"), the phone row's items group at the end beside the menu button; the toggle no longer sits straight after the brand. A footer toggle (position: "footer") now ends the bottom row, after the credit.

linkSeparator now hangs off the link before the gap, so a wrapped line ends on a separator rather than starting with one. The bottom row's "Cookie settings" is one of the row's links: it takes linkSize, the link ink and the separator, in the columns as well.

Round-3 showcase keys (2026-10-12)

{
  "chrome": {
    "brandText": "auto",
    "ctas": [{ "label": "Sign up", "href": "/signup", "phone": "bar" }],
    "headerLinks": [
      { "label": "Ask AI", "href": "/ask", "kbd": "mod-i", "ink": "#52525b", "border": "#d4d4d8", "borderDark": "#3f3f46" }
    ],
    "signInStyle": { "look": "outline", "order": "after-ctas" },
    "sidebarToggle": { "placement": "end" }
  }
}

Unflagged with these: below 420px at most one filled button (solid, pill, subtle) stays in the phone row — the first one pinned there; the rest are drawn in the menu panel at that width — and the sign-in label never wraps. A pill with searchStyle.width gives way (down to 160px) before the buttons and the sign-in are crowded off the row. A desktop menu (desktopNav: "menu") or a sidebarToggle alone now asks for a header, like links do. The menu panel carries an empty [data-forum-menu-slot] the forum sidebar folds into.

A logo for each scheme

theme.logoUrlLight and theme.logoUrlDark are the wordmark for a light and a dark rendering; logoUrl fills in for whichever you leave unset. Both images are in the page and the RENDERED scheme picks one — the reader's own choice, a pinned colorScheme (a post's own included, so a dark story under a light blog switches the logo with no logo key of its own), the OS, and inside a footer with its own chrome.footer.scheme, that scheme. The footer shows the pair too, unless it has a chrome.footer.logo of its own.

Your own footer HTML, and a newsletter row

{
  "chrome": {
    "footer": {
      "html": "<div class=\"badges\"><img src=\"https://cdn.example.com/soc2.svg\" alt=\"SOC 2\"> <a href=\"/security\">Security</a></div>",
      "css": ".badges { display: flex; gap: 16px; align-items: center; }",
      "htmlPlacement": "above",
      "newsletter": {
        "formId": "0b5a6f43-27c4-4d5b-9a51-3c1d2f8e9a10",
        "heading": "The monthly digest"
      }
    }
  }
}

html goes through the same sanitiser as a header HTML panel: no <script>, <style>, <iframe>, form control or on* handler survives in the markup, on any host — custom domain included — and your CSS is scoped to a class of its own. Images are routed through the reader's image rule. Your raw source is never sent to the browser: only the sanitised markup is. A provider whose embed needs an external script works on your own custom domain — the <script src> is taken out of the markup and loaded by the page (see Scripts in an HTML panel or the footer HTML); on our hosts use newsletter with a form of your own, or the provider's hosted link.

newsletter is the form block, not a second form: it posts to the same public door on this address's own API mount, works with no JavaScript, shows the form's own success message, and its responses land in the Forms area with everything else. A form that is closed or deleted renders nothing in the footer rather than an error on every page. replace with no rich footer tier (no description, columns or social links) sits where above would.

Hooks: [data-fx-footer-html] (your HTML) and [data-fx-footer-newsletter] (the row). Setting html or newsletter alone gives a lone space a footer.

The footer's look

The footer was one fixed design — the page's paper, uppercase labels over the columns, a two-then-three grid. Its colours are palette.footer_background / footer_primary (and their paletteDark twins); the rest is chrome.footer:

{
  "chrome": {
    "footer": {
      "scheme": "dark",
      "headingStyle": "plain",
      "columns": 4,
      "background": { "color": "#0b0b10", "colorDark": "#000000", "edge": "wave" },
      "newsletter": {
        "formId": "8f4c2b1e-3a5d-4e6f-9a7b-1c2d3e4f5a6b",
        "layout": "split",
        "hideLabel": true
      }
    }
  }
}

newsletter.consent uses the Forms area's consent wording. A form that has its own consent line (consentText, set in the Forms area) keeps that one instead — it is the line the API requires and stores beside each answer, and the footer never draws a second box. The footer's own checkbox is enforced by the browser (required); for a consent you need on record, set it on the form. To use the footer's note instead, clear the form's consent line in the Forms area (consentText: null).

Your footer HTML can no longer widen the page: the slot contains its own paint, so a band written with margin: 0 -50vw stays inside it.

The footer's type, its brand block and a status pill

{
  "chrome": {
    "footer": {
      "headingInk": "#6e6e73",
      "headingInkDark": "#a1a1a6",
      "headingFont": "mono",
      "headingSize": 12,
      "font": "body",
      "showBrandName": false,
      "brandPlacement": "top",
      "status": { "monitorSpaceId": "0b5a6f43-27c4-4d5b-9a51-3c1d2f8e9a10" }
    }
  }
}

The pill reads the status page's own board, so it cannot disagree with the page; a page with too little history says "Status unknown", never "operational". The id must name a status space of yours — anything else is a 422 naming the key. Hooks: [data-fx-footer-heading], [data-fx-footer-brand], [data-fx-footer-status] (with [data-status]), [data-fx-footer-crumbs] (the breadcrumb row).

The breadcrumb's last crumb is the page's own title ([data-fx-page-title]), read once the page has rendered; a page without one (a front page, a list) shows just your mark and home link. For an extra line such as "More ways to shop: Find a store", use chrome.footer.html with htmlPlacement: "above" — a plain <p> with a link needs no css.

Footer columns: stacking a group under another

A column with "stack": true continues the column before it: its heading and links sit under that column's, in the same grid track, instead of wrapping into the grid's next row. columns: "auto" counts tracks, not groups. In the console's footer-columns box, start a heading with + to stack that block. footerColumns takes up to 12 columns of up to 20 links each.

Footer layouts

Two worked recipes, both with no CSS:

{ "chrome": {
  // …twelve of these: each column is a heading and its links.
  "footerColumns": [{ "heading": "Product", "links": [{ "label": "Docs", "href": "/docs" }] }],
  "themeToggle": { "position": "footer" },
  "footer": { "brandPlacement": "bottom", "columns": 6,
    // The id of your STATUS space.
    "status": { "monitorSpaceId": "4f9c2d1e-8b7a-4c3d-9e2f-1a0b5c6d7e8f", "style": "text" } } } }

Columns first (Kestrel): brandPlacement: "bottom" draws the brand row after the column grid, columns: 6 lays twelve columns out as two rows of six, and the status reads as a line of text beside the theme toggle in the bottom row.

{ "chrome": {
  "footerLinks": [{ "label": "Privacy", "href": "/legal/privacy" }],
  "socialLinks": [{ "platform": "github", "href": "https://github.com/example" }],
  "footer": { "layout": "rows", "linkSeparator": "pipe", "socialStyle": "circle" } } }

Rows (Kilter): the brand lockup on the left with the circled social marks on the right, then footerLinks as one flat row with | between them, then the legal row (copyright, consent, credit). Link columns, if you set any, sit between the first two rows.

Footer art

chrome.footer.art is a fixed-height band of artwork above or below the columns — no html, no css:

{ "chrome": { "footer": { "art": {
  "preset": "streaks", "color": "#e5132f", "height": 150, "fade": "both", "placement": "above" } } } }

Hook: [data-fx-footer-art] (with [data-art], [data-preset], [data-fade]). It is decorative: hidden from screen readers, and it takes no clicks.

Navigation menus: dropdowns, mega menus and HTML panels

Every headerLinks item is still the { label, href } it always was, and one stored before this existed renders exactly as it did. An item can also open something when the reader hovers over it, clicks it or tabs to it. It opens one of three things:

• A dropdown list (children): links, each with an optional one-line description, icon and badge.

• A mega menu (panel with columns): up to four columns of links with optional headings, an optional image card (featured), and an optional footer row of links plus a call to action (footer).

• A panel of your own HTML (panel with html, plus optional css).

All of this works the same in a site's config (at its top level, beside its other chrome keys) and in a lone space's theme.chrome. It shows on every page of the site or space and on its 404.

An item

An item with neither href, children nor panel is refused, because it would go nowhere.

A link inside a dropdown or a column — { label, href, description?, icon?, badge? }: description ≤ 160 chars, badge ≤ 24 chars ("New", "Beta"). icon is either one of our glyph names or an image URL (https://…, a library path /api/assets/…, or a data: PNG, JPEG, WebP or GIF image — not an SVG, which is a script container; upload the SVG and use its /api/assets/… URL). The glyph names are: book, book-arrow, code, message, calendar, chart, pie-chart, puzzle, lock, shield, star, bell, search, sparkle, link, cog, clock, heart, image, trophy, medal, crown, headset, webhook, ticket, board, tracker, template, check-circle, warning, translate, share, eye, bookmark, hash, chat-app, team-chat, upload, pencil, quote and user. A glyph takes the link's own colour. Anything else that is not an image URL is refused with a 422 that names it, so a misspelled glyph does not silently become a broken image.

Menus go one level deep. A dropdown's links have no children, and sending children inside one is a 422 that names …children.0.children. A mega menu's columns are the only extra level.

A panel

navMenu: how menus open and look. Every key is optional. Leaving all of them out gives a panel in your own surface colour, with a hairline border, a 10px radius, a medium shadow and a quick fade.

How readers use it. Desktop: hovering over the word opens the menu after openDelay. Clicking the word, or the caret beside a word that has its own href, opens it and keeps it open. A click on an open menu that hovering opened pins it. A second click closes it. From the keyboard, Enter or Space toggles it, ↓ opens it and moves into it, ↑/↓/Home/End move between its links, and Escape closes it and returns focus to the button. Only one menu is open at a time. A menu closes when the reader clicks outside it, tabs out of it, follows a link in it or moves to another page. The button carries aria-expanded and aria-controls: this is the disclosure pattern, not role="menu", so Tab keeps its ordinary meaning. Phones: in the hamburger menu (mobileNav: "menu"), each item that opens something becomes an accordion. A dropdown is a list, a mega menu's columns stack, and an HTML panel renders inline. With JavaScript off, every href still navigates, desktop menus open on hover and on keyboard focus, and the phone accordions still open.

A simple dropdown (each example is a whole theme body. On a site, put the headerLinks list at the top level of config instead):

{
  "chrome": {
    "headerLinks": [
      {
        "label": "Product",
        "href": "/product",
        "children": [
          {
            "label": "Docs",
            "href": "/docs",
            "description": "Guides and reference",
            "icon": "book"
          },
          { "label": "API", "href": "/reference", "icon": "code" },
          { "label": "Changelog", "href": "/changelog", "badge": "New" }
        ]
      }
    ]
  }
}

A mega menu with a featured card:

{
  "chrome": {
    "headerLinks": [
      {
        "label": "Solutions",
        "panel": {
          "width": "full",
          "columns": [
            {
              "heading": "By team",
              "links": [{ "label": "Support", "href": "/support", "icon": "headset" }]
            },
            { "heading": "By size", "links": [{ "label": "Startups", "href": "/startups" }] }
          ],
          "featured": {
            "image": "/api/assets/0f0e0d0c-0b0a-4908-8706-050403020100",
            "title": "How Acme cut tickets by 40%",
            "text": "A two-minute read.",
            "href": "/customers/acme"
          },
          "footer": {
            "links": [{ "label": "All solutions", "href": "/solutions" }],
            "cta": { "label": "Talk to sales", "href": "/contact" }
          }
        }
      }
    ],
    "navMenu": { "animation": "slide", "shadow": "lg", "radius": 14 }
  }
}

A panel of your own HTML:

{
  "chrome": {
    "headerLinks": [
      {
        "label": "Resources",
        "panel": {
          "html": "<div class=\"grid\"><a href=\"/blog\"><img src=\"/api/assets/0f0e0d0c-0b0a-4908-8706-050403020100\" alt=\"\">Blog</a><a href=\"/webinars\">Webinars</a></div>",
          "css": ".grid{display:grid;grid-template-columns:repeat(2,12rem);gap:1rem} img{width:100%;border-radius:8px}",
          "width": "content",
          "align": "center"
        }
      }
    ]
  }
}

The script rule for HTML panels. Your panel's markup is cleaned the same way a custom-code block's is, on the way out, on every host. Every <script>, <style>, <link>, <meta>, <base>, <object>, <embed>, <form>, <input>, <button>, <select>, <textarea> and <template> is removed, along with every on… attribute (onclick, onerror, …) and every javascript: URL. That applies on your own domain too: inline code in a panel never runs. An external <script src="https://…"> in the panel is the one exception, and only on your own custom domain — see below. For anything inline, put the code in customJs and target [data-fx-nav-panel]. customJs runs only on your own custom domain (see Where owner and vendor scripts run), never on ours. Each panel that opens also fires a forumulate:nav-open event on document, with { detail: { id } } naming the panel's element id, so a script can react when a panel opens. Your css is scoped to the panel, so h2 { … } styles only the panel's own h2. :root, html and body mean the panel itself, and @import is removed. Images in your HTML and in url(…) in your CSS follow the same address rule as every other image on the page, so a library path (/api/assets/…) also loads on a domain that hosts the space under a path.

Scripts in an HTML panel or the footer HTML

A widget that ships as <div id="status-widget"></div><script src="https://status.example.com/embed.js"></script> can go straight into a nav item's panel.html or into chrome.footer.html:

• Only on your verified custom domain. There the <script src> is taken out of the markup and loaded by the page once (not once per copy of the panel — the desktop row and the phone menu share it), through exactly the mechanism a customHead <script src> uses: the page's CSP nonce, the functional consent tier, after the page is interactive. On forumulate.com, a *.forumulate.com subdomain or /p/… it is dropped, the same rule as every owner script (see Where owner and vendor scripts run).

• External https only. A src must be an absolute https:// URL. Inline <script> bodies, on… handlers, javascript: URLs and relative or http: srcs are always removed, on every host.

• Allowed automatically. Each script's origin is added to the address's script origins — the list the reader's CSP script-src and Trusted Types allowlist are built from — so you do not have to repeat it in scriptOrigins. It shares that list's cap of 20 origins with everything else the space loads, and at most 20 scripts are taken from one chrome.

• Find your markup by a selector. The script is not placed inside the panel, so document.currentScript.parentNode is not your panel; give your markup an id or class and look it up, or listen for forumulate:nav-open.

• The chrome a page wears decides. A space inside a site loads the site's panel and footer scripts, not those in its own (unrendered) theme.chrome.

Hooks. [data-fx-nav-item] is every top-level item, plain or not. [data-fx-nav-panel] is what an item opens (on a phone, the accordion's body). [data-fx-nav-link] is a link inside a panel, and [data-fx-nav-featured] is a mega menu's image card. An open desktop item carries [data-open="true"]. See the fx-1 hook set.

Clearing. PATCH {"chrome": {"navMenu": null}} removes every menu setting, {"chrome": {"navMenu": {"shadow": null}}} removes one, and on a site it is PATCH /orgs/{orgId}/sites/{siteId} with {"config": {"navMenu": null}}. headerLinks is a list and is replaced as a whole. A misspelled key at any depth, such as navMenu.delay, children.0.desc or panel.columns.0.title, is a 422 that names it.

In the console, Header navigation (in a space's theme and in a site's navigation editor) lists the items. For each one you choose what it opens. You type a dropdown's links one per line as Label | URL | description | icon | badge, edit a mega menu as JSON, and write an HTML panel as HTML plus CSS. The menu look settings sit under the list.

sticky, height and align are settings rather than CSS: a theme that positions our chrome by hand breaks the first time the markup changes, which is exactly what the data-fx-* hooks exist to avoid. elementStyles does take position (relative, sticky, or absolute inside a named block — never fixed), offsets and a z-index of 0–10, for laying out YOUR content (an overlapping card, a sticky rail); the header is layer 30, above any of it. See "Size, pictures, underlines and layering" in the advanced theming guide.

A site's header lists its member spaces by name. headerSpaceIds curates that list: unset means every space, a list of ids means those in that order, and [] means none — for an owner whose headerLinks are the whole bar. [] used to mean "every space", so there was no way to say "none".

A footer column's label is heading. Every link carries label; a column carries heading. Sending title or label for a column is a 422 naming the key — it used to be a silent 200 that rendered a column with no heading.

The header bar renders only once there is something to put on it (headerLinks, a cta or a brand mark); the footer only once something fills it. A themed space that configures no chrome still gets its colours and font — the theme belongs to the space, not to the furniture.

Both of the things this guide used to list as "not configurable here" are settings now: the footer's lockup is chrome.footer.logo / logoMark, and chrome.footer.cookieLinkPlacement says where "Cookie settings" sits. The one part that is still not a choice is whether that control exists at all — see chrome.footer above for why, and note that it renders nothing when your organization has no preference centre to open.

The reader's account control, and the forum header keys

Signed in, the reader's control is an avatar that opens their menu: Profile, Bookmarks, Notifications and Preferences on a forum, and Sign out everywhere. On a forum a bell sits beside it. The control wears the header nav's ink (header.navInk / navInkDark, font and case), so it reads on a dark header. Hooks: [data-fx-signin], [data-reader-account], [data-reader-bell].

{
  "chrome": {
    "signInStyle": { "look": "outline", "icon": "user" },
    "ctas": [{ "label": "Join", "href": "/join", "action": "signUp", "icon": "sparkle" }],
    "sidebarToggle": true,
    "header": { "accentTop": { "color": "brand", "width": 3 } }
  }
}

The 404 page

notFound (in the theme, not in chrome) says what a reader sees at an address under this space that does not exist. There are two ways to fill it: words (a heading, a paragraph, some links), or a page of your own, built from the same blocks as any other page and shown as the 404's body.

A page as the 404

{ "notFound": { "pageId": "3292a77d-91b9-4aec-9ea2-7207a85e1bbc", "showSections": false } }

Write the page in the editor like any other — headings, images, cards, buttons, tabs, a form, an embed — publish it, and choose it under Theme → Page not found (404) → Page to show as the 404 (or set pageId through the API). On every address that is not a page, its blocks replace the stock heading and paragraph:

• It still answers 404. The status, and the noindex every reader 404 carries, do not change. That is the difference from a "soft 404" — a missing page answered 200 — which search engines penalise: a crawler is told the truth, and a reader gets the page you designed.

• Your header and footer stay, exactly as on every other page (below). Under the page come the search box and the section list, unless showSearch: false / showSections: false, then any links.

• It is rendered the way a docs page is: the same renderer, your library images through this address, external images through our image proxy, embeds only from the hosts you trust, and the interactive blocks working — code highlighting, diagrams, spoilers, extension blocks and forms.

• Where the page can live. In a space's theme, pageId must be a page of that space. In a site's config.theme.notFound, it may be a page of any space in the site, and that 404 is what readers see at a site address that names no section (/nope); a space inside the site that sets no notFound of its own uses the site's too. A pageId that is not there is refused with a 422 naming the key (notFound.pageId, or config.theme.notFound.pageId on a site) — it is checked when the theme or theme draft is saved and again when a draft is published.

• The page itself is hidden (hidePage, on unless you send false). We set the page's own Hide from navigation and noindex flags, so it leaves the sidebar, llms.txt, the sitemap and search, and its own address stops being indexed. Both flags show in the page's details panel; choosing a different 404 page later does not clear them on the old one — untick them there if you want it back.

• If it cannot be shown, the words are. A page that has been deleted or unpublished, a space that turned private, an API that does not answer in time: the 404 falls back to the words-and-links screen (title, body, links, plus a link to the page in case it opens when followed). The 404 never turns into an error screen because of the page.

This works on every reader address: the platform address (/p/…, /b/…, /f/… and the rest), a site's own domain, a space mounted on a path of your domain, and a site address whose first segment names nothing.

Around the body

Everything around the body is your chrome, not ours — and it is the same chrome, rendered by the same components, as every other page of the space. The 404's header is your header: the brand lockup, your header links, your cta, "Sign in" (unless chrome.showSignIn: false), the light/dark toggle at the themeToggle.position you chose (start, end or menu), and the phone menu. Its footer is your full footer: footerDescription, footerColumns, footerLinks, social marks, copyright and "Cookie settings" where chrome.footer.cookieLinkPlacement puts it. A pinned colorScheme sets data-theme on <html>, as on any page. The same precedence applies: a space inside a site wears the site's header and footer on its 404 too, and a space that configures no header or footer gets what its pages get — the toggle row, the sign-in bar and the consent control. Your faviconUrl is in the tab. With the words (no page), the body is followed by a link home and the failed address; then, in both cases, the search box and the sections this address publishes, each unless switched off.

Announcement strip

{
  "announcement": {
    "text": "We are moving to v2 on Friday",
    "level": "warning",
    "href": "/blog/v2"
  }
}

text 1–280 chars; level is info (default) | warning | danger; href optional. Rendered by the space's chrome, above the header and spanning the full page width, on every reader surface of the space — index and piece alike. It is in the server-rendered HTML, so curl | grep data-announcement-banner finds it. (It used to be fetched by each page after first paint, and only five of the twelve surfaces mounted it.)

info and warning carry a dismiss button and are remembered per visitor, keyed on the text — editing the notice brings it back. A danger notice cannot be dismissed. Not rendered inside an embed (?embed=1): an embed is somebody else's page.

href can be a path on this site (/blog/v2), a fragment (#install), or an absolute https:, mailto:, tel: or sms: URL, like every other link in the reader's chrome.

Since October 2026 the strip also takes, all optional:

style is bar (default, the tinted full-width strip) or inline: no fill, the text in the page's ink, the link as a small pill, and a hairline rule under it. placement is above-header (default) or below-header, between the header and the page; a space with no header keeps it on top. Hooks: [data-announcement-banner][data-style], [data-placement].

span (2026-10-12) is page (default — edge to edge) or content: with placement: "below-header", the strip is as wide as the page's content, and on a documentation page with a sidebar its left edge is the article's (the sidebar beside it stays clear). Read only with below-header. Hooks: [data-announcement-banner][data-span="content"] inside [data-ann-frame].

{ "announcement": { "text": "Astro 5 is out", "placement": "below-header", "span": "content" } }

Component shape (components)

Colour is only half of a look. components sets the SHAPE of the reader's built-in components — radius, elevation, the focus ring, the code, input and button surfaces, the vertical rhythm, selected text, the scrollbars and the syntax palette — so a brand with square corners, a thicker focus ring, roomier prose or a dark code block does not need customCss aimed at our class names.

{
  "components": {
    "radius": 2,
    "shadow": "sm",
    "focus": { "color": "#2d6cdf", "width": 3, "offset": 2 },
    "code": { "background": "#0d1117", "ink": "#e6edf3", "border": "#30363d", "radius": 4 },
    "input": { "border": "#d4d4d8", "radius": 2 },
    "button": { "radius": 999, "weight": "semibold", "shadow": "none" },
    "spacing": { "scale": 1.15, "pad": 1 },
    "selection": { "background": "#2d6cdf", "ink": "#ffffff" },
    "scrollbar": { "width": "thin", "thumb": "#30363d", "track": "#0d1117" },
    "syntax": { "comment": "#8b949e", "keyword": "#ff7b72", "string": "#a5d6ff" }
  }
}

Dark twins, the codeDark idiom — a sibling *Dark object whose slots fall through to the light one: components.inputDark and components.buttonDark, each { background, ink, border }, emitted only in dark mode. (A request for button.backgroundDark is spelled buttonDark.background: one shape for every component's dark twin.)

{
  "components": {
    "button": { "background": "#111111", "ink": "#ffffff" },
    "buttonDark": { "background": "#ffffff", "ink": "#111111" },
    "inputDark": { "background": "#18181b", "border": "#3f3f46" }
  }
}

Dropdowns and popovers (components.popover)

Every panel that opens over the page wears one surface: the header's menus and mega menus, the account menu, the notification bell, the docs version / variant / SDK pickers, "On this page" and page-action menus, share and post-action menus, the forum's filter pickers and the header search box. Unset, the panel is your palette's surface colour in each mode, with a 1px line border, a 10px corner and a soft shadow — always opaque.

blur is the only way to make a panel see-through: with it set, the fill is mixed to 82% so the blur has something to show. Leave it unset under a header that already blurs (chrome.header.blur, motion.header.blur) — a blur inside a blur only sees the header, and the panel reads as transparent.

The header's dropdowns take their radius, shadow and width from chrome.navMenu; a colour set there wins over this one for those panels.

{
  "components": {
    "popover": {
      "background": "#ffffff",
      "backgroundDark": "#17181c",
      "border": "#e4e4e7",
      "borderDark": "#2a2b31",
      "radius": 12,
      "shadow": "lg"
    }
  }
}

Published as --popover-bg, --popover-ink, --popover-border, --popover-radius, --popover-shadow and --popover-blur on the reader, for customCss that draws a panel of its own. Panels sit on one stacking scale — --z-header 30, --z-popover 40, --z-drawer 60, --z-modal 70 — and the region holding an open panel is lifted above its neighbours, so a menu is never painted under the row or the content beside it.

Selects and the language switcher (components.select)

Every dropdown on a reader page — a filter or sort, a form field, the theme switcher, the docs version and variant pickers, the language switchers — is drawn by the reader, not by the operating system, so it wears your tokens instead of a grey OS box. It keeps a native select's behaviour: ↑/↓, Home/End, typing a label to jump, Enter/Space to choose, Esc to close; it works before the page has finished loading and without JavaScript (the native control is the fallback), and its list floats above headers, sidebars and panels, so it is never clipped.

Unset, the box is components.input (then your line and ink colours), the open list is components.popover, the focus ring is components.focus.

{
  "components": {
    "input": { "radius": 999, "border": "#2a2b31" },
    "select": { "optionHover": "#1f2a24", "check": "#20e3a2" },
    "popover": { "backgroundDark": "#0e0e14", "radius": 12 }
  }
}

Published as --reader-select-* on the reader. Per-element overrides go through elementStyles on the stable hooks: [data-fx-select] (the box), [data-fx-select-menu] (the open list), [data-fx-select-option] (one option; [aria-selected="true"] is the chosen one, [data-active] the highlighted one) and [data-fx-language-switcher] (any language switcher's box, wherever it is placed).

Where the language switcher goes (i18n.switcher)

A translated docs space shows a switcher between its languages; so do a translated changelog, blog, forum, FAQ, status page and legal document. Where it sits, and whether it is the dropdown above or a row of pills, is one key:

• header puts it in the header beside the other header controls (and in the phone menu); sidebar at the head of the docs sidebar; footer just above the site footer; content-top above the article; none hides it (the languages' addresses still work, and hreflang still lists them for search engines). Every placement is in the page as served — nothing moves into place after it loads, and it works without JavaScript. In the header and the footer the switcher lists the space's declared languages; a language this page has no translation in leads to what the reader serves there (see docs.localeFallback).

• A surface that has no sidebar (a changelog, a status page) reads sidebar as content-top, so a site-wide setting never makes the control vanish.

• Set it on the site theme and every space in the site follows; set it on one space to override the site for that space only.

• The older docs-only docs.localeSwitcher.placement / .style still work and apply wherever i18n.switcher leaves a value unset. docs.localeSwitcher.label (the control's caption) is still read.

• This is the switcher between the content's translations. The control that changes the reader's interface language ("English" in the header) is a different one, shown by showLanguageSwitcher.

{ "i18n": { "switcher": { "placement": "header" } } }

In the studio this is Design → Languages.

The value types

Every key is optional, and an unset key changes nothing.

• Sizes are JSON numbers, in pixels. Send "radius": 12, not "radius": "12px" or "radius": "0.75rem". A string is a 422 at that key's path, for example "components.radius": ["Expected number, received string"]. Decimals are accepted (1.5). A number outside the range listed for its key is also a 422. It is not clamped.

• Colours are #rrggbb, the same rule as every other theme colour. A bare 0b835b or a three-digit #0b8 is normalised; anything else is a 422.

• Elevations (shadow, button.shadow) are none, sm, md or lg, not a raw box-shadow string. That leaves nothing to sanitise and keeps the four steps the same across surfaces.

• Spacing values are unitless multipliers from 0.5 to 2, also JSON numbers.

Shared shape

focus: the keyboard focus ring

Unset, the colour is the brand as the reader's other brand-coloured TEXT uses it — moved, per light and dark mode, until it reads on the page — so a pale brand still gets a visible ring. On the reader, a focused link, button or summary also gets a thin band of the page colour around its ring, so the ring reads on a dark card or a photo as well as on the page.

The 1px minimum on focus.width is deliberate. A visible focus ring is an accessibility commitment, so a theme can restyle it but not remove it.

code: code blocks and inline code

input: text fields

Every input on a reader page reads these: the docs sidebar's search box, the forum's search box, the search box on a 404 page, and the forum's member search.

button: buttons and the header call-to-action

An outline or link call-to-action has no fill by design, so button.background, button.ink, button.shadow and button.edge do not apply to it. Its corner and weight still follow button.radius and button.weight.

Its label is the brand colour as it reads on the page. When palette.header_background (or paletteDark.header_background) repaints the header, the label is checked against that colour instead: it stays the brand when the brand reaches 4.5:1 on the header, and otherwise takes the header's foreground — header_primary if you set one that is itself readable there, else near-black or near-white. Each mode is decided on its own. With no header palette nothing changes.

apiRef: the API reference block

How an OpenAPI operation block looks. Every key unset keeps today's look.

{
  "components": {
    "apiRef": {
      "methodColors": { "get": "#0f766e", "post": "#4338ca", "delete": "#b91c1c" },
      "methodColorsDark": { "get": "#5eead4" },
      "methodStyle": "soft",
      "surface": { "background": "#fafafa", "border": "#e4e4e7", "radius": 12 },
      "size": "sm",
      "card": false
    }
  }
}

spacing, selection, scrollbar and syntax

The sections below explain spacing, scrollbar and syntax in more detail.

spacing is a multiplier, not a length

Every gap in the reader is a literal chosen against its neighbours — a paragraph is 0.85rem from the next one, an h2 claims 2.4rem above itself, a code block pads 0.95rem/1.1rem. So spacing scales those rather than replacing them, and 1 is exactly today's layout:

• block — the gap between blocks: paragraphs, lists, quotes, code, callouts, rules, and the space under a heading.

• section — the space a heading claims above itself, which is what makes sections separate without a divider.

• pad — padding inside the surfaces our stylesheet owns: a code block, an inline code chip, a callout, a caption bar.

• scale sets all three at once; naming one of the others overrides it for that axis.

An absolute scale could only have meant anything by naming one length per element, and the first element nobody named would be the one that stopped lining up.

scrollbar: what is honoured where

width, thumb and track compile to the standard scrollbar-width and scrollbar-color — Firefox 64+, Chrome/Edge 121+, Safari 18.2+ — and, for older WebKit/Blink, to a matching ::-webkit-scrollbar block. A browser that honours the standard properties ignores the ::-webkit-scrollbar rules once they are set, so the two cannot disagree; an older one falls back to the webkit block. There is deliberately no thumb radius, hover colour or track border: scrollbar-color cannot express any of them, so they would work in one engine and silently do nothing in the others.

scrollbar-color takes a pair, so naming one colour pins the other to our neutral (a grey thumb, a transparent track) — "leave the other one alone" is not something the property can say.

syntax: the highlight.js groups

The keys are highlight.js's own class names, so a palette lifted from any hljs stylesheet maps across by name. Each one paints its whole alias group:

built_in keeps highlight.js's underscore as a key; the variable hyphenates it (--reader-syntax-built-in). The base ink of a code block is not a syntax slot — it is code.ink, the same decision as the surface it sits on.

syntax applies in every mode and syntaxDark overrides it in dark mode, exactly like palette and paletteDark. A slot you leave out of either falls through to our own palette, so an unset theme highlights code exactly as it always did.

Code themes (syntaxTheme) and the dark code surface (codeDark)

syntaxTheme names a whole code look — the ten token colours AND the surface they were drawn for, per mode:

{ "components": { "syntaxTheme": "one-dark" } }

A preset paints code BLOCKS — inline code in a sentence keeps components.code — and anything you set yourself wins slot by slot: syntax, syntaxDark, code and codeDark adjust a preset rather than fight it.

{
  "components": {
    "syntaxTheme": "github",
    "syntax": { "keyword": "#d73a49" },
    "codeDark": { "background": "#010409" }
  }
}

codeDark is code's surface in dark mode (background, ink, border), for a code block that is pale on a light page and should not stay pale on a dark one.

An ink you set for light is lifted for dark unless you set codeDark.ink: code.ink: "#24272f" with a dark codeDark.background used to leave inline code at 1:1 in dark mode. The lift is skipped when you set only the light background, because then you chose that background for both modes.

inputDark is the same for input (background, ink, border): the search field and text inputs in dark mode. An unset slot falls through to input, then to ours.

Code blocks and inline code separately, and everything else about code (2026-10-12)

components.code keeps its four keys (background, ink, border, radius, which paint blocks AND inline code) and gains:

codeDark takes the same block and inline (without radius), outer, highlightBar, highlightBackground, insert and delete for dark mode.

{
  "components": {
    "code": {
      "block": { "background": "#0b1020", "ink": "#e6e8eb", "border": "#1c2333", "radius": 12 },
      "inline": { "background": "#f1f3f5", "ink": "#1f2328", "weight": 500 },
      "copy": "icon",
      "showLanguage": true,
      "look": "inset"
    },
    "codeDark": { "inline": { "background": "#262a31", "ink": "#e6e8eb" } }
  }
}

Every key is optional and unset draws today's code block.

Links in running text (link)

{
  "components": {
    "link": {
      "underline": "always",
      "offset": 3,
      "thickness": 1,
      "weight": 400,
      "color": "#0066cc",
      "colorDark": "#2997ff"
    }
  }
}

underline is hover (today's), always or none; offset and thickness are px; weight 100–1000; color/colorDark publish --reader-link. underlineColor / underlineColorDark colour the underline itself (unset: the link's colour), and external: "arrow" puts ↗ after every absolute (http(s)://) link — including one to your own host spelled absolute.

{ "components": { "link": { "underline": "always", "underlineColor": "#c7d2fe", "external": "arrow" } } }
``` Only a
link in running text is styled — a card, a button or a mention chip that
happens to be a link keeps its own look.

#### Metadata rows and image corners

```json
{
  "components": {
    "meta": { "font": "mono", "case": "upper", "tracking": 0.06 },
    "image": { "radius": 0 }
  }
}

meta styles every [data-fx-meta] row (dates, bylines, reading time) and publishes --reader-meta-font, --reader-meta-case, --reader-meta-tracking. meta.scope: "date" keeps the face and case on the row's date only (its <time>), so a mono, upper-case date can sit beside author names set in the body face; all (the default) is the whole row — a post head's byline row as well as a feed card's. cards reaches the meta rows on feed cards only, and cards-date only the dates on feed cards, so a mono card meta leaves the post head alone. meta.size (px 10–24, a length, or one per screen size) and meta.color / meta.colorDark publish --reader-meta-size / --reader-meta-color on the same target. A feed's own card.meta sets the same tokens on the card, so it wins over these.

The button block follows components.button. Its fill, ink, border, shadow, weight and radius — and the form submit and modal buttons, which are the same element — read the --reader-button-* tokens, falling back to the brand fill and 8px corner they always had.

Lists and callouts (components.list, components.hint)

{
  "components": {
    "list": { "marker": "emdash", "markerColor": "#ff6363" },
    "hint": { "icon": "badge", "edge": "none", "background": "#f4f1fb", "radius": 12 }
  }
}

Round-5 keys (2026-10-11, Package D)

• list.marker/markerColor/itemGap reach only the lists a document wrote (a bare <ul>/<ol>). Before, they also drew on the front page's own lists — every tag of the tags band carried the theme's em dash.

• list.itemGap and hint.hang are new (rows above). A list block's own itemGap and weight, a paragraph's weight, and a row of columns' spaceBefore/spaceAfter/spaceAround are block look keys — see Advanced theming.

image.radius is --reader-img-radius: content images here, and the covers and feed cards the blog and changelog draw.

{
  "components": {
    "image": { "margin": { "lg": "2.5rem", "sm": "1.5rem" } },
    "byline": { "link": { "color": "#0a0a0a", "colorDark": "#fafafa", "weight": 600 } },
    "caption": { "align": "center" }
  }
}

image.margin is the space above and below a picture in running text (--reader-img-margin, a length or one per screen size). byline.link styles author links in a byline ([data-fx-byline] a, on posts and feed cards; a card's own card.byline.color/weight beat it). caption.align (start or center) sets every caption under a picture, a video and a code block (--reader-caption-align).

image.backdrop (CL-6) puts a panel behind every block picture in running text — the soft gradient or flat colour Cursor's and Linear's release notes frame screenshots on, without baking it into the image file. A picture inline in a sentence, a list, a table cell or a link stays bare.

{ "components": { "image": { "radius": 14, "backdrop": { "style": "gradient", "padding": 28 } } } }

The panel's corner is image.radius; the picture's reserved box still holds (no layout shift).

quote: blockquotes

These reach a quote that did not say for itself. A quote block with its own variant or align (> text {: .pull .center} in Markdown, or blockquote.attrs — see Authoring) keeps what it asked for, including an explicit default under a theme-wide pull.

A blog post's layout (post)

post arranges ONE blog post: the layout (single, rail-left, rail-right, offset, split-cover), the rail beside the words, the order of the head (kicker, date, title, dek, byline…), the cover, the share control, more to read, the breadcrumb, the authors and their card, a masthead band, the contents rail's type, a drop cap, the series navigation, and per-tag templates (byTag). Every key is optional; a theme without post renders each post as it always did. The blog's piece layouts (article-rail, article-meta-rail, article-margin, article-split) are patches over it, and your post lands on top of the one chosen.

{
  "post": {
    "layout": "rail-left",
    "rail": { "items": ["bylines", "date", "share"], "width": "16rem" },
    "header": {
      "order": ["kicker", "date", "title", "dek"],
      "kicker": "firstTag",
      "dateStyle": "mono-caps"
    },
    "cover": { "show": false },
    "share": { "position": "rail", "style": "icons" },
    "byTag": {
      "press": {
        "align": "center",
        "masthead": { "layers": [{ "color": "#0b2545" }], "scheme": "dark" }
      }
    }
  },
  "footnotes": { "placement": "margin" }
}

The whole vocabulary, key by key, is in Blog and changelog. Round 3 added the head's type and the share row's choice: header.kickerStyle (font, case, size, color, tracking, weight, rule: start|bar), header.titleLineHeight, header.gap (responsive), header.dateRule, header.filedUnder ("Filed under {tags} on {date}", strict tokens), share.networks / share.frame (circle|square|none), rail.phoneLayout: row, breadcrumbStyle.placement: grid and byline.initials. post.masthead speaks the title band's vocabulary (layers, layersDark, height, above, blend, titleColor…), plus scheme and overlapsHeader. footnotes.placement is popover (today), margin (in the right margin at 1280px and wider, inline below) or end (numbered, listed after the body).

Round-5 keys (2026-10-11): post page

byline.weight / font / roleSize / roleColor / separator, header.spacing.afterDek, header.measure ({title, dek, meta}: head|text), header.dateLocale and rail.dateLocale, breadcrumbStyle.blog: false (needs root or levels: 2), split.verticalAlign: spread, pageActions.look: text and pageActions.placement: body-end, rail.phoneLayout: spread, share.size, toc.subItemSize. The full rows are in Blog and changelog.

Each part a template adds carries a hook — [data-fx-masthead], [data-fx-breadcrumb], [data-fx-kicker], [data-fx-lede], [data-fx-byline], [data-fx-post-rail], [data-fx-author-card], [data-fx-series-nav], [data-fx-suggested] — and the page root says which layout it wears ([data-post-layout]), so the one touch no key reaches is a rule on a name rather than on our class names.

Motion (motion)

Page transitions, scroll reveals, hover treatments, a header that shrinks or hides, a reading-progress bar, and your own keyframes on the documented hooks — the animations you would otherwise write in your own site's code, as theme keys. Every reader surface honours them (docs, blog, forum, roadmap, changelog, events, courses, status, FAQ, jobs, legal, contact, the site index and the 404), on our domain and yours.

Unset is the reader you have today, byte for byte. Nothing is emitted until you set a key, so motion absent, {}, {"preset": "none"} and {"enabled": false} all produce exactly the stylesheet you had before.

Nothing is hidden from crawlers or from visitors without JavaScript. A reveal's "before" state only applies once the reader's motion script has run and has already marked every block that is on screen as shown. The served HTML is the whole, visible page; a search engine, a reader with scripts blocked, or a page whose script failed to load sees everything. A printout shows everything too. Content at the very end of a page always reveals, even on a screen as tall as the page, and a window resized to show more reveals what it now shows.

Reduced motion. When a reader's device asks for reduced motion and respectReducedMotion is on (the default), every effect becomes an instant change: durations collapse to zero, reveals become opacity-only, hover lifts and tilts stay put, loops stop, the page transition is skipped, smooth scrolling is off and the pointer glow never starts. Turning respectReducedMotion off keeps your opacity fades at their own speed for those readers (a fade instead of a snap) and nothing more: movement — lifts, tilts, slides, loops, page transitions, smooth scrolling — stays off whatever the key says, because some readers get motion sick and WCAG 2.3.3 asks you to respect them.

PATCH {"motion": null} takes the whole layer off; null on any group (reveal, hover, header, ambient, keyframes) or on one key inside a group clears just that part. A misspelt key is refused by name, like the rest of the theme.

Presets

preset sets everything at once. Every other key overrides the preset one key at a time, so {"preset": "lively", "reveal": {"stagger": 0}} keeps lively's reveal effect and only drops the stagger.

What a reveal applies to

reveal.targets picks what scrolls in. everything is the recommended choice and what every preset uses: every top-level block of every body (an article, a post, a page) and every entry of an index page, in reading order, staggered as they come into view together.

Or name kinds. Every block type belongs to exactly one:

What keeps it seamless, whatever you pick:

• Nothing on screen at load fades in. What is visible when the page opens is marked shown before reveals are armed; only what is below the fold starts hidden, and it is hidden at once, never faded out.

• One entrance per thing. A block inside another that is also revealing (the paragraphs of a callout, the code in its titled frame, the blocks of a forum post) moves with its container, never twice.

• Tall blocks reveal in pieces. A block taller than the screen (a long table, list, feed or section) reveals by its child blocks as each reaches the viewport, instead of once while most of it is still off screen.

• Late content reveals too: posts a forum appends live, lazy blocks, and the new page after a client-side navigation. Code highlighting and images loading replay nothing, and nothing moves the layout — a reveal changes only opacity, transform and filter.

lively and playful make the header sticky, overriding chrome.sticky. Set "header": {"behavior": "static"} (or null to fall back to chrome.sticky) if you want their other effects without it.

The keys

ambient.scrollProgress is the fixed bar at the very top; the docs header's 2px rule is docs.topRule. An explicit scrollProgress: false also drops that rule unless docs.topRule says otherwise.