@xtframe/skills 0.18.0 → 0.19.2

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xtframe/skills",
3
- "version": "0.18.0",
3
+ "version": "0.19.2",
4
4
  "description": "Search for XTFrame agent skills and install them, with the XTFrame converter, into every coding agent on this machine (Claude Code, Codex, Gemini CLI, Copilot, Cursor, OpenCode, ...).",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xtframe",
3
- "version": "0.18.0",
3
+ "version": "0.19.2",
4
4
  "description": "XTFrame game UI skills: make a UI from a board (xtui) and change a UI open in the XTFrame editor (xtui-editor).",
5
5
  "author": {
6
6
  "name": "XTFrame"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xtframe",
3
- "version": "0.18.0",
3
+ "version": "0.19.2",
4
4
  "description": "XTFrame game UI skills: make a UI from a board (xtui) and change a UI open in the XTFrame editor (xtui-editor).",
5
5
  "skills": "./skills/",
6
6
  "interface": {
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "xtframe",
3
- "version": "0.18.0",
3
+ "version": "0.19.2",
4
4
  "description": "XTFrame game UI skills: make a UI from a board (xtui) and change a UI open in the XTFrame editor (xtui-editor)."
5
5
  }
@@ -30,6 +30,7 @@ before doing the step**, not after.
30
30
  | `references/upgrade.md` | bringing an existing UI Project up to the current rules: backup, board fixes, flow generator, `--force` / `--prune`, verify, what to leave alone |
31
31
  | `references/vector.md` | icons, gauges and shapes as inline `<svg>` vector layers: the subset, ids, token colours, `#Svg/Shape` rules, path-trim / hover examples |
32
32
  | `references/performance.md` | the board has shadows, filters, backdrop blurs, large animated elements or many images, and before a publish: what costs on the GPU (cheap shadows, effect layers and animated size, `publish.images.compress`, 1x antialiasing, hiding) |
33
+ | `references/from-procedural.md` | the source computes its values from the time every frame (a web page, a Claude Design canvas with script, a motion-graphics file): which board CSS -- or which editor expression after the import -- does each kind of motion, each with an example to copy |
33
34
  | `references/style-groups.md` | the editor's style names (Fill, Stroke, Corners, Opacity & Blend, ...) and the CSS properties each covers: talk to the user in style names, write CSS on the board (generated; the dialect is unchanged) |
34
35
 
35
36
  The user never has to know the dialect, pick a tool or fix a lint finding. Compliance is your job:
@@ -155,12 +156,38 @@ Use `{{hole}}` only where the game supplies the value, always with a `data-props
155
156
  are `<img src="/_blob/<file>">` with the file in `<dump>/_blob/`. Keep the dump: it is how the UI
156
157
  changes later.
157
158
 
159
+ ## 1c. Converting an existing work: the conversion list (required)
160
+
161
+ When the source is an existing work -- a web page, a Claude Design canvas, a video storyboard, a
162
+ UI from another engine -- **convert everything it shows**, and before you deliver, show the user a
163
+ table with one row per motion and per effect of the source:
164
+
165
+ | Source (what moves or shows) | Result | Why / evidence |
166
+ |---|---|---|
167
+ | title logo bobs before the hit | done | -- |
168
+ | speed lines (`repeating-conic-gradient` + `mask-image`) | done differently: inline SVG wedges turned with `steps()` | the import drops both (`repeating-conic-gradient is not one of the gradients ...; dropped`); the lines are regular, the source's vary in length |
169
+ | music drives the timing | not done: engine does not support | a board has no audio element (`dialect.md`, **Allowed elements**); a timeline cannot follow an audio clock -- only a `sound()` cue to the host |
170
+
171
+ `Result` is one of: `done`, `done differently (what differs)`, `not done (reason)`. A reason is
172
+ one of exactly three, each with its evidence:
173
+
174
+ - `engine does not support` -- the importer's or compiler's message, or the reference line that
175
+ says so;
176
+ - `measured too slow` -- the number you measured (`xtframe-view --perf`, `references/performance.md`);
177
+ - `the user agreed to leave it out`.
178
+
179
+ "Might be slow", "might break" and "too much work" are **not** reasons you may decide on: write it
180
+ first (`references/from-procedural.md` has the patterns, `references/dialect.md` what imports); if
181
+ it really fails, put the message or the number in the table. Never mark something unsupported that
182
+ you did not try or look up.
183
+
158
184
  ## 2. Verify and open the editor
159
185
 
160
186
  Convert mode: read `references/verify.md` and follow it step by step on `<dump>`: lint, import
161
187
  into `<project-dir>`, compile every UI, headless screenshot, report the degradations and missing
162
188
  ids. Its last step opens `<project-dir>` (its `<name>.xtui`) in `xtframe-editor` in the
163
- background. Every entry ends there; finish with the UI Project path and "editor opened".
189
+ background. Every entry ends there; finish with the UI Project path and "editor opened" -- and,
190
+ for a converted work, the conversion list of section 1c.
164
191
 
165
192
  Deliver mode: follow `references/verify.md` "Deliver mode" instead -- self-check the board against
166
193
  `references/dialect.md`, package the dump, and finish with the dump path plus the one command the
@@ -26,8 +26,9 @@ is written as a local board instead (SKILL.md, entry 1).
26
26
  5. Read it back into a local dump with the steps of (b) below, then go to `references/verify.md`.
27
27
 
28
28
  When the user later changes the board on the canvas, repeat step 5 into the **same** dump and the
29
- same UI Project directory; the re-import keeps hand edits and the `.xtflow` (see **(c)** below and
30
- `references/verify.md` step 3).
29
+ same UI Project directory; the re-import keeps hand edits and a hand-edited `.xtflow` (a flow the
30
+ import generated and nobody edited follows the board; see **(c)** below and `references/verify.md`
31
+ step 3).
31
32
 
32
33
  ## (c) Round trip: re-import, and carry editor changes back to the canvas
33
34
 
@@ -36,9 +37,11 @@ what the editor changed; nothing is synced live.
36
37
 
37
38
  - **Keep layers findable.** A re-import pairs every layer by its `data-xt-name` (or `id`) first,
38
39
  then, for unnamed ones, by position, size, order, nesting and text. When more than 20% of the old
39
- layers cannot be found again, it refuses to merge (`fallback: "one-way"`, exit 3). So when you
40
- write or fix a board, give every layer that matters a `data-xt-name` or an `id`, and never rename
41
- one the editor already knows.
40
+ layers cannot be found again, it refuses to merge (`fallback: "one-way"`, exit 3). With `--prune`
41
+ the layers that are gone from the board do not count (only low-confidence pairings do), so when
42
+ layers were removed from the board on purpose, re-run with `--prune`. So when you write or fix a
43
+ board, give every layer that matters a `data-xt-name` or an `id`, and never rename one the editor
44
+ already knows.
42
45
  - **Editor changes back to the canvas.** Before re-importing a canvas the user also changed, ask
43
46
  the importer what the editor side changed since the last import:
44
47
 
@@ -275,12 +275,51 @@ DOM only exists in the browser, so they are dropped), and `<sc-for>` / `<sc-if>`
275
275
  `grayscale()`, `hue-rotate()`, `invert()`, `sepia()`, `opacity()` and `drop-shadow()`.
276
276
  The colour functions merge into one adjustment applied in a fixed order (brightness, contrast,
277
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.
278
+ only once. Every other filter function is dropped. XTFrame's own `brightness` is additive and
279
+ `hue-rotate()` is a YIQ hue rotation (18 §18.3), so a `hue-rotate()` that changes anything is
280
+ reported as `degraded`, and an out-of-range `contrast`/`saturate` is clamped with a finding
281
+ (24 §24.15.4, T-566a/b records).
282
+ - **`filter: brightness()` is converted to look the same as on the web** (18 §18.13 amendment,
283
+ T-824). The import composes the `brightness()` and `contrast()` of one `filter` in the order
284
+ written and writes them as a `contrast` + `brightness` pair: `brightness(0.4)` becomes
285
+ `color-adjust(contrast(-0.6) brightness(-0.75))`, which is CSS's `0.4 * colour`. Between
286
+ `brightness(1/3)` and `brightness(2)` the result matches the web with no finding (the editor's
287
+ panel then shows those two numbers, not the one you wrote). Outside that range:
288
+ `brightness(0)` is black, exact; below 1/3 white stays exact but dark tones turn black sooner than
289
+ on the web (`degraded: below 1/3 the dark tones turn black sooner ...`) -- for a strong dim put
290
+ a black element over it with `opacity` = 1 - the value instead (`brightness(0.2)` -> a black
291
+ overlay at `opacity: 0.8`); above 2 it is clamped to `brightness(2)` with a finding. A `filter`
292
+ that also holds `invert()`, `sepia()` or `opacity()` keeps the old additive conversion
293
+ (`brightness(0.4)` adds -0.6, so a dark background goes black) and says so as `degraded` --
294
+ keep `brightness()` out of such a `filter`. `backdrop-filter: brightness()` is still additive
295
+ with the same finding (`backdrop-blur` has no contrast): do not dim a backdrop with it.
296
+ `brightness()` and `drop-shadow()` in one `filter` work and may be keyed together (a silhouette
297
+ revealed with a rim light): every key lists both, in the same order; the rim light does not
298
+ darken with the brightness. Check such an element in a screenshot.
299
+ - `clip-path` with `inset()`, `circle()`, `ellipse()` or `polygon()` is supported **statically**
300
+ (a diagonal split screen: two layers with `polygon(0 0, 58% 0, 42% 100%, 0 100%)` and its
301
+ complement). It **cannot be animated**: a `clip-path` in a keyframe or a transition is dropped
302
+ with `"clip-path" is not animatable; ignored`. A circle that closes on the centre (an iris out)
303
+ is done instead with either (a) a ring -- a round element with a very thick border in the cover
304
+ colour whose `width` / `height` animate to 0:
305
+
306
+ ```html
307
+ <style> @keyframes iris-close { from { width: 2400px; height: 2400px } to { width: 0px; height: 0px } } </style>
308
+ <div id="iris" style="position: absolute; left: 50%; top: 50%; width: 2400px; height: 2400px;
309
+ box-sizing: content-box; border: 2400px solid #000000; border-radius: 50%;
310
+ transform: translate(-50%, -50%); animation: iris-close 2s linear 0s 1 both"></div>
311
+ ```
312
+
313
+ or (b) an inline SVG over the screen: one black path, a huge rectangle with a circular hole
314
+ (`fill-rule="evenodd"`), its `transform` keyed from `scale(1)` to `scale(0.001)` around the
315
+ centre (`transform-origin: 50% 50%`).
316
+ - `repeating-conic-gradient` and `mask-image` are not supported: the import drops them with
317
+ `repeating-conic-gradient is not one of the gradients 05 §5.5c has; dropped` and `property
318
+ mask-image is not in the XTFrame style subset (05 §5.4); dropped`. A radial or linear fade-out
319
+ mask is the `gradient-mask` effect after the import (`catalog_add {"id": "gradient-mask"}` in the
320
+ editor). Radial speed lines need neither: an inline SVG of thin solid triangles around a centre
321
+ (each tip 30-50 % of the radius out, so the centre stays clear), turned a few degrees with a
322
+ `steps()` easing (`animation: jitter 1s steps(24) infinite`) for the flicker.
284
323
  - `backdrop-filter: blur(<px>) [saturate(<n>)] [brightness(<n>)]` — frosted glass. It becomes
285
324
  XTFrame's `effect: backdrop-blur(…)`, which blurs whatever is painted **below** the element (the
286
325
  game world included). `blur()` is required; any other backdrop function drops the declaration
@@ -307,7 +346,13 @@ DOM only exists in the browser, so they are dropped), and `<sc-for>` / `<sc-if>`
307
346
  (24 §24.14.5). `object-position` and `mask-image` / `-webkit-mask-image` have no XTFrame
308
347
  property: the import renames the prefixed one and reports both as unsupported (a gradient mask is
309
348
  18's `effect: gradient-mask()`). A `background-image: url(/_blob/…)` is moved into the project
310
- like an `<img>`'s blob.
349
+ like an `<img>`'s blob. Image formats the runtime decodes (on every renderer, and mirrored
350
+ builds alike): PNG, JPEG, GIF (first frame), BMP, TGA, PSD, HDR, PIC, PNM and DDS. Anything
351
+ else -- WebP above all, also AVIF, HEIF/HEIC, JPEG XL, TIFF, QOI -- draws as nothing: the import
352
+ copies the file as it is and reports `asset.undecodable`, `xtframe-compile` warns
353
+ `image asset "<path>": format <fmt> cannot be decoded (supported: …)` (an error under
354
+ `--strict`) and the editor's lint says `asset.undecodable`. The format is told by the file's
355
+ bytes, not its extension. Convert such images to PNG or JPG before the import.
311
356
  - `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
357
  - `text-decoration` and `text-decoration-line/color/thickness` are kept: `underline`, `overline`,
313
358
  `line-through` (several at once allowed); other line styles (`dotted`, `wavy`, …) are drawn solid
@@ -320,8 +365,9 @@ DOM only exists in the browser, so they are dropped), and `<sc-for>` / `<sc-if>`
320
365
  - `font-variant-numeric: tabular-nums` (inherited) gives every figure the same width, for counters
321
366
  and timers that change; `normal` switches it off again. Other values are dropped with a warning.
322
367
  - 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
368
+ keeps a subtree out of the project's scale policy (factor 1: 1 px stays 1 px, like CSS px) when the
369
+ game resolution changes (crosshairs, pixel icons, 1 px lines; pair pixel icons with
370
+ `image-rendering: pixelated`), `ui-scale: clamp(<min>, <max>)` limits
325
371
  how far the subtree follows the project's scale, `ui-scale: auto` (the default) follows it. px,
326
372
  em, font sizes, borders, radii and shadows follow the factor; `%`, `vw`/`vh` and `uiscale` units
327
373
  do not. `media-override: show | hide` stops `@media` rules from switching the subtree's `display`
@@ -387,8 +433,15 @@ transition: <prop|all> <duration> [<easing>] [<delay>]
387
433
  - Time units `s` / `ms`. Easing: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`,
388
434
  `cubic-bezier(a,b,c,d)` or `steps(n[, start|end])`. Numbers **may** omit the leading zero
389
435
  (`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.
436
+ - The eight longhands (`animation-name`, `-duration`, `-timing-function`, `-delay`,
437
+ `-iteration-count`, `-direction`, `-fill-mode`, `-play-state`) work as in CSS: each one cascades
438
+ on its own, so a `:hover` or class rule can change only the `animation-play-state` or
439
+ `animation-delay` of the animation a base rule names (`.card { animation: pulse 1s }`
440
+ `.card:hover { animation-play-state: paused }`), and lists combine by `animation-name`'s length.
441
+ Each longhand is a style property of its own (a whole-value `var()` works), so any rule that
442
+ matches the element can change one of them; the `transition-*` longhands work the same way.
443
+ `animation-composition`, `animation-timeline` and `animation-range` are not supported; the import
444
+ drops them with a finding.
392
445
  - Declarations inside a `@keyframes` block in `<helmet><style>` are converted like any other
393
446
  (`filter`, `box-shadow`, `text-shadow`, `backdrop-filter`, `var()`), so animate them as you
394
447
  would in a browser. Every keyframe of a rule must list the same `transform` functions and the
@@ -410,19 +463,31 @@ transition: <prop|all> <duration> [<easing>] [<delay>]
410
463
  `t < 0.5 ? a : b`; 05 T-229 note). To switch at an exact time, add a key with the old value just
411
464
  before the switch (`390 visibility visible, 400 visibility hidden`), so the segment is 10 ms long.
412
465
  - Naming a `@keyframes` that does not exist is a compile error, not a warning.
466
+ - Accepted and drawn right (each tried in a converted project): `filter: grayscale(0)` to
467
+ `grayscale(1)` keyed (a freeze frame going grey); `brightness()` and `drop-shadow()` keyed
468
+ together in one `filter` (each key's `brightness()` is converted on its own: the keys match the
469
+ web, the frames between them are slightly darker, since the pair is not linear in the factor); a looping `@keyframes` animation on the child of an element a timeline
470
+ moves; `steps()` with large step counts; a whole-shot `filter: blur(18px)` to `blur(0px)` on a
471
+ sliding container (a whip pan). Procedural motion of every kind: `references/from-procedural.md`.
413
472
 
414
473
  ## Icons and vectors
415
474
 
416
475
  Inline `<svg>` with `path/rect/circle/ellipse/line/polygon`, `viewBox`, solid **or gradient** fills
417
476
  and strokes — a `<linearGradient>`/`<radialGradient>` in `<defs>` referenced by `fill="url(#id)"`
418
477
  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
478
+ `<filter>`, `<mask>` or `<pattern>` inside SVG (`fill="url(#p)"` on a `<pattern>` paints black).
479
+ Gradients must be defined inside the same `<svg>` that uses them; `fx`/`fy` (focal point),
480
+ `spreadMethod="reflect|repeat"`, and a radial gradient stretched into an ellipse (a non-uniform
481
+ or skewed `gradientTransform`, or `objectBoundingBox` on a non-square shape) are not supported:
482
+ the centre, pad and a circle are used, with a warning. Linear gradients follow any
483
+ `gradientTransform` (skew, non-uniform scale) and a diagonal `objectBoundingBox` gradient on a
484
+ non-square shape as browsers draw them, and `objectBoundingBox` x `gradientTransform` is applied in
485
+ SVG's order for both kinds (T-829, T-830). Or upload a PNG. An inline `<svg>` is imported as
420
486
  an editable vector layer (T-224); `data-xt-vector="file"` asks for a `shared/img/` file instead.
421
487
  Inside `<svg>` tag and attribute names keep their case (`linearGradient`, `viewBox`,
422
488
  `gradientUnits`), and intent tags work on the `<svg>` and on its shapes: a `data-xt-timeline` on
423
489
  a shape (with an `id`) becomes a `#<svg id>/<shape id>` track (24 §24.14.4, T-565 record).
424
490
  Rules, ids, token colours, which tags work where and motion examples: `references/vector.md`.
425
-
426
491
  ## Colors, type, spacing
427
492
 
428
493
  Take them from the project's tokens: a UI Project's `shared/tokens.xts` when there is one
@@ -473,6 +538,7 @@ versus a token, `left/top` versus an anchor), **the tag wins**.
473
538
  | `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
539
  | `data-xt-trigger` | `event:actions; event:actions` | `on:event="actions"` (on the board root: on `<body>`) |
475
540
  | `data-xt-timeline` | `name[ loop]: t prop value, t prop value; name2: ...` | a track of `@timeline name` in `<timelines>` |
541
+ | `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) |
476
542
  | `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
543
  | `data-xt-bind` | `target=port \| converters; ...` | `bind:target` |
478
544
  | `data-xt-token` | token name (`accent`) | the colour or background becomes `var(--accent)` |
@@ -611,7 +677,24 @@ state identical to Normal is reported (`tag.stateNoDiff`).
611
677
  **Animation**; properties are CSS names (`opacity`, `transform`, `background-color`, …). The same
612
678
  timeline name on several elements is **one** timeline with a track per element (a staggered
613
679
  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.
680
+ the menu). `name loop:` makes every plain `play(name)` loop. The editor's operations take
681
+ seconds (`xtui-editor` `ops.md` has the table): `400` here is `0.4` there.
682
+ - **The base style is what shows when no timeline plays** -- in the editor with autoplay off,
683
+ before a trigger plays the timeline, on a host that never plays it -- not the timeline's value
684
+ at 0 s. A layer that only appears later in a timeline must be invisible in its own style
685
+ (`opacity: 0` in its `style`) as well as at the timeline's first key; otherwise every layer of
686
+ every shot shows at once.
687
+ - `data-xt-timeline-from-animations="intro 15s once markers"`: write the motion as ordinary CSS
688
+ (`@keyframes` plus `animation: <name> 15s <easing> infinite both` / `animation-delay`, every
689
+ element on the same cycle) and let the import turn it into one controllable timeline. Each
690
+ `@keyframes` stop at p% becomes a key at `delay + p x duration` (iterations and `alternate`
691
+ expanded); the length is the seconds given, else the longest `delay + duration`; `loop` (default)
692
+ plays it on show in a loop, `once` plays it once and holds, `none` leaves playing to a trigger;
693
+ `markers` adds a marker where each layer first appears. An animation that does not fit (a cycle
694
+ that does not divide the length, `reverse`, a property a timeline cannot key, a class shared with
695
+ an element outside the tag, a `:hover` or `@media` rule) stays as it was, with a
696
+ `timeline.animationKept` finding that says why. `xtframe-import dc ... --animations-to-timeline
697
+ intro,15s,once` does the same for the board root.
615
698
  - A trigger that plays a timeline no element declares is dropped and reported
616
699
  (`tag.triggerWithoutTimeline`); timelines inside a symbol are the symbol's own.
617
700
  - Convention names: `intro` (with `show:play(intro)`), `outro` (`hide:play(outro) then hide`),
@@ -12,7 +12,8 @@ generator: `<xtframe>/tests/import/fixtures/dc/difficulty-select/gen_flow_v2.py`
12
12
 
13
13
  Arguments: `<project-dir>` (the UI Project) and `<ui-id>` (required), plus the interaction spec in plain words. Find
14
14
  `<xtframe>` and the binaries as in SKILL.md step 0. The UI is static until this file exists;
15
- the board and the flow have different lifetimes (a re-import keeps the `.xtflow`).
15
+ the board and the flow have different lifetimes (a re-import keeps a `.xtflow` you wrote or
16
+ edited; only a flow the import generated from the board and nobody edited follows the board).
16
17
 
17
18
  ## 1. Inventory the connection points
18
19
 
@@ -0,0 +1,140 @@
1
+ Read this when the source computes its values from the time every frame (a web page or Claude Design canvas whose script sets styles per frame, a motion-graphics file with expressions): which board CSS does each kind of motion, and which motions go into an editor expression after the import.
2
+
3
+ # From procedural motion to a board
4
+
5
+ A procedural source recomputes every value each frame (`y = sin(t) * 12`). A board holds keyframes,
6
+ CSS animations and static styles. Almost every procedural motion has a direct board form, so
7
+ **convert it, do not drop it** (`SKILL.md` section 1c); the few that need a formula get one in the
8
+ editor after the import. Each pattern below imported at high fidelity and compiled; copy it and
9
+ change the numbers.
10
+
11
+ General rules:
12
+
13
+ - **Loops go on a wrapper.** A CSS `animation` on an element runs next to the timelines; when a
14
+ timeline also keys the same property of the same element, the timeline wins. Put the timeline's
15
+ move (enter, slide, fly in) on the outer element and the loop (sway, breathe, flicker) on an inner
16
+ one. A looping `@keyframes` on the child of an element a timeline moves works.
17
+ - Times in a CSS `animation` are `s` / `ms`; in `data-xt-timeline` a time without a unit is ms;
18
+ expressions read `time` in seconds (`dialect.md`, **Triggers and timelines**).
19
+ - A layer that only shows later must be hidden in its own style (`opacity: 0`), not only at the
20
+ timeline's first key: with autoplay off (the editor) or before the timeline plays, the base style
21
+ is what shows.
22
+
23
+ ## Continuous back-and-forth: breathing, sway, a swinging lamp, drifting fog
24
+
25
+ `sin(t)`-like motion that never stops is `animation: <name> <duration> ease-in-out infinite
26
+ alternate` -- `alternate` plays it back and forth, `ease-in-out` slows it at both ends like a sine.
27
+
28
+ ```html
29
+ <style>
30
+ @keyframes sway { from { transform: rotate(-4deg) } to { transform: rotate(4deg) } }
31
+ </style>
32
+ <div id="lamp-pos" style="position: absolute; left: 200px; top: 100px; width: 40px; height: 160px">
33
+ <div id="lamp" style="position: absolute; left: 0; top: 0; width: 40px; height: 160px;
34
+ transform-origin: 50% 0%; animation: sway 2.4s ease-in-out 0s infinite alternate"></div>
35
+ </div>
36
+ ```
37
+
38
+ Breathing is the same with `transform: scaleY(0.99)` to `scaleY(1.01)` (origin at the feet); fog
39
+ drifts with `translateX(-40px)` to `translateX(40px)` over 8-12 s. The duration is half the source's
40
+ period (one `alternate` pass goes one way).
41
+
42
+ ## Many things out of step: glints, sparks, stars
43
+
44
+ Give each its own period and delay; the same `@keyframes` can serve all of them.
45
+
46
+ ```html
47
+ <style> @keyframes flicker { from { opacity: 0.2 } to { opacity: 1 } } </style>
48
+ <div id="glint-a" style="... animation: flicker 1.7s ease-in-out 0s infinite alternate"></div>
49
+ <div id="glint-b" style="... animation: flicker 2.3s ease-in-out 0.4s infinite alternate"></div>
50
+ <div id="glint-c" style="... animation: flicker 3.1s ease-in-out 1.1s infinite alternate"></div>
51
+ ```
52
+
53
+ Periods that share no common factor (1.7 / 2.3 / 3.1) never line up. Nest for two motions at once:
54
+ an outer element rises (timeline), a middle one drifts left and right (loop), an inner one
55
+ flickers (loop).
56
+
57
+ ## Fast landing, slow in the air: `abs(sin)` steps and bounces
58
+
59
+ One cycle: up with `ease-out` (fast off the ground, slowing at the top), down with `ease-in`
60
+ (speeding into the ground). `animation-timing-function` inside a keyframe is the easing of the
61
+ segment that starts there.
62
+
63
+ ```html
64
+ <style>
65
+ @keyframes hop {
66
+ 0% { transform: translateY(0px); animation-timing-function: ease-out }
67
+ 50% { transform: translateY(-12px); animation-timing-function: ease-in }
68
+ 100% { transform: translateY(0px) }
69
+ }
70
+ </style>
71
+ <div id="walker" style="... animation: hop 0.4s linear 0s infinite"></div>
72
+ ```
73
+
74
+ ## A curved flight path (an arc)
75
+
76
+ Split the axes: the outer element moves X linearly, the inner one moves Y up with `ease-out` and
77
+ down with `ease-in`. The two together draw a smooth arc (measured: at the start, the middle and
78
+ the end of the flight the inner element is at the left / top / right of the arc).
79
+
80
+ ```html
81
+ <style>
82
+ @keyframes arc-x { from { transform: translateX(0px) } to { transform: translateX(600px) } }
83
+ @keyframes arc-y {
84
+ 0% { transform: translateY(0px); animation-timing-function: ease-out }
85
+ 50% { transform: translateY(-300px); animation-timing-function: ease-in }
86
+ 100% { transform: translateY(0px) }
87
+ }
88
+ </style>
89
+ <div id="paper-x" style="... animation: arc-x 1.5s linear 0s 1 both">
90
+ <div id="paper-y" style="... animation: arc-y 1.5s linear 0s 1 both"></div>
91
+ </div>
92
+ ```
93
+
94
+ The same two layers work as `data-xt-timeline` tracks (outer `translateX` with `linear`, inner
95
+ `translateY` with `ease-out` then `ease-in`) when the flight belongs to a timeline.
96
+
97
+ ## N jumps a second: ticking, jitter, a hand-drawn look
98
+
99
+ `steps(n)` holds each value and jumps; large step counts are fine.
100
+
101
+ ```html
102
+ <div id="ticker" style="... animation: tick 1s steps(4) 0s infinite"></div> <!-- 4 jumps a second -->
103
+ <svg id="speed-lines" style="... animation: jitter 1s steps(24) 0s infinite">...</svg> <!-- 24 a second -->
104
+ ```
105
+
106
+ ## A decaying shake, a one-off jolt, any formula: an expression after the import
107
+
108
+ A board cannot hold an expression. Import first, then write it on the timeline row with the
109
+ `xtui-editor` skill: `timeline_setExpression {"timeline", "layer", "prop", "text"}` (`prop` with
110
+ a component for one axis, e.g. `"translate.y"`). The expression is lowered to keys when the
111
+ document compiles, and a re-import of the board keeps it. `time` is seconds; `Math.*`, `clamp`,
112
+ `linear` / `ease`, `wiggle`, local `function`s, `var`, `if` and `posterizeTime(fps)` (hold each
113
+ value for 1/fps s) are available (Docs/design/58). These compiled as written:
114
+
115
+ | Motion | `prop` | `text` |
116
+ |---|---|---|
117
+ | sway | `rotate` | `Math.sin(time * 1.7) * 12` |
118
+ | fast landing, slow air | `translate.y` | `-Math.abs(Math.sin(time / 0.3947 * Math.PI)) * 12` |
119
+ | a shake that fades out over 0.5 s, starting at 0.5 s | `translate.x` | `function hit(a, d) { return time >= a && time < a + d ? 1 - (time - a) / d : 0; } hit(0.5, 0.5) * 14 * Math.sin(time * 90)` |
120
+ | arc: X | `translate.x` | `clamp((time - 0.2) / 1.5, 0, 1) * 1000` |
121
+ | arc: Y | `translate.y` | `400 - Math.sin(clamp((time - 0.2) / 1.5, 0, 1) * Math.PI) * 300` |
122
+ | 24 jumps a second | `rotate` | `posterizeTime(24); (Math.floor(time * 24) % 5) * 14` |
123
+
124
+ For several shakes, call `hit()` once per start time and add them. A row needs a key first; the
125
+ operation adds one at 0 s when the row has none.
126
+
127
+ ## "Everything freezes" for a beat
128
+
129
+ There is no single "freeze all" action today. Put every motion of that shot on **one** timeline and
130
+ hold its values over the freeze (two keys with the same value at the start and the end of the
131
+ freeze); stop the loops with a state rule that pauses them, switched on by a trigger at that moment:
132
+
133
+ ```html
134
+ <style> #lamp:state(Frozen) { animation-play-state: paused } </style>
135
+ <div id="lamp-pos" data-xt-trigger="press:state(Frozen, toggle, target=#lamp)"> ... </div>
136
+ ```
137
+
138
+ (`press` stands for whatever starts the freeze: a timeline marker event
139
+ `timeline(<name>).marker(<m>)` or a port.) A greyscale freeze frame is `filter: grayscale(0)` to
140
+ `grayscale(1)` keyed on the outermost element.
@@ -2,6 +2,20 @@ Read this when a board has shadows, filters, backdrop blurs, large animated elem
2
2
 
3
3
  # Performance: what costs on the GPU, and what does not
4
4
 
5
+ **Do not remove an effect because you guess it is expensive.** Write it, then measure with
6
+ `xtframe-view <project-dir> --ui <ui> --headless --renderer wgpu --perf`; only a measured number
7
+ is a reason to drop or change it (`SKILL.md` section 1c). A blur over static content is cached and
8
+ costs one textured quad per frame once drawn; a blur whose radius animates is redrawn every frame
9
+ and its layer grows and shrinks with the radius -- still a few passes, so try it before deciding.
10
+
11
+ One project's measurement, not a guarantee: a 59-second converted opening rendered 900 frames on
12
+ the GPU in 2.4 s as first converted (blurs dropped, particles and shaders added later) and in
13
+ 2.3 s as fully converted (whole-shot blur, full-screen greyscale and a dozen looping animations
14
+ kept) -- different content, so not a strict comparison, but no measurable cost. Software rendering was slow for both
15
+ (about 0.15 s a frame at 1920x1080), so check long animations on the GPU: `--renderer wgpu` with
16
+ `--advance <seconds>` to jump to a moment (`references/verify.md`). Blur and shadow radii above
17
+ 64 device px are clamped with a message (`dialect.md`).
18
+
5
19
  These are the costs of XTFrame's GPU renderers (wgpu, GL). The headless screenshot of
6
20
  `references/verify.md` step 5 renders in software and shows none of them; when you need numbers,
7
21
  `xtframe-view <project-dir> --ui <ui> --headless --renderer wgpu --perf` prints per-frame passes,
@@ -119,6 +133,12 @@ picture on screen, took a third of the frame cost away.
119
133
  them. A binding that writes the same value again does nothing.
120
134
  - A transition starts when the **target** value changes; re-applying the same value does not
121
135
  restart it (05 §5.6a).
136
+ - Put text that changes often (a counter, a timer, a round number, a score) in a container whose
137
+ `width` and `height` are fixed lengths (06 §6.x; T-755, T-782 -- its `overflow` does not matter).
138
+ Such a container is a layout boundary: a change inside it lays out only the container, not the
139
+ whole screen. A container sized by its content (`auto`) or a flex item that grows or shrinks
140
+ (anything but `flex: none`) is not one, and the change lays out everything up to the next
141
+ boundary above it -- often the whole UI.
122
142
 
123
143
  ## Clips
124
144
 
@@ -258,6 +258,11 @@ Also present when `display` is `flex` or `grid`.
258
258
  | Max rotation / 最大旋轉 | `rotationMax` | `particle-rotation-max` | style | angle | ° | | yes |
259
259
  | Max particles / 粒子上限 | `max` | `particle-max` | style | number | 1.. | | yes |
260
260
 
261
+ Without a `texture` every particle is a solid square of `particle-size` in `particle-color`.
262
+ `texture` is an attribute of `<particles>` (`layer.setAttrs`), a path **relative to the document**:
263
+ `asset.import` replies with a path relative to the project root (`shared/img/spark.png`), so a
264
+ document at `hud/hud.xt` writes `texture="../shared/img/spark.png"`.
265
+
261
266
  ## Hit & Cursor / 命中與游標 -- `interaction`
262
267
 
263
268
  | Parameter | Parameter name | CSS property | Section | Row | Range / unit | Values | Animatable |
@@ -376,3 +381,26 @@ polar coordinates: `x = d cos(angle)`, `y = d sin(angle)`, 0 deg right, 90 deg d
376
381
  | `outline-fx` | Outline / 輪廓線 | `outline` | Color / 顏色 | `color` |
377
382
  | `outline-fx` | Outline / 輪廓線 | `outline` | Softness / 柔邊 | `softness` |
378
383
  | `outline-fx` | Outline / 輪廓線 | `outline` | Position / 位置 | `outer \| center \| inner` |
384
+
385
+ ### Effect parameters on a timeline: track names
386
+
387
+ The **Argument** column above is the CSS / `effect:` function name. A timeline track (and
388
+ `timeline.setKeyframe`'s `prop`) addresses a parameter as `effect.<function>.<name>` with the
389
+ names below -- e.g. `effect.color-adjust.saturation`, not `saturate`. With the same effect twice
390
+ in the chain use its index, `effect.<i>.<name>`. Every effect also has `enabled`; `color` is its
391
+ colour; a drop shadow's `offset` keys `offsetX` / `offsetY` as one value (`"<x>px <y>px"`).
392
+ `brightness` is **additive** (0 = unchanged, -1 = black), unlike CSS `brightness()`, which
393
+ multiplies. The board import writes a `filter: brightness(x)` as the equivalent pair
394
+ `contrast` x - 1 with `brightness` 0.5 - 0.5/x (T-824), so an imported element keys both; to dim
395
+ a layer by hand, lower `contrast` and `brightness` together the same way, or its `opacity`.
396
+
397
+ | Function | Track names (in order) | `color` |
398
+ |---|---|---|
399
+ | `shadow` | `offsetX`, `offsetY`, `blur`, `spread`, `opacity`, `inset` | yes |
400
+ | `glow` | `radius`, `intensity`, `inner` | yes |
401
+ | `blur` | `radiusX`, `radiusY` | -- |
402
+ | `color-adjust` | `brightness`, `contrast`, `saturation`, `hue`, `opacity`, `invert`, `sepia` | -- |
403
+ | `gradient-mask` | `p0x`, `p0y`, `p1x`, `p1y`, `radial`, `invert` | -- |
404
+ | `shine` | `position`, `width`, `softness`, `angle`, `intensity` | yes |
405
+ | `outline` | `radius`, `softness`, `position` | yes |
406
+ | `backdrop-blur` | `radius`, `saturation`, `brightness` | -- |
@@ -38,5 +38,64 @@
38
38
  "space": [4, 8, 12, 16, 20, 24, 32, 48],
39
39
  "radius": { "chip": 0, "button": 0, "panel": 0, "tile": 0 },
40
40
  "shadow": { "panel": "0 0 0 0 #00000000" },
41
- "board": { "width": 1280, "height": 720 }
41
+ "board": { "width": 1280, "height": 720 },
42
+ "tokens": [
43
+ { "name": "--border-w", "value": "1px", "core": true },
44
+ { "name": "--color-accent", "value": "#1f1c18", "core": true },
45
+ { "name": "--color-accent-hover", "value": "#4a463f", "core": true },
46
+ { "name": "--color-accent-pressed", "value": "#dcd7c8", "core": true },
47
+ { "name": "--color-bg", "value": "#e6e2d6", "core": true },
48
+ { "name": "--color-border", "value": "#1f1c18", "core": true },
49
+ { "name": "--color-border-strong", "value": "#1f1c18", "core": true },
50
+ { "name": "--color-danger", "value": "#b3281e", "core": true },
51
+ { "name": "--color-disabled-bg", "value": "#dcd7c8", "core": true },
52
+ { "name": "--color-disabled-text", "value": "#8a857a", "core": true },
53
+ { "name": "--color-focus", "value": "#b3281e", "core": true },
54
+ { "name": "--color-info", "value": "#2f4f6f", "core": true },
55
+ { "name": "--color-scrim", "value": "#1f1c18b3", "core": true },
56
+ { "name": "--color-shadow", "value": "#4a463f", "core": true },
57
+ { "name": "--color-success", "value": "#3f6b43", "core": true },
58
+ { "name": "--color-surface", "value": "#ece8dd", "core": true },
59
+ { "name": "--color-surface-raised", "value": "#ece8dd", "core": true },
60
+ { "name": "--color-surface-sunken", "value": "#dcd7c8", "core": true },
61
+ { "name": "--color-text", "value": "#1f1c18", "core": true },
62
+ { "name": "--color-text-dim", "value": "#4a463f", "core": true },
63
+ { "name": "--color-text-on-accent", "value": "#e6e2d6", "core": true },
64
+ { "name": "--color-track", "value": "#dcd7c8", "core": true },
65
+ { "name": "--color-warning", "value": "#a0761f", "core": true },
66
+ { "name": "--control-l", "value": "44px", "core": true },
67
+ { "name": "--control-m", "value": "36px", "core": true },
68
+ { "name": "--control-s", "value": "28px", "core": true },
69
+ { "name": "--focus-w", "value": "2px", "core": true },
70
+ { "name": "--font-body", "value": "\"Noto Serif\", \"Georgia\", \"DejaVu Serif\", \"Times New Roman\"", "core": true },
71
+ { "name": "--font-display", "value": "\"Noto Serif Display ExtraCondensed\", \"Noto Serif Display\", \"Georgia\", \"Times New Roman\"", "core": true },
72
+ { "name": "--font-family", "value": "\"Noto Serif\", \"Georgia\", \"DejaVu Serif\", \"Times New Roman\"", "core": true },
73
+ { "name": "--font-size-l", "value": "20px", "core": true },
74
+ { "name": "--font-size-m", "value": "16px", "core": true },
75
+ { "name": "--font-size-s", "value": "14px", "core": true },
76
+ { "name": "--font-size-xl", "value": "28px", "core": true },
77
+ { "name": "--font-size-xs", "value": "12px", "core": true },
78
+ { "name": "--letter-display", "value": "0.5px", "core": true },
79
+ { "name": "--motion-fast", "value": "150ms", "core": true },
80
+ { "name": "--motion-instant", "value": "50ms", "core": true },
81
+ { "name": "--motion-normal", "value": "250ms", "core": true },
82
+ { "name": "--radius-full", "value": "999px", "core": true },
83
+ { "name": "--radius-l", "value": "0px", "core": true },
84
+ { "name": "--radius-m", "value": "0px", "core": true },
85
+ { "name": "--radius-s", "value": "0px", "core": true },
86
+ { "name": "--rule-thick", "value": "3px", "core": true },
87
+ { "name": "--rule-thin", "value": "1px", "core": true },
88
+ { "name": "--space-1", "value": "4px", "core": true },
89
+ { "name": "--space-2", "value": "8px", "core": true },
90
+ { "name": "--space-3", "value": "12px", "core": true },
91
+ { "name": "--space-4", "value": "16px", "core": true },
92
+ { "name": "--space-6", "value": "24px", "core": true },
93
+ { "name": "--tex-dots", "value": "url(\"textures/dots-ink.png\")", "core": false },
94
+ { "name": "--tex-grain", "value": "url(\"textures/grain-paper.png\")", "core": false },
95
+ { "name": "--tex-hatch", "value": "url(\"textures/hatch-ink.png\")", "core": false },
96
+ { "name": "--tex-rule-h", "value": "url(\"textures/rule-double.png\")", "core": false },
97
+ { "name": "--tex-rule-v", "value": "url(\"textures/rule-double-v.png\")", "core": false },
98
+ { "name": "--touch-lg", "value": "88px", "core": true },
99
+ { "name": "--touch-min", "value": "44px", "core": true }
100
+ ]
42
101
  }
@@ -61,6 +61,15 @@ a UI Project of its own, which borrows `<project>`'s token sheet and `spec`.
61
61
  HealthBar, ...), draw the board element with the same **structure and slot names** and
62
62
  `data-xt-symbol` of the same name, so the imported instance matches the project's component;
63
63
  `symbols_get {name}` gives the contract (required states and slots, ports, timelines, tokens).
64
+ **Same-named symbols** (Docs/design/56-symbol-identity-style-scope.md 56.3): two libraries may
65
+ both ship a `Button`, and the project keeps them apart by itself. A project symbol is known by its
66
+ path under `shared/symbols`: `Button` for `shared/symbols/Button.xt`, `survey-2026/Button` for
67
+ `shared/symbols/survey-2026/Button.xt` (one level of folders, named like a group id). Using a
68
+ library symbol whose name the project already has for another symbol stores the copy in
69
+ `shared/symbols/<group id>/` (with the symbols of its group it uses), and its name in the project
70
+ becomes `<group id>/<Name>`: write that in `<use symbol="survey-2026/Button">` and in `.xts` as
71
+ `symbol(survey-2026/Button) { ... }`; the file keeps `<symbol name="Button">`. A bare name in a UI
72
+ always means the flat one. Never rename library symbols or ask the user for prefixes.
64
73
 
65
74
  ## 2b. A Claude Design design system from the project
66
75
 
@@ -66,8 +66,9 @@ merge found properties that differ between the board and the project. Decide:
66
66
  list and ask. `--force` discards every editor change.
67
67
  - `--prune`: add it when the restructured board intentionally dropped layers (the stray root you
68
68
  merged, an old duplicate) and the user agrees; without it those layers stay greyed as
69
- `data-xt-missing`. When `--force` is the decision and the board is the full source, `--force
70
- --prune` together is the clean rebuild.
69
+ `data-xt-missing`. With no hand edits in the project, a re-import with `--prune` gives the same
70
+ result as a fresh import. When `--force` is the decision and the board is the full source,
71
+ `--force --prune` together is the clean rebuild.
71
72
 
72
73
  ## 6. Verify
73
74