> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inklyai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Top-level fields

> Identity, visibility, chrome, background, theme, and aspect-ratio fields in demo.config.json.

Top-level fields are the demo's main settings. They name the demo, decide whether it is public, control the player chrome, and point to the ordered list of steps.

Start here when you want to change how the whole demo behaves, rather than changing one individual screen.

| Field             | Type                      | Required | Default    | Notes                                                                                                                                              |
| ----------------- | ------------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | `string`                  | Yes      | —          | Stable, opaque demo identity. Exactly 12 characters from the URL-safe alphabet `A-Z a-z 0-9 - _` (pattern `^[A-Za-z0-9_-]{12}$`).                  |
| `version`         | `integer`                 | Yes      | —          | Schema version. Use `1` today. The parser accepts positive integers for forward compatibility.                                                     |
| `title`           | `string`                  | No       | —          | Demo title.                                                                                                                                        |
| `subtitle`        | `string`                  | No       | —          | Demo subtitle.                                                                                                                                     |
| `runtime`         | `string`                  | No       | —          | Optional per-demo runtime version override. Use sparingly.                                                                                         |
| `visibility`      | `"public"` \| `"private"` | No       | `"public"` | `private` demos are hidden from the hub index and return 404 on direct public URLs. Local `inkly dev` ignores this flag.                           |
| `background`      | `object`                  | No       | —          | Full-page canvas background behind the player. See [Demo background](#demo-background).                                                            |
| `backgroundColor` | `string`                  | No       | —          | Legacy solid-color canvas hex. New authors should use `background`.                                                                                |
| `theme`           | `object`                  | No       | —          | Per-demo theme override. See [Theme override](#theme-override).                                                                                    |
| `chrome`          | `object`                  | No       | `{}`       | Player chrome toggles. See [Chrome](#chrome).                                                                                                      |
| `aspectRatio`     | `object`                  | No       | —          | Explicit player aspect ratio. When set, wins over the auto-detected ratio from the first content step. `{ width, height }`, both positive numbers. |
| `chapters`        | `object[]`                | No       | `[]`       | Navigation metadata grouping step ids. See [Navigation and actions](/schema/demo/navigation-and-actions).                                          |
| `steps`           | `object[]`                | Yes      | —          | Ordered cover and content steps. At least one is required.                                                                                         |

## Chrome

Player chrome toggles control the embed look without changing step content.

| Field                 | Type                                  | Required | Default | Notes                                                                                                                          |
| --------------------- | ------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `hideHeader`          | `boolean`                             | No       | `false` | Skip rendering the header chrome.                                                                                              |
| `hideControls`        | `boolean`                             | No       | `false` | Legacy boolean. When `controls` is unset, the renderer reads `hideControls ? 'hidden' : 'full'`.                               |
| `controls`            | `"full"` \| `"minimal"` \| `"hidden"` | No       | —       | Tri-state controls mode that layers over `hideControls`.                                                                       |
| `showHubBreadcrumb`   | `boolean`                             | No       | `false` | When `true`, hosted and CLI player shells link the header back to the parent hub.                                              |
| `mobileFooterMessage` | `boolean`                             | No       | `true`  | On small viewports, hide the in-stage message and show a footer bar with step nav.                                             |
| `autoplay`            | `boolean`                             | No       | `false` | When `false`, the player waits for Next at the end of each step. When `true`, the engine honors each step's `advance.trigger`. |

## Demo background

The full-page canvas sits behind the player. `type` selects the source.

| Field   | Type                               | Required    | Default | Notes                                                                                                                  |
| ------- | ---------------------------------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `type`  | `"none"` \| `"color"` \| `"image"` | Yes         | —       | `none` uses Inkly's default dotted gray canvas; `color` uses a flat fill or gradient; `image` uses a wallpaper source. |
| `color` | `string`                           | Conditional | —       | Hex color for a flat fill. Required for `type: "color"` unless `from`/`to` are set.                                    |
| `from`  | `string`                           | Conditional | —       | Gradient start hex. Required together with `to` for a gradient.                                                        |
| `to`    | `string`                           | Conditional | —       | Gradient end hex. Required together with `from`.                                                                       |
| `src`   | `string`                           | Conditional | —       | Image source. Required for `type: "image"`.                                                                            |
| `alt`   | `string`                           | No          | —       | Alt text for the image background.                                                                                     |

## Theme override

| Field    | Type     | Required | Default | Notes                                                                                                                           |
| -------- | -------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `preset` | `string` | No       | —       | Swaps the active preset for this demo, overriding the hub `theme`.                                                              |
| `tokens` | `object` | No       | —       | Token overrides applied after preset defaults and hub tokens. Same four fields as hub [Theme tokens](/schema/hub/theme-tokens). |
| `brand`  | `object` | No       | —       | Per-demo brand override. Same shape as hub [Branding](/schema/hub/branding) minus `favicon` because favicon is hub-owned.       |