# Authoring Talos UI This is the reference for writing a game screen: the files, the TSX, the stylesheet, the values a behaviour pushes in, and every diagnostic the engine will hand back. It is written to be read once and then used. `docs/PLAN-UI.md` is the plan this implements and the place to look for *why*; where a rule here has a reason worth knowing, the section number points at it. The shape of the whole thing, in one line: ``` ui/screens/*.tsx --esbuild--> h() calls --> description JSON --> crates/ui builder --> tree ui/styles/*.css ---------------------------------------parsed in Rust--> typed rules --> cascade ``` Structure is TSX because that is what an author and an agent both write most reliably. Style is a documented CSS subset parsed in **Rust**, not in script, because that is where hot reload is free and where the cascade already lives (§1.3). A behaviour never walks the tree; it sets values, and the runtime rebuilds only what changed (§2.7). ## 1. Where the files go ``` ui/ screens/**.tsx one screen per file, exported as default, any depth components/**.tsx vendored component source, any depth styles/**.css the CSS subset, any depth theme/**.css tokens and themes, any depth scenarios/**.json named mock data, any depth fonts/**.ttf the project's font chain, plus fonts.json to order it fonts/**.fnt|.json bitmap fonts, each named by an @font-face rule, with its atlas PNG locales/.json one language per file (§2.11) ``` Every one of those is watched. A change to a stylesheet or a theme is reparsed and re-resolved in Rust with no script involvement, and **must not lose focus, scroll position or an open dialog**. A change to a screen or a component goes through esbuild and a script reload, which keeps state only while the props shape is unchanged. A change to a scenario re-reads the mock data and nothing else. Anything else under `ui/` — a README, a note, an editor's leftover — is not a UI input and fires no reload at all. `ui/fonts/**` is read at project open and not watched: a font is an asset, and reloading one would mean throwing away the glyph atlas and every shaped run in it. It is the project's **fallback chain** — see "Fonts and fallback" in §4 for what that means and the order it resolves in. A change to a **locale** takes the same tier as a stylesheet, and for the same reason: keys are resolved in Rust at render time, so a changed string is re-read and re-resolved with no bundle rebuilt and no script run. A translator saving a file keeps their focus, their scroll position and their open dialog. One more directory under `ui/` is read but not watched, because it is not compiled and not resolved: `ui/icons/.png` is what `Icon`'s `name` resolves to (§10). A change to it is a change to an asset, so it fires no reload. `fixtures/ui/gallery/ui/icons` is the worked example, and its README is worth reading: the one icon the library's shipped scenarios name is there, and the two that stand for a missing asset are deliberately not. Detection **polls**; it is not a file-system watcher. Windows delivers no events for files on the WSL path and inotify inside WSL does not see writes made from Windows to `/mnt/c`, so a watcher would silently fail to fire on the machine that most needs it (§5). The six directory names and the `ui/` prefix are matched **case-insensitively**, as is the extension, because the same project is edited from Windows where `Styles` and `styles` are one directory. Nothing below them is: a file name is the author's. `ui/Styles/Menu.CSS` is a stylesheet and reloads; `ui/style/menu.css` is not one of the six names and is not a UI input. A locale file's name **is** its tag, so `ui/locales/pt-BR.json` is the locale `pt-BR`. The esbuild configuration is `@argus/ui`'s, stated once, and there are **two** spellings of it because there are two ways to use it. `ESBUILD_JSX_FLAGS` is the three flags to *add* to a list a host already has — `--loader=tsx` and the two JSX flags — which is what the engine's own TypeScript transpile does. `ESBUILD_TSX_ARGS` is the *complete* list for a caller that spawns esbuild itself, and it carries `--format=esm --target=es2020` as well, because those are the contract with the engine's QuickJS rather than a host preference: without the target, `||=` and `static {}` reach the runtime untranspiled and fail at load. Appending either list to an existing one is safe, since esbuild takes the last of a repeated flag. ## 2. A screen ```tsx // ui/screens/main-menu.tsx import { defineScreen, h, t } from "@argus/ui"; export interface MainMenuProps { canRestart: boolean; } export default defineScreen({ name: "main-menu", inputContext: "menu", modal: true, dismissible: false, render: ({ canRestart }) => ( {t("menu.title")} ), scenarios: { default: { canRestart: false }, "mid-run": { canRestart: true }, }, }); ``` A screen is **a pure function of typed props**. There are no hooks, no context, no effects, no state and no handlers that run code, and none of them are coming: behaviour lives in the game's TypeScript and pushes values in (§4, §2.7). React's spellings are accepted wherever they mean the same thing here — `
`, `style={{ … }}`, `onClick={emit("start-game")}` — and "Writing screens the React way" below lists them. What needs a DOM or code running inside a screen is refused with the way to write it. ### The element set Ten elements, which are the engine's ten roles. A role decides three things and nothing else: whether the node takes focus by default, whether it draws text or an image, and what an agent reading `GET /ui` is looking at. Appearance comes from the stylesheet, never from the role. | element | what it is | focusable by default | |---|---|---| | `` | a layout box with no content of its own | no | | `` | a run of text | no | | `` | a PNG, by its path from the project root: `ui/icons/key.png`, or a scene's own sprite sheet (`scenes/sprites/gun.png`), any folder but a hidden one; a path that leaves the project, or is not there, draws the magenta missing-image box and raises `ui.asset.image-missing`. With no `width` or `height` it takes its file's size (one of them set, the other follows the file's aspect ratio); one that still lays out at zero size raises `ui.layout.image-zero-size`. **Unlike CSS**, such an image is not stretched by its container's default `align-items: stretch`: give it `align-self: stretch` to stretch it, or set both `width` and `height` | no | | ``, `` — which the factory wraps in the `text` node the engine draws, or the `Button` component of `@argus/ui/components`, which takes `text` and `textKey` as props. In a running game the UI critic reports a non-`text` node that carries words under the same code. `t("menu.start")` produces a **string key** rather than a literal. Every label a player reads should be a key: resolution happens at render time, so switching language is a re-render rather than a reload, and a key that is missing from the table is reported for the critic (§2.11). A literal is for something that is not translated — a build string, a number already formatted. Setting both on one node is an error. `t()` takes a second argument for a message with slots: `t("score.line", { n, max })` fills `{n}` and `{max}`, and a message written as a plural table picks its form from `n` — or from `count` where there is no `n`. **Pass a number as a number.** The plural rule selects on it, so a count written as text would make the plural form depend on how you spelled your own integer. Both the substitution and the selection happen in Rust at render time, so a later `ctx.ui.setLocale` resolves the same parameters into the other language's message with no behaviour running again. The long form is ``, and `textParams` without a `textKey` is refused — the slots fill a message's placeholders, so there has to be a message. See §12 for the file format. ### Scenarios `scenarios` are named sets of props. They are three things at once: the mock data a screen previews against with no game running, the critic's inputs, and the gallery's entries (§4). They are **not** what the game draws: a screen pushed with props renders those props, and a screen pushed with none renders its default scenario (`default`, or the first one declared). Ship at least two, and make one of them the empty or failing case — loading, empty and error states are part of a component's contract, not optional extras. `defineScreen` warns with `ui.screen.scenarios` when a screen declares fewer than two, because a screen with none is one the critic never runs and the gallery cannot show. It is a warning rather than a refusal: the screen still describes correctly, and a fixture or a test is allowed to declare a throwaway. The warning is on the screen as `screen.diagnostics`, and `onDiagnostic` routes the same one wherever a build tool wants it. ### Writing screens the React way A screen may be written the way React writes a page. Every React spelling below lowers onto the engine's own vocabulary when the element is built, so the description `crates/ui` reads is the one the Talos spelling produces, byte for byte (`fixtures/ui/title.screen.json` is written from both spellings). Nothing needs a DOM or a browser, which is what keeps a screen portable to consoles, phones and PCs. ```tsx // ui/screens/title.tsx import { defineScreen, emit, h } from "@argus/ui"; function TitleMenu() { return (

Recipe Game

); } export default defineScreen({ name: "title", inputContext: "menu", modal: true, dismissible: false, render: () => , scenarios: { default: {}, again: {} }, }); ``` ```ts // scenes/behaviors/title.ts, in init ctx.events.on("start-game", () => ctx.ui.pop()) ctx.events.on("quit-game", () => ctx.session.quit()) ``` Three things are the engine's rather than React's: - **JSX compiles to `h(…)`.** The engine supplies `h` and `Fragment` when a screen does not import them, so a screen written the React 17 way works, and one that imports them from `@argus/ui` works the same. `import … from "react"` resolves to the engine's own answer (`@argus/ui/react`): `createElement` (which is `h`), `Fragment`, `StrictMode`, `memo`, `useMemo` and `useCallback` work, and `useState`, `useEffect`, `Suspense`, `Component` and the rest refuse when used, with the way to write it instead. - **A screen is `defineScreen({ name, render, scenarios })`**, not a default-exported function: the name is what `ctx.ui.push` addresses and the scenarios are what the preview and the critic render. A default-exported component is refused with the wrapper to write. - **`onClick` holds `emit(event, data?)`, not a function.** A screen is described once and runs no code afterwards, so only data survives. Every activation of the node — a click, Return or Space on the focused node, the pad's `uiActivate`, `POST /ui/activate` — raises `event` on the script bus with `data`, on the tick after the press, just after the unchanged `"ui-activated"`. A behaviour hears it with `ctx.events.on("start-game", (ev) => …)`; `ev.data` is the data and `by` is null. A closure in `onClick` is refused with the `emit` to write instead. Focus is the engine's, since React has none: buttons, list rows and text fields take focus whatever they are spelled, Tab follows `tabIndex`, the pad and the arrow keys move geometrically (§9, *Input*), and `autoFocus` picks where focus starts. A stylesheet imported by the screen (`import "./title.css"`) is not how styles arrive: the import is dropped when the screen is bundled, and every file in `ui/styles/**` and `ui/theme/**` is loaded for every screen. Put the rules there; a `.css` file anywhere else is never read. The selectors match what was built, so `div { … }` is refused with a pointer to `container`, and a class is the portable way to reach a React-spelled element. §13 is the whole mapping. ### The builder API TSX compiles onto a Rust builder that is a supported surface in its own right (§1.3). A fixture, a test or an editor panel writes it directly: ```rust let pause = Ui::screen("pause") .input_context("menu") .modal() .child( Ui::dialog() .class("panel") .child(Ui::text("Paused")) .child(Ui::button("Resume").id("resume")) .child(Ui::button("Quit").id("quit").variant("danger")), ) .build(); ``` ## 3. Stylesheets ```css /* ui/styles/menu.css */ .menu { display: flex; flex-direction: column; gap: var(--space-3); padding: var(--space-5); } .btn { background-color: var(--surface); color: var(--on-surface); border: 1ui solid var(--border); border-radius: var(--radius-md); padding: 8ui 16ui; transition: background-color 120ms ease-out; } .btn[data-variant="primary"] { background-color: var(--accent); } .btn:hover { background-color: var(--accent); } .btn:focus-visible { border-color: var(--focus-ring); } .btn:disabled { color: var(--disabled); } .menu > .menu__row:first { margin-top: 0; } ``` Everything a component looks like should be reachable from its class and its data attributes, because that is what lets an agent restyle it without touching the TSX, and what let the reference project's design language travel to another application in another language (§2.2). ### Selectors | form | example | notes | |---|---|---| | class | `.panel` | | | role | `button` | one per compound; the ten element names | | data attribute | `[data-variant="danger"]`, `[data-state]` | the `data-` namespace only | | state | `:hover` `:active` `:focus` `:focus-visible` `:disabled` `:selected` `:checked` `:first` `:last` | nine, and no others | | child | `.list > .row` | the direct parent | | descendant | `[data-theme="dark"] .menu .row` | any ancestor | | list | `.a, .b` | becomes one rule per selector | **Two combinators at most**, child or descendant in any mix: `.menu .row > .label` and `[data-theme="dark"] .menu .row` are fine, and `.a .b .c .d` is refused with `ui.css.combinator-depth`. Two is what a theme-scoped component rule needs — one step for the theme, one for the component — and matching stays one walk up the node's ancestors, so its cost is the same order as one combinator's (measured on the gallery: no change within noise). Past two, give the element a class of its own. Refused on purpose: `*`, `#id`, `::before`, `:not()` and every other functional pseudo-class, `+` and `~`, attribute selectors outside `data-`, and `!important`. **Specificity** is CSS's `(b, c)`: classes, attributes and pseudo-classes first, then roles, summed over every compound. There is no `a`, because there are no id selectors. A class beats a role wherever the two rules sit. A tie breaks on position, so the later rule wins. Inline declarations on the node beat every rule, and are the only override there is. **A theme or size scope counts.** `[data-theme="x"]` is an attribute, so `[data-theme="x"] text` is `(1, 1)` and beats a bare `.label` at `(1, 0)`, exactly as it would in a browser. A theme that restyles a role this way outranks every unscoped one-class rule; scope the class rules the same way (`[data-theme="x"] .label`, `(2, 0)`), or put the theme's look in its tokens, which need no selector at all. **Inheritance** is four properties: `color`, `font-size`, `font-weight`, `text-align`. Nothing geometric inherits. ### Tokens and themes Two layers, and components should reference the second only. ```css /* ui/theme/tokens.css — the primitive layer */ @tokens { --ink-900: #0f1319; --ink-50: #f1f4f8; --teal-400: #2ebfba; --red-400: #ef6666; --space-4: 16ui; --radius-md: 6ui; --duration-base: 150ms; } /* ui/theme/dark.css — the semantic layer */ @theme dark { --surface: var(--ink-900); --on-surface: var(--ink-50); --accent: var(--teal-400); --danger: var(--red-400); } ``` **Every token name is written `--name`, and eleven of them are reserved**: `surface`, `on-surface`, `accent`, `danger`, `success`, `warning`, `focus-ring`, `disabled`, `scrim`, `border`, `muted`. Those eleven are the semantic layer and may only be set inside a `@theme` block; setting one in `@tokens` is an error pointing at `@theme`. Every other name is a primitive. `var(--x)` resolves the semantic names first, so `var(--accent)` follows the active theme and `var(--teal-400)` names one palette entry. A token holds a colour, a length, a number or a time, and the kind is checked where it is used: `padding: var(--accent)` is an error saying that `accent` is a colour. **A colour stays a reference until the cascade resolves it**, so switching theme is a re-resolve rather than a reparse. **A length is resolved when the sheet is parsed** — taffy needs a number — so a theme that gives a length, number or time its own value (`--radius-lg: 14ui` in `@theme game`) has the rules parsed once more against its table, and switching to it swaps those rules in with the table. Either way a theme may move any token, and the rules take the active theme's value. The extra parse happens only for a theme that moves a non-colour; a project whose themes differ in colour alone (every theme the design system ships) parses once. The parser starts from the engine's built-in table — the dark palette, the design system's extended colour names, and every measurement the component library reads: the type, spacing (`space-0`…`space-9`), radius (`radius-none`…`radius-xl`, `radius-full`), stroke, control, bar, shadow-geometry, duration and elevation scales — and a project's `@tokens` and `@theme` blocks override and extend it. A project never has to define `--radius-lg` or `--space-4` to use them; `GET /ui/schema` lists the whole table. The first `@theme` block across the files is the default. Scoping rules to a theme needs no special form. `data-theme` on the screen root plus a descendant selector is all of it: ```css [data-theme="alert"] .panel { background-color: var(--danger); } ``` ### Size classes, not media queries ```css @size compact { .stat-row { flex-direction: column; } } /* identical to: */ [data-size="compact"] .stat-row { flex-direction: column; } ``` | class | width in `ui` units | what it means | |---|---|---| | `compact` | under 1900 | a small window, or a player who turned the UI scale up | | `regular` | 1900 to 2100 | every ordinary surface, 4:3 through 16:9, at any resolution | | `expanded` | 2100 and over | wider than 16:9: ultrawide and multi-monitor | There are no media queries because a pixel count has no useful answer here. The root scale follows viewport height and is then capped at `width / 1920`, so a screen is about 1080 `ui` units tall and **exactly 1920 units wide** on a 720p laptop, a 1440p monitor and a 4K television alike. What escapes that normalisation is a surface wider than 16:9, a surface small enough that the scale's floor caught it, and the player's UI-scale multiplier — which is the point: a screen that reflows in the compact band survives an accessibility setting (§2.5, §2.12). A rule inside `@size` may have one combinator of its own: the scope spends the other of the two. ### At-rules | at-rule | example | |---|---| | `@tokens` | `@tokens { --ink-900: #0f1319; }` | | `@theme ` | `@theme dark { --surface: var(--ink-900); }` | | `@size ` | `@size compact { .row { flex-direction: column; } }` | | `@font-face` | `@font-face { font-family: "Score"; src: url("ui/fonts/score.fnt"); }` | `@media`, `@import`, `@keyframes` and `@supports` are refused, each with the reason and the alternative. `@font-face` takes `font-family` and one `src: url("ui/…")` and nothing else; see "Bitmap fonts and `@font-face`" in §4 for what the file may be. ## 4. Every property Generated from the parser's own tables. The same document is what U3 serves at `GET /ui/schema`, and it is the copy to trust if this file and the engine ever disagree: `argus_ui::style::schema()` produces it, and `cargo run -p argus-ui --example schema` prints it. The parser's dispatch and the schema are two exhaustive matches over one list, so a property cannot exist in one and not the other. | property | values | initial | inherits | transitions as | |---|---|---|---|---| | `display` | `flex \| block \| grid \| none` | `flex` | — | — | | `flex-direction` | `row \| column \| row-reverse \| column-reverse` | `row` | — | — | | `flex-wrap` | `nowrap \| wrap \| wrap-reverse` | `nowrap` | — | — | | `justify-content` | `auto \| flex-start \| start \| flex-end \| end \| center \| stretch \| space-between \| space-around \| space-evenly` | `auto` | — | — | | `align-items` | `auto \| flex-start \| start \| flex-end \| end \| center \| stretch \| baseline` | `auto` | — | — | | `align-self` | `auto \| flex-start \| start \| flex-end \| end \| center \| stretch \| baseline` | `auto` | — | — | | `align-content` | `auto \| flex-start \| start \| flex-end \| end \| center \| stretch \| space-between \| space-around \| space-evenly` | `auto` | — | — | | `gap` | `{1,2}` | `0` | — | — | | `row-gap` | `` | `0` | — | — | | `column-gap` | `` | `0` | — | — | | `flex-grow` | `` | `0` | — | — | | `flex-shrink` | `` | `1` | — | — | | `flex-basis` | ` \| auto` | `auto` | — | — | | `order` | `` | `0` | — | — | | `position` | `relative \| absolute` | `relative` | — | — | | `inset` | `{1,4}` | `auto` | — | position | | `top` | ` \| auto` | `auto` | — | position | | `right` | ` \| auto` | `auto` | — | position | | `bottom` | ` \| auto` | `auto` | — | position | | `left` | ` \| auto` | `auto` | — | position | | `width` | ` \| auto` | `auto` | — | size | | `height` | ` \| auto` | `auto` | — | size | | `min-width` | ` \| auto` | `auto` | — | — | | `min-height` | ` \| auto` | `auto` | — | — | | `max-width` | ` \| auto` | `auto` | — | — | | `max-height` | ` \| auto` | `auto` | — | — | | `aspect-ratio` | ` \| / \| auto` | `auto` | — | — | | `padding` | `{1,4}` | `0` | — | — | | `padding-top` | `` | `0` | — | — | | `padding-right` | `` | `0` | — | — | | `padding-bottom` | `` | `0` | — | — | | `padding-left` | `` | `0` | — | — | | `margin` | `{1,4}` | `0` | — | — | | `margin-top` | ` \| auto` | `0` | — | — | | `margin-right` | ` \| auto` | `0` | — | — | | `margin-bottom` | ` \| auto` | `0` | — | — | | `margin-left` | ` \| auto` | `0` | — | — | | `overflow` | `(visible \| hidden \| scroll \| auto){1,2}` | `visible` | — | — | | `grid-template-columns` | `none \| + where = auto \| min-content \| max-content \| \| \| fr \| repeat(, +)` | `none` | — | — | | `grid-template-rows` | `none \| + where = auto \| min-content \| max-content \| \| \| fr \| repeat(, +)` | `none` | — | — | | `grid-column` | `auto \| \| span \| / ` | `auto` | — | — | | `grid-row` | `auto \| \| span \| / ` | `auto` | — | — | | `background-color` | `` | `transparent` | — | background-color | | `background-image` | `none \| linear-gradient(, {2,4})` | `none` | — | — | | `border` | ` solid ` | `0 solid transparent` | — | — | | `border-width` | `` | `0` | — | — | | `border-color` | `` | `transparent` | — | border-color | | `border-style` | `solid` | `solid` | — | — | | `border-image-slice` | `none \| {1,4} \| {1,4}` | `none` | — | — | | `object-fit` | `fill \| contain \| cover` | `fill` | — | — | | `border-radius` | `{1,4}` | `0` | — | — | | `border-top-left-radius` | `` | `0` | — | — | | `border-top-right-radius` | `` | `0` | — | — | | `border-bottom-right-radius` | `` | `0` | — | — | | `border-bottom-left-radius` | `` | `0` | — | — | | `opacity` | `` | `1` | — | opacity | | `box-shadow` | `none \| ` | `none` | — | — | | `color` | `` | `white` | yes | color | | `font-size` | ` \| ` | `16px` | yes | — | | `font-weight` | `100..900 by 100 \| normal \| bold` | `400` | yes | — | | `text-align` | `start \| center \| end` | `start` | yes | — | | `font-family` | ` \| \| var()` | `the chain's first font` | yes | — | | `font-style` | `normal \| italic` | `normal` | yes | — | | `line-height` | `normal \| \| ` | `normal` | yes | — | | `letter-spacing` | `` | `0` | yes | — | | `white-space` | `normal \| nowrap \| pre` | `normal` | yes | — | | `text-overflow` | `clip \| ellipsis` | `clip` | yes | — | | `font-variant-numeric` | `normal \| tabular-nums` | `normal` | yes | — | | `text-shadow` | `none \| [ ? ?]#` | `none` | yes | — | | `transform` | `none \| translate([, ]) \| scale([, ]) \| rotate()` | `none` | — | — | | `translate` | `{1,2}` | `0 0` | — | translate | | `scale` | `{1,2}` | `1 1` | — | scale | | `rotate` | `` | `0deg` | — | — | | `animation` | `none \| [