@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 +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 +97 -14
- 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 +28 -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 +7 -1
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +30 -8
- 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 +47 -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.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": {
|
|
@@ -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
|
|
|
@@ -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.
|
|
279
|
-
(
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
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
|
|
324
|
-
|
|
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
|
|
391
|
-
|
|
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
|
|
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
|
|
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`.
|
|
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
|
|