Top-level fields

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.
`backgroundColor`	`string`	No	—	Legacy solid-color canvas hex. New authors should use `background`.
`theme`	`object`	No	—	Per-demo theme override. See Theme override.
`chrome`	`object`	No	`{}`	Player chrome toggles. See 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.
`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.
`brand`	`object`	No	—	Per-demo brand override. Same shape as hub Branding minus `favicon` because favicon is hub-owned.

​Chrome

​Demo background

​Theme override

Chrome

Demo background

Theme override