@514sid/signagekit 0.0.0-stage → 0.0.2

package/docs/format.md

@@ -0,0 +1,183 @@
+# Document format
+
+A screen is one document, JSON or YAML, plus an optional data object. The document holds the shape of the screen; the data holds anything that changes: values, states, list rows, messages. Something that updates the screen then only rewrites the data.
+
+[schema.json](../schema.json) has every property with its default; editors that read JSON Schema autocomplete and check documents against it.
+
+## Example
+
+```yaml
+# yaml-language-server: $schema=https://signagekit.514sid.com/schema.json
+colors:
+  scheme: dark
+  accent: '#2563eb'
+
+layout:
+  design: landscape
+  flow:
+    - { zone: head, span: 9, height: 150px }
+    - { zone: clock, span: 3, height: 150px }
+    - { zone: menu, span: 8, height: 3 }
+    - { zone: side, span: 4, height: 3 }
+
+zones:
+  head: { type: heading, text: Today's lunch }
+  clock: { type: clock, show_date: true }
+  menu:
+    { type: table, title: Menu, columns: [Dish, Price], rows: { bind: /menu } }
+  side: { type: list, title: Notices, items: { bind: /notices } }
+```
+
+[examples/lunch](../examples/lunch/) has this screen in full. [examples/](../examples/) has more, one folder per screen with its layout and data.
+
+## Layout
+
+The canvas is 1080 px on the screen's short side and follows its shape, so a 4:3, 21:9 or portrait screen is never letterboxed. All sizes in a document are px on that canvas.
+
+A `flow` layout lists zones in reading order and is designed once, for landscape or portrait (`design`, default landscape). `span` is the zone's width in the design orientation, out of 12 columns (default 12). `height` is a share of the free height, like CSS `fr` (default 1), or fixed pixels such as `150px`.
+
+On a screen of another shape each zone keeps about its designed width. On a narrower screen zones take more columns and move to new rows; on a wider one they shrink up to a quarter to share a row. Every row fills the full width, and zones in a row take the tallest height in it. A fixed-height strip, like a header or footer, never shares a row with zones that grow. On a screen of the design's own orientation, a row whose spans add up to 12 stays exactly as written.
+
+For a screen that must stay exactly as drawn, `areas` takes a fixed CSS grid instead (`areas`, `columns`, `rows`). It doesn't reflow for other shapes.
+
+Zone names use lowercase letters, digits, `-` and `_`, and start with a letter. A zone in `zones` that the layout doesn't place is a warning; a name in the layout without a zone is left empty.
+
+## Components
+
+Every component can also take `title` (a small label above it), `icon` (shown before the title), `surface` (`base`, `raised` or `accent`), `size` and `weight` (see [Adjusting by hand](#adjusting-by-hand)).
+
+| Type        | Shows                                                                                  | Required                   |
+| ----------- | -------------------------------------------------------------------------------------- | -------------------------- |
+| `heading`   | Large title filling its zone                                                           | `text`                     |
+| `text`      | Paragraph; `fit: true` fills the zone, else `size` s, m, l or xl                       | `text`                     |
+| `stat`      | Big number with `unit`, `label`, `state`, `thresholds`, `trend`, `spark`               | `value`                    |
+| `meter`     | One value against `max` (default 100) with a bar                                       | `value`                    |
+| `meters`    | One row per item, value against limit, bars lined up                                   | `items`                    |
+| `bars`      | Ranked horizontal bars, largest first                                                  | `items`                    |
+| `split`     | One whole in up to six parts, shares printed                                           | `items`                    |
+| `chart`     | Line, area or column chart, with optional `target` line                                | `kind`, `labels`, `series` |
+| `table`     | Rows and columns; pages when rows don't fit                                            | `columns`, `rows`          |
+| `list`      | Bulleted list                                                                          | `items`                    |
+| `status`    | Rows with a state icon each, like service health                                       | `items`                    |
+| `schedule`  | Entries from the current one on, with Now and Next marked                              | `items`                    |
+| `queue`     | "Now serving" number and the recently called ones                                      | `current`                  |
+| `clock`     | Current time, optionally the date                                                      |                            |
+| `clocks`    | One clock per time zone                                                                | `zones`                    |
+| `countdown` | Time left until `to`; shows `done` (default "Now") once it has passed                  | `to`                       |
+| `cycle`     | One-line messages that swap instantly on a timer, never scrolling                      | `items`                    |
+| `image`     | Image from an https URL                                                                | `src`                      |
+| `slideshow` | Images swapped instantly on a timer                                                    | `images`                   |
+| `qr`        | QR code, black on white so phones can scan it                                          | `value`                    |
+| `stack`     | Splits a zone into parts holding other components; `direction` row or column (default) | `items`                    |
+
+The schema has every property, with defaults.
+
+## Data
+
+### Binding
+
+Any value can be a literal or a bind: `{ bind: /menu/0/2 }` reads key `menu`, item 0, item 2. Add `fallback` to show something when the path is missing or empty: `{ bind: /wait, fallback: Ask at the desk }`.
+
+Bound lists take the same shape as their literal form:
+
+| Component                    | Each item                         |
+| ---------------------------- | --------------------------------- |
+| `table.rows`                 | an array of cells                 |
+| `list`, `cycle`, `slideshow` | a string                          |
+| `meters`, `bars`, `split`    | `{ label, value, max?, state? }`  |
+| `status`                     | `{ label, state, note? }`         |
+| `schedule`                   | `{ start, end?, title, detail? }` |
+| chart `labels` and `values`  | a string or number per point      |
+
+### Missing and empty values
+
+Nothing breaks and nothing renders as a blank box:
+
+- A missing single value (a stat, a meter, a queue number, a table cell) shows a dash, unless its bind has a `fallback`.
+- Empty list items are skipped, and an empty list, table, chart, cycle or schedule shows "Nothing to show" (or similar).
+- A countdown past its time shows its `done` text.
+- `check()`, `mount()` and the `signagekit check` command warn about every bind whose path isn't in the data.
+
+### Numbers and text
+
+YAML data is read with every value as text, so a price written as `4.50` stays `4.50`. JSON data keeps its numbers. Either way, components that need numbers (meters, bars, charts, thresholds) read numeric text like `1,240` as a number, and stats shorten values from 10,000 up (`format: full` shows every digit).
+
+A YAML layout uses the core schema, so `true`, `24` and `+6` are a boolean and numbers. Quote layout values that must stay text: `delta: '+0.04'` keeps its plus sign. In YAML generally, quote any value that starts with `%`, `#`, `@` or `*`, and any value containing `: ` or, inside `{ }` and `[ ]`, a comma.
+
+## How text is sized
+
+You don't set sizes; signagekit does, after every render, for the zone sizes on the actual screen:
+
+- Small zones get tighter padding, and short strips put their title beside the content, so content always has room.
+- Text grows to fill its zone, then snaps to a type scale. Row-based components (tables, lists, status, meters, bars, schedules, world clocks) share one body size across the screen. Stats and countdowns in a row share a size, so values and labels line up. Headings and cycles stay within a few times the body size.
+- Text never goes below a readable size (22 px). Lists that don't fit drop whole rows from the end and say "+N more"; tables page; a table too wide truncates its widest column with an ellipsis; long titles and labels end in an ellipsis.
+- A row of three or more narrow stats in a stack wraps into two columns.
+
+## Adjusting by hand
+
+Every automatic choice can be overridden:
+
+| Property           | On                 | Does                                                                    |
+| ------------------ | ------------------ | ----------------------------------------------------------------------- |
+| `size`             | any component      | Pins the text size in px and skips automatic sizing for that zone       |
+| `weight`           | parts of a `stack` | Share of the space relative to siblings, like 1 and 3 (default 1)       |
+| `match_row: false` | `stat`             | Keeps its own size instead of matching its row                          |
+| `format: full`     | `stat`             | Shows every digit instead of 1.2M                                       |
+| `page_rows`        | `table`            | Most rows per page (pages still shrink if fewer fit)                    |
+| `widths`           | `table`            | Relative column widths, like `[3, 1, 1]`; long cells end in an ellipsis |
+| `y_min`, `y_max`   | `chart`            | Fixed y-axis range                                                      |
+| `limit`            | `bars`             | Rows to show (default 12)                                               |
+
+## States, thresholds and trends
+
+`stat` and `meter` take `state`: `neutral`, `good`, `warning` or `danger`, literal or bound. A state adds a colored strip across the top of the zone (down its left edge in short zones) and a badge by the label with a check, an exclamation mark or a cross, so it never relies on color alone. In short zones, where the label may not fit, the badge moves into the title line. The label defaults to Good, Warning or Danger.
+
+`thresholds` sets the state from the value, so data only carries numbers: `{ warning: 80, danger: 95 }` shows warning from 80 and danger from 95. With danger below warning, lower is worse: `{ warning: 40, danger: 20 }` for a battery. An explicit `state` wins. On `meters`, thresholds apply to each row without its own state.
+
+A `stat` can show a trend arrow: `trend` is `up`, `down` or `flat`, `delta` is text beside it like `+12%`, and `good_when` (`up` or `down`) colors the arrow green when the move is good news and red when it isn't. Without `good_when` the arrow stays neutral. `spark` adds recent values as a small line under the number.
+
+## Charts
+
+`chart` draws line, area and column charts with [uPlot](https://github.com/leeoniya/uPlot), loaded only on screens that have one. Series take colors from a fixed order checked for color blindness and contrast on both schemes. Two or more series get a legend with each series' latest value; column charts print each value on its bar. `target` draws a labelled line, like a goal or an SLO, and stays in view. Column and area charts start at zero; `y_min` and `y_max` fix the range. Charts don't animate and have no hover, since screens aren't interactive.
+
+## Alerts
+
+One `alert` block covers every screen-wide message, from an evacuation to a maintenance notice:
+
+```yaml
+alert:
+  level: danger # info, good (all clear), warning or danger
+  icon: fire # names the situation; see the icon list below
+  title: Fire alarm # short, shown very large
+  message: Leave the building now by the nearest exit.
+  steps: # numbered instructions
+    - Do not use the lifts
+    - Gather at assembly point B
+  footer: Wait for the all clear.
+  mode: takeover # or banner: a strip across the top, screen stays visible
+  until: '2026-11-14T15:00:00Z' # optional: stops showing after this time
+```
+
+It shows while its `title` or `message` is set. Bind the whole alert to the data, `alert: { bind: /alert }`, and an assistant raises or clears it by writing the data alone: an object with the fields above shows it, and `null` or an empty object brings the screen back. Unknown levels show as danger and unknown icons fall back to the level's icon, so a bad value never hides an alert. The older `text` and `state` fields still work as `message` and `level`.
+
+### Icons
+
+Alerts and zone titles share one set of icons from [Lucide](https://lucide.dev): `info`, `check`, `warning`, `danger`, `fire`, `evacuate`, `assembly`, `medical`, `first-aid`, `storm`, `wind`, `snow`, `flood`, `heat`, `lockdown`, `shelter`, `security`, `power`, `water`, `network`, `closed`, `delay`, `maintenance`, `announcement`, `phone`, `biohazard`, `radiation`, `chemical`, `event`, `location` and `accessibility`. Any zone can set `icon` to show one before its title in place of the square marker. Storybook shows them all under Components → Alerts → Icons.
+
+## Colors
+
+All colors come from the `colors` block as hex values: `background`, `surface`, `text`, `muted`, `line`, `accent`, `on_accent`, and the state colors `good`, `warning` and `danger`. `scheme` (`dark` or `light`) fills in whatever is left out; without it the `scheme` passed to `mount()` decides (default dark), so set it when a screen must look the same everywhere. `accent` defaults to the accent passed to `mount()`, else `#2563eb`, and `on_accent` to whichever of near-black and white reads better on it. signagekit warns when text has less than 4.5:1 contrast with its background, and when a state color leaves its icon under 3:1.
+
+## Versions
+
+`version` says which format a document is written in. Leaving it out means format 1, the current one; writing `version: 1` keeps the document unambiguous when the format changes later.
+
+When the format changes, signagekit keeps reading the old one. A document in an older format is upgraded on load, one version at a time, and any property with no place in the new format is reported as a warning. Each upgrade step is its own small file, loaded only for documents that need it, so current documents load no upgrade code.
+
+A document in a newer format than the library reads is shown as far as it can be. Everything the library knows renders; newer properties and component types are skipped with warnings, and the first warning names the format the document was written for. A screen therefore never goes blank because a player runs an older version.
+
+The data has no version of its own. Its shape follows the binds in the layout.
+
+## Errors
+
+Errors drop only what they affect: a broken layout renders nothing, a broken zone is left out and the rest of the screen renders, and warnings never block rendering. Every message names the exact path, like `zones.menu.rows: expected an array or a bind`.

package/docs/getting-started.md

@@ -0,0 +1,77 @@
+# Getting started
+
+signagekit turns a short document into a screen. The document names the zones of the screen and what each one shows; a separate data object holds the values that change. signagekit lays the zones out for the screen's shape and sizes all the text together.
+
+## Install
+
+```bash
+npm install @514sid/signagekit
+```
+
+## A first screen
+
+Write the layout. This one has a heading, a clock, a table and a stat:
+
+```yaml
+# lunch.layout.yml
+layout:
+  flow:
+    - { zone: head, span: 9, height: 150px }
+    - { zone: clock, span: 3, height: 150px }
+    - { zone: menu, span: 8 }
+    - { zone: wait, span: 4 }
+zones:
+  head: { type: heading, text: Today's lunch }
+  clock: { type: clock, show_date: true }
+  menu: { type: table, columns: [Dish, Price], rows: { bind: /menu } }
+  wait: { type: stat, title: Wait time, value: { bind: /wait }, unit: min }
+```
+
+Then the data. Each `{ bind: /path }` in the layout reads a value from it:
+
+```yaml
+# lunch.data.yml
+menu:
+  - [Tomato soup, 4.50]
+  - [Chickpea curry, 7.90]
+  - [Grilled halloumi wrap, 6.50]
+wait: 6
+```
+
+Mount it into an element. The screen fills the element, so size the element the way the screen should be:
+
+```js
+import { mount } from '@514sid/signagekit'
+import '@514sid/signagekit/style.css'
+
+const screen = await mount(document.getElementById('screen'), {
+  layout: await fetch('lunch.layout.yml').then((r) => r.text()),
+  data: await fetch('lunch.data.yml').then((r) => r.text()),
+})
+```
+
+When the values change, update the data and leave the layout alone:
+
+```js
+await screen.update({ data: { menu, wait: 12 } })
+```
+
+## Check it
+
+```bash
+npx @514sid/signagekit check lunch.layout.yml lunch.data.yml
+```
+
+The check lists every error and warning with its exact path: unknown properties, low contrast, and binds that find nothing in the data. It exits with 1 on errors.
+
+## See it without a display
+
+```bash
+npx @514sid/signagekit url lunch.layout.yml lunch.data.yml --mode sizes
+```
+
+This prints a link to the [preview tool](preview.md) with the screen packed into it. Open it to see the screen at five resolutions at once, from Full HD to portrait and ultrawide, or point a headless browser at it for a screenshot.
+
+## Next
+
+The [document format](format.md) covers every layout option and component. [Writing with assistants](assistants.md) has the rules to give an AI that writes screens for you. The [API](api.md) lists every option of `mount()` and `check()`.

package/docs/preview.md

@@ -0,0 +1,84 @@
+# Preview tool
+
+The preview page renders a screen from its URL, so a person can share a screen as a link and an AI assistant can screenshot what it built. Everything it needs is in the URL; nothing is uploaded.
+
+```bash
+npx @514sid/signagekit url screen.layout.yml screen.data.yml --mode sizes
+```
+
+prints a link like `https://signagekit.514sid.com/preview/?mode=sizes#s=rVXfb9s2...`. The layout and data are compressed into the part after `#s=`, which browsers never send to a server.
+
+## Modes
+
+| `mode`    | Shows                                                                                                             |
+| --------- | ----------------------------------------------------------------------------------------------------------------- |
+| `screen`  | One screen. With `size`, at that resolution; without, the window is the screen. The default.                      |
+| `sizes`   | The screen at several resolutions side by side, to check that a flow layout adapts. Problems are listed.          |
+| `schemes` | The screen in the dark and the light scheme side by side.                                                         |
+| `edit`    | An editor for the layout and data with the screen beside it, and a resolution menu. The link updates as you type. |
+
+## Parameters
+
+| Parameter                | Example                         | Does                                                                                                   |
+| ------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `#s=`                    | from `signagekit url`           | The layout and data, compressed. Use this one when you can.                                            |
+| `layout`, `data`         | `?layout=%7B...%7D`             | The layout and data as URL-encoded JSON or YAML, for short documents.                                  |
+| `layout_url`, `data_url` | `?layout_url=https://...`       | Fetch the layout and data from URLs. The server must allow cross-origin requests.                      |
+| `example`                | `noc-wall`                      | One of the [examples](../examples/).                                                                   |
+| `mode`                   | `sizes`                         | See above.                                                                                             |
+| `size`                   | `portrait` or `fullhd,1366x768` | Resolutions, by name or as `WIDTHxHEIGHT`. One for `screen`, `schemes` and `edit`; a list for `sizes`. |
+| `frame`                  | `480`                           | In `sizes` and `schemes`, the long side of each screen on the page in px. Default 640.                 |
+| `scheme`                 | `light`                         | Shows the screen in this scheme, even when the document sets its own.                                  |
+| `accent`                 | `%23e11d48`                     | Accent when the document doesn't set one. Encode `#` as `%23`.                                         |
+| `tz`, `locale`           | `Europe/Berlin`, `de-DE`        | Time zone and locale for clocks, dates and schedules.                                                  |
+| `now`                    | `2026-11-14T09:30`              | Freezes the clock, so clocks, schedules and countdowns come out the same every time.                   |
+| `problems`               | `1`                             | In `screen` mode, show errors and warnings over the screen.                                            |
+
+## Resolutions
+
+Every screen renders at its real resolution and is scaled down to fit, so text sizes come out exactly as on that display. Any `WIDTHxHEIGHT` works, from 64 to 16384 px a side. These have names:
+
+| Name           | Resolution | Also              |
+| -------------- | ---------- | ----------------- |
+| `hd`           | 1280×720   | `720p`            |
+| `fullhd`       | 1920×1080  | `1080p`, `fhd`    |
+| `qhd`          | 2560×1440  | `1440p`           |
+| `4k`           | 3840×2160  | `uhd`, `2160p`    |
+| `hd-portrait`  | 720×1280   |                   |
+| `portrait`     | 1080×1920  | `fullhd-portrait` |
+| `4k-portrait`  | 2160×3840  |                   |
+| `xga`          | 1024×768   | 4:3               |
+| `xga-portrait` | 768×1024   | 3:4               |
+| `sxga`         | 1280×1024  | 5:4               |
+| `ultrawide`    | 2560×1080  | 21:9              |
+| `bar`          | 1920×540   | 32:9 strip        |
+| `square`       | 1080×1080  |                   |
+
+Without `size`, `sizes` mode shows `fullhd`, `portrait`, `xga`, `ultrawide` and `square`. The library exports the same list as `SIZES`, with `parseSize()` to read either form.
+
+## Taking screenshots
+
+The page sets `data-status` on `<html>` to `ready` once every screen on it is drawn, charts included, or to `error` when the layout couldn't be read. Wait for it before taking the screenshot. The same result is on `window.signagekit` as `{ status, errors, warnings }`, and every error and warning is also logged to the console.
+
+For a screenshot of one screen at its real pixels, use `screen` mode without `size` and make the window that size:
+
+```js
+await page.setViewportSize({ width: 1080, height: 1920 })
+await page.goto(url)
+await page.waitForSelector(
+  'html[data-status="ready"], html[data-status="error"]',
+)
+await page.screenshot({ path: 'screen.png' })
+```
+
+With Chrome alone, give the page a few seconds of virtual time:
+
+```bash
+chrome --headless --window-size=1920,1080 --virtual-time-budget=5000 --screenshot=screen.png "$URL"
+```
+
+When you can't set the window size, pass `size` instead: the screen lays out for that resolution and scales to fit the window. `sizes` mode needs a window about 1400 px wide and a full-page screenshot.
+
+## Running your own
+
+The site is static. Build it with `bun run site:build` and serve `site/dist` from anywhere; pass `--base https://your.host/preview/` to `signagekit url`, or `base` to `previewUrl()`, to link to your copy.

package/examples/clinic-queue/data.json

@@ -0,0 +1,17 @@
+{
+  "current": "B 047",
+  "recent": ["A 112", "B 046", "A 111", "B 045"],
+  "wait": 18,
+  "clinics": [
+    { "start": "10:00", "end": "12:00", "title": "Diabetes review", "detail": "Room 4, Nurse Hughes" },
+    { "start": "12:00", "end": "14:00", "title": "Walk-in minor illness", "detail": "Room 1, Dr Okafor" },
+    { "start": "14:00", "end": "16:00", "title": "Child immunisations", "detail": "Room 3, Nurse Patel" },
+    { "start": "16:00", "end": "17:30", "title": "Flu jab drop-in", "detail": "Room 4, Nurse Hughes" },
+    { "start": "17:30", "end": "18:00", "title": "Prescription pick-up", "detail": "Reception" }
+  ],
+  "messages": [
+    "Please keep your ticket until called",
+    "Masks available at reception",
+    "Flu jab drop-in 16:00 to 17:30 today"
+  ]
+}

package/examples/clinic-queue/layout.yml

@@ -0,0 +1,43 @@
+# yaml-language-server: $schema=https://signagekit.514sid.com/schema.json
+# Elm Park Surgery waiting room. Light scheme for a bright room, ticket
+# numbers only so no patient names are on the wall.
+colors:
+  scheme: light
+  accent: '#0f766e'
+
+layout:
+  design: landscape
+  flow:
+    - { zone: head, span: 8, height: 170px }
+    - { zone: clock, span: 4, height: 170px }
+    - { zone: serving, span: 5, height: 4 }
+    - { zone: clinics, span: 7, height: 4 }
+    - { zone: ticker, height: 110px }
+
+zones:
+  head: { type: heading, text: Elm Park Surgery, icon: medical }
+  clock: { type: clock, surface: raised, hour12: false, show_date: true }
+  serving:
+    type: stack
+    items:
+      - type: queue
+        weight: 4
+        label: Now calling
+        current: { bind: /current }
+        recent: { bind: /recent }
+      - type: stat
+        weight: 2
+        title: Average wait
+        value: { bind: /wait }
+        unit: min
+        thresholds: { warning: 20, danger: 40 }
+  clinics:
+    type: schedule
+    title: Clinics today
+    rows: 5
+    items: { bind: /clinics }
+  ticker:
+    type: cycle
+    surface: accent
+    seconds: 8
+    items: { bind: /messages }

package/examples/fire-alarm/data.yml

@@ -0,0 +1,23 @@
+hours:
+  - [Maternity, '14:00 - 20:00']
+  - [Surgical, '15:00 - 19:00']
+  - [Paediatrics, '10:00 - 20:00']
+  - [Cardiology, '14:00 - 18:00']
+notices:
+  - Two visitors per bed
+  - Use the hand gel at every ward door
+  - Parking validation at Reception
+
+alert:
+  level: danger
+  icon: fire
+  title: Fire alarm
+  message: 'Fire reported on Level 2, East Wing. Leave the building by the nearest exit.'
+  steps:
+    - Do not use the lifts
+    - Follow the green exit signs
+    - Staff will guide patients and visitors
+    - Gather in Car Park B, away from the entrance
+  footer: 'Do not re-enter until a fire officer gives the all clear. Updated 14:32'
+  mode: takeover
+  until: '2026-11-15T00:00:00Z'

package/examples/fire-alarm/layout.yml

@@ -0,0 +1,30 @@
+# yaml-language-server: $schema=https://signagekit.514sid.com/schema.json
+# St. Mary's Hospital main entrance: visitor information, with a fire alarm
+# takeover bound to /alert. Clear the alert by setting /alert to null.
+colors:
+  scheme: light
+  accent: '#0b5cad'
+
+layout:
+  design: landscape
+  flow:
+    - { zone: head, span: 9, height: 170px }
+    - { zone: clock, span: 3, height: 170px }
+    - { zone: hours, span: 7, height: 2 }
+    - { zone: info, span: 5, height: 2 }
+
+zones:
+  head: { type: heading, text: Welcome to St. Mary's }
+  clock: { type: clock, surface: raised, show_date: true }
+  hours:
+    type: table
+    title: Visiting hours
+    columns: [Ward, Hours]
+    align: [start, end]
+    rows: { bind: /hours }
+  info:
+    type: list
+    title: Visitor notices
+    items: { bind: /notices }
+
+alert: { bind: /alert }

package/examples/gym-classes/data.yml

@@ -0,0 +1,17 @@
+# Leeds is on GMT in November, so Z matches local time.
+next_at: '2026-11-14T14:00:00Z'
+next_label: Spin Power, Studio 1
+spots_left: 3
+spots_label: Book in the app
+classes:
+  - ['14:00', Spin Power, Studio 1, Dani, 3 left]
+  - ['14:30', Yoga Flow, Studio 2, Mei, 8 left]
+  - ['15:15', HIIT 45, Studio 1, Marcus, 11 left]
+  - ['16:00', Pilates Core, Studio 2, Sofia, Full]
+  - ['17:00', Boxfit, Studio 3, Jayden, 6 left]
+  - ['17:30', Spin Endurance, Studio 1, Dani, 9 left]
+  - ['18:00', Stretch and Restore, Studio 2, Mei, 14 left]
+messages:
+  - Towels at the front desk
+  - Late cancellations after 2 hours are charged
+  - Sauna closed for cleaning 15:00 to 15:30

package/examples/gym-classes/layout.yml

@@ -0,0 +1,47 @@
+# yaml-language-server: $schema=https://signagekit.514sid.com/schema.json
+# Pulse Fitness Leeds, reception wall. Landscape, dark with a hot accent.
+colors:
+  scheme: dark
+  accent: '#f97316'
+
+layout:
+  design: landscape
+  flow:
+    - { zone: head, span: 8, height: 170px }
+    - { zone: clock, span: 4, height: 170px }
+    - { zone: classes, span: 8, height: 4 }
+    - { zone: next, span: 4, height: 4 }
+    - { zone: ticker, height: 110px }
+
+zones:
+  head: { type: heading, text: Classes today }
+  clock: { type: clock, surface: raised, hour12: false }
+  classes:
+    type: table
+    columns: [Time, Class, Studio, Coach, Spots]
+    align: [start, start, start, start, end]
+    widths: [1.1, 2.6, 1.4, 1.8, 1.3]
+    page_rows: 7
+    seconds: 12
+    rows: { bind: /classes }
+  next:
+    type: stack
+    items:
+      - type: countdown
+        weight: 2
+        title: Next class
+        label: { bind: /next_label }
+        to: { bind: /next_at }
+        done: Starting now
+      - type: stat
+        weight: 2
+        title: Studio 1 spots
+        value: { bind: /spots_left }
+        unit: left
+        thresholds: { warning: 5, danger: 2 }
+        label: { bind: /spots_label }
+  ticker:
+    type: cycle
+    surface: raised
+    seconds: 8
+    items: { bind: /messages }

package/examples/hotel-lobby/data.yml

@@ -0,0 +1,2 @@
+guest_url: https://guest.harborhouse.example
+desk_note: Front desk is staffed 24 hours. Dial 0 from any room phone for anything you need, including a late checkout or a taxi.

package/examples/hotel-lobby/layout.yml

@@ -0,0 +1,29 @@
+# yaml-language-server: $schema=https://signagekit.514sid.com/schema.json
+# Sparse lobby screen: four zones, light scheme, landscape.
+colors:
+  scheme: light
+  accent: '#0f5132'
+
+layout:
+  design: landscape
+  flow:
+    - { zone: head, span: 12, height: 200px }
+    - { zone: time, span: 4, height: 1 }
+    - { zone: guide, span: 4, height: 1 }
+    - { zone: desk, span: 4, height: 1 }
+
+zones:
+  head: { type: heading, title: Lobby, text: Welcome to Harbor House, align: start }
+  time: { type: clock, title: Local time, surface: raised, show_date: true, hour12: false }
+  guide:
+    type: qr
+    title: Guest guide
+    value: { bind: /guest_url }
+    label: Wi-Fi, room service and checkout
+  desk:
+    type: text
+    title: Front desk
+    surface: accent
+    text: { bind: /desk_note }
+    fit: true
+    align: start

package/examples/lunch/data.yml

@@ -0,0 +1,16 @@
+# Every value in YAML data is read as text, so 4.50 stays "4.50".
+menu:
+  - [Tomato soup, VG, 4.50]
+  - [Chicken curry, GF, 8.90]
+  - [Mushroom risotto, V, 8.20]
+  - [Fish and chips, '', 9.50]
+  - [Falafel wrap, VG, 6.80]
+wait: 6
+seats: 42
+notices:
+  - 'Fire drill Thursday at 10:00'
+  - New vegan station opens Monday
+messages:
+  - 'Coffee bar open until 16:00'
+  - 'Card payments only after 14:00'
+  - Reusable cups get 20p off

package/examples/lunch/layout.yml

@@ -0,0 +1,43 @@
+# yaml-language-server: $schema=https://signagekit.514sid.com/schema.json
+# A canteen screen: the menu, wait time, free seats and notices. Designed for
+# landscape; on a portrait screen the zones move onto rows of their own.
+colors:
+  scheme: dark
+  accent: '#2563eb'
+
+layout:
+  design: landscape
+  flow:
+    - { zone: head, span: 9, height: 170px }
+    - { zone: clock, span: 3, height: 170px }
+    - { zone: menu, span: 6, height: 2 }
+    - { zone: info, span: 6, height: 2 }
+    - { zone: news, height: 110px }
+
+zones:
+  head: { type: heading, text: Today's lunch }
+  clock: { type: clock, surface: raised, show_date: true }
+  menu:
+    type: table
+    title: Menu
+    columns: [Dish, Diet, Price]
+    align: [start, start, end]
+    rows: { bind: /menu }
+  info:
+    type: stack
+    items:
+      - type: stack
+        direction: row
+        items:
+          - { type: stat, title: Wait time, value: { bind: /wait }, unit: min }
+          - { type: stat, title: Seats free, value: { bind: /seats } }
+      - type: stack
+        direction: row
+        items:
+          - { type: list, title: Notices, items: { bind: /notices } }
+          - type: text
+            surface: accent
+            title: Allergens
+            fit: true
+            text: Ask at the counter for allergen information.
+  news: { type: cycle, surface: raised, items: { bind: /messages }, seconds: 8 }

package/examples/meeting-room/data.json

@@ -0,0 +1,19 @@
+{
+  "room": {
+    "name": "Ada Lovelace",
+    "floor": "Floor 3, east wing",
+    "book_url": "https://rooms.northwind.example/r/ada-lovelace"
+  },
+  "status": {
+    "text": "In use",
+    "label": "Busy until 15:00",
+    "state": "danger",
+    "ends_at": "2026-11-14T15:00:00Z"
+  },
+  "agenda": [
+    { "start": "13:00", "end": "15:00", "title": "Pricing review", "detail": "Organiser: M. Oyelaran" },
+    { "start": "15:00", "end": "15:30", "title": "Interview debrief" },
+    { "start": "15:30", "end": "16:30", "title": "Sprint planning, Payments squad", "detail": "Organiser: J. Whitcombe-Tarasova" },
+    { "start": "17:00", "end": "17:30", "title": "1:1 Priya / Daniel" }
+  ]
+}