@xtframe/skills 0.0.0-stage → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +22 -2
  2. package/package.json +41 -4
  3. package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
  4. package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
  5. package/payload/plugins/xtframe/gemini-extension.json +5 -0
  6. package/payload/plugins/xtframe/skills/xtui/SKILL.md +218 -0
  7. package/payload/plugins/xtframe/skills/xtui/references/canvas.md +90 -0
  8. package/payload/plugins/xtframe/skills/xtui/references/dialect.md +799 -0
  9. package/payload/plugins/xtframe/skills/xtui/references/flow.md +338 -0
  10. package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
  11. package/payload/plugins/xtframe/skills/xtui/references/performance.md +162 -0
  12. package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
  13. package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +378 -0
  14. package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
  15. package/payload/plugins/xtframe/skills/xtui/references/tokens.json +42 -0
  16. package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +161 -0
  17. package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +140 -0
  18. package/payload/plugins/xtframe/skills/xtui/references/vector.md +219 -0
  19. package/payload/plugins/xtframe/skills/xtui/references/verify.md +327 -0
  20. package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +209 -0
  21. package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
  22. package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +849 -0
  23. package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
  24. package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +180 -0
  25. package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +167 -0
  26. package/src/agents.mjs +73 -0
  27. package/src/bin.mjs +4 -0
  28. package/src/cli.mjs +286 -0
  29. package/src/converter.mjs +73 -0
  30. package/src/fsutil.mjs +76 -0
  31. package/src/install.mjs +154 -0
  32. package/src/packs.mjs +150 -0
  33. package/src/plugins.mjs +109 -0
  34. package/src/proc.mjs +66 -0
  35. package/src/tar.mjs +103 -0
@@ -0,0 +1,799 @@
1
+ Read this when you write or fix a board: it is the contract for what a `.dc.html` may contain so `xtframe-import dc` converts it without loss.
2
+
3
+ # XTFrame board dialect
4
+
5
+ Use this dialect when the boards you write will be imported into XTFrame (a game UI
6
+ runtime) with `xtframe-import dc`. XTFrame renders an HTML/CSS subset; everything below keeps a board
7
+ inside that subset so the import is lossless. Anything outside it is imported as a warning plus a
8
+ degraded (sometimes rasterized) result, which is worse than avoiding it.
9
+
10
+ The import reads the board's **source**, not a rendered DOM: no browser runs. So `<sc-for>`,
11
+ `<sc-if>` and any `renderVals()` / `data-dc-script` logic are not executed — a `<sc-for>`/`<sc-if>`
12
+ is expanded **once** from the `data-props` defaults, and script-generated markup never appears at
13
+ all. Write lists and states out literally.
14
+
15
+ ## Board setup
16
+
17
+ - One artboard = one game UI screen. Size **1280×720** (or 1920×1080 for 4K-first projects).
18
+ - **The UI id comes from the root `<div>`'s `id` attribute**; give every board's root an id made of
19
+ lowercase letters, digits and `-` (`hud`, `pause-menu`, `inventory`). The board `title` is only
20
+ the fallback (slugified) and the display name, so a title with spaces or capitals is fine as long
21
+ as the root has an id.
22
+ - The root `<div>` has the board's fixed `width`/`height` in px; draw everything in px from the
23
+ board's top-left. The import turns that into the layout contract (25 §25.4.1): the root fills
24
+ the screen (`width: 100vw; height: 100vh`), and every absolutely positioned child of the root
25
+ without `data-xt-anchor` is anchored by where it sits on the board -- within 25% of the board's
26
+ width/height from an edge it is pinned to that safe-area edge (`anchor: left top; offset: -8px
27
+ 6px`, the same spot at the board's size), in the middle it is kept proportional (`anchor:
28
+ center ...` with a `size` for a box centred on the board, else `left: calc(<P>% - <n>px)`), and
29
+ a child covering the whole board bleeds to the screen edges (`anchor: stretch stretch screen`).
30
+ The anchor shorthands are written when both axes fit them; otherwise the element keeps the
31
+ long-hand `position: absolute; left: calc(1safe-left - 8px); top: calc(42.86% - 8.57px)` (see
32
+ **What the import writes**). The import reads where the board puts an element after `<helmet>` rules and
33
+ classes (a position written only in a `<helmet>` `#id` rule, or `position: absolute` from a
34
+ class, is anchored too), measured at rest: without bindings, triggers, timelines or
35
+ animations, and with the root's children shown (a child the board hides -- `display: none`,
36
+ `bind:display` at the port's default -- is anchored where it is drawn when shown). Two px
37
+ offsets on one axis (`left` and `right`, `top` and `bottom`) stretch the element: each offset
38
+ is pinned to its own safe-area edge and both are kept (`anchor: stretch ...`). Every element the
39
+ anchoring rewrites is an `anchor.rewritten` info item in the diagnostics (`anchor: #x left: 24px;
40
+ top: 24px -> anchor: left top; offset: -8px 6px; size: 240px auto`);
41
+ `xtframe-import dc --lint --anchors <dump>` lists them. Inside a
42
+ UI Project the safe area is its `spec.safeArea.default` and the board height becomes its
43
+ `spec.logicalHeight` when that is still the default 1080. `--no-auto-anchor` keeps the fixed
44
+ root and the px. Extra top-level frames beside the root are imported as full-screen overlays
45
+ (they fill the screen and their children are anchored like the root's); put overlays inside the
46
+ root unless they must sit outside its perspective/stacking context. Several top-level elements
47
+ also get the lint warning `board.multipleRoots: <N> top-level elements (<ids>); a stray closing
48
+ tag above the second one is the usual cause` -- check for an extra `</div>` before keeping them.
49
+ `box-sizing` is always
50
+ `border-box` in XTFrame; writing it is fine (it is dropped silently), and so is
51
+ `transform-style: preserve-3d` (always on) and any `-webkit-`/`-moz-`/`-ms-`/`-o-` prefixed copy
52
+ of a property you already wrote unprefixed.
53
+ - **Elements the flow moves are not anchored; use a dock.** An element whose `left` / `top` (or
54
+ `right` / `bottom`) a `.xtflow` writes with `setStyle` keeps its board px (warning
55
+ `anchor.flowMoved: <id> is moved by the flow; wrap it in a dock`). To make it follow the screen,
56
+ wrap it in a **dock**: a plain element with the panel's board box and no `transform` /
57
+ `translateZ` / animation, which takes the anchoring; the moved element sits at `left: 0; top: 0`
58
+ inside it and the flow's positions become dock-relative. A dock is also how a `translateZ` panel
59
+ is anchored, and how sibling panels that must stay aligned are kept together (one dock, anchored
60
+ once, instead of each being pinned to its own nearest edge). The automatic anchoring measures the
61
+ layout box without its 3D projection. See `references/responsive.md` (skill) for examples.
62
+ - **`data-xt-uiscale`** on the root: `height` | `width` | `shortEdge` | `fit`. The import writes it
63
+ to `<name>.xtui` `spec.uiscaleRule` (how big one design px is on a given screen); on a re-import a
64
+ board with the tag sets the rule, a board without it keeps the project's value. It is the only
65
+ regular way to set the rule from a board. For "fit any window" use `fit` (the whole design always
66
+ visible: margins on a wide screen, scaled down on a narrow one).
67
+ - Every element the game or a flow will talk to (a button, a value readout, a bar) gets an `id`
68
+ attribute: `id="hp-value"`, `id="btn-resume"`. Ids become the connection points the engine binds
69
+ to, so name them by role, not by look. See **Flow bindings** below.
70
+ - `data-xt-name="<layer name>"` names a layer when the id should stay free for the page's own use;
71
+ it wins over `id` and becomes the layer id (slugified). A re-import pairs layers by this name
72
+ first, so a named layer keeps its editor-side changes even when the canvas moves it around.
73
+ `data-xt-name` is one of the **intent tags** (below) that declare symbols, states, triggers,
74
+ timelines, ports and bindings on the board itself.
75
+
76
+ ## What the import writes (source format 2)
77
+
78
+ You never write these files (the board is the source), but you read them in reports, diffs and
79
+ compile errors. Per UI the import writes `<ui>/<ui>.xt` and `<ui>/<ui>.xts` (Docs/design/54):
80
+
81
+ - `<ui>.xt` is `<xt version="2">` with its sections in this order: `<head>` (`<title>`,
82
+ `<symbols src>` for a symbol library), `<symbol>` definitions, `<ports>` (one declaration per
83
+ line), `<body>` (the elements with their `on:` / `bind:` / `slot:` attributes), `<layout>`
84
+ (every geometry declaration, one `#id` rule per element in layer order, the anchor shorthands),
85
+ `<style src="...">` (the appearance: `shared/base.xts` first inside a UI Project, then
86
+ `<ui>.xts`) and `<timelines>` (the `@timeline` blocks).
87
+ - `<ui>.xts` holds only appearance: colours, borders, text, effects, tokens, `:hover` /
88
+ `:state()` looks, `@keyframes`. A board rule that mixes both is split: the same selector once in
89
+ `<layout>` (geometry) and once in `<ui>.xts` (the rest). Which property goes where is the
90
+ Section column of `style-groups.md`.
91
+ - A trigger on the board root becomes `on:` on `<body>`; the board's ports become the document's
92
+ `<ports>`, whatever element carried `data-xt-port`; a symbol has its own `<ports>`, `<layout>`
93
+ and `<style>` inside its `<symbol>`. Inline board geometry is reported once per UI
94
+ (`style.geometryInline`, info) and written to the elements' `<layout>` rules.
95
+
96
+ A board root `hud` with `data-xt-port="hp:number in = 0.8; hp_max:number in = 100; pause:event
97
+ out"`, `data-xt-trigger="show:play(intro)"`, an intro timeline and two anchored children imports
98
+ as (trimmed):
99
+
100
+ ```xml
101
+ <xt version="2">
102
+ <head>
103
+ <title>HUD</title>
104
+ </head>
105
+
106
+ <ports>
107
+ hp: number in = 0.8
108
+ hp_max: number in = 100
109
+ pause: event out
110
+ </ports>
111
+
112
+ <body on:show="play(intro)">
113
+ <div id="hud">
114
+ <div id="vitals">
115
+ <span id="hp-text" bind:text="format('{0} / {1}', hp | scale(100) | round(0), hp_max)">80 / 100</span>
116
+ <div id="hp-track">
117
+ <div id="hp-fill" bind:width="hp|range(0,1,0%,100%)"/>
118
+ </div>
119
+ </div>
120
+ <div id="pause-btn" class="chip" on:click="emit(pause)">Pause</div>
121
+ <div id="hint">Press Esc</div>
122
+ </div>
123
+ </body>
124
+
125
+ <layout>
126
+ /* import: hud.dc.html:1/0 */
127
+ #vitals {
128
+ anchor: left top;
129
+ display: flex;
130
+ flex-direction: column;
131
+ gap: 8px;
132
+ offset: -8px 6px;
133
+ size: 240px auto;
134
+ }
135
+ /* import: hud.dc.html:1/1 */
136
+ #pause-btn {
137
+ anchor: right top;
138
+ offset: -8px 6px;
139
+ size: 80px 32px;
140
+ }
141
+ /* import: hud.dc.html:1/2 */
142
+ #hint {
143
+ anchor: center bottom;
144
+ offset: 0 22px;
145
+ size: 200px 24px;
146
+ }
147
+ .chip {
148
+ padding-top: 4px;
149
+ padding-right: 8px;
150
+ padding-bottom: 4px;
151
+ padding-left: 8px;
152
+ }
153
+ </layout>
154
+ <style src="hud.xts"/>
155
+ <timelines>
156
+ @timeline intro {
157
+ #vitals {
158
+ 0ms {
159
+ opacity: 0.25;
160
+ }
161
+ 300ms ease-out {
162
+ opacity: 1;
163
+ }
164
+ }
165
+ }
166
+ </timelines>
167
+ </xt>
168
+ ```
169
+
170
+ and `hud.xts` holds `#hint { color: #8b949e; text-align: center; }`, `.chip { border-radius:
171
+ 6px; background-color: #161b22; ... }`, `.chip:hover { background-color: #2f81f7; }`. The
172
+ `/* import: <board>:<path> */` comments are the re-import's map back to the board.
173
+ What the shorthands mean (54 §54.5.1): `anchor: <x> <y> [safe|screen]` pins each axis to `left` /
174
+ `center` / `right` / `stretch` (and `top` / `center` / `bottom` / `stretch`) of the safe area
175
+ (`safe`, the default) or the screen; `offset` is the distance from that edge (from the centre for
176
+ `center`, the start inset for `stretch`), `offset-end` the end inset of a `stretch` axis,
177
+ `size: <w> <h>` a length, `auto` or `fill`. The import writes `size` when the element declares a
178
+ `width` or `height` itself: each axis gets its length, or `auto` where the measured box takes that
179
+ axis from its content -- `#vitals` above, a flex column with a fixed width and its children
180
+ stacked, is `size: 240px auto`. An element that declares neither gets no `size`; when one axis has
181
+ no known value (no measurement), no `size` is written and the declared `width` / `height` stay
182
+ long-hand. A `stretch` axis takes no length (an element that declares one keeps its long-hands)
183
+ and a `center` axis needs one (without it the element keeps its long-hands; written by hand it is
184
+ the error `layout.centerNeedsSize`). A UI Project from before format 2 is upgraded with
185
+ `references/upgrade.md` section 8.
186
+
187
+ ## Allowed elements
188
+
189
+ `div`, `span`, `p`, `h1`–`h6`, `section`, `label`, `b`, `i`, `img`, `button`, `input`, `ul`, `li`.
190
+
191
+ `nav`, `header`, `footer`, `main`, `aside`, `article` and `figure` are accepted as aliases of `div`
192
+ with no fidelity penalty — use them freely for structure.
193
+
194
+ Do not use: `a` (use `button`), `table`/`tr`/`td` (they become plain `<div>`s and lose their
195
+ layout), `video`, `canvas`, `iframe`, `<dc-import>` / `x-import` design-system components (their
196
+ DOM only exists in the browser, so they are dropped), and `<sc-for>` / `<sc-if>` (see above).
197
+
198
+ ## Layout
199
+
200
+ - `display: flex` (row/column, `gap`, `padding`, `justify-content`, `align-items`,
201
+ `flex-wrap` — `wrap-reverse` included —, `flex-grow`, `order`), a **grid subset** (below) and
202
+ `position: absolute` with `left/top/right/bottom` inside a `position: relative` parent.
203
+ `order: <integer>` reorders flex items for layout, painting and hit testing (absolute children
204
+ keep document order); it does not animate and does nothing in a grid.
205
+ - **A flex item has no min-content minimum** (Docs/design/06-layout.md §6.9: the minimum is 0,
206
+ not CSS's `min-width: auto`). A shrinking flex item holding text squeezes below its longest
207
+ word instead of stopping there; give it a `min-width` (or `flex-shrink: 0`). The import reports
208
+ such an item as `layout.flexShrinkText` (24 §24.14.5).
209
+ - `display: grid` — fixed tracks only: `grid-template-columns` / `-rows` take `px`, `%`, `fr`,
210
+ `auto` and `repeat(<n>, …)`; `gap` / `row-gap` / `column-gap`; `grid-template-areas`
211
+ (`"a a b" "c . b"`, every area a rectangle) with `grid-area: <name>` on the children;
212
+ `grid-column` / `grid-row` as `<start> [/ <end>]` or `span <n>`; the rest fill the free cells
213
+ row by row. `justify-items` / `align-items`: `start | center | end | stretch`;
214
+ `justify-content` / `align-content`: `start | center | end | space-between | space-around`.
215
+ An `auto` track is as wide as its widest child. Not available: `minmax()`, `auto-fill` /
216
+ `auto-fit`, named or negative lines, `grid-auto-*`, `dense`, `subgrid` — the importer turns a
217
+ grid using them into a plain block plus a warning. A grid with one row (or one column) and no
218
+ areas still becomes a flex line.
219
+ - Units: `px`, `%`, `em`, `vw/vh/vmin/vmax`, `calc()` in length longhands; `rem/ch/ex` dropped
220
+ (`rem` is not resolved yet: write `em` or `px`).
221
+ (`calc()` anywhere else — a shorthand such as `margin`, a transform, a shadow — drops the
222
+ declaration; the physical units `cm/mm/in/pt/pc` are dropped too.)
223
+ - Selectors in `<helmet>` rules: tags, `.class`, `#id`, the descendant and `>` child combinators,
224
+ `:hover`, `:active`, `:focus`, `:disabled`, `:checked`, `:not()`, `:nth-child()`, `[attr]`,
225
+ `:focus-within`, `:lang()`, `:state()`. Not supported: pseudo-elements other than the
226
+ `::before`/`::after` expansion below, `+`, `~`, `:nth-of-type`, `:has()`, `:is()`/`:where()` —
227
+ a rule written with one is dropped (reported, the import still succeeds), inside `@media`
228
+ blocks too; in a selector list only that selector goes.
229
+ - `::before`/`::after` with a `content` (not `none`/`normal`) in a top-level `<helmet>` rule are
230
+ expanded **at import only**: each matching element gets a real `<span data-xt-pseudo="before">`
231
+ first child (`"after"`: last child) — `content: "text"` becomes its text, `url(x.png)` (or the
232
+ first `image-set()` item) an `<img>` inside it, `""` an empty box (decoration dots, badges with
233
+ `position: absolute` and insets work); the rule's other declarations become a `pseudo-<hash>`
234
+ class on it, and several rules for one element merge by specificity and order. In the editor it
235
+ is an ordinary layer from then on. The base selector may only use tags, `.class`, `#id`, `*` and
236
+ the descendant combinator: a stateful one (`.btn:hover::before`), `>`, `[attr]`, a rule inside
237
+ `@media`, `attr()`/counter content, and a rule without `content` are not expanded (dropped).
238
+ - `overflow: hidden` is fine and is how rounded clipping works: with a `border-radius` the
239
+ children are clipped to the rounded corners too, in the software and GL renderers alike
240
+ (18 §18.13); hit testing still uses the square box. `overflow` takes `visible`,
241
+ `hidden`, `scroll` and `auto` (clips and scrolls only once the content overflows), one value or
242
+ two (`overflow: <x> <y>`), and `overflow-x` / `overflow-y` work too: the clip is always the whole
243
+ padding box, the wheel scrolls only the non-`visible` axes (a `visible` axis next to a
244
+ non-`visible` one acts as `auto`, as in CSS). Scrollbars are not drawn.
245
+ - Per-side `padding-*` and `margin-*` longhands are supported, as are per-side `border-*-width`
246
+ and per-corner `border-*-radius`.
247
+
248
+ ## Visual properties that import 1:1
249
+
250
+ - `background: #hex` / `background-color`; `background: linear-gradient(<angle>deg, #hex <p>%, …)`,
251
+ `radial-gradient(…)` and `conic-gradient([from <angle>] [at <pos>], …)` with percentage (or, for
252
+ conic, angle) stops (2–16 stops). `circle`/`ellipse` keywords, the
253
+ size keywords (`closest-side`, `closest-corner`, `farthest-side`, `farthest-corner` — the default
254
+ when no size is given, as in CSS) and `repeating-linear-gradient` are normalized for you (a
255
+ repeating gradient is expanded to at most 32 plain stops). A keyword-sized `circle` needs the
256
+ element's `width`/`height` in px in the same rule or `style`, otherwise it is only round on a
257
+ square box. A **multi-layer** `background` is split into stacked absolutely-positioned child
258
+ `<div>`s — it works, but it changes the node tree, so prefer one layer per element.
259
+ - `border: <w>px <style> <color>` with the style `solid`, `dashed`, `dotted` or `none` (other
260
+ styles are drawn solid with a warning); `border-style` (1–4 values) and `border-*-style` too. The
261
+ colour may be `#rgb`, `#rrggbb`, `#rrggbbaa` or `rgba()` — `rgba()` is normalized to
262
+ `#rrggbbaa`. Per-side colours are kept: `border-color` with 2–4 values and
263
+ `border-top/right/bottom/left-color`.
264
+ - `border-radius` (px, per-corner allowed).
265
+ - `opacity` — including `opacity: 0`, which really does hide the element.
266
+ - `visibility: hidden` — including on an `<img>`. Animated, it switches at the middle of a
267
+ segment, not at a keyframe (see **Animation**).
268
+ - `box-shadow: x y blur spread <color>`, `inset` allowed, **several layers allowed** (up to 16);
269
+ it becomes XTFrame's `effect: shadow(…)`. A blur (or any radius-like effect parameter) above
270
+ **64 device px** is clamped, and the import says so (`effect.degraded: ... exceeded the 64
271
+ device px cap; clamped`; 24 §24.14.3). `text-shadow` becomes the glyph-level
272
+ `text-effect: shadow …` instead (up to 16 layers; the rest are dropped), and its blur is capped
273
+ at **8 px** (`effect.degraded: text-shadow blur <n>px: text-effect radius clamped to 8px`).
274
+ - `filter` on the element itself: `blur()`, `brightness()`, `contrast()`, `saturate()`,
275
+ `grayscale()`, `hue-rotate()`, `invert()`, `sepia()`, `opacity()` and `drop-shadow()`.
276
+ The colour functions merge into one adjustment applied in a fixed order (brightness, contrast,
277
+ saturate/grayscale, hue-rotate, invert, sepia, opacity), not in the order written; each may appear
278
+ only once. Every other filter function is dropped. They are not CSS's colour matrices
279
+ (18 §18.3, kept by 18 §18.13): `brightness()` is **additive** in XTFrame and `hue-rotate()` is a
280
+ YIQ hue rotation, so the import reports a `brightness()`/`hue-rotate()` that changes anything as
281
+ `degraded` (`brightness is additive in XTFrame (18 §18.3)`), and an out-of-range
282
+ `brightness`/`contrast`/`saturate` is clamped with a finding (24 §24.15.4, T-566a/b records).
283
+ Check such an element in a screenshot.
284
+ - `backdrop-filter: blur(<px>) [saturate(<n>)] [brightness(<n>)]` — frosted glass. It becomes
285
+ XTFrame's `effect: backdrop-blur(…)`, which blurs whatever is painted **below** the element (the
286
+ game world included). `blur()` is required; any other backdrop function drops the declaration
287
+ with a warning. Keep the blur radius ≤ 32px on a 1280×720 board (the runtime caps it at 64
288
+ device px). Write `backdrop-filter` **before** `box-shadow`/`filter` on the same element: they
289
+ merge into one effect list and backdrop-blur has to be first, otherwise the import fails.
290
+ - A `<button>`'s text is a bare text node, not a flex item: centre it with `text-align: center`
291
+ and a `line-height` equal to the button height, not with `display: flex`.
292
+ - Text: `font-family` (from the tokens, or a Google Font linked in `<helmet>`), `font-size` px,
293
+ `font-weight`, `font-style`, `line-height` px, `letter-spacing` px, `text-align`, `color`,
294
+ `text-transform` (`uppercase`/`lowercase`/`capitalize`/`none`; inherited and applied at run
295
+ time, so toggling a class changes the case; only ASCII, Latin-1 and Latin Extended-A letters change
296
+ case). The `font` shorthand is expanded for you (it needs a size).
297
+ - Fonts (07 §7.20): `.ttf`, `.otf` and the collections `.ttc` / `.otc` are found (each face of a
298
+ collection is its own family); `font-weight` picks the nearest installed weight (CSS Fonts 4
299
+ rules, the `wght` axis of a variable font), and a weight of 600 or more on a family whose
300
+ heaviest face is lighter is drawn as synthetic bold. When the first CJK family of a
301
+ `font-family` stack is not installed, import, `xtframe-view` and `xtframe-pack` report
302
+ `missing font '<family>'` (`font.missing`; the fix hint is the stack without that family)
303
+ instead of falling back silently: install the font or drop it from the stack. CJK line breaking
304
+ follows the kinsoku rules (no `。,、」』)!?:;` at a line start, no `「『(` at a line end).
305
+ - Images: `<img src="/_blob/…" style="width; height; object-fit: cover|contain">`. `object-fit`
306
+ is carried over; when the board writes none the import writes `fill`, the CSS default
307
+ (24 §24.14.5). `object-position` and `mask-image` / `-webkit-mask-image` have no XTFrame
308
+ property: the import renames the prefixed one and reports both as unsupported (a gradient mask is
309
+ 18's `effect: gradient-mask()`). A `background-image: url(/_blob/…)` is moved into the project
310
+ like an `<img>`'s blob.
311
+ - `outline` and `outline-width/color/offset/style` are kept (a ring outside the border box; no layout or hit-test change); line styles other than `solid`/`none` are drawn solid with a warning.
312
+ - `text-decoration` and `text-decoration-line/color/thickness` are kept: `underline`, `overline`,
313
+ `line-through` (several at once allowed); other line styles (`dotted`, `wavy`, …) are drawn solid
314
+ with a warning. Rich text's `<u>`/`<ins>` and `<s>`/`<del>`/`<strike>` map to underline and
315
+ line-through.
316
+ - `line-clamp: <n>` (or `-webkit-line-clamp`) shows at most n lines of wrapping text and ends the
317
+ last one with `…`; the usual `display: -webkit-box; -webkit-box-orient: vertical;
318
+ -webkit-line-clamp: n` idiom becomes a block with `line-clamp: n`. With `white-space: nowrap` it
319
+ only matters together with `text-overflow: ellipsis` (one line).
320
+ - `font-variant-numeric: tabular-nums` (inherited) gives every figure the same width, for counters
321
+ and timers that change; `normal` switches it off again. Other values are dropped with a warning.
322
+ - Responsive exceptions (XTFrame properties, kept as written, both inherited): `ui-scale: none`
323
+ keeps a subtree at device pixels when the game resolution changes (crosshairs, pixel icons, 1 px
324
+ lines; pair pixel icons with `image-rendering: pixelated`), `ui-scale: clamp(<min>, <max>)` limits
325
+ how far the subtree follows the project's scale, `ui-scale: auto` (the default) follows it. px,
326
+ em, font sizes, borders, radii and shadows follow the factor; `%`, `vw`/`vh` and `uiscale` units
327
+ do not. `media-override: show | hide` stops `@media` rules from switching the subtree's `display`
328
+ (`show` = shown as the plain rules say, `hide` = always hidden); `auto` lets them.
329
+ - `background-image: url(…)` with `background-size` (`auto`, `cover`, `contain`, one or two px/%
330
+ lengths), `background-position` (`left|center|right` or a length, then `top|center|bottom` or a
331
+ length; edge-offset forms like `right 10px bottom 4px` are dropped) and `background-repeat`
332
+ (`no-repeat`, `repeat`, `repeat-x`, `repeat-y`; `space`/`round` tile like `repeat`). The
333
+ `background` shorthand is split into these. **Without** a `background-repeat` the image is
334
+ stretched over the padding box and size/position are ignored (XTFrame's default, unlike CSS):
335
+ write `background-repeat` whenever you set a size or position. Rounded corners clip the image.
336
+ `image-rendering: pixelated` (also `crisp-edges`) gives crisp pixel-art scaling for backgrounds
337
+ and `<img>`.
338
+
339
+ ### Carried over to the `.xt` / `.xts` as written (24 §24.14.5, T-566a record)
340
+
341
+ | On the board | Becomes |
342
+ |---|---|
343
+ | CSS `hit-slop: <1-4 lengths>` | the same property in the `.xts` (a wider pointer target, no layout change) |
344
+ | CSS `layer: overlay` | the same property in `<layout>` (escapes `overflow: hidden`, draws above the UI) |
345
+ | CSS `world-layer: on` (default `off`) | the same property in `<style>`: on a host that shows the UI in layers, the element and its subtree become a layer of their own; every other view ignores it. Not inherited, not animatable -- never in `@keyframes`, a transition or a timeline |
346
+ | `tabindex="<n>"` | `tabindex`; a negative value is kept but still makes the element focusable (a finding says so) |
347
+ | `autofocus`, `focus-trap` (bare, `true` or `false`) | the same attribute |
348
+ | `nav-up/down/left/right="#id"` | `nav:up="#id"` …, the id mapped to the imported one; a target that is no element of the board is dropped with a warning |
349
+ | `key-activation="auto\|none"` | on the board's root only; it goes on `<body>` |
350
+ | `-webkit-text-stroke` | `text-effect: outline` (a centred stroke becomes an outer one; a note says so) |
351
+ | any other lone `-webkit-*` property | converted under its unprefixed name, with a note |
352
+
353
+ Everything the import drops or rewrites (an attribute, a prefix, an unknown `data-xt-*`, an id
354
+ it had to slugify, a clamped number) is a finding with the board line, never silent (24 §24.14.5).
355
+
356
+ ## Transforms
357
+
358
+ `transform` may list the functions **in any order and more than once** — the compiler composes the
359
+ whole sequence into one 4×4 matrix and decomposes it again, so `rotateY(18deg) translateZ(40px)`
360
+ and `translateZ(40px) rotateY(18deg)` both compile and mean what CSS says they mean.
361
+
362
+ Supported: `translate/translateX/translateY/translateZ/translate3d`, `rotate`, `rotateZ`,
363
+ `rotateX`, `rotateY`, `skew/skewX/skewY`, `scale/scaleX/scaleY`, 2D `matrix(a, b, c, d, e, f)`
364
+ (decomposed into translate/rotate/skew/scale; a singular matrix is dropped with a warning), and
365
+ `none`. Not supported: `rotate3d()`, `scale3d()`, `matrix3d()`, and `perspective()` as a transform
366
+ function (use the `perspective` property instead) -- the import drops each such function on its
367
+ own, keeps the rest of the sequence and lists the drop in the report (a source issue for a class
368
+ rule). A sequence that would need a 3D shear or a z scale cannot be
369
+ represented and is a compile error — in practice only exotic combinations hit this.
370
+
371
+ `translateZ` accepts `px` only, never `%`.
372
+
373
+ **3D layers sort whole, by their anchor's depth** (19 §19.6): there is no per-pixel depth test.
374
+ Two planes that cross are drawn one after the other by the depth of each layer's anchor point,
375
+ so one covers the other entirely instead of cutting through it; and a 2D sibling between 3D
376
+ siblings splits them into separate sort groups. Keep intersecting planes apart in z, or split a
377
+ plane that must pass through another into two layers.
378
+
379
+ ## Animation
380
+
381
+ ```
382
+ animation: <keyframes-name> <duration> [<easing>] [<delay>] [<count>|infinite]
383
+ [<direction>] [<fill-mode>] [<play-state>]
384
+ transition: <prop|all> <duration> [<easing>] [<delay>]
385
+ ```
386
+
387
+ - Time units `s` / `ms`. Easing: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`,
388
+ `cubic-bezier(a,b,c,d)` or `steps(n[, start|end])`. Numbers **may** omit the leading zero
389
+ (`cubic-bezier(.6,0,.3,1)` is fine) and `forwards` / `backwards` / `both` are accepted.
390
+ - The `animation-name` / `-duration` / `-timing-function` / … longhands are composed back into the
391
+ shorthand for you, so either style works.
392
+ - Declarations inside a `@keyframes` block in `<helmet><style>` are converted like any other
393
+ (`filter`, `box-shadow`, `text-shadow`, `backdrop-filter`, `var()`), so animate them as you
394
+ would in a browser. Every keyframe of a rule must list the same `transform` functions and the
395
+ same effect functions in the same order; missing transforms are filled with the identity plus a
396
+ warning (`transform: none` is the explicit, warning-free way to say "identity"). A multi-layer
397
+ `background` inside a keyframe animates only its bottom layer. `@media` blocks are kept as they
398
+ are (an information line, not a warning).
399
+ - **Effects animate against a base the import adds** (24 §24.14.3, T-567 record). An effect
400
+ (`filter`, `box-shadow`, `backdrop-filter`) can only animate when the element already has that
401
+ effect in its static style; when a `@keyframes` or a `data-xt-timeline` animates one the element
402
+ does not have, the import adds the base effect itself, taken from the first key, and reports it
403
+ as `effect.baseAdded` (info). Not covered: a `@keyframes` started only by a class rule (a
404
+ trigger adds the class) gets no base -- give that element the effect in its own style.
405
+ - `transition: box-shadow | filter | text-shadow` becomes `transition: effect` (XTFrame
406
+ transitions the effect list as one property); `transition: text-shadow` is also reported as
407
+ `effect.degraded`, and `backdrop-filter` is not rewritten.
408
+ - **`visibility` flips at the middle of a segment.** It is a discrete value: between two keyframes
409
+ it switches when the eased progress passes 0.5, not at either keyframe (03 §3.10 `Enum`: discrete,
410
+ `t < 0.5 ? a : b`; 05 T-229 note). To switch at an exact time, add a key with the old value just
411
+ before the switch (`390 visibility visible, 400 visibility hidden`), so the segment is 10 ms long.
412
+ - Naming a `@keyframes` that does not exist is a compile error, not a warning.
413
+
414
+ ## Icons and vectors
415
+
416
+ Inline `<svg>` with `path/rect/circle/ellipse/line/polygon`, `viewBox`, solid **or gradient** fills
417
+ and strokes — a `<linearGradient>`/`<radialGradient>` in `<defs>` referenced by `fill="url(#id)"`
418
+ works even when the `<defs>` comes after the shape or sits inside a `<g>`. No `<text>`,
419
+ `<filter>`, `<mask>` or `<pattern>` inside SVG. Or upload a PNG. An inline `<svg>` is imported as
420
+ an editable vector layer (T-224); `data-xt-vector="file"` asks for a `shared/img/` file instead.
421
+ Inside `<svg>` tag and attribute names keep their case (`linearGradient`, `viewBox`,
422
+ `gradientUnits`), and intent tags work on the `<svg>` and on its shapes: a `data-xt-timeline` on
423
+ a shape (with an `id`) becomes a `#<svg id>/<shape id>` track (24 §24.14.4, T-565 record).
424
+ Rules, ids, token colours, which tags work where and motion examples: `references/vector.md`.
425
+
426
+ ## Colors, type, spacing
427
+
428
+ Take them from the project's tokens: a UI Project's `shared/tokens.xts` when there is one
429
+ (`references/ui-project.md` of the `xtui` skill), otherwise `tokens.json` (shipped next to this
430
+ file). Prefer the token values over ad-hoc hex so the game's theme can be swapped later.
431
+ `var(--name)` is expanded at import time, or kept as a theme reference on the colour and length
432
+ properties that take it whole; a `var()` that resolves to nothing drops the declaration.
433
+ `data-xt-token` (below) is the explicit way to say "this colour is that token".
434
+
435
+ The shipped `tokens.json` follows the Broadsheet style of the standard symbol library
436
+ (Docs/design/47-symbol-visual-style.md, section 47.13): grey-white newsprint (`#e6e2d6`, not yellow)
437
+ with ink-black lines and type blocks (theme `base`), a dark "night desk" set (theme `dark`), square
438
+ corners (radius 0), no blurred shadows (a hard letterpress edge instead), a paper-grain tile
439
+ (`--tex-grain`) under every screen, Noto Serif Display ExtraCondensed Black for display text
440
+ (always upper case) and Noto Serif for body text. A board that should look like
441
+ the standard symbols draws with those values; a project's own tokens always win.
442
+
443
+ ## Holes (`{{name}}`)
444
+
445
+ `{{hole}}` marks a value the game will supply at runtime. Use it in CSS values **and** in inline
446
+ SVG attributes; it is expanded from the `data-props` default so the board still looks right, and
447
+ the import records `{node, prop, hole}` in `import-report.json`'s `bindings[]` so the host or a
448
+ flow can wire it. A hole with no default keeps the declaration but is reported.
449
+
450
+ ## Classes and state
451
+
452
+ Authored `class` attributes are **kept**, and `<helmet><style>` class rules are imported as real
453
+ stylesheet rules (`:hover` included). That is the right way to express a state: write
454
+ `.selected { … }`, `.hidden { visibility: hidden }` in `<helmet>`, and let a trigger
455
+ (`class(selected, toggle)`) or the flow switch it instead of pushing whole style strings around.
456
+ To draw a state as its own element instead, use `data-xt-state` (below).
457
+
458
+ ## Intent tags (`data-xt-*`)
459
+
460
+ A board says what an element **is for** with `data-xt-*` attributes. The browser ignores them;
461
+ `xtframe-import dc` turns each into the XTFrame structure it names (Docs/design/27-interaction.md
462
+ §27.5). Prefer a tag over a script or a `.xtflow`: a hover, a click that plays an animation, a bar
463
+ that follows a game value are all tags. An unknown `data-xt-*` is a warning and is ignored; where a
464
+ tag and what the board implies disagree (an `<a href>` versus a click trigger, a literal colour
465
+ versus a token, `left/top` versus an anchor), **the tag wins**.
466
+
467
+ | Tag | Value | Becomes |
468
+ |---|---|---|
469
+ | `data-xt-name` | layer name | the layer id (slugified), and the re-import key |
470
+ | `data-xt-symbol` | `Name[; variants=Kind:A,B]` | first element: `<symbol name>` definition + `<use>`; later: `<use>` |
471
+ | `data-xt-variant` | `Kind=A[; Size=M]` | `variant:Kind="A"` on that instance |
472
+ | `data-xt-slot` | slot name | `<slot name>` in the definition; later instances fill it (`slot:name`) |
473
+ | `data-xt-state` | `Hover` / `Pressed` / `Focus` / `Disabled` / `Checked` / any name | the element is that state's look: its differences become a `#id:hover` / `#id:state(Name)` rule in the `.xts`; it is not drawn |
474
+ | `data-xt-trigger` | `event:actions; event:actions` | `on:event="actions"` (on the board root: on `<body>`) |
475
+ | `data-xt-timeline` | `name[ loop]: t prop value, t prop value; name2: ...` | a track of `@timeline name` in `<timelines>` |
476
+ | `data-xt-port` | `name:type [in\|out\|call]; ...` | a line `name: type ...` of the UI's `<ports>` (on a symbol's element: of the symbol's `<ports>`) |
477
+ | `data-xt-bind` | `target=port \| converters; ...` | `bind:target` |
478
+ | `data-xt-token` | token name (`accent`) | the colour or background becomes `var(--accent)` |
479
+ | `data-xt-token-prop` | CSS property | which property `data-xt-token` replaces (default: `color`, else `background`) |
480
+ | `data-xt-sound` | `event:cue[, volume]; ...` | `sound(cue)` first in that event's `on:` |
481
+ | `data-xt-anchor` | `top-left` … `bottom-right`, `center`, `safe` | `anchor: <x> <y>` + `offset` in `<layout>`, pinned to the safe area |
482
+ | `data-xt-uiscale` | `height`, `width`, `shortEdge`, `fit` (board root only) | `<name>.xtui` `spec.uiscaleRule` (see **Board setup**) |
483
+ | `data-xt-role` | `hud-health`, `menu-list`, … | `data-role` (templates and lint) |
484
+ | `data-xt-glyph` | input action (`jump`) | `<glyph key="jump">`, the current device's button glyph |
485
+ | `data-xt-rich` | (bare) | the element's text and inline `<b>`/`<i>`/`<span style>`/`<img>` become one rich text |
486
+ | `data-xt-editor-only` | (bare) | `editor-only`: shown in the editor, removed with its subtree when the UI is published |
487
+ | `data-xt-key` | localization key (`menu_title`) | the text element's text becomes `@menu_title`; the board's text is only the preview (see **Localization keys**) |
488
+ | `data-xt-repeat` | list port (`items`), or `item(<field>)` inside another repeat | `<repeat port="items">`; the first child element is the template (see **Lists**) |
489
+ | `data-xt-allow` | diagnostic codes (`anchor.rewritten, layout.flexShrinkText`) | those findings on this element are accepted and no longer listed (24 §24.15.1); not written to the `.xt` |
490
+
491
+ ### Names
492
+
493
+ `data-xt-name="HpBar"` → layer `hpbar` (lowercase, `-` between words). Give every layer that a
494
+ trigger, a binding, a state or a re-import has to find a name. Symbol, state, timeline, port and
495
+ slot names are `[A-Za-z_][A-Za-z0-9_-]*` and keep their case.
496
+
497
+ ### Symbols, variants, slots
498
+
499
+ ```html
500
+ <div data-xt-name="Play" data-xt-symbol="MenuButton; variants=Kind:Primary,Secondary"
501
+ data-xt-variant="Kind=Primary" style="width: 140px; height: 40px; background-color: #2f81f7">
502
+ <span data-xt-name="Caption" data-xt-slot="label" style="color: #ffffff">Play</span>
503
+ </div>
504
+ <div data-xt-name="Quit" data-xt-symbol="MenuButton" data-xt-variant="Kind=Secondary"
505
+ style="width: 140px; height: 40px; background-color: #30363d">
506
+ <span data-xt-slot="label">Quit</span>
507
+ </div>
508
+ ```
509
+
510
+ - The **first** element with a symbol name defines it: its children become the definition (a
511
+ `<symbol name="MenuButton">` with its own `<layout>` and `<style>` sections), and the element
512
+ itself becomes the first instance.
513
+ - Every later element with the same name is an instance: its **own** style, classes and tags
514
+ apply to the instance box; of its children only the `data-xt-slot` texts are read (they fill
515
+ the slots). Anything else inside a later instance is ignored, so write the content once.
516
+ - A symbol element with only text (`<button data-xt-symbol="Chip">OK</button>`) gets a `label`
517
+ slot automatically; each instance's text fills it.
518
+ - `variants=` declares the variant groups (`Kind:Primary,Secondary`; several groups separated by
519
+ spaces, or several `variants=` entries); `data-xt-variant` picks one per instance, which puts the
520
+ class `v-Kind-Primary` on the instance box. An instance's own inline style still beats a
521
+ `<helmet>` class rule, so the simplest variant is each instance's own colours, as above.
522
+ - The instance box is a `<div>`: a symbol made from a `<button>` is still clickable (triggers work
523
+ on any element), but give it `data-xt-trigger` for what the click does.
524
+ - A `data-xt-port` on the first symbol element declares a **port of the symbol** (24 §24.14.5,
525
+ T-566b correction): it is written to the definition's `<ports>`, and each instance sets it like
526
+ any `<use>` port (a plain attribute such as `<use title="…">`, or `bind:`).
527
+ - The symbol element's own look (background, border, radius on the element that carries
528
+ `data-xt-symbol`) is the instance box, not part of the definition -- a `symbol()` rule cannot
529
+ select it. The import copies that look onto later instances that write none of their own and
530
+ says so (`tag.symbolRootAppearance`, info). Put the look on an inner element when every instance
531
+ must share it from the definition.
532
+
533
+ ### States
534
+
535
+ ```html
536
+ <div data-xt-name="Play" ...>Play</div> <!-- Normal -->
537
+ <div data-xt-name="Play" data-xt-state="Hover"
538
+ style="... background-color: #58a6ff"></div> <!-- how it looks hovered -->
539
+ ```
540
+
541
+ The state element names its Normal element with the same `data-xt-name`. Only the declarations
542
+ that differ from Normal are written (`#play:hover { background-color: #58a6ff }`); named children
543
+ of the state element restyle the Normal element's children of the same name
544
+ (`#play:hover #caption { ... }`). `Hover`, `Pressed`, `Focus`, `Disabled` and `Checked` are the
545
+ built-in states; any other name is a custom state (`:state(Selected)`) that a trigger or a binding
546
+ switches (`state(Selected, toggle)`, `bind:state.Low`). State elements are never drawn, and the
547
+ state rule never takes their **geometry**: `left`, `top`, `right`, `bottom`, `width`, `height`
548
+ and `transform` are left out of the difference (24 §24.14.5), so a state element may sit anywhere
549
+ -- a "states" strip beside the UI is fine -- without moving the Normal element. Any geometry
550
+ difference is reported as `tag.stateGeometry`; a state that differs only in geometry writes no
551
+ rule (and is not `tag.stateNoDiff`). To move or scale an element in a state, write the
552
+ `:hover` / `:state()` rule in `<helmet>` or animate it with a `state(<Name>).enter` timeline. A
553
+ state identical to Normal is reported (`tag.stateNoDiff`).
554
+
555
+ ### Triggers and timelines
556
+
557
+ ```html
558
+ <div data-xt-name="Card"
559
+ data-xt-timeline="pulse: 0 transform scale(1), 200ms ease-out transform scale(1.06)"
560
+ data-xt-trigger="hover:play(pulse); leave:play(pulse, reverse); press:state(Selected, toggle)"
561
+ data-xt-sound="press:ui_click">
562
+ ```
563
+
564
+ - `data-xt-trigger`: `event:actions` pairs separated by `;`. Several actions for one event: keep
565
+ writing them after `;` (`press:sound(x); state(Sel, toggle)`). The events and actions are those
566
+ of `on:` (27 §27.2.2 / §27.2.3, 08 §8.12-§8.20):
567
+
568
+ | Event | Fires |
569
+ |---|---|
570
+ | `hover`, `leave` | the pointer enters / leaves the element |
571
+ | `press`, `release`, `click`, `dblclick` (`pointerdown` / `pointerup` = press / release) | the pointer; `press(right)`, `click(middle)` … pick a button |
572
+ | `pointermove`, `pointercancel` | every move over the element (the pressed element while a button is held); the press taken away |
573
+ | `pointerdrag` | once per frame after a left press on the element moved `drag-threshold` px (default 4); the release then sends no `click` (08 §8.20) |
574
+ | `outsidepress` | a press outside the element's subtree while it is visible (light-dismiss; does not bubble) |
575
+ | `focus`, `blur` / `focusin`, `focusout` | focus arrives / leaves; the `focusin` / `focusout` pair bubbles to the ancestors (08 §8.17) |
576
+ | `check`, `uncheck`, `change`, `input` | a checkbox; an `<input>` edit |
577
+ | `show`, `hide` | the element (or, on the root, the screen) is shown / asked to hide |
578
+ | `key(<key>)`, `key(any)` | a key while the element has the focus; `any` = every key and gamepad button except a modifier alone (27 §27.8, T-573) |
579
+ | `back` | the gamepad's B / Circle button (08 §8.9) |
580
+ | `scroll` | the scroll offset of a scroll container changed |
581
+ | `port(<name>)` | the port's value changed |
582
+ | `timeline(<name>).end`, `timeline(<name>).marker(<m>)` | a timeline finished / reached a marker |
583
+ | `state(<Name>).enter`, `.exit` | a custom state turned on / off |
584
+ | `drag.start`, `drag.over`, `drag.leave`, `drop`, `drag.cancel` | drag and drop (`draggable`, `drop-target`) |
585
+
586
+ | Action | Does |
587
+ |---|---|
588
+ | `play(<timeline>[, reverse\|loop\|once\|hold][, from=<marker>])` | plays a timeline of this scope (default: once, holding the last frame) |
589
+ | `stop(<timeline>)`, `seek(<timeline>, <time\|marker>)` | |
590
+ | `pause(<timeline>)`, `resume(<timeline>)` | pauses / continues a playing timeline (27 §27.8, T-573) |
591
+ | `state(<Name>[, on\|off\|toggle][, target=#<id>])` | a custom state; `target=` switches it on **another** element -- the one way for a trigger to change a different element (27 §27.13) |
592
+ | `class(<name>[, on\|off\|toggle])` | a class of the element |
593
+ | `show()`, `hide()`, `then hide` | the trigger's **own** element (no argument: `hide(#x)` is an error; use `state(…, target=#x)` plus a `:state()` rule) |
594
+ | `layer(overlay)`, `layer(normal)` | lifts the element into the overlay layer (out of a parent's `overflow: hidden`) and back |
595
+ | `consume()` | only in `outsidepress`: that press reaches nothing else (no press, release or click below; 08 §8.15) |
596
+ | `focus()`, `focus(<id>)` | focuses the element itself / another element |
597
+ | `set(<port>, <value>)`, `emit(<port>)` | writes a port / sends an event (see **Ports and bindings**) |
598
+ | `sound(<cue>[, volume])`, `haptic(<cue>)` | host cues |
599
+ | `reset(value)` | re-applies `bind:value` on an `<input>` |
600
+ | `spawn(<symbol>, at=…, lifetime=…)` | a short-lived instance (damage numbers) |
601
+ | `if <cond> <action> [else <action>]` | comparisons of the converter catalogue only |
602
+
603
+ `set()` values: a number, `true` / `false`, `toggle` (bool ports), a **quoted** string
604
+ (`set(lang, 'zh')`; a bare word is a compile error), `event.value`, `value` (an `<input>`'s text),
605
+ `pointer.fraction(#id).x` / `pointer.local(#id).y` (pointer triggers), `port(<name>)` (another port
606
+ of the same scope), or inside a repeat template `item(<field>)` / `repeat.index`; all but `toggle`
607
+ may go through converters, and a chain must start with one of these heads -- write
608
+ `set(is_zh, port(lang) | eq('zh'))`, not `set(is_zh, lang | eq(zh))` (27 §27.2.3, T-411 record).
609
+ - `data-xt-timeline`: `name: <time> [<easing>] <property> <value>, ...`; several timelines
610
+ separated by `;`. A time without a unit is ms (`0`, `400`, `400ms`, `0.4s`); easings as in
611
+ **Animation**; properties are CSS names (`opacity`, `transform`, `background-color`, …). The same
612
+ timeline name on several elements is **one** timeline with a track per element (a staggered
613
+ intro: `intro: 0 opacity 0, 300 opacity 1` on the title, `intro: 150 opacity 0, 450 opacity 1` on
614
+ the menu). `name loop:` makes every plain `play(name)` loop.
615
+ - A trigger that plays a timeline no element declares is dropped and reported
616
+ (`tag.triggerWithoutTimeline`); timelines inside a symbol are the symbol's own.
617
+ - Convention names: `intro` (with `show:play(intro)`), `outro` (`hide:play(outro) then hide`),
618
+ `hover-in`, `hover-out`, `idle`.
619
+
620
+ ### Ports and bindings
621
+
622
+ ```html
623
+ <div id="hud" data-xt-port="hp:number in; hp_max:number in; fire:event out" ...>
624
+ <div data-xt-name="HpFill" data-xt-bind="width=hp|range(0,hp_max,0%,100%)"></div>
625
+ <span data-xt-name="HpText" data-xt-bind="text=format('{0}/{1}', hp, hp_max)">75/100</span>
626
+ <div data-xt-name="Fire" data-xt-trigger="click:emit(fire)">Fire</div>
627
+ </div>
628
+ ```
629
+
630
+ - A port is the game's value (`in`), an event or value the UI sends (`out`), or a call (`call`).
631
+ Types: `number`, `string`, `bool`, `color`, `vec2`, `vec3`, `entity`, `enum(a|b)` (values
632
+ separated by `|`; `enum(a,b)` is an error, 27 §27.3.1), `list<T>`, `texture`, `event`. A default
633
+ follows `=`: `mode:enum(low|mid|high) in = mid`. Ports of the board go to the UI's `<ports>`
634
+ whatever element carries the tag (`mode: enum(low|mid|high) in = mid`, one line each); inside a
635
+ symbol definition they are the symbol's own `<ports>`. A flow addresses them as
636
+ `#document.<port>` (`references/flow.md`).
637
+ - **Bind from `in` ports.** A binding reads what the game (or a flow) writes into an `in` port. A
638
+ binding whose source is an `out` port is a warning (`bind.outPortSource`, 27 §27.8 and the T-568
639
+ / T-573 records); it does update when the host writes that port with `setPort`, or when a flow's
640
+ `emit` node sends to it, but nothing else feeds it. Copy a value between the
641
+ two directions with `set()` (`port(hp):set(hp_shown, port(hp))`).
642
+ - Bind targets: a CSS property, `text`, `src`, `visible`, `display`, `state.<Name>`,
643
+ `class.<name>`, `variant.<Prop>`, `checked`, `translate-x`/`-y`, `scale-x`/`-y`, `rotate`.
644
+ Converters: `range`, `clamp`, `round`, `floor`, `ceil`, `lt`/`gt`/`between`, `not`, `format`,
645
+ `thousands`, `percent`, `time(mm:ss)`, `select(...)`, `step(...)`, `lerpColor`, `fromToken`,
646
+ `localize`, `glyph(action)`, `tween(...)`.
647
+ - Converter arguments may be chains (03 §3.12.11, T-585): `format('{0} / {1}', hp | round(0),
648
+ hp_max | thousands)`, and likewise in `select()`, `step()` and `lookup()`; a sub-chain reads the
649
+ outer chain's input or starts with its own `port(<name>)`; nesting goes 4 deep. A bound length
650
+ may hold a static `calc()` (T-586): `bind:width="flag | select(calc(100% - 48px), 0px)"` is
651
+ evaluated at run time like a declared `calc()` (`%`, `vw`, `em` and the parent's size follow
652
+ the viewport); a `calc()` that reads a port (`calc(port(x) + 10px)`) is not evaluated
653
+ (`bind.calcNotEvaluated`) -- convert the port with `range()` instead.
654
+ - What the compiler warns about (27 §27.8): a bare converter argument that
655
+ is both an enum value and a port name (`bind.enumPortName`: quote it, `eq('low')`, to mean the
656
+ value). The lint reports an element that binds `display` / `visible` but writes `display: none`
657
+ / `visibility: hidden` itself (`tag.boundDisplayInlineNone`: true only restores the element's own
658
+ style, so it stays hidden) -- hide it with the port's default instead.
659
+ - A number bound to `text` prints with 6 significant digits (`%.6g`, the flow's rule, 53 §53.4.9):
660
+ `123.45`, not `123.450003`; an integer of 1,000,000 or more prints as `1e+06`, so use
661
+ `thousands` or `fixed(0)` for scores (T-568 record).
662
+ - Binding a port that is not declared fails the import (the compiler refuses it); a declared port
663
+ nothing binds, triggers on or emits is reported (`tag.portUnbound`).
664
+ - Keep the literal value on the board (`75/100`, `width: 75%`) so the board still looks right.
665
+ Use `{{hole}}` only when there is no port for it yet.
666
+
667
+ ### Lists (`data-xt-repeat`)
668
+
669
+ ```html
670
+ <div id="hud" data-xt-port="items:list&lt;struct{title: string}&gt; in">
671
+ <div data-xt-name="Rows" data-xt-repeat="items" style="display: flex; flex-direction: column">
672
+ <span data-xt-name="Title" data-xt-bind="text=item(title)">First entry</span>
673
+ </div>
674
+ </div>
675
+ ```
676
+
677
+ The element becomes `<repeat port="items">` and its **first child element** is the template every
678
+ entry copies (24 §24.14.5, T-566b record; 27 §27.3.4). Further children and loose text are dropped
679
+ with a warning, so draw one entry, not three. Bindings inside the template read the entry with
680
+ `item(<field>)`, `item()`, `index`, `count` and `outer.` (nested repeats); a binding there that
681
+ reads none of them is reported (`tag.repeatBinding`). Inside another template the value may be
682
+ `item(<field>)` for a nested list.
683
+
684
+ ### Localization keys (`data-xt-key`)
685
+
686
+ `<span data-xt-key="menu_title">Main menu</span>` imports as the key `@menu_title`; the board's
687
+ text is only the preview. A key is `[A-Za-z_][A-Za-z0-9_-]*` -- **no dots** (`menu.title` is a
688
+ finding and the text stays literal); only a text element (no child elements) can carry one
689
+ (24 §24.14.5, 07 §7.8). Any other text that starts with `@` stays literal text. The strings come
690
+ from the host at run time (see `references/not-like-web.md`, **Language**).
691
+
692
+ ### Tokens, anchors, roles, glyphs
693
+
694
+ - `data-xt-token="accent"` replaces the element's `color` (or, without one, its `background`)
695
+ with `var(--accent)`, so a theme can change it; `data-xt-token-prop="border-color"` names any
696
+ other colour property. The token must exist in the tokens (see **Colors, type, spacing**); an
697
+ unknown one is a warning and the literal stays.
698
+ - `data-xt-anchor="bottom-left"` pins the element to the safe area: `anchor: left bottom` in the
699
+ UI's `<layout>`, the board's px distance from each named edge as `offset`, the opposite edges
700
+ dropped. `safe` pins all four edges (`anchor: stretch stretch`); `center` leaves that axis
701
+ alone. A px offset the board gave a pinned edge uses the automatic anchoring's formula, so both
702
+ forms give the same result for the same board numbers (24 §24.14.2 item 4; `safe_px` = the UI
703
+ Project's `spec.safeArea` default -- 2.5% without a project -- x the board's width for
704
+ left/right, x its height for top/bottom; 2.5% of 1280 x 720 = 32 px / 18 px):
705
+
706
+ | board | automatic (edge within 25%) and `data-xt-anchor` |
707
+ |---|---|
708
+ | `left: 24px; bottom: 24px; width: 100px; height: 20px` | `anchor: left bottom; offset: -8px 6px; size: 100px 20px` |
709
+ | `right: 24px; top: 24px` | `anchor: right top; offset: -8px 6px` |
710
+ | `left: 0; top: 0; right: 0; bottom: 0` with `data-xt-anchor="safe"` | `anchor: stretch stretch; offset: -32px -18px` |
711
+ | formula | `offset` = board px - `safe_px` per axis (0 = exactly on the safe-area edge) |
712
+ | an axis the shorthand cannot say (a proportional `calc(<P>% - <n>px)`, one axis `safe` and the other `screen`) | both axes stay long-hand: `left: calc(1safe-left - 8px)` / `bottom: calc(1safe-bottom + 6px)` |
713
+
714
+ Use it for everything a TV or a phone notch must not cut. Re-importing an older project whose
715
+ `data-xt-anchor` elements carry px offsets changes those numbers to this formula (T-564 record).
716
+ The tag wins over the import's automatic anchoring (see **Board setup**): tag an element whose
717
+ nearest board edge is not the one it belongs to.
718
+ - `data-xt-role="hud-health"` is kept as `data-role` for layout templates and the lint.
719
+ - `data-xt-glyph="jump"` makes the element a button glyph for the `jump` action; its own text is
720
+ ignored. Inside `data-xt-rich` text, `<span data-xt-glyph="jump"></span>` is an inline glyph.
721
+ - `data-xt-editor-only` (bare) marks a reference the artist works over, such as a game screenshot
722
+ under a HUD that has no background: `<img src="references/game-shot.png" data-xt-editor-only>`.
723
+ It is imported as `editor-only`; the editor canvas shows it, the Demo space and the published
724
+ bundle do not (its whole subtree goes, and an image only it uses is not packed). Never give it
725
+ an id a trigger, binding or flow needs: the published UI has no such element.
726
+
727
+ ### Rich text
728
+
729
+ ```html
730
+ <span data-xt-name="Hint" data-xt-rich>Press <b>Esc</b> to <i>leave</i>,
731
+ <span style="color: #da3633">now</span></span>
732
+ ```
733
+
734
+ Without `data-xt-rich` every text run beside an element becomes its own `<span>` layer. With it,
735
+ the text stays **one** layer with styled runs. Allowed inside: `<b>`/`<strong>`, `<i>`/`<em>`,
736
+ `<span style class>` (a run takes `color`, `font-size`, `font-weight`, `font-style`,
737
+ `letter-spacing`; other properties are dropped with a warning), `<img>` (an inline image; give it a
738
+ `height`), `<span data-xt-glyph>` and `<br>` (a space). Whitespace-only gaps between two inline
739
+ elements are dropped, so write `</b> or <span…>` with a word between rather than a bare space.
740
+
741
+
742
+ ## 3D HUD
743
+
744
+ 3D is what XTFrame is for, and it imports faithfully. The shape that works:
745
+
746
+ ```html
747
+ <div id="hud" style="position:relative; width:1280px; height:720px; perspective: 1400px;
748
+ perspective-origin: 50% 50%">
749
+ <div id="panel-left"
750
+ style="position:absolute; left:80px; top:140px; width:360px; height:440px;
751
+ transform-origin: 100% 50%;
752
+ transform: rotateY(18deg) translateZ(-40px);
753
+ background-color:#161b22e6; border:1px solid #30363d; border-radius:12px;
754
+ animation: sway 6s ease-in-out 0s infinite alternate">
755
+ </div>
756
+ </div>
757
+ ```
758
+
759
+ ```css
760
+ @keyframes sway {
761
+ from { transform: rotateY(16deg) translateZ(-40px); }
762
+ to { transform: rotateY(20deg) translateZ(-40px); }
763
+ }
764
+ ```
765
+
766
+ - Put `perspective` (and `perspective-origin`) on the **container**, never on the panel itself.
767
+ - Give each panel a `transform-origin` on its hinge edge (`100% 50%` for a panel on the left,
768
+ `0% 50%` on the right) so it opens like a door instead of spinning in place.
769
+ - Keep the idle `sway` small (2–4°) and make every keyframe list the same transform functions.
770
+ - Flip cards: `backface-visibility: hidden` on both faces works under a parent that rotates
771
+ (`rotateY(0 -> 180deg)`): the back is judged on the **composed** transform, so at 180deg the front
772
+ is culled and the back shows (18 §18.13, T-572). Hit testing does not follow yet: the face turned
773
+ away can still be clicked, so switch `pointer-events` (a state or class) with the flip.
774
+ - `world-layer: on` on a panel only matters on a layered host (a game engine placing UI layers in
775
+ its 3D world); the board and every flat view draw it like any other element. It is not the same
776
+ as having a 3D `transform`, and it is written as a plain style (`world-layer: on`), never animated.
777
+ - **Do not try to author pointer parallax on the board.** Author the resting angle you want; the
778
+ lean is a `pointermove` trigger writing a port plus `bind:rotate-y` on the panel (the flow step of
779
+ `xtui` only wires logic; see `references/flow.md` Rules).
780
+
781
+ ## Flow bindings
782
+
783
+ Reach for the intent tags first (`data-xt-trigger`, `data-xt-timeline`, `data-xt-bind`,
784
+ `data-xt-port`); a `.xtflow` is for logic that spans UIs or needs computation (counters, timers,
785
+ selection, screen flow). An element driven by a `.xtflow` **must** have an authored `id`. Elements without one get a content-hash id (`n-xxxxxxxx`) that changes whenever the design
786
+ changes, so nothing can bind to it safely.
787
+
788
+ - Name ids by role: `diff-veteran`, `stat-damage-fill`, `btn-start`, `world-layer`.
789
+ - A bar is two elements: a track with `overflow: hidden` and a fill whose `width` (or
790
+ `transform: scaleX()`) the flow sets.
791
+ - Wrap anything that gets shown and hidden in its own `<div>`, and give the wrapper the id.
792
+ - Give a group's container an id as well, so a flow can restyle the whole group at once.
793
+ - States belong in classes (see above); the flow only toggles the class or state.
794
+
795
+ ## Prototype links
796
+
797
+ `<a href="Other.dc.html">` navigation is recorded as a hint for the game (which screen a button
798
+ leads to) but not executed; keep the element a `<button>` with an `id`. A `data-xt-trigger` with a
799
+ `click` or `press` event on the same element wins: the link is then ignored.