@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 +1 -1
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +1 -1
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +1 -1
- package/payload/plugins/xtframe/gemini-extension.json +1 -1
- package/payload/plugins/xtframe/skills/xtui/SKILL.md +28 -1
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +8 -5
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +84 -9
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +2 -1
- package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +20 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +26 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +60 -1
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +9 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +3 -2
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +5 -1
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +29 -7
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +14 -4
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +161 -22
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +45 -14
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +9 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xtframe/skills",
|
|
3
|
-
"version": "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": {
|
|
@@ -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
|
|
30
|
-
`references/verify.md`
|
|
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).
|
|
40
|
-
|
|
41
|
-
|
|
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
|
|
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
|
|
324
|
-
|
|
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
|
|
391
|
-
|
|
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
|
|
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
|
|
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`.
|
|
70
|
-
|
|
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.
|