@xtframe/skills 0.0.0-stage → 0.19.1
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.
- package/README.md +22 -2
- package/package.json +41 -4
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
- package/payload/plugins/xtframe/gemini-extension.json +5 -0
- package/payload/plugins/xtframe/skills/xtui/SKILL.md +245 -0
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +93 -0
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +874 -0
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +339 -0
- package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +182 -0
- package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +404 -0
- package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +101 -0
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +170 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +141 -0
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +223 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +349 -0
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +219 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +988 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +211 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +175 -0
- package/src/agents.mjs +73 -0
- package/src/bin.mjs +4 -0
- package/src/cli.mjs +286 -0
- package/src/converter.mjs +73 -0
- package/src/fsutil.mjs +76 -0
- package/src/install.mjs +154 -0
- package/src/packs.mjs +150 -0
- package/src/plugins.mjs +109 -0
- package/src/proc.mjs +66 -0
- package/src/tar.mjs +103 -0
|
@@ -0,0 +1,874 @@
|
|
|
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(0.4) is multiplicative in CSS but additive here (becomes -0.60)` ...: a
|
|
282
|
+
CSS dimming brightness turns the element much darker; dim with a black overlay of opacity
|
|
283
|
+
`1 - factor` instead, or lower the element's opacity over a dark backdrop), and an out-of-range
|
|
284
|
+
`brightness`/`contrast`/`saturate` is clamped with a finding (24 §24.15.4, T-566a/b records).
|
|
285
|
+
Check such an element in a screenshot.
|
|
286
|
+
- **`brightness()` is the most damaging trap of a web source.** CSS `brightness(0.4)` multiplies
|
|
287
|
+
the colour by 0.4; here it adds -0.6, so a dark background goes black (a converted project lost
|
|
288
|
+
seven backgrounds this way) and `brightness(0)` makes a silhouette. To **dim**, never use
|
|
289
|
+
`brightness()` below 1: put a black element over the image with `opacity` = 1 - the value
|
|
290
|
+
(`brightness(0.4)` -> a black overlay at `opacity: 0.6`), or make the element itself
|
|
291
|
+
semi-transparent over a dark backdrop. `brightness(1.6)` washes it to white: for a flash use a
|
|
292
|
+
small value (about 1.25) or a glow. `brightness()` and `drop-shadow()` in one `filter` work and
|
|
293
|
+
may be keyed together (a silhouette revealed with a rim light): every key lists both, in the
|
|
294
|
+
same order; the rim light does not darken with the brightness.
|
|
295
|
+
- `clip-path` with `inset()`, `circle()`, `ellipse()` or `polygon()` is supported **statically**
|
|
296
|
+
(a diagonal split screen: two layers with `polygon(0 0, 58% 0, 42% 100%, 0 100%)` and its
|
|
297
|
+
complement). It **cannot be animated**: a `clip-path` in a keyframe or a transition is dropped
|
|
298
|
+
with `"clip-path" is not animatable; ignored`. A circle that closes on the centre (an iris out)
|
|
299
|
+
is done instead with either (a) a ring -- a round element with a very thick border in the cover
|
|
300
|
+
colour whose `width` / `height` animate to 0:
|
|
301
|
+
|
|
302
|
+
```html
|
|
303
|
+
<style> @keyframes iris-close { from { width: 2400px; height: 2400px } to { width: 0px; height: 0px } } </style>
|
|
304
|
+
<div id="iris" style="position: absolute; left: 50%; top: 50%; width: 2400px; height: 2400px;
|
|
305
|
+
box-sizing: content-box; border: 2400px solid #000000; border-radius: 50%;
|
|
306
|
+
transform: translate(-50%, -50%); animation: iris-close 2s linear 0s 1 both"></div>
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
or (b) an inline SVG over the screen: one black path, a huge rectangle with a circular hole
|
|
310
|
+
(`fill-rule="evenodd"`), its `transform` keyed from `scale(1)` to `scale(0.001)` around the
|
|
311
|
+
centre (`transform-origin: 50% 50%`).
|
|
312
|
+
- `repeating-conic-gradient` and `mask-image` are not supported: the import drops them with
|
|
313
|
+
`repeating-conic-gradient is not one of the gradients 05 §5.5c has; dropped` and `property
|
|
314
|
+
mask-image is not in the XTFrame style subset (05 §5.4); dropped`. A radial or linear fade-out
|
|
315
|
+
mask is the `gradient-mask` effect after the import (`catalog_add {"id": "gradient-mask"}` in the
|
|
316
|
+
editor). Radial speed lines need neither: an inline SVG of thin solid triangles around a centre
|
|
317
|
+
(each tip 30-50 % of the radius out, so the centre stays clear), turned a few degrees with a
|
|
318
|
+
`steps()` easing (`animation: jitter 1s steps(24) infinite`) for the flicker.
|
|
319
|
+
- `backdrop-filter: blur(<px>) [saturate(<n>)] [brightness(<n>)]` — frosted glass. It becomes
|
|
320
|
+
XTFrame's `effect: backdrop-blur(…)`, which blurs whatever is painted **below** the element (the
|
|
321
|
+
game world included). `blur()` is required; any other backdrop function drops the declaration
|
|
322
|
+
with a warning. Keep the blur radius ≤ 32px on a 1280×720 board (the runtime caps it at 64
|
|
323
|
+
device px). Write `backdrop-filter` **before** `box-shadow`/`filter` on the same element: they
|
|
324
|
+
merge into one effect list and backdrop-blur has to be first, otherwise the import fails.
|
|
325
|
+
- A `<button>`'s text is a bare text node, not a flex item: centre it with `text-align: center`
|
|
326
|
+
and a `line-height` equal to the button height, not with `display: flex`.
|
|
327
|
+
- Text: `font-family` (from the tokens, or a Google Font linked in `<helmet>`), `font-size` px,
|
|
328
|
+
`font-weight`, `font-style`, `line-height` px, `letter-spacing` px, `text-align`, `color`,
|
|
329
|
+
`text-transform` (`uppercase`/`lowercase`/`capitalize`/`none`; inherited and applied at run
|
|
330
|
+
time, so toggling a class changes the case; only ASCII, Latin-1 and Latin Extended-A letters change
|
|
331
|
+
case). The `font` shorthand is expanded for you (it needs a size).
|
|
332
|
+
- Fonts (07 §7.20): `.ttf`, `.otf` and the collections `.ttc` / `.otc` are found (each face of a
|
|
333
|
+
collection is its own family); `font-weight` picks the nearest installed weight (CSS Fonts 4
|
|
334
|
+
rules, the `wght` axis of a variable font), and a weight of 600 or more on a family whose
|
|
335
|
+
heaviest face is lighter is drawn as synthetic bold. When the first CJK family of a
|
|
336
|
+
`font-family` stack is not installed, import, `xtframe-view` and `xtframe-pack` report
|
|
337
|
+
`missing font '<family>'` (`font.missing`; the fix hint is the stack without that family)
|
|
338
|
+
instead of falling back silently: install the font or drop it from the stack. CJK line breaking
|
|
339
|
+
follows the kinsoku rules (no `。,、」』)!?:;` at a line start, no `「『(` at a line end).
|
|
340
|
+
- Images: `<img src="/_blob/…" style="width; height; object-fit: cover|contain">`. `object-fit`
|
|
341
|
+
is carried over; when the board writes none the import writes `fill`, the CSS default
|
|
342
|
+
(24 §24.14.5). `object-position` and `mask-image` / `-webkit-mask-image` have no XTFrame
|
|
343
|
+
property: the import renames the prefixed one and reports both as unsupported (a gradient mask is
|
|
344
|
+
18's `effect: gradient-mask()`). A `background-image: url(/_blob/…)` is moved into the project
|
|
345
|
+
like an `<img>`'s blob. Image formats the runtime decodes (on every renderer, and mirrored
|
|
346
|
+
builds alike): PNG, JPEG, GIF (first frame), BMP, TGA, PSD, HDR, PIC, PNM and DDS. Anything
|
|
347
|
+
else -- WebP above all, also AVIF, HEIF/HEIC, JPEG XL, TIFF, QOI -- draws as nothing: the import
|
|
348
|
+
copies the file as it is and reports `asset.undecodable`, `xtframe-compile` warns
|
|
349
|
+
`image asset "<path>": format <fmt> cannot be decoded (supported: …)` (an error under
|
|
350
|
+
`--strict`) and the editor's lint says `asset.undecodable`. The format is told by the file's
|
|
351
|
+
bytes, not its extension. Convert such images to PNG or JPG before the import.
|
|
352
|
+
- `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.
|
|
353
|
+
- `text-decoration` and `text-decoration-line/color/thickness` are kept: `underline`, `overline`,
|
|
354
|
+
`line-through` (several at once allowed); other line styles (`dotted`, `wavy`, …) are drawn solid
|
|
355
|
+
with a warning. Rich text's `<u>`/`<ins>` and `<s>`/`<del>`/`<strike>` map to underline and
|
|
356
|
+
line-through.
|
|
357
|
+
- `line-clamp: <n>` (or `-webkit-line-clamp`) shows at most n lines of wrapping text and ends the
|
|
358
|
+
last one with `…`; the usual `display: -webkit-box; -webkit-box-orient: vertical;
|
|
359
|
+
-webkit-line-clamp: n` idiom becomes a block with `line-clamp: n`. With `white-space: nowrap` it
|
|
360
|
+
only matters together with `text-overflow: ellipsis` (one line).
|
|
361
|
+
- `font-variant-numeric: tabular-nums` (inherited) gives every figure the same width, for counters
|
|
362
|
+
and timers that change; `normal` switches it off again. Other values are dropped with a warning.
|
|
363
|
+
- Responsive exceptions (XTFrame properties, kept as written, both inherited): `ui-scale: none`
|
|
364
|
+
keeps a subtree out of the project's scale policy (factor 1: 1 px stays 1 px, like CSS px) when the
|
|
365
|
+
game resolution changes (crosshairs, pixel icons, 1 px lines; pair pixel icons with
|
|
366
|
+
`image-rendering: pixelated`), `ui-scale: clamp(<min>, <max>)` limits
|
|
367
|
+
how far the subtree follows the project's scale, `ui-scale: auto` (the default) follows it. px,
|
|
368
|
+
em, font sizes, borders, radii and shadows follow the factor; `%`, `vw`/`vh` and `uiscale` units
|
|
369
|
+
do not. `media-override: show | hide` stops `@media` rules from switching the subtree's `display`
|
|
370
|
+
(`show` = shown as the plain rules say, `hide` = always hidden); `auto` lets them.
|
|
371
|
+
- `background-image: url(…)` with `background-size` (`auto`, `cover`, `contain`, one or two px/%
|
|
372
|
+
lengths), `background-position` (`left|center|right` or a length, then `top|center|bottom` or a
|
|
373
|
+
length; edge-offset forms like `right 10px bottom 4px` are dropped) and `background-repeat`
|
|
374
|
+
(`no-repeat`, `repeat`, `repeat-x`, `repeat-y`; `space`/`round` tile like `repeat`). The
|
|
375
|
+
`background` shorthand is split into these. **Without** a `background-repeat` the image is
|
|
376
|
+
stretched over the padding box and size/position are ignored (XTFrame's default, unlike CSS):
|
|
377
|
+
write `background-repeat` whenever you set a size or position. Rounded corners clip the image.
|
|
378
|
+
`image-rendering: pixelated` (also `crisp-edges`) gives crisp pixel-art scaling for backgrounds
|
|
379
|
+
and `<img>`.
|
|
380
|
+
|
|
381
|
+
### Carried over to the `.xt` / `.xts` as written (24 §24.14.5, T-566a record)
|
|
382
|
+
|
|
383
|
+
| On the board | Becomes |
|
|
384
|
+
|---|---|
|
|
385
|
+
| CSS `hit-slop: <1-4 lengths>` | the same property in the `.xts` (a wider pointer target, no layout change) |
|
|
386
|
+
| CSS `layer: overlay` | the same property in `<layout>` (escapes `overflow: hidden`, draws above the UI) |
|
|
387
|
+
| 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 |
|
|
388
|
+
| `tabindex="<n>"` | `tabindex`; a negative value is kept but still makes the element focusable (a finding says so) |
|
|
389
|
+
| `autofocus`, `focus-trap` (bare, `true` or `false`) | the same attribute |
|
|
390
|
+
| `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 |
|
|
391
|
+
| `key-activation="auto\|none"` | on the board's root only; it goes on `<body>` |
|
|
392
|
+
| `-webkit-text-stroke` | `text-effect: outline` (a centred stroke becomes an outer one; a note says so) |
|
|
393
|
+
| any other lone `-webkit-*` property | converted under its unprefixed name, with a note |
|
|
394
|
+
|
|
395
|
+
Everything the import drops or rewrites (an attribute, a prefix, an unknown `data-xt-*`, an id
|
|
396
|
+
it had to slugify, a clamped number) is a finding with the board line, never silent (24 §24.14.5).
|
|
397
|
+
|
|
398
|
+
## Transforms
|
|
399
|
+
|
|
400
|
+
`transform` may list the functions **in any order and more than once** — the compiler composes the
|
|
401
|
+
whole sequence into one 4×4 matrix and decomposes it again, so `rotateY(18deg) translateZ(40px)`
|
|
402
|
+
and `translateZ(40px) rotateY(18deg)` both compile and mean what CSS says they mean.
|
|
403
|
+
|
|
404
|
+
Supported: `translate/translateX/translateY/translateZ/translate3d`, `rotate`, `rotateZ`,
|
|
405
|
+
`rotateX`, `rotateY`, `skew/skewX/skewY`, `scale/scaleX/scaleY`, 2D `matrix(a, b, c, d, e, f)`
|
|
406
|
+
(decomposed into translate/rotate/skew/scale; a singular matrix is dropped with a warning), and
|
|
407
|
+
`none`. Not supported: `rotate3d()`, `scale3d()`, `matrix3d()`, and `perspective()` as a transform
|
|
408
|
+
function (use the `perspective` property instead) -- the import drops each such function on its
|
|
409
|
+
own, keeps the rest of the sequence and lists the drop in the report (a source issue for a class
|
|
410
|
+
rule). A sequence that would need a 3D shear or a z scale cannot be
|
|
411
|
+
represented and is a compile error — in practice only exotic combinations hit this.
|
|
412
|
+
|
|
413
|
+
`translateZ` accepts `px` only, never `%`.
|
|
414
|
+
|
|
415
|
+
**3D layers sort whole, by their anchor's depth** (19 §19.6): there is no per-pixel depth test.
|
|
416
|
+
Two planes that cross are drawn one after the other by the depth of each layer's anchor point,
|
|
417
|
+
so one covers the other entirely instead of cutting through it; and a 2D sibling between 3D
|
|
418
|
+
siblings splits them into separate sort groups. Keep intersecting planes apart in z, or split a
|
|
419
|
+
plane that must pass through another into two layers.
|
|
420
|
+
|
|
421
|
+
## Animation
|
|
422
|
+
|
|
423
|
+
```
|
|
424
|
+
animation: <keyframes-name> <duration> [<easing>] [<delay>] [<count>|infinite]
|
|
425
|
+
[<direction>] [<fill-mode>] [<play-state>]
|
|
426
|
+
transition: <prop|all> <duration> [<easing>] [<delay>]
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
- Time units `s` / `ms`. Easing: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`,
|
|
430
|
+
`cubic-bezier(a,b,c,d)` or `steps(n[, start|end])`. Numbers **may** omit the leading zero
|
|
431
|
+
(`cubic-bezier(.6,0,.3,1)` is fine) and `forwards` / `backwards` / `both` are accepted.
|
|
432
|
+
- The eight longhands (`animation-name`, `-duration`, `-timing-function`, `-delay`,
|
|
433
|
+
`-iteration-count`, `-direction`, `-fill-mode`, `-play-state`) work as in CSS: each one cascades
|
|
434
|
+
on its own, so a `:hover` or class rule can change only the `animation-play-state` or
|
|
435
|
+
`animation-delay` of the animation a base rule names (`.card { animation: pulse 1s }`
|
|
436
|
+
`.card:hover { animation-play-state: paused }`), and lists combine by `animation-name`'s length.
|
|
437
|
+
Each longhand is a style property of its own (a whole-value `var()` works), so any rule that
|
|
438
|
+
matches the element can change one of them; the `transition-*` longhands work the same way.
|
|
439
|
+
`animation-composition`, `animation-timeline` and `animation-range` are not supported; the import
|
|
440
|
+
drops them with a finding.
|
|
441
|
+
- Declarations inside a `@keyframes` block in `<helmet><style>` are converted like any other
|
|
442
|
+
(`filter`, `box-shadow`, `text-shadow`, `backdrop-filter`, `var()`), so animate them as you
|
|
443
|
+
would in a browser. Every keyframe of a rule must list the same `transform` functions and the
|
|
444
|
+
same effect functions in the same order; missing transforms are filled with the identity plus a
|
|
445
|
+
warning (`transform: none` is the explicit, warning-free way to say "identity"). A multi-layer
|
|
446
|
+
`background` inside a keyframe animates only its bottom layer. `@media` blocks are kept as they
|
|
447
|
+
are (an information line, not a warning).
|
|
448
|
+
- **Effects animate against a base the import adds** (24 §24.14.3, T-567 record). An effect
|
|
449
|
+
(`filter`, `box-shadow`, `backdrop-filter`) can only animate when the element already has that
|
|
450
|
+
effect in its static style; when a `@keyframes` or a `data-xt-timeline` animates one the element
|
|
451
|
+
does not have, the import adds the base effect itself, taken from the first key, and reports it
|
|
452
|
+
as `effect.baseAdded` (info). Not covered: a `@keyframes` started only by a class rule (a
|
|
453
|
+
trigger adds the class) gets no base -- give that element the effect in its own style.
|
|
454
|
+
- `transition: box-shadow | filter | text-shadow` becomes `transition: effect` (XTFrame
|
|
455
|
+
transitions the effect list as one property); `transition: text-shadow` is also reported as
|
|
456
|
+
`effect.degraded`, and `backdrop-filter` is not rewritten.
|
|
457
|
+
- **`visibility` flips at the middle of a segment.** It is a discrete value: between two keyframes
|
|
458
|
+
it switches when the eased progress passes 0.5, not at either keyframe (03 §3.10 `Enum`: discrete,
|
|
459
|
+
`t < 0.5 ? a : b`; 05 T-229 note). To switch at an exact time, add a key with the old value just
|
|
460
|
+
before the switch (`390 visibility visible, 400 visibility hidden`), so the segment is 10 ms long.
|
|
461
|
+
- Naming a `@keyframes` that does not exist is a compile error, not a warning.
|
|
462
|
+
- Accepted and drawn right (each tried in a converted project): `filter: grayscale(0)` to
|
|
463
|
+
`grayscale(1)` keyed (a freeze frame going grey); `brightness()` and `drop-shadow()` keyed
|
|
464
|
+
together in one `filter`; a looping `@keyframes` animation on the child of an element a timeline
|
|
465
|
+
moves; `steps()` with large step counts; a whole-shot `filter: blur(18px)` to `blur(0px)` on a
|
|
466
|
+
sliding container (a whip pan). Procedural motion of every kind: `references/from-procedural.md`.
|
|
467
|
+
|
|
468
|
+
## Icons and vectors
|
|
469
|
+
|
|
470
|
+
Inline `<svg>` with `path/rect/circle/ellipse/line/polygon`, `viewBox`, solid **or gradient** fills
|
|
471
|
+
and strokes — a `<linearGradient>`/`<radialGradient>` in `<defs>` referenced by `fill="url(#id)"`
|
|
472
|
+
works even when the `<defs>` comes after the shape or sits inside a `<g>`. No `<text>`,
|
|
473
|
+
`<filter>`, `<mask>` or `<pattern>` inside SVG (`fill="url(#p)"` on a `<pattern>` paints black).
|
|
474
|
+
Gradients must be defined inside the same `<svg>` that uses them; `fx`/`fy` (focal point),
|
|
475
|
+
`spreadMethod="reflect|repeat"`, and a radial gradient stretched into an ellipse (a non-uniform
|
|
476
|
+
or skewed `gradientTransform`, or `objectBoundingBox` on a non-square shape) are not supported:
|
|
477
|
+
the centre, pad and a circle are used, with a warning. Or upload a PNG. An inline `<svg>` is imported as
|
|
478
|
+
an editable vector layer (T-224); `data-xt-vector="file"` asks for a `shared/img/` file instead.
|
|
479
|
+
Inside `<svg>` tag and attribute names keep their case (`linearGradient`, `viewBox`,
|
|
480
|
+
`gradientUnits`), and intent tags work on the `<svg>` and on its shapes: a `data-xt-timeline` on
|
|
481
|
+
a shape (with an `id`) becomes a `#<svg id>/<shape id>` track (24 §24.14.4, T-565 record).
|
|
482
|
+
Rules, ids, token colours, which tags work where and motion examples: `references/vector.md`.
|
|
483
|
+
## Colors, type, spacing
|
|
484
|
+
|
|
485
|
+
Take them from the project's tokens: a UI Project's `shared/tokens.xts` when there is one
|
|
486
|
+
(`references/ui-project.md` of the `xtui` skill), otherwise `tokens.json` (shipped next to this
|
|
487
|
+
file). Prefer the token values over ad-hoc hex so the game's theme can be swapped later.
|
|
488
|
+
`var(--name)` is expanded at import time, or kept as a theme reference on the colour and length
|
|
489
|
+
properties that take it whole; a `var()` that resolves to nothing drops the declaration.
|
|
490
|
+
`data-xt-token` (below) is the explicit way to say "this colour is that token".
|
|
491
|
+
|
|
492
|
+
The shipped `tokens.json` follows the Broadsheet style of the standard symbol library
|
|
493
|
+
(Docs/design/47-symbol-visual-style.md, section 47.13): grey-white newsprint (`#e6e2d6`, not yellow)
|
|
494
|
+
with ink-black lines and type blocks (theme `base`), a dark "night desk" set (theme `dark`), square
|
|
495
|
+
corners (radius 0), no blurred shadows (a hard letterpress edge instead), a paper-grain tile
|
|
496
|
+
(`--tex-grain`) under every screen, Noto Serif Display ExtraCondensed Black for display text
|
|
497
|
+
(always upper case) and Noto Serif for body text. A board that should look like
|
|
498
|
+
the standard symbols draws with those values; a project's own tokens always win.
|
|
499
|
+
|
|
500
|
+
## Holes (`{{name}}`)
|
|
501
|
+
|
|
502
|
+
`{{hole}}` marks a value the game will supply at runtime. Use it in CSS values **and** in inline
|
|
503
|
+
SVG attributes; it is expanded from the `data-props` default so the board still looks right, and
|
|
504
|
+
the import records `{node, prop, hole}` in `import-report.json`'s `bindings[]` so the host or a
|
|
505
|
+
flow can wire it. A hole with no default keeps the declaration but is reported.
|
|
506
|
+
|
|
507
|
+
## Classes and state
|
|
508
|
+
|
|
509
|
+
Authored `class` attributes are **kept**, and `<helmet><style>` class rules are imported as real
|
|
510
|
+
stylesheet rules (`:hover` included). That is the right way to express a state: write
|
|
511
|
+
`.selected { … }`, `.hidden { visibility: hidden }` in `<helmet>`, and let a trigger
|
|
512
|
+
(`class(selected, toggle)`) or the flow switch it instead of pushing whole style strings around.
|
|
513
|
+
To draw a state as its own element instead, use `data-xt-state` (below).
|
|
514
|
+
|
|
515
|
+
## Intent tags (`data-xt-*`)
|
|
516
|
+
|
|
517
|
+
A board says what an element **is for** with `data-xt-*` attributes. The browser ignores them;
|
|
518
|
+
`xtframe-import dc` turns each into the XTFrame structure it names (Docs/design/27-interaction.md
|
|
519
|
+
§27.5). Prefer a tag over a script or a `.xtflow`: a hover, a click that plays an animation, a bar
|
|
520
|
+
that follows a game value are all tags. An unknown `data-xt-*` is a warning and is ignored; where a
|
|
521
|
+
tag and what the board implies disagree (an `<a href>` versus a click trigger, a literal colour
|
|
522
|
+
versus a token, `left/top` versus an anchor), **the tag wins**.
|
|
523
|
+
|
|
524
|
+
| Tag | Value | Becomes |
|
|
525
|
+
|---|---|---|
|
|
526
|
+
| `data-xt-name` | layer name | the layer id (slugified), and the re-import key |
|
|
527
|
+
| `data-xt-symbol` | `Name[; variants=Kind:A,B]` | first element: `<symbol name>` definition + `<use>`; later: `<use>` |
|
|
528
|
+
| `data-xt-variant` | `Kind=A[; Size=M]` | `variant:Kind="A"` on that instance |
|
|
529
|
+
| `data-xt-slot` | slot name | `<slot name>` in the definition; later instances fill it (`slot:name`) |
|
|
530
|
+
| `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 |
|
|
531
|
+
| `data-xt-trigger` | `event:actions; event:actions` | `on:event="actions"` (on the board root: on `<body>`) |
|
|
532
|
+
| `data-xt-timeline` | `name[ loop]: t prop value, t prop value; name2: ...` | a track of `@timeline name` in `<timelines>` |
|
|
533
|
+
| `data-xt-timeline-from-animations` | `name[ <seconds>s][ loop\|once\|none][ markers]` (on the root or a container) | the CSS `animation`s of its subtree that share a cycle become `@timeline name`; their declarations go; `on:show="play(name, loop)"` on it (see below) |
|
|
534
|
+
| `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>`) |
|
|
535
|
+
| `data-xt-bind` | `target=port \| converters; ...` | `bind:target` |
|
|
536
|
+
| `data-xt-token` | token name (`accent`) | the colour or background becomes `var(--accent)` |
|
|
537
|
+
| `data-xt-token-prop` | CSS property | which property `data-xt-token` replaces (default: `color`, else `background`) |
|
|
538
|
+
| `data-xt-sound` | `event:cue[, volume]; ...` | `sound(cue)` first in that event's `on:` |
|
|
539
|
+
| `data-xt-anchor` | `top-left` … `bottom-right`, `center`, `safe` | `anchor: <x> <y>` + `offset` in `<layout>`, pinned to the safe area |
|
|
540
|
+
| `data-xt-uiscale` | `height`, `width`, `shortEdge`, `fit` (board root only) | `<name>.xtui` `spec.uiscaleRule` (see **Board setup**) |
|
|
541
|
+
| `data-xt-role` | `hud-health`, `menu-list`, … | `data-role` (templates and lint) |
|
|
542
|
+
| `data-xt-glyph` | input action (`jump`) | `<glyph key="jump">`, the current device's button glyph |
|
|
543
|
+
| `data-xt-rich` | (bare) | the element's text and inline `<b>`/`<i>`/`<span style>`/`<img>` become one rich text |
|
|
544
|
+
| `data-xt-editor-only` | (bare) | `editor-only`: shown in the editor, removed with its subtree when the UI is published |
|
|
545
|
+
| `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**) |
|
|
546
|
+
| `data-xt-repeat` | list port (`items`), or `item(<field>)` inside another repeat | `<repeat port="items">`; the first child element is the template (see **Lists**) |
|
|
547
|
+
| `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` |
|
|
548
|
+
|
|
549
|
+
### Names
|
|
550
|
+
|
|
551
|
+
`data-xt-name="HpBar"` → layer `hpbar` (lowercase, `-` between words). Give every layer that a
|
|
552
|
+
trigger, a binding, a state or a re-import has to find a name. Symbol, state, timeline, port and
|
|
553
|
+
slot names are `[A-Za-z_][A-Za-z0-9_-]*` and keep their case.
|
|
554
|
+
|
|
555
|
+
### Symbols, variants, slots
|
|
556
|
+
|
|
557
|
+
```html
|
|
558
|
+
<div data-xt-name="Play" data-xt-symbol="MenuButton; variants=Kind:Primary,Secondary"
|
|
559
|
+
data-xt-variant="Kind=Primary" style="width: 140px; height: 40px; background-color: #2f81f7">
|
|
560
|
+
<span data-xt-name="Caption" data-xt-slot="label" style="color: #ffffff">Play</span>
|
|
561
|
+
</div>
|
|
562
|
+
<div data-xt-name="Quit" data-xt-symbol="MenuButton" data-xt-variant="Kind=Secondary"
|
|
563
|
+
style="width: 140px; height: 40px; background-color: #30363d">
|
|
564
|
+
<span data-xt-slot="label">Quit</span>
|
|
565
|
+
</div>
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
- The **first** element with a symbol name defines it: its children become the definition (a
|
|
569
|
+
`<symbol name="MenuButton">` with its own `<layout>` and `<style>` sections), and the element
|
|
570
|
+
itself becomes the first instance.
|
|
571
|
+
- Every later element with the same name is an instance: its **own** style, classes and tags
|
|
572
|
+
apply to the instance box; of its children only the `data-xt-slot` texts are read (they fill
|
|
573
|
+
the slots). Anything else inside a later instance is ignored, so write the content once.
|
|
574
|
+
- A symbol element with only text (`<button data-xt-symbol="Chip">OK</button>`) gets a `label`
|
|
575
|
+
slot automatically; each instance's text fills it.
|
|
576
|
+
- `variants=` declares the variant groups (`Kind:Primary,Secondary`; several groups separated by
|
|
577
|
+
spaces, or several `variants=` entries); `data-xt-variant` picks one per instance, which puts the
|
|
578
|
+
class `v-Kind-Primary` on the instance box. An instance's own inline style still beats a
|
|
579
|
+
`<helmet>` class rule, so the simplest variant is each instance's own colours, as above.
|
|
580
|
+
- The instance box is a `<div>`: a symbol made from a `<button>` is still clickable (triggers work
|
|
581
|
+
on any element), but give it `data-xt-trigger` for what the click does.
|
|
582
|
+
- A `data-xt-port` on the first symbol element declares a **port of the symbol** (24 §24.14.5,
|
|
583
|
+
T-566b correction): it is written to the definition's `<ports>`, and each instance sets it like
|
|
584
|
+
any `<use>` port (a plain attribute such as `<use title="…">`, or `bind:`).
|
|
585
|
+
- The symbol element's own look (background, border, radius on the element that carries
|
|
586
|
+
`data-xt-symbol`) is the instance box, not part of the definition -- a `symbol()` rule cannot
|
|
587
|
+
select it. The import copies that look onto later instances that write none of their own and
|
|
588
|
+
says so (`tag.symbolRootAppearance`, info). Put the look on an inner element when every instance
|
|
589
|
+
must share it from the definition.
|
|
590
|
+
|
|
591
|
+
### States
|
|
592
|
+
|
|
593
|
+
```html
|
|
594
|
+
<div data-xt-name="Play" ...>Play</div> <!-- Normal -->
|
|
595
|
+
<div data-xt-name="Play" data-xt-state="Hover"
|
|
596
|
+
style="... background-color: #58a6ff"></div> <!-- how it looks hovered -->
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
The state element names its Normal element with the same `data-xt-name`. Only the declarations
|
|
600
|
+
that differ from Normal are written (`#play:hover { background-color: #58a6ff }`); named children
|
|
601
|
+
of the state element restyle the Normal element's children of the same name
|
|
602
|
+
(`#play:hover #caption { ... }`). `Hover`, `Pressed`, `Focus`, `Disabled` and `Checked` are the
|
|
603
|
+
built-in states; any other name is a custom state (`:state(Selected)`) that a trigger or a binding
|
|
604
|
+
switches (`state(Selected, toggle)`, `bind:state.Low`). State elements are never drawn, and the
|
|
605
|
+
state rule never takes their **geometry**: `left`, `top`, `right`, `bottom`, `width`, `height`
|
|
606
|
+
and `transform` are left out of the difference (24 §24.14.5), so a state element may sit anywhere
|
|
607
|
+
-- a "states" strip beside the UI is fine -- without moving the Normal element. Any geometry
|
|
608
|
+
difference is reported as `tag.stateGeometry`; a state that differs only in geometry writes no
|
|
609
|
+
rule (and is not `tag.stateNoDiff`). To move or scale an element in a state, write the
|
|
610
|
+
`:hover` / `:state()` rule in `<helmet>` or animate it with a `state(<Name>).enter` timeline. A
|
|
611
|
+
state identical to Normal is reported (`tag.stateNoDiff`).
|
|
612
|
+
|
|
613
|
+
### Triggers and timelines
|
|
614
|
+
|
|
615
|
+
```html
|
|
616
|
+
<div data-xt-name="Card"
|
|
617
|
+
data-xt-timeline="pulse: 0 transform scale(1), 200ms ease-out transform scale(1.06)"
|
|
618
|
+
data-xt-trigger="hover:play(pulse); leave:play(pulse, reverse); press:state(Selected, toggle)"
|
|
619
|
+
data-xt-sound="press:ui_click">
|
|
620
|
+
```
|
|
621
|
+
|
|
622
|
+
- `data-xt-trigger`: `event:actions` pairs separated by `;`. Several actions for one event: keep
|
|
623
|
+
writing them after `;` (`press:sound(x); state(Sel, toggle)`). The events and actions are those
|
|
624
|
+
of `on:` (27 §27.2.2 / §27.2.3, 08 §8.12-§8.20):
|
|
625
|
+
|
|
626
|
+
| Event | Fires |
|
|
627
|
+
|---|---|
|
|
628
|
+
| `hover`, `leave` | the pointer enters / leaves the element |
|
|
629
|
+
| `press`, `release`, `click`, `dblclick` (`pointerdown` / `pointerup` = press / release) | the pointer; `press(right)`, `click(middle)` … pick a button |
|
|
630
|
+
| `pointermove`, `pointercancel` | every move over the element (the pressed element while a button is held); the press taken away |
|
|
631
|
+
| `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) |
|
|
632
|
+
| `outsidepress` | a press outside the element's subtree while it is visible (light-dismiss; does not bubble) |
|
|
633
|
+
| `focus`, `blur` / `focusin`, `focusout` | focus arrives / leaves; the `focusin` / `focusout` pair bubbles to the ancestors (08 §8.17) |
|
|
634
|
+
| `check`, `uncheck`, `change`, `input` | a checkbox; an `<input>` edit |
|
|
635
|
+
| `show`, `hide` | the element (or, on the root, the screen) is shown / asked to hide |
|
|
636
|
+
| `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) |
|
|
637
|
+
| `back` | the gamepad's B / Circle button (08 §8.9) |
|
|
638
|
+
| `scroll` | the scroll offset of a scroll container changed |
|
|
639
|
+
| `port(<name>)` | the port's value changed |
|
|
640
|
+
| `timeline(<name>).end`, `timeline(<name>).marker(<m>)` | a timeline finished / reached a marker |
|
|
641
|
+
| `state(<Name>).enter`, `.exit` | a custom state turned on / off |
|
|
642
|
+
| `drag.start`, `drag.over`, `drag.leave`, `drop`, `drag.cancel` | drag and drop (`draggable`, `drop-target`) |
|
|
643
|
+
|
|
644
|
+
| Action | Does |
|
|
645
|
+
|---|---|
|
|
646
|
+
| `play(<timeline>[, reverse\|loop\|once\|hold][, from=<marker>])` | plays a timeline of this scope (default: once, holding the last frame) |
|
|
647
|
+
| `stop(<timeline>)`, `seek(<timeline>, <time\|marker>)` | |
|
|
648
|
+
| `pause(<timeline>)`, `resume(<timeline>)` | pauses / continues a playing timeline (27 §27.8, T-573) |
|
|
649
|
+
| `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) |
|
|
650
|
+
| `class(<name>[, on\|off\|toggle])` | a class of the element |
|
|
651
|
+
| `show()`, `hide()`, `then hide` | the trigger's **own** element (no argument: `hide(#x)` is an error; use `state(…, target=#x)` plus a `:state()` rule) |
|
|
652
|
+
| `layer(overlay)`, `layer(normal)` | lifts the element into the overlay layer (out of a parent's `overflow: hidden`) and back |
|
|
653
|
+
| `consume()` | only in `outsidepress`: that press reaches nothing else (no press, release or click below; 08 §8.15) |
|
|
654
|
+
| `focus()`, `focus(<id>)` | focuses the element itself / another element |
|
|
655
|
+
| `set(<port>, <value>)`, `emit(<port>)` | writes a port / sends an event (see **Ports and bindings**) |
|
|
656
|
+
| `sound(<cue>[, volume])`, `haptic(<cue>)` | host cues |
|
|
657
|
+
| `reset(value)` | re-applies `bind:value` on an `<input>` |
|
|
658
|
+
| `spawn(<symbol>, at=…, lifetime=…)` | a short-lived instance (damage numbers) |
|
|
659
|
+
| `if <cond> <action> [else <action>]` | comparisons of the converter catalogue only |
|
|
660
|
+
|
|
661
|
+
`set()` values: a number, `true` / `false`, `toggle` (bool ports), a **quoted** string
|
|
662
|
+
(`set(lang, 'zh')`; a bare word is a compile error), `event.value`, `value` (an `<input>`'s text),
|
|
663
|
+
`pointer.fraction(#id).x` / `pointer.local(#id).y` (pointer triggers), `port(<name>)` (another port
|
|
664
|
+
of the same scope), or inside a repeat template `item(<field>)` / `repeat.index`; all but `toggle`
|
|
665
|
+
may go through converters, and a chain must start with one of these heads -- write
|
|
666
|
+
`set(is_zh, port(lang) | eq('zh'))`, not `set(is_zh, lang | eq(zh))` (27 §27.2.3, T-411 record).
|
|
667
|
+
- `data-xt-timeline`: `name: <time> [<easing>] <property> <value>, ...`; several timelines
|
|
668
|
+
separated by `;`. A time without a unit is ms (`0`, `400`, `400ms`, `0.4s`); easings as in
|
|
669
|
+
**Animation**; properties are CSS names (`opacity`, `transform`, `background-color`, …). The same
|
|
670
|
+
timeline name on several elements is **one** timeline with a track per element (a staggered
|
|
671
|
+
intro: `intro: 0 opacity 0, 300 opacity 1` on the title, `intro: 150 opacity 0, 450 opacity 1` on
|
|
672
|
+
the menu). `name loop:` makes every plain `play(name)` loop. The editor's operations take
|
|
673
|
+
seconds (`xtui-editor` `ops.md` has the table): `400` here is `0.4` there.
|
|
674
|
+
- **The base style is what shows when no timeline plays** -- in the editor with autoplay off,
|
|
675
|
+
before a trigger plays the timeline, on a host that never plays it -- not the timeline's value
|
|
676
|
+
at 0 s. A layer that only appears later in a timeline must be invisible in its own style
|
|
677
|
+
(`opacity: 0` in its `style`) as well as at the timeline's first key; otherwise every layer of
|
|
678
|
+
every shot shows at once.
|
|
679
|
+
- `data-xt-timeline-from-animations="intro 15s once markers"`: write the motion as ordinary CSS
|
|
680
|
+
(`@keyframes` plus `animation: <name> 15s <easing> infinite both` / `animation-delay`, every
|
|
681
|
+
element on the same cycle) and let the import turn it into one controllable timeline. Each
|
|
682
|
+
`@keyframes` stop at p% becomes a key at `delay + p x duration` (iterations and `alternate`
|
|
683
|
+
expanded); the length is the seconds given, else the longest `delay + duration`; `loop` (default)
|
|
684
|
+
plays it on show in a loop, `once` plays it once and holds, `none` leaves playing to a trigger;
|
|
685
|
+
`markers` adds a marker where each layer first appears. An animation that does not fit (a cycle
|
|
686
|
+
that does not divide the length, `reverse`, a property a timeline cannot key, a class shared with
|
|
687
|
+
an element outside the tag, a `:hover` or `@media` rule) stays as it was, with a
|
|
688
|
+
`timeline.animationKept` finding that says why. `xtframe-import dc ... --animations-to-timeline
|
|
689
|
+
intro,15s,once` does the same for the board root.
|
|
690
|
+
- A trigger that plays a timeline no element declares is dropped and reported
|
|
691
|
+
(`tag.triggerWithoutTimeline`); timelines inside a symbol are the symbol's own.
|
|
692
|
+
- Convention names: `intro` (with `show:play(intro)`), `outro` (`hide:play(outro) then hide`),
|
|
693
|
+
`hover-in`, `hover-out`, `idle`.
|
|
694
|
+
|
|
695
|
+
### Ports and bindings
|
|
696
|
+
|
|
697
|
+
```html
|
|
698
|
+
<div id="hud" data-xt-port="hp:number in; hp_max:number in; fire:event out" ...>
|
|
699
|
+
<div data-xt-name="HpFill" data-xt-bind="width=hp|range(0,hp_max,0%,100%)"></div>
|
|
700
|
+
<span data-xt-name="HpText" data-xt-bind="text=format('{0}/{1}', hp, hp_max)">75/100</span>
|
|
701
|
+
<div data-xt-name="Fire" data-xt-trigger="click:emit(fire)">Fire</div>
|
|
702
|
+
</div>
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
- A port is the game's value (`in`), an event or value the UI sends (`out`), or a call (`call`).
|
|
706
|
+
Types: `number`, `string`, `bool`, `color`, `vec2`, `vec3`, `entity`, `enum(a|b)` (values
|
|
707
|
+
separated by `|`; `enum(a,b)` is an error, 27 §27.3.1), `list<T>`, `texture`, `event`. A default
|
|
708
|
+
follows `=`: `mode:enum(low|mid|high) in = mid`. Ports of the board go to the UI's `<ports>`
|
|
709
|
+
whatever element carries the tag (`mode: enum(low|mid|high) in = mid`, one line each); inside a
|
|
710
|
+
symbol definition they are the symbol's own `<ports>`. A flow addresses them as
|
|
711
|
+
`#document.<port>` (`references/flow.md`).
|
|
712
|
+
- **Bind from `in` ports.** A binding reads what the game (or a flow) writes into an `in` port. A
|
|
713
|
+
binding whose source is an `out` port is a warning (`bind.outPortSource`, 27 §27.8 and the T-568
|
|
714
|
+
/ T-573 records); it does update when the host writes that port with `setPort`, or when a flow's
|
|
715
|
+
`emit` node sends to it, but nothing else feeds it. Copy a value between the
|
|
716
|
+
two directions with `set()` (`port(hp):set(hp_shown, port(hp))`).
|
|
717
|
+
- Bind targets: a CSS property, `text`, `src`, `visible`, `display`, `state.<Name>`,
|
|
718
|
+
`class.<name>`, `variant.<Prop>`, `checked`, `translate-x`/`-y`, `scale-x`/`-y`, `rotate`.
|
|
719
|
+
Converters: `range`, `clamp`, `round`, `floor`, `ceil`, `lt`/`gt`/`between`, `not`, `format`,
|
|
720
|
+
`thousands`, `percent`, `time(mm:ss)`, `select(...)`, `step(...)`, `lerpColor`, `fromToken`,
|
|
721
|
+
`localize`, `glyph(action)`, `tween(...)`.
|
|
722
|
+
- Converter arguments may be chains (03 §3.12.11, T-585): `format('{0} / {1}', hp | round(0),
|
|
723
|
+
hp_max | thousands)`, and likewise in `select()`, `step()` and `lookup()`; a sub-chain reads the
|
|
724
|
+
outer chain's input or starts with its own `port(<name>)`; nesting goes 4 deep. A bound length
|
|
725
|
+
may hold a static `calc()` (T-586): `bind:width="flag | select(calc(100% - 48px), 0px)"` is
|
|
726
|
+
evaluated at run time like a declared `calc()` (`%`, `vw`, `em` and the parent's size follow
|
|
727
|
+
the viewport); a `calc()` that reads a port (`calc(port(x) + 10px)`) is not evaluated
|
|
728
|
+
(`bind.calcNotEvaluated`) -- convert the port with `range()` instead.
|
|
729
|
+
- What the compiler warns about (27 §27.8): a bare converter argument that
|
|
730
|
+
is both an enum value and a port name (`bind.enumPortName`: quote it, `eq('low')`, to mean the
|
|
731
|
+
value). The lint reports an element that binds `display` / `visible` but writes `display: none`
|
|
732
|
+
/ `visibility: hidden` itself (`tag.boundDisplayInlineNone`: true only restores the element's own
|
|
733
|
+
style, so it stays hidden) -- hide it with the port's default instead.
|
|
734
|
+
- A number bound to `text` prints with 6 significant digits (`%.6g`, the flow's rule, 53 §53.4.9):
|
|
735
|
+
`123.45`, not `123.450003`; an integer of 1,000,000 or more prints as `1e+06`, so use
|
|
736
|
+
`thousands` or `fixed(0)` for scores (T-568 record).
|
|
737
|
+
- Binding a port that is not declared fails the import (the compiler refuses it); a declared port
|
|
738
|
+
nothing binds, triggers on or emits is reported (`tag.portUnbound`).
|
|
739
|
+
- Keep the literal value on the board (`75/100`, `width: 75%`) so the board still looks right.
|
|
740
|
+
Use `{{hole}}` only when there is no port for it yet.
|
|
741
|
+
|
|
742
|
+
### Lists (`data-xt-repeat`)
|
|
743
|
+
|
|
744
|
+
```html
|
|
745
|
+
<div id="hud" data-xt-port="items:list<struct{title: string}> in">
|
|
746
|
+
<div data-xt-name="Rows" data-xt-repeat="items" style="display: flex; flex-direction: column">
|
|
747
|
+
<span data-xt-name="Title" data-xt-bind="text=item(title)">First entry</span>
|
|
748
|
+
</div>
|
|
749
|
+
</div>
|
|
750
|
+
```
|
|
751
|
+
|
|
752
|
+
The element becomes `<repeat port="items">` and its **first child element** is the template every
|
|
753
|
+
entry copies (24 §24.14.5, T-566b record; 27 §27.3.4). Further children and loose text are dropped
|
|
754
|
+
with a warning, so draw one entry, not three. Bindings inside the template read the entry with
|
|
755
|
+
`item(<field>)`, `item()`, `index`, `count` and `outer.` (nested repeats); a binding there that
|
|
756
|
+
reads none of them is reported (`tag.repeatBinding`). Inside another template the value may be
|
|
757
|
+
`item(<field>)` for a nested list.
|
|
758
|
+
|
|
759
|
+
### Localization keys (`data-xt-key`)
|
|
760
|
+
|
|
761
|
+
`<span data-xt-key="menu_title">Main menu</span>` imports as the key `@menu_title`; the board's
|
|
762
|
+
text is only the preview. A key is `[A-Za-z_][A-Za-z0-9_-]*` -- **no dots** (`menu.title` is a
|
|
763
|
+
finding and the text stays literal); only a text element (no child elements) can carry one
|
|
764
|
+
(24 §24.14.5, 07 §7.8). Any other text that starts with `@` stays literal text. The strings come
|
|
765
|
+
from the host at run time (see `references/not-like-web.md`, **Language**).
|
|
766
|
+
|
|
767
|
+
### Tokens, anchors, roles, glyphs
|
|
768
|
+
|
|
769
|
+
- `data-xt-token="accent"` replaces the element's `color` (or, without one, its `background`)
|
|
770
|
+
with `var(--accent)`, so a theme can change it; `data-xt-token-prop="border-color"` names any
|
|
771
|
+
other colour property. The token must exist in the tokens (see **Colors, type, spacing**); an
|
|
772
|
+
unknown one is a warning and the literal stays.
|
|
773
|
+
- `data-xt-anchor="bottom-left"` pins the element to the safe area: `anchor: left bottom` in the
|
|
774
|
+
UI's `<layout>`, the board's px distance from each named edge as `offset`, the opposite edges
|
|
775
|
+
dropped. `safe` pins all four edges (`anchor: stretch stretch`); `center` leaves that axis
|
|
776
|
+
alone. A px offset the board gave a pinned edge uses the automatic anchoring's formula, so both
|
|
777
|
+
forms give the same result for the same board numbers (24 §24.14.2 item 4; `safe_px` = the UI
|
|
778
|
+
Project's `spec.safeArea` default -- 2.5% without a project -- x the board's width for
|
|
779
|
+
left/right, x its height for top/bottom; 2.5% of 1280 x 720 = 32 px / 18 px):
|
|
780
|
+
|
|
781
|
+
| board | automatic (edge within 25%) and `data-xt-anchor` |
|
|
782
|
+
|---|---|
|
|
783
|
+
| `left: 24px; bottom: 24px; width: 100px; height: 20px` | `anchor: left bottom; offset: -8px 6px; size: 100px 20px` |
|
|
784
|
+
| `right: 24px; top: 24px` | `anchor: right top; offset: -8px 6px` |
|
|
785
|
+
| `left: 0; top: 0; right: 0; bottom: 0` with `data-xt-anchor="safe"` | `anchor: stretch stretch; offset: -32px -18px` |
|
|
786
|
+
| formula | `offset` = board px - `safe_px` per axis (0 = exactly on the safe-area edge) |
|
|
787
|
+
| 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)` |
|
|
788
|
+
|
|
789
|
+
Use it for everything a TV or a phone notch must not cut. Re-importing an older project whose
|
|
790
|
+
`data-xt-anchor` elements carry px offsets changes those numbers to this formula (T-564 record).
|
|
791
|
+
The tag wins over the import's automatic anchoring (see **Board setup**): tag an element whose
|
|
792
|
+
nearest board edge is not the one it belongs to.
|
|
793
|
+
- `data-xt-role="hud-health"` is kept as `data-role` for layout templates and the lint.
|
|
794
|
+
- `data-xt-glyph="jump"` makes the element a button glyph for the `jump` action; its own text is
|
|
795
|
+
ignored. Inside `data-xt-rich` text, `<span data-xt-glyph="jump"></span>` is an inline glyph.
|
|
796
|
+
- `data-xt-editor-only` (bare) marks a reference the artist works over, such as a game screenshot
|
|
797
|
+
under a HUD that has no background: `<img src="references/game-shot.png" data-xt-editor-only>`.
|
|
798
|
+
It is imported as `editor-only`; the editor canvas shows it, the Demo space and the published
|
|
799
|
+
bundle do not (its whole subtree goes, and an image only it uses is not packed). Never give it
|
|
800
|
+
an id a trigger, binding or flow needs: the published UI has no such element.
|
|
801
|
+
|
|
802
|
+
### Rich text
|
|
803
|
+
|
|
804
|
+
```html
|
|
805
|
+
<span data-xt-name="Hint" data-xt-rich>Press <b>Esc</b> to <i>leave</i>,
|
|
806
|
+
<span style="color: #da3633">now</span></span>
|
|
807
|
+
```
|
|
808
|
+
|
|
809
|
+
Without `data-xt-rich` every text run beside an element becomes its own `<span>` layer. With it,
|
|
810
|
+
the text stays **one** layer with styled runs. Allowed inside: `<b>`/`<strong>`, `<i>`/`<em>`,
|
|
811
|
+
`<span style class>` (a run takes `color`, `font-size`, `font-weight`, `font-style`,
|
|
812
|
+
`letter-spacing`; other properties are dropped with a warning), `<img>` (an inline image; give it a
|
|
813
|
+
`height`), `<span data-xt-glyph>` and `<br>` (a space). Whitespace-only gaps between two inline
|
|
814
|
+
elements are dropped, so write `</b> or <span…>` with a word between rather than a bare space.
|
|
815
|
+
|
|
816
|
+
|
|
817
|
+
## 3D HUD
|
|
818
|
+
|
|
819
|
+
3D is what XTFrame is for, and it imports faithfully. The shape that works:
|
|
820
|
+
|
|
821
|
+
```html
|
|
822
|
+
<div id="hud" style="position:relative; width:1280px; height:720px; perspective: 1400px;
|
|
823
|
+
perspective-origin: 50% 50%">
|
|
824
|
+
<div id="panel-left"
|
|
825
|
+
style="position:absolute; left:80px; top:140px; width:360px; height:440px;
|
|
826
|
+
transform-origin: 100% 50%;
|
|
827
|
+
transform: rotateY(18deg) translateZ(-40px);
|
|
828
|
+
background-color:#161b22e6; border:1px solid #30363d; border-radius:12px;
|
|
829
|
+
animation: sway 6s ease-in-out 0s infinite alternate">
|
|
830
|
+
</div>
|
|
831
|
+
</div>
|
|
832
|
+
```
|
|
833
|
+
|
|
834
|
+
```css
|
|
835
|
+
@keyframes sway {
|
|
836
|
+
from { transform: rotateY(16deg) translateZ(-40px); }
|
|
837
|
+
to { transform: rotateY(20deg) translateZ(-40px); }
|
|
838
|
+
}
|
|
839
|
+
```
|
|
840
|
+
|
|
841
|
+
- Put `perspective` (and `perspective-origin`) on the **container**, never on the panel itself.
|
|
842
|
+
- Give each panel a `transform-origin` on its hinge edge (`100% 50%` for a panel on the left,
|
|
843
|
+
`0% 50%` on the right) so it opens like a door instead of spinning in place.
|
|
844
|
+
- Keep the idle `sway` small (2–4°) and make every keyframe list the same transform functions.
|
|
845
|
+
- Flip cards: `backface-visibility: hidden` on both faces works under a parent that rotates
|
|
846
|
+
(`rotateY(0 -> 180deg)`): the back is judged on the **composed** transform, so at 180deg the front
|
|
847
|
+
is culled and the back shows (18 §18.13, T-572). Hit testing does not follow yet: the face turned
|
|
848
|
+
away can still be clicked, so switch `pointer-events` (a state or class) with the flip.
|
|
849
|
+
- `world-layer: on` on a panel only matters on a layered host (a game engine placing UI layers in
|
|
850
|
+
its 3D world); the board and every flat view draw it like any other element. It is not the same
|
|
851
|
+
as having a 3D `transform`, and it is written as a plain style (`world-layer: on`), never animated.
|
|
852
|
+
- **Do not try to author pointer parallax on the board.** Author the resting angle you want; the
|
|
853
|
+
lean is a `pointermove` trigger writing a port plus `bind:rotate-y` on the panel (the flow step of
|
|
854
|
+
`xtui` only wires logic; see `references/flow.md` Rules).
|
|
855
|
+
|
|
856
|
+
## Flow bindings
|
|
857
|
+
|
|
858
|
+
Reach for the intent tags first (`data-xt-trigger`, `data-xt-timeline`, `data-xt-bind`,
|
|
859
|
+
`data-xt-port`); a `.xtflow` is for logic that spans UIs or needs computation (counters, timers,
|
|
860
|
+
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
|
|
861
|
+
changes, so nothing can bind to it safely.
|
|
862
|
+
|
|
863
|
+
- Name ids by role: `diff-veteran`, `stat-damage-fill`, `btn-start`, `world-layer`.
|
|
864
|
+
- A bar is two elements: a track with `overflow: hidden` and a fill whose `width` (or
|
|
865
|
+
`transform: scaleX()`) the flow sets.
|
|
866
|
+
- Wrap anything that gets shown and hidden in its own `<div>`, and give the wrapper the id.
|
|
867
|
+
- Give a group's container an id as well, so a flow can restyle the whole group at once.
|
|
868
|
+
- States belong in classes (see above); the flow only toggles the class or state.
|
|
869
|
+
|
|
870
|
+
## Prototype links
|
|
871
|
+
|
|
872
|
+
`<a href="Other.dc.html">` navigation is recorded as a hint for the game (which screen a button
|
|
873
|
+
leads to) but not executed; keep the element a `<button>` with an `id`. A `data-xt-trigger` with a
|
|
874
|
+
`click` or `press` event on the same element wins: the link is then ignored.
|