Portal JSON — Component Reference

Complete reference for every component in the portal JSON format: fields, types, allowed values, and defaults. For a tutorial overview see PORTAL_JSON.md; for styling (custom_css hooks + limits) see PORTAL_CUSTOMIZATION.md.

All values come from the live schema (app/portal_io.py, app/composer.py, app/render.py). Unknown fields are dropped on import; any field you omit falls back to the default shown here.

Legend — Type column: string, int, bool, object, array<T>, enum(...). Req column: ● required, ○ optional.

1. Document envelope

The top-level object.

2. Theme object

Every theme key is optional; omitted keys use the portal default. Colors accept any CSS color string (#rrggbb, rgb(...), named). Grouped by purpose.

2.1 Color

2.2 Search overlay (optional accents)

Derived from brand/surface by default; set only to tune the ⌘K search chrome.

2.3 Typography

Curated webfonts (first family in a stack triggers a Google Fonts import, only if external fonts are enabled): Inter, Manrope, Plus Jakarta Sans, Lora, Newsreader, Source Serif 4, JetBrains Mono, IBM Plex Mono. Any other family is used as-is with no external request.

2.4 Shape / density

2.5 Layout (page skeleton)

2.6 Branding & chrome

2.7 Background (art direction)

theme.background is a declarative BackgroundSpec — a stack of layers the renderer composes into one CSS background, painted identically in the composer canvas, the live-preview iframe, and the published page. It is config, not CSS or JS. Design rationale lives in ART_DIRECTION_SPEC.md; this table is the shipped schema.

BackgroundSpec

Layer — every layer has a type. All types accept an optional visibility: { "desktop"?: bool, "mobile"?: bool }; a layer set false for a surface is dropped there (mobile drop emits a @media (max-width:640px) rule).

stop = { "color": ColorValue, "at": 0–100 }. Anchors are the 9-grid top-left … center … bottom-right. The animated layer type is reserved (accepted but not painted) — use the spec-level "animated": true flag for motion.

ColorValue — either a CSS color string ("#5b5bd6", "#5b5bd6cc", …) or a theme-token ref { "token": <name>, "alpha"?: 0–1 }. Token names mirror the CSS variables: brand, accent, bg, surface, text, muted, border (note brand, not the theme field name primary). alpha wraps the token in color-mix(... N%, transparent); an unknown token falls back to brand. Prefer token refs over literals so a background reskins with the theme.

"background": {
  "scope": "hero",
  "scrim": "auto",
  "animated": true,
  "layers": [
    { "type": "color", "color": { "token": "bg" } },
    { "type": "gradient", "kind": "mesh", "blobs": [
      { "color": { "token": "brand" }, "x": 18, "y": 22, "radius": 55 },
      { "color": { "token": "accent" }, "x": 82, "y": 30, "radius": 48 }
    ] },
    { "type": "noise", "intensity": 0.06 }
  ]
}

Guarantees. render_background(theme) is a pure function of (spec, theme), so the same spec yields byte-identical CSS in preview and publish. Image and decoration URLs pass a scheme guard (blocks javascript: etc.); a missing or unsafe URL drops just that layer, never the page.

3. Page object

4. Blocks

Every block is { "type": <enum>, "config": <object> }.

type — one of: markdown, code, callout, image, tabs, card_grid, divider, endpoint, schema, endpoint_list.

Config fields per type below. Unknown config keys are dropped.

4.1 markdown

4.2 code

language values: bash, javascript, typescript, jsx, tsx, python, go, rust, java, ruby, json, yaml, sql, css, markup (HTML/XML), plain.

4.3 callout

4.4 image

4.5 tabs

Tab object:

4.6 card_grid

Card object:

Media priority when several are set: icon_url → image → icon.

4.7 divider

No config. { "type": "divider", "config": {} }.

4.8 endpoint (spec-driven)

Renders one operation from an attached spec.

show keys (all bool, default true): params, request_body, responses, code_samples, try_it.

4.9 schema (spec-driven)

4.10 endpoint_list (spec-driven)

Renders every operation of a spec as a compact list.

Finding address values: export a spec-driven portal (Settings → General → Export JSON) to see the exact op: / schema: addresses the spec exposes.

5. Nav object

The sidebar structure. Omit to auto-generate from the page list; include (as produced by export) to preserve exact sections, icons, and ordering. Pages are referenced by slug, so nav stays valid across import.

{
  "topbar": {
    "search": true,
    "links": [
      { "id": "l1", "label": "Status", "url": "https://status.example.com" }
    ]
  },
  "tabs": [
    {
      "id": "t1",
      "label": "Documentation",
      "groups": [
        {
          "id": "g1",
          "label": "Getting started",
          "items": [
            { "id": "i1", "type": "page", "page_slug": "overview", "icon": "rocket", "hidden": false },
            { "id": "i2", "type": "external", "label": "Anthropic", "url": "https://anthropic.com", "hidden": false }
          ]
        }
      ]
    }
  ]
}

Topbar (optional):

Link: id (string, preserved on round-trip), label (string), and url (absolute URL).

Tab: id (string), label (string), groups (array<Group>). Use a unique, stable id when authoring JSON so later composer edits and round-trips can identify the same navigation node.

Group: id (string), label (string), items (array<Item>). Group and item IDs should also be unique and stable within the navigation document.

Item:

Nav is reconciled against the actual pages at render/publish, so minor drift (a page added without a nav entry) is auto-healed.

6. Enumerations quick reference

7. Caps & safety

Import always creates a new portal; it never edits an existing one. auth_required is not carried across import — a new portal starts as Draft (safe default); set its access in Settings afterward.