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

# Summer Apps design kit

> The Summer UI kit for apps: tokens, Geist, summer-* components that follow Studio light and dark, the layout format, and the rules that make an agent-built tool look crafted.

<Warning>
  **Draft.** Summer Apps is in a closed test. This page goes live after the end-to-end test on production.
</Warning>

Apps should look like Summer: calm, precise studio instruments around colourful game content. The kit and the `summer-apps-design` skill carry the rules, so agents get them right without being told.

## Load the kit

```html theme={null}
<script type="module" src="/summer-ui/v1/ui.js"></script>
```

It adds the Summer design tokens (CSS variables `--se-*`), the Geist font and every `<summer-*>` component, and follows Studio's light or dark theme. The stylesheet alone is `/summer-ui/v1/ui.css`. `summerUI.toast(text)` shows a toast in the app.

The full catalog, with every attribute, property, method, event and a copyable example per component, is `summer_app_guide` section `kit`, and `/summer-ui/v1/catalog.json` on the app host. Copy its examples instead of inventing markup.

## Components

| Need | Component |
| - | - |
| The page | `summer-page` (`heading`, `purpose`, a `slot="actions"` for the one primary button), then `summer-section`s (`heading`, `description`, a `slot="aside"`) |
| Key numbers | `summer-stats` holding `summer-stat`s (`label`, `value`, `delta`, `hint`, `tone`) |
| Records | `summer-table`: `columns`, `rows`, `row-key`, `sortable`, `clickable` (a `summer-row` event), `selectable`. A column takes `format` (`number`, `percent`, `usd`), `type` (`bar` with `over`, `badge`, `muted`), `badges` for a status column (`{"draft":"quiet","review":"info","done":"ok"}`), `editable`, `priority: "secondary"`, `width` (`"narrow"`, `"wide"` or a size), `minWidth` and `wrap`. Text wraps to two lines. Below 640 px badge columns fold into the first cell, and rows stack only if they still do not fit. |
| Edit cells in place | `editable` columns send `edit`; show `summer-save-bar` (`count`, `save` and `discard` events), then `table.commit()` or `table.discard()` |
| Edit a record | `summer-dialog` holding a `summer-form`: `form.setValues(record)`, then `dialog.show()`. The form's `submit` event gives `detail.values` (numbers as numbers). |
| Filter and find | `summer-toolbar` holding `summer-search`, `summer-segmented` and a `summer-select` with `inline` |
| A list of text items | `summer-list` (one trailing `action` per row, the rest in `menu`) |
| Work in stages | `summer-board` with `summer-lane`s and `summer-board-card`s |
| Trends and comparisons | `summer-chart` (`kind` bar, line, area or pie; `x`, `y`; `highlight` marks the bars that matter; `reference` draws a target line; whole-number data gets whole-number axes) |
| An error | `summer-notice tone="error" text="..." action="Try again"`; listen for its `action` event |
| Sound | `summer-audio` (the kit player and waveform, never the browser's) |
| Pick one version | `summer-choice-grid` |
| Media | `summer-image`, `summer-video`, `summer-model-viewer` |
| Inputs | `summer-text-input` (`input` and `change`), `summer-slider` (`input` and `change`), `summer-select`, `summer-toggle`, `summer-segmented` (`change`); every event has `detail.value`. `summer-button` sends `click`. |
| Layout | `summer-stack`, `summer-grid`, `summer-tabs`, `summer-card`, `summer-heading`, `summer-markdown` |
| People and progress | `summer-avatar-stack`, `summer-badge`, `summer-progress` (`value` 0 to 1) |
| States | `loading` on data components while fetching; `empty-text` on a table or chart, or `summer-empty-state`; `summerUI.toast(text)` for a finished action |

## Rules for every component

* `hidden` hides any kit component.
* A JSON attribute is also a property of the same name: `select.options = [...]`, `table.rows = [...]`.
* Setting `.value` from code never emits `change`. Only the person's input does, so updating a control while you render never loops.
* Clear `loading` once the data is shown, also when the data is empty.
* Number inputs have no `min` or `max`. Check the range in the form's `submit` handler and set the field's `error`.
* Tables have no buttons per row. For a one-click row action, use `summer-list` row actions, or clickable rows that open a dialog.
* A chart with several `y` keys draws grouped bars side by side, not stacked. Negative values hang below zero.

## The rules in short

* One line says what the tool does and where its data goes. One primary button finishes the task.
* Tokens only: no hex colours. Geist only; weights 400, 500 and 600; numbers tabular and right-aligned.
* No frame around the whole app, no cards inside cards, no badge on every row, no native audio, video, select or range controls.
* Design the loading, empty and error states.
* When a teammate or an agent changes something, flash that row briefly instead of showing a toast.
* Check light and dark, at phone and desktop widths. `summer_app_screenshot` with `width: 390` and `theme: "dark"` shows both.

The full rules are in the `summer-apps-design` skill and in `summer_app_guide` (section `design`).

## Layout apps

For a quick decision UI, an agent can publish a **layout** instead of code: one JSON object of kit nodes that Summer draws inside the sandbox. No code runs.

```json theme={null}
{
  "version": 1,
  "title": "Sword swing: pick a sound",
  "root": { "type": "stack", "props": { "gap": "md" }, "children": [
    { "type": "choice-group", "id": "pick", "props": { "label": "Versions", "items": [
      { "id": "a", "label": "Version A", "assetId": "<asset id>" },
      { "id": "b", "label": "Version B", "assetId": "<asset id>" } ] } },
    { "type": "button", "id": "use", "props": { "label": "Use this one", "variant": "primary", "action": { "type": "send", "name": "sound.picked" } } }
  ] }
}
```

A node is `{ type, id?, props, children? }`. Unknown props are errors. Inputs, buttons and forms need an `id`. Limits: 200 KB, 200 nodes, depth 8.

Node types: page, stack, grid, tabs, card, form, heading, text, notice, stat, table, chart, image, audio, video, model3d, asset, choice-group, list, button, slider, select, toggle, text-input. There is no dialog in a layout; build a code app for edit flows.

Button and form actions:

* `{ "type": "send", "name": "sound.picked" }`: an event your agent reads with `summer_app_events`. Its payload holds `values`, every input's current value by `id`.
* `{ "type": "open", "path": "/studio/..." }`: moves the Studio tab.
* `{ "type": "generate", "method": "generate.image", "args": { "prompt": { "$input": "prompt" } } }`: a paid generation for the person using the app.

`summer_app_guide` (section `layout`) has every prop.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.