@xtframe/skills 0.18.0 → 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xtframe/skills",
3
- "version": "0.18.0",
3
+ "version": "0.19.1",
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.1",
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.1",
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.1",
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
 
@@ -278,9 +278,44 @@ DOM only exists in the browser, so they are dropped), and `<sc-for>` / `<sc-if>`
278
278
  only once. Every other filter function is dropped. They are not CSS's colour matrices
279
279
  (18 §18.3, kept by 18 §18.13): `brightness()` is **additive** in XTFrame and `hue-rotate()` is a
280
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
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
282
284
  `brightness`/`contrast`/`saturate` is clamped with a finding (24 §24.15.4, T-566a/b records).
283
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.
284
319
  - `backdrop-filter: blur(<px>) [saturate(<n>)] [brightness(<n>)]` — frosted glass. It becomes
285
320
  XTFrame's `effect: backdrop-blur(…)`, which blurs whatever is painted **below** the element (the
286
321
  game world included). `blur()` is required; any other backdrop function drops the declaration
@@ -307,7 +342,13 @@ DOM only exists in the browser, so they are dropped), and `<sc-for>` / `<sc-if>`
307
342
  (24 §24.14.5). `object-position` and `mask-image` / `-webkit-mask-image` have no XTFrame
308
343
  property: the import renames the prefixed one and reports both as unsupported (a gradient mask is
309
344
  18's `effect: gradient-mask()`). A `background-image: url(/_blob/…)` is moved into the project
310
- like an `<img>`'s blob.
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.
311
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.
312
353
  - `text-decoration` and `text-decoration-line/color/thickness` are kept: `underline`, `overline`,
313
354
  `line-through` (several at once allowed); other line styles (`dotted`, `wavy`, …) are drawn solid
@@ -320,8 +361,9 @@ DOM only exists in the browser, so they are dropped), and `<sc-for>` / `<sc-if>`
320
361
  - `font-variant-numeric: tabular-nums` (inherited) gives every figure the same width, for counters
321
362
  and timers that change; `normal` switches it off again. Other values are dropped with a warning.
322
363
  - 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
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
325
367
  how far the subtree follows the project's scale, `ui-scale: auto` (the default) follows it. px,
326
368
  em, font sizes, borders, radii and shadows follow the factor; `%`, `vw`/`vh` and `uiscale` units
327
369
  do not. `media-override: show | hide` stops `@media` rules from switching the subtree's `display`
@@ -387,8 +429,15 @@ transition: <prop|all> <duration> [<easing>] [<delay>]
387
429
  - Time units `s` / `ms`. Easing: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`,
388
430
  `cubic-bezier(a,b,c,d)` or `steps(n[, start|end])`. Numbers **may** omit the leading zero
389
431
  (`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.
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.
392
441
  - Declarations inside a `@keyframes` block in `<helmet><style>` are converted like any other
393
442
  (`filter`, `box-shadow`, `text-shadow`, `backdrop-filter`, `var()`), so animate them as you
394
443
  would in a browser. Every keyframe of a rule must list the same `transform` functions and the
@@ -410,19 +459,27 @@ transition: <prop|all> <duration> [<easing>] [<delay>]
410
459
  `t < 0.5 ? a : b`; 05 T-229 note). To switch at an exact time, add a key with the old value just
411
460
  before the switch (`390 visibility visible, 400 visibility hidden`), so the segment is 10 ms long.
412
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`.
413
467
 
414
468
  ## Icons and vectors
415
469
 
416
470
  Inline `<svg>` with `path/rect/circle/ellipse/line/polygon`, `viewBox`, solid **or gradient** fills
417
471
  and strokes — a `<linearGradient>`/`<radialGradient>` in `<defs>` referenced by `fill="url(#id)"`
418
472
  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
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
420
478
  an editable vector layer (T-224); `data-xt-vector="file"` asks for a `shared/img/` file instead.
421
479
  Inside `<svg>` tag and attribute names keep their case (`linearGradient`, `viewBox`,
422
480
  `gradientUnits`), and intent tags work on the `<svg>` and on its shapes: a `data-xt-timeline` on
423
481
  a shape (with an `id`) becomes a `#<svg id>/<shape id>` track (24 §24.14.4, T-565 record).
424
482
  Rules, ids, token colours, which tags work where and motion examples: `references/vector.md`.
425
-
426
483
  ## Colors, type, spacing
427
484
 
428
485
  Take them from the project's tokens: a UI Project's `shared/tokens.xts` when there is one
@@ -473,6 +530,7 @@ versus a token, `left/top` versus an anchor), **the tag wins**.
473
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 |
474
531
  | `data-xt-trigger` | `event:actions; event:actions` | `on:event="actions"` (on the board root: on `<body>`) |
475
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) |
476
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>`) |
477
535
  | `data-xt-bind` | `target=port \| converters; ...` | `bind:target` |
478
536
  | `data-xt-token` | token name (`accent`) | the colour or background becomes `var(--accent)` |
@@ -611,7 +669,24 @@ state identical to Normal is reported (`tag.stateNoDiff`).
611
669
  **Animation**; properties are CSS names (`opacity`, `transform`, `background-color`, …). The same
612
670
  timeline name on several elements is **one** timeline with a track per element (a staggered
613
671
  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.
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.
615
690
  - A trigger that plays a timeline no element declares is dropped and reported
616
691
  (`tag.triggerWithoutTimeline`); timelines inside a symbol are the symbol's own.
617
692
  - 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,24 @@ 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.
394
+
395
+ | Function | Track names (in order) | `color` |
396
+ |---|---|---|
397
+ | `shadow` | `offsetX`, `offsetY`, `blur`, `spread`, `opacity`, `inset` | yes |
398
+ | `glow` | `radius`, `intensity`, `inner` | yes |
399
+ | `blur` | `radiusX`, `radiusY` | -- |
400
+ | `color-adjust` | `brightness`, `contrast`, `saturation`, `hue`, `opacity`, `invert`, `sepia` | -- |
401
+ | `gradient-mask` | `p0x`, `p0y`, `p1x`, `p1y`, `radial`, `invert` | -- |
402
+ | `shine` | `position`, `width`, `softness`, `angle`, `intensity` | yes |
403
+ | `outline` | `radius`, `softness`, `position` | yes |
404
+ | `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
 
@@ -30,7 +30,11 @@ and animated.
30
30
  `stroke-width`, `opacity` and `path-trim-*` cascade and transition like any property. In the
31
31
  editor, `vector.set` with `fill: "var(--x)"` writes the same rule (xtui-editor).
32
32
  5. **Use gradients with `gradientUnits="userSpaceOnUse"`** and an id per shape (`<shape>-fill`).
33
- That is what the editor's gradient handles write.
33
+ That is what the editor's gradient handles write. Define the gradient inside the same `<svg>`
34
+ (one in another `<svg>` is "not found" and paints black; so does a `<pattern>` fill). Not
35
+ supported, each with a warning: `fx`/`fy` (the centre is used), `spreadMethod="reflect"` /
36
+ `"repeat"` (pad is used), and elliptical radial gradients -- a `gradientTransform` with
37
+ non-uniform scale or skew, or `objectBoundingBox` on a non-square shape, draws a circle.
34
38
  6. **Prefer declarative motion to hand-computed keyframes.** Use `path-trim` for strokes that
35
39
  draw on, `transform` / `opacity` on shapes, and `d` keyframes only for real morphs. A morph
36
40
  needs the same number of vertices in every keyframe.