@xtframe/skills 0.0.0-stage → 0.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -2
- package/package.json +41 -4
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
- package/payload/plugins/xtframe/gemini-extension.json +5 -0
- package/payload/plugins/xtframe/skills/xtui/SKILL.md +218 -0
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +90 -0
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +799 -0
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +338 -0
- package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +162 -0
- package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +378 -0
- package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +42 -0
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +161 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +219 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +327 -0
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +209 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +849 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +180 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +167 -0
- package/src/agents.mjs +73 -0
- package/src/bin.mjs +4 -0
- package/src/cli.mjs +286 -0
- package/src/converter.mjs +73 -0
- package/src/fsutil.mjs +76 -0
- package/src/install.mjs +154 -0
- package/src/packs.mjs +150 -0
- package/src/plugins.mjs +109 -0
- package/src/proc.mjs +66 -0
- package/src/tar.mjs +103 -0
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
Read this before writing a board when the UI belongs to a UI Project (a directory with a `<name>.xtui`): its tokens, contracts and conventions are the source for the board, ahead of the `tokens.json` shipped with this skill.
|
|
2
|
+
|
|
3
|
+
# UI Project: where the board takes its tokens and habits from
|
|
4
|
+
|
|
5
|
+
A UI Project (Docs/design/30-ui-project.md) is the game's UI workspace: `<name>.xtui` (JSON, one
|
|
6
|
+
per folder, e.g. `Fall of Warlord.xtui`) at its root, `AGENTS.md` for you, `shared/tokens.xts` (the design tokens), `shared/themes/*.xts`,
|
|
7
|
+
`shared/symbols/`, `conventions/` (layout templates, naming, timeline and state habits) and
|
|
8
|
+
`contracts/` (the motion spec and scenario contracts). When one exists, the board has to look like
|
|
9
|
+
it belongs to that game: same colours, type scale, spacing, names, timings.
|
|
10
|
+
|
|
11
|
+
## 1. Find it
|
|
12
|
+
|
|
13
|
+
Look for a `*.xtui` in `<project-dir>`, then in each parent directory of it, then in the current
|
|
14
|
+
directory and its parents (an old `ui-project.json` or `bundle.xtproj` counts too: it is read and
|
|
15
|
+
upgraded, never written). The first one found is the project root `<project>`. None found: there is
|
|
16
|
+
no UI Project yet; use `references/tokens.json` as before and skip the rest of this file (the
|
|
17
|
+
import creates `<name>.xtui` in `<project-dir>`).
|
|
18
|
+
|
|
19
|
+
Import into `<project>` itself (`xtframe-import dc <dump> -o <project>`): the new UI is added to its
|
|
20
|
+
`.xtui` and sits next to the project's other UIs. A directory below `<project>` becomes
|
|
21
|
+
a UI Project of its own, which borrows `<project>`'s token sheet and `spec`.
|
|
22
|
+
|
|
23
|
+
## 2. Read, in this order
|
|
24
|
+
|
|
25
|
+
1. `<project>/design/DESIGN.md`, when it exists: the project's authoritative design document
|
|
26
|
+
(generated from `design/`, `shared/` and `conventions/`; never edit it). Its palette, semantic
|
|
27
|
+
variables, type roles, spacing, motion, voice and principles are what the board uses; where it
|
|
28
|
+
and the files below disagree on a design question, it wins. The palette is the source for
|
|
29
|
+
picking colours, not a list of variables: the variables are still the ones in item 4.
|
|
30
|
+
2. `<project>/AGENTS.md`: what the project is and its house rules (process, naming, what not to
|
|
31
|
+
touch).
|
|
32
|
+
3. `<project>/<name>.xtui`: `spec` (resolutions -> board size, `safeArea`, input methods ->
|
|
33
|
+
whether glyphs matter, `languages` -> leave room for the longest translation, `budget`), `uis`
|
|
34
|
+
(existing UI ids: do not reuse one for a new screen), `shared` (which tokens file and theme).
|
|
35
|
+
4. `<project>/shared/tokens.xts` (or the file `shared.tokens` names): the `:root { --name: value; }`
|
|
36
|
+
block is the token set. `shared/themes/*.xts` redefine some of them; the board is drawn with the
|
|
37
|
+
base set.
|
|
38
|
+
5. `<project>/contracts/motion-spec.yaml`: durations, easings, how many things may enter at once,
|
|
39
|
+
stagger. Write every `data-xt-timeline` inside it (29.6's defaults when the file is missing:
|
|
40
|
+
entrances 150-400 ms, `ease-out` for movement, at most a few elements entering together).
|
|
41
|
+
6. `<project>/conventions/`: `layouts/*.xt` are layout templates (where a HUD's corners are, where a
|
|
42
|
+
main menu's list sits; the positions are in their `<layout>` section): place the board's
|
|
43
|
+
blocks the same way. Naming and state YAML files give
|
|
44
|
+
the layer names, state names and timeline names to use (`intro`/`idle`/`outro`, the button's
|
|
45
|
+
Hover/Pressed/Focus/Disabled).
|
|
46
|
+
7. `<project>/shared/symbols/`: the project's **copies** of library symbols. Symbols live in
|
|
47
|
+
**libraries** (the presets next to the editor, read-only; the user's own library under the user
|
|
48
|
+
data directory; extra libraries the user mounted; `<project>/shared/symbol-library/` when the
|
|
49
|
+
project ships one), each library in **groups** (`broadsheet-2026` is the preset default), and a
|
|
50
|
+
group travels between people as a **set** (`.xtsymbols`, Docs/design/49-symbol-sets.md). A
|
|
51
|
+
project never links a library file: using a symbol copies `<group>/<Name>.xt` to
|
|
52
|
+
`shared/symbols/<Name>.xt`, its fonts and textures to `shared/fonts/` and `shared/textures/` (a
|
|
53
|
+
file of other content under a hashed name), appends the tokens it reads that
|
|
54
|
+
`shared/tokens.xts` lacks with the group's defaults (and each theme's values to
|
|
55
|
+
`shared/themes/<theme>.xts`), and records the source in `shared/symbols/index.json` (library,
|
|
56
|
+
group, set, version, hash) -- `symbols_useGroup` / `symbols_use` in the editor (SKILL.md section
|
|
57
|
+
1b), or the Symbols tab's drag-in. The project's copy is what the UI uses; it may drift from the
|
|
58
|
+
library (edited in the project, or the library moved on): `project_syncSymbols` reports
|
|
59
|
+
`outdated` / `modified` copies, and `symbols_updateCopy {name}` rewrites one from the library --
|
|
60
|
+
only when the user agrees, never on your own. If a symbol already exists for something (Button,
|
|
61
|
+
HealthBar, ...), draw the board element with the same **structure and slot names** and
|
|
62
|
+
`data-xt-symbol` of the same name, so the imported instance matches the project's component;
|
|
63
|
+
`symbols_get {name}` gives the contract (required states and slots, ports, timelines, tokens).
|
|
64
|
+
|
|
65
|
+
## 2b. A Claude Design design system from the project
|
|
66
|
+
|
|
67
|
+
When the project has a `design/` directory and the user works in Claude Design, build the Claude
|
|
68
|
+
Design design system from the project first, then draw the boards with it:
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
xtframe-design export <project> --claude-design <out dir> [--json]
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
writes `README.md` (identity, voice, colour, type, space and shape, motion, components and
|
|
75
|
+
decisions of `DESIGN.md`), `tokens.json` (the shape of this skill's `references/tokens.json`:
|
|
76
|
+
`themes.base` is the base colour set, every other theme lists only what it changes),
|
|
77
|
+
`palette.json` (the colour library) and `components.md` (the symbol library). Give that folder to
|
|
78
|
+
Claude Design to set up its design system; boards made with it already use the project's colours,
|
|
79
|
+
sizes and component names. Files only: the command never talks to Claude Design. The way back is
|
|
80
|
+
`xtframe-design import <project> --claude-design <dir>` (or `design.importDesignSystem` in the
|
|
81
|
+
editor): everything comes in as drafts and existing values are never overwritten.
|
|
82
|
+
|
|
83
|
+
## 3. Use the tokens on the board
|
|
84
|
+
|
|
85
|
+
The importer resolves `var(--x)` and `data-xt-token` from a `tokens.json`, so turn the token block
|
|
86
|
+
into one for the dump: a flat JSON object, token name without `--` -> value exactly as written.
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
:root { --color-accent: #0f7b8a; --font-size-xs: 12px; --radius-button: 8px; }
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
becomes `<dump>/project/ds/project/tokens.json`:
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{ "color-accent": "#0f7b8a", "font-size-xs": "12px", "radius-button": "8px" }
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Then write the board with those names: `color: var(--color-accent)`, or the literal value plus
|
|
99
|
+
`data-xt-token="color-accent"` on the element, and import with
|
|
100
|
+
`--tokens <dump>/project/ds/project/tokens.json` (`references/verify.md` step 3) so this file wins
|
|
101
|
+
over any other `ds/*/tokens.json` in the dump. A colour that is not a token is the exception: the
|
|
102
|
+
editor's lint reports literal colours (`lint.literalColor`).
|
|
103
|
+
|
|
104
|
+
The imported UI's own stylesheet (`<ui>/<ui>.xts`, the `.xt`'s appearance `<style src>`; tokens
|
|
105
|
+
are never declared in `<layout>`) declares the tokens it uses in its own `:root` block. Inside a
|
|
106
|
+
UI Project the same names come from `shared/tokens.xts` too; tell the user the UI's copies can be
|
|
107
|
+
deleted once the UI lives in the project (the compiler warns about a token declared twice).
|
|
108
|
+
|
|
109
|
+
## 3b. Mobile UI (phones and tablets)
|
|
110
|
+
|
|
111
|
+
A project for phones has `spec.platforms` with a `mobile` entry (e.g. 1080x2400), `spec.input`
|
|
112
|
+
`touch` and usually `"uiscaleRule": "shortEdge"` (uiscale = the short screen edge / 1080, so a
|
|
113
|
+
portrait phone scales by its width). When the user asks for a phone UI:
|
|
114
|
+
|
|
115
|
+
- **Portrait.** Draw the board 1080 wide and 2400 tall (Phone 20:9); the editor's device presets
|
|
116
|
+
are Phone 20:9 (1080x2400), Phone 19.5:9 (1170x2532) and Tablet 16:10 (2560x1600).
|
|
117
|
+
- **Safe area.** Keep the status bar / notch and the home indicator clear: on a phone about 4% of
|
|
118
|
+
the height at the top and 3% at the bottom. Bars stick to the edges and pad by the inset
|
|
119
|
+
(`padding-top: 1safe-top`, `bottom: calc(1safe-bottom + 24px)`), never by a fixed number.
|
|
120
|
+
- **Touch sizes.** Nothing tappable under 44 px (`--touch-min`); main actions 88 px
|
|
121
|
+
(`--touch-lg`). Leave at least 8 px between targets. No hover-only affordances.
|
|
122
|
+
- **Thumb zones.** Movement bottom-left, actions bottom-right, status along the top, menus in a
|
|
123
|
+
bottom sheet or a bottom tab bar.
|
|
124
|
+
- **Standard mobile symbols** (`Assets/Symbols/groups/broadsheet-2026/mobile/`, linked like the others as
|
|
125
|
+
`shared/symbols/<Name>.xt`; draw the board element with `data-xt-symbol` of the same name):
|
|
126
|
+
VirtualJoystick (`axis: vec2 out`, `dead`), TouchButton (`pressed`, `held`, `repeat`,
|
|
127
|
+
`cooldown`; slots icon, label), DPad (`dir`, `axis`), SwipeCard (`swipe`, `direction`),
|
|
128
|
+
BottomSheet (`open`; Collapsed / Expanded; slots title, content), TabBar (`value`, `select`;
|
|
129
|
+
3-5 tabs), TopBar (slots left, title, right), PullIndicator (`progress`), ToggleTouch,
|
|
130
|
+
SliderTouch and PinchZoomView (`scale`, `min`, `max`, `pinch`). Toast stays the toast.
|
|
131
|
+
- The example project `Examples/demos/mobile-hud/` (Mobile HUD demo.xtui) shows a portrait HUD and
|
|
132
|
+
a settings sheet built from them.
|
|
133
|
+
|
|
134
|
+
## 3c. Image compression when publishing
|
|
135
|
+
|
|
136
|
+
`<name>.xtui` `publish.images.compress` decides how `xtframe-pack` (and the editor's Publish)
|
|
137
|
+
writes bitmaps into the Bundle (10 §10.13; T-687):
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
"publish": { "images": { "compress": "auto" } }
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
- `none` -- the default, also when the key is missing: images are packed as they are.
|
|
144
|
+
- `bc7` -- every bitmap and atlas page becomes a BC7 DDS.
|
|
145
|
+
- `auto` -- BC7 only for images and atlas pages with both sides at least 256 px; smaller ones stay
|
|
146
|
+
as they are.
|
|
147
|
+
|
|
148
|
+
Any other value makes the project fail to load. `xtframe-pack --compress` overrides the key for one
|
|
149
|
+
run (`references/verify.md`, **Packing a Bundle**); one asset can opt out with `compress: none` in
|
|
150
|
+
`manifest/assets.yaml`. With compression on, every packed DDS carries its full mip chain whatever
|
|
151
|
+
`publish.atlas.mipmaps` says (that setting no longer affects compressed images). The layout keeps
|
|
152
|
+
each image's own size. When to use which: `references/performance.md`, **Images**. The key is the
|
|
153
|
+
project's setting (section 4): suggest it to the user before a publish, do not write it yourself.
|
|
154
|
+
|
|
155
|
+
## 4. What not to do
|
|
156
|
+
|
|
157
|
+
- Do not edit anything under `<project>` except through the import (`xtframe-import dc -o ...`):
|
|
158
|
+
tokens, contracts, conventions and symbols are the humans' (or `xtui-editor`'s) to change.
|
|
159
|
+
- Do not invent tokens. When the board needs a colour the project does not have, use the closest
|
|
160
|
+
token and list the gap in your report.
|
|
161
|
+
- Do not copy `references/tokens.json` into a dump that belongs to a UI Project.
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
Read this when the user asks to bring an existing UI Project (a directory with a `<name>.xtui`, often an older demo or a project made months ago) up to the current rules: "upgrade", "modernize", "make it work with the new editor", "fix the layout contract", "migrate to format 2" (its `.xt` files start with `<xt>`, not `<xt version="2">`: section 8), or before a responsive request on an old project.
|
|
2
|
+
|
|
3
|
+
# Upgrade an existing UI Project
|
|
4
|
+
|
|
5
|
+
The board stays the source: an upgrade fixes the **board** (and a flow generator, when there is
|
|
6
|
+
one) and re-imports. It never patches the generated `.xt` / `.xts` by hand (the format upgrade
|
|
7
|
+
of section 8 is a tool run, not a patch). Work through the list in order and keep a note of each
|
|
8
|
+
item for the report.
|
|
9
|
+
|
|
10
|
+
## 1. Back up first
|
|
11
|
+
|
|
12
|
+
Copy `<project>` (the whole directory, `.xtui`, every UI folder, `shared/`, `contracts/`) and the
|
|
13
|
+
board dump to a sibling `<name>.bak-<date>` before the first import. A `--force` re-import
|
|
14
|
+
discards editor changes; the backup is how the user gets them back. When `<project>` is in git and
|
|
15
|
+
the tree is clean, a commit is the backup instead; say which one you used.
|
|
16
|
+
|
|
17
|
+
## 2. Find the board
|
|
18
|
+
|
|
19
|
+
The board is the dump the project was imported from (`<dump>/project/canvas.json` plus
|
|
20
|
+
`*.dc.html`). Look, in order, at: a `claude-design/` or `board/` directory beside `<project>`
|
|
21
|
+
(the demos keep it there, e.g. `Examples/demos/challenge-menu/claude-design/`), the `source`
|
|
22
|
+
recorded in `<project>/import-report.json`, the project's `AGENTS.md`. Not found: ask the user.
|
|
23
|
+
No board at all (the project was made in the editor): this is not an upgrade by import; use
|
|
24
|
+
`xtui-editor` (its `repair-import` scenario, `repair.anchor`) instead and stop here.
|
|
25
|
+
|
|
26
|
+
## 3. Fix the board
|
|
27
|
+
|
|
28
|
+
Run the lint (`references/verify.md` step 2) and work through it, plus:
|
|
29
|
+
|
|
30
|
+
- **Multiple roots.** `board.multipleRoots: <N> top-level elements (<ids>)` (or, on an older
|
|
31
|
+
converter, the import's "extra top-level frames" warning) usually means a **stray closing tag**:
|
|
32
|
+
a `</div>` too many above the second root closes the real root early, and everything after it
|
|
33
|
+
becomes a separate full-screen overlay. Find the extra `</div>` (count open/close tags up to the
|
|
34
|
+
first id the lint lists), delete it, and lint again. Only keep several roots when they really are
|
|
35
|
+
overlays meant to sit outside the root's stacking context (`references/dialect.md`, **Board
|
|
36
|
+
setup**).
|
|
37
|
+
- **Ids.** Every element the game, a flow or a binding reaches gets a role id
|
|
38
|
+
(`references/verify.md` step 7); content-hash ids (`n-xxxxxxxx`) in `import-report.json` or the
|
|
39
|
+
flow are the list to fix. Keep existing ids: the flow and the host already use them.
|
|
40
|
+
- **Ports.** Values the game supplies (`{{hole}}` with a `data-props` default, or a flow `set` on
|
|
41
|
+
a text) become `data-xt-port` + `data-xt-bind` (`references/dialect.md`, **Ports and bindings**).
|
|
42
|
+
- **Layout.** A fixed-size root is fine (the import anchors it). Elements the flow moves and
|
|
43
|
+
panels with `translateZ` get a dock; sibling panels that must stay aligned share one
|
|
44
|
+
(`references/responsive.md` section 3). For a responsive request also set `data-xt-uiscale`
|
|
45
|
+
on the root (`references/responsive.md` section 1).
|
|
46
|
+
|
|
47
|
+
## 4. The flow: generated or hand-written
|
|
48
|
+
|
|
49
|
+
Look at the UI's `.xtflow` header and the UI folder. When a script writes it (a
|
|
50
|
+
`gen_<ui>.py` beside it, e.g. `challenge-menu/gen_challenge_menu.py`, or the header says
|
|
51
|
+
"Generated by"), change the **script** (new dock-relative positions, renamed ids) and re-run it;
|
|
52
|
+
never edit the generated `.xtflow`. A hand-written flow is changed in place, through `xtui-editor`
|
|
53
|
+
(`flow.set`) when the editor has the UI open (`references/flow.md`). A re-import never touches the
|
|
54
|
+
`.xtflow`, so do this after the import.
|
|
55
|
+
|
|
56
|
+
## 5. Re-import: baseline, `--force`, `--prune`
|
|
57
|
+
|
|
58
|
+
Import into `<project>` itself (`references/verify.md` step 3). Exit 3 with conflicts means the
|
|
59
|
+
merge found properties that differ between the board and the project. Decide:
|
|
60
|
+
|
|
61
|
+
- **No re-import baseline** (an old project imported before the merge existed; the conflict report
|
|
62
|
+
says `no reimport baseline: these conflicts compare the board with the generated files, not with
|
|
63
|
+
hand edits; ...`) **and** the user has said the board is the source of truth: re-run with
|
|
64
|
+
`--force` directly. The "conflicts" are only the old generated output.
|
|
65
|
+
- **Otherwise** (a baseline exists, or the user has not said the board wins): show the conflict
|
|
66
|
+
list and ask. `--force` discards every editor change.
|
|
67
|
+
- `--prune`: add it when the restructured board intentionally dropped layers (the stray root you
|
|
68
|
+
merged, an old duplicate) and the user agrees; without it those layers stay greyed as
|
|
69
|
+
`data-xt-missing`. When `--force` is the decision and the board is the full source, `--force
|
|
70
|
+
--prune` together is the clean rebuild.
|
|
71
|
+
|
|
72
|
+
## 6. Verify
|
|
73
|
+
|
|
74
|
+
All of `references/verify.md` steps 2-5, and the upgrade is done only when:
|
|
75
|
+
|
|
76
|
+
- the lint has **0** findings left that you can fix on the board (list any you deliberately keep);
|
|
77
|
+
- every UI compiles with **0** errors (`xtframe-compile`; list the warnings);
|
|
78
|
+
- screenshots at the aspect set (`references/responsive.md` section 4; at least 16:9 at the board
|
|
79
|
+
size and 21:9 for a non-responsive request) look like the board;
|
|
80
|
+
- the flow still runs (`xtframe-view` prints `loaded flow`; click/hover paths you changed behave).
|
|
81
|
+
|
|
82
|
+
## 7. Report what you did not change
|
|
83
|
+
|
|
84
|
+
An upgrade fixes structure, not the design. Say which of these you saw and left alone, so the user
|
|
85
|
+
decides:
|
|
86
|
+
|
|
87
|
+
- `motion.ambient` (looping ambient animations) outside the project's motion spec;
|
|
88
|
+
- animations of `left` / `top` (they work, but `transform` is cheaper and a dock may be needed);
|
|
89
|
+
- text under the project's minimum font size;
|
|
90
|
+
- literal colours that should be tokens, tokens declared twice, or missing tokens;
|
|
91
|
+
- files in `<project>` or the dump no UI references (old screenshots, unused images);
|
|
92
|
+
- anything you backed up and where the backup is.
|
|
93
|
+
|
|
94
|
+
## 8. Source format 1 -> 2
|
|
95
|
+
|
|
96
|
+
A UI Project written before source format 2 (Docs/design/54) has `.xt` files without
|
|
97
|
+
`<xt version="2">`: ports as `port:` attributes on `<body>` or the root element, `<link href>` in
|
|
98
|
+
the `<head>`, geometry and appearance mixed in the `.xts`, `@timeline` and `on-<event>` rules in
|
|
99
|
+
the `.xts`. They still compile (the format 1 reader stays until 1.0), but the editor writes only
|
|
100
|
+
format 2 and the current import writes format 2, so a project is upgraded **once, as a whole**
|
|
101
|
+
(a `.xts` linked by both a format 1 and a format 2 file is checked by the format 2 rules):
|
|
102
|
+
|
|
103
|
+
1. Back up (section 1); the migration writes in place and keeps no backup of its own (git is the
|
|
104
|
+
backup).
|
|
105
|
+
2. Dry run into a scratch directory and read the report:
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
xtframe-compile --migrate <project> -o <scratch dir> --anchors --report <scratch>/migrate.json
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
prints `migrate: N files (N migrated, 0 skipped, 0 with errors); R rules split, A anchors, I ids
|
|
112
|
+
assigned` and the self-check `layer two N equal, 0 differ`. `-o` writes only the rewritten
|
|
113
|
+
files. `--anchors` also turns the three `calc(1safe-...)` anchoring forms into
|
|
114
|
+
`anchor` / `offset` / `size` (what it cannot express stays long-hand).
|
|
115
|
+
3. When the report has **0 with errors** and **0 differ**, run it in place: the same command
|
|
116
|
+
without `-o` (it writes only when everything is green and exits 1 otherwise). The packer does
|
|
117
|
+
the same with `xtframe-pack --upgrade --format 2 <project>`. The editor is specified to offer
|
|
118
|
+
the same upgrade when it opens a format 1 project (54 §54.10); when your editor build does not
|
|
119
|
+
ask, run the command.
|
|
120
|
+
4. Re-run section 6 (compile, screenshots, flow).
|
|
121
|
+
|
|
122
|
+
What it does per `.xt` and every `.xts` / symbol library it links (54 §54.10): `<link href>` ->
|
|
123
|
+
`<style src>`, `<link rel="symbols">` -> `<symbols src>`; `port:` -> `<ports>` (declaration order
|
|
124
|
+
kept); `@timeline` -> `<timelines>`; `on-<event>` rules -> `on:<event>` on the element or
|
|
125
|
+
`on:<event>@<inner path>` on the `<use>`, `state-enter` / `state-exit` -> `on:state(X).enter` /
|
|
126
|
+
`.exit`; every rule split by the Section column of `style-groups.md`, **selectors unchanged** (one
|
|
127
|
+
rule can become two, one per section); a linked `<stem>.xts` becomes `<stem>.xts` (appearance) plus
|
|
128
|
+
`<stem>.layout.xts` / `<stem>.timelines.xts`, each pulled in by its own section; inline `style=`
|
|
129
|
+
geometry -> an `#id` rule in `<layout>` (an element without an id gets one); flow endpoints
|
|
130
|
+
`#<root id>.<port>` in the UI's `.xtflow` -> `#document.<port>`. The guarantee: every element's
|
|
131
|
+
computed style, in every pseudo-class combination and every `@media` case, is the same as before
|
|
132
|
+
(`xtframe-compile <ui>.xt --dump-computed` prints it), so the pixels are the same; the `.xtir`
|
|
133
|
+
bytes may differ (a split rule is two style rules).
|
|
134
|
+
|
|
135
|
+
The migrated files keep the project's own file layout (`<ui>.layout.xts` beside the `.xt`); a
|
|
136
|
+
later `--force` re-import from the board writes the import's layout instead (`<layout>` and
|
|
137
|
+
`<timelines>` inline in the `.xt`, the appearance in `<ui>.xts`; `references/dialect.md`, **What
|
|
138
|
+
the import writes**). Both are format 2. Migration errors (a trigger rule inside `@media` or
|
|
139
|
+
under a pseudo-class, a port declared deeper than the root) are listed per file: fix those on
|
|
140
|
+
the board and re-import instead.
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
# Vector icons and motion (inline `<svg>`)
|
|
2
|
+
|
|
3
|
+
Write icons, gauges and decorative shapes straight into the board as inline `<svg>`. They stay
|
|
4
|
+
editable vector layers in XTFrame. The importer keeps them inline; `data-xt-vector="file"` on an
|
|
5
|
+
`<svg>` asks for a `shared/img/` file instead, and `xtframe-import --extract-svg` does that for
|
|
6
|
+
every SVG. Every shape can then be edited in the editor (node tool, appearance panel, booleans)
|
|
7
|
+
and animated.
|
|
8
|
+
|
|
9
|
+
## Rules
|
|
10
|
+
|
|
11
|
+
1. **Use the SVG subset.** Allowed: `<svg viewBox>`, `<g>`, `<path d>`, `<rect>`, `<circle>`,
|
|
12
|
+
`<ellipse>`, `<line>`, `<polygon>`, `<polyline>`, `<defs>` with `<linearGradient>` or
|
|
13
|
+
`<radialGradient>`, plus `<xt-star cx cy points r r2? rotation? round? round2?>` for stars and
|
|
14
|
+
polygons (`round` cuts real rounded corners, 0..1). Not allowed: `<text>`, `<image>`,
|
|
15
|
+
`<filter>`, `<mask>`, `<clipPath>`, `<pattern>`, `<style>`. These are skipped with a warning.
|
|
16
|
+
2. **Give every shape an `id`**, for example `<path id="Ring" ...>`. Ids are how timelines, rules
|
|
17
|
+
and the editor address a shape, and a shape without one gets an automatic name on first save.
|
|
18
|
+
3. **Keep `viewBox` 1:1 with the box.** A 24 px icon gets `viewBox="0 0 24 24"` and a 24 px box.
|
|
19
|
+
The editor normalises other ratios on the first edit, but 1:1 keeps coordinates readable.
|
|
20
|
+
4. **Take colours from tokens.** In the board, write the token's current value as a literal
|
|
21
|
+
(`fill="#2f81f7"`). In the imported UI, a shape is themed by a scene-target rule in the UI's
|
|
22
|
+
`.xts`:
|
|
23
|
+
|
|
24
|
+
```css
|
|
25
|
+
#Icon/Ring { stroke: var(--color-accent); }
|
|
26
|
+
#Button:hover #Icon/Ring { stroke: var(--color-accent-hover); }
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`#<svg id>/<shape id>` addresses the shape inside the vector layer. `fill`, `stroke`,
|
|
30
|
+
`stroke-width`, `opacity` and `path-trim-*` cascade and transition like any property. In the
|
|
31
|
+
editor, `vector.set` with `fill: "var(--x)"` writes the same rule (xtui-editor).
|
|
32
|
+
5. **Use gradients with `gradientUnits="userSpaceOnUse"`** and an id per shape (`<shape>-fill`).
|
|
33
|
+
That is what the editor's gradient handles write.
|
|
34
|
+
6. **Prefer declarative motion to hand-computed keyframes.** Use `path-trim` for strokes that
|
|
35
|
+
draw on, `transform` / `opacity` on shapes, and `d` keyframes only for real morphs. A morph
|
|
36
|
+
needs the same number of vertices in every keyframe.
|
|
37
|
+
7. **Case is kept inside `<svg>`** (24 §24.14.4): tag and attribute names such as
|
|
38
|
+
`linearGradient`, `viewBox` and `gradientUnits` arrive as written (`data-*` names stay lower
|
|
39
|
+
case).
|
|
40
|
+
8. **Intent tags on the `<svg>` and its shapes** (24 §24.14.4, T-565 record):
|
|
41
|
+
- `data-xt-timeline` on a **shape** becomes a `#<svg id>/<shape id>` track of that `@timeline`
|
|
42
|
+
(the shape needs an `id`; none is made up for it), with the vector properties (`fill`,
|
|
43
|
+
`stroke`, `path-trim-*`, `d`, `transform`, `opacity` …).
|
|
44
|
+
- `data-xt-timeline` on the **`<svg>` itself** takes only `transform`, `opacity` and
|
|
45
|
+
`visibility`; a vector property there is dropped and reported (`svg.unsupported`) -- move it to
|
|
46
|
+
the shape.
|
|
47
|
+
- `data-xt-bind`, `data-xt-trigger` and `data-xt-state` on the `<svg>` work as on any element;
|
|
48
|
+
a state element's shape differences become `#btn:hover #icon/blade` style rules.
|
|
49
|
+
- `data-xt-symbol`, `data-xt-slot`, `data-xt-glyph` and `data-xt-rich` on an `<svg>` are not
|
|
50
|
+
possible and are reported as `svg.unsupported` (the fix names the attribute or
|
|
51
|
+
`data-xt-vector`).
|
|
52
|
+
|
|
53
|
+
## Examples
|
|
54
|
+
|
|
55
|
+
Icon, a shield with two shapes:
|
|
56
|
+
|
|
57
|
+
```html
|
|
58
|
+
<svg id="icon-shield" viewBox="0 0 24 24" style="width:24px;height:24px">
|
|
59
|
+
<path id="Body" d="M12 2 L21 6 V12 C21 17 17 21 12 22 C7 21 3 17 3 12 V6 Z" fill="#2f81f7"/>
|
|
60
|
+
<path id="Mark" d="M8 12 L11 15 L16 9" fill="none" stroke="#ffffff" stroke-width="2"
|
|
61
|
+
stroke-linecap="round" stroke-linejoin="round"/>
|
|
62
|
+
</svg>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Progress ring driven by `path-trim` (0..1 of the stroke's length). Bind or animate
|
|
66
|
+
`path-trim-end`:
|
|
67
|
+
|
|
68
|
+
```html
|
|
69
|
+
<svg id="Progress" viewBox="0 0 64 64" style="width:64px;height:64px">
|
|
70
|
+
<circle id="Track" cx="32" cy="32" r="28" fill="none" stroke="#2a2f3a" stroke-width="6"/>
|
|
71
|
+
<circle id="Ring" cx="32" cy="32" r="28" fill="none" stroke="#2f81f7" stroke-width="6"
|
|
72
|
+
stroke-linecap="round" path-trim="0 0.65" transform="rotate(-90 32 32)"/>
|
|
73
|
+
</svg>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
```css
|
|
77
|
+
/* in the UI's .xts after import */
|
|
78
|
+
@timeline intro {
|
|
79
|
+
#Progress/Ring { 0s { path-trim-end: 0 } 0.8s ease-out { path-trim-end: 0.65 } }
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Hover colour change on one shape (scene-target rule plus transition; the pseudo-class sits on
|
|
84
|
+
an ancestor, here the button holding the icon):
|
|
85
|
+
|
|
86
|
+
```css
|
|
87
|
+
#icon-shield/Body { fill: var(--color-accent); transition: fill 0.15s ease-out; }
|
|
88
|
+
#btn-shield:hover #icon-shield/Body { fill: var(--color-accent-hover); }
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
A star badge:
|
|
92
|
+
|
|
93
|
+
```html
|
|
94
|
+
<svg id="Badge" viewBox="0 0 40 40" style="width:40px;height:40px">
|
|
95
|
+
<xt-star id="Star" cx="20" cy="20" points="5" r="18" r2="8" round="0.3" fill="#f5c542"/>
|
|
96
|
+
</svg>
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Cel animation (frame by frame)
|
|
100
|
+
|
|
101
|
+
For hand-drawn loops (a flame, a spark, a blinking eye), mark the `<svg>` with `data-xt-cels="1"`
|
|
102
|
+
and put one `<g>` per drawing. The `<g>`s are the cels, in order, and only one shows at a time.
|
|
103
|
+
Give every cel an id (`Cel_1`, `Cel_2`, ...). Its timing lives in the `.xt`'s `<timelines>`
|
|
104
|
+
section as `visibility` hold keys, one track per cel, all `steps(1, end)`: cel i is visible from
|
|
105
|
+
`t_i` until `t_(i+1)`.
|
|
106
|
+
|
|
107
|
+
```html
|
|
108
|
+
<svg id="Flame" viewBox="0 0 32 32" style="width:32px;height:32px" data-xt-cels="1">
|
|
109
|
+
<g id="Cel_1"><path id="F1" d="M16 4 C22 12 24 18 16 28 C8 18 10 12 16 4 Z" fill="#ff8a00"/></g>
|
|
110
|
+
<g id="Cel_2"><path id="F2" d="M16 6 C23 13 22 20 16 28 C9 20 9 13 16 6 Z" fill="#ff8a00"/></g>
|
|
111
|
+
<g id="Cel_3"><path id="F3" d="M16 3 C21 11 25 19 16 28 C7 19 11 11 16 3 Z" fill="#ff8a00"/></g>
|
|
112
|
+
</svg>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
```css
|
|
116
|
+
/* in the .xt's <timelines> after import: three cels of 4 frames at 24 fps, looped by the trigger */
|
|
117
|
+
@timeline idle {
|
|
118
|
+
duration: 0.5s;
|
|
119
|
+
#Flame/Cel_1 { 0s steps(1, end) { visibility: visible } 0.167s steps(1, end) { visibility: hidden } }
|
|
120
|
+
#Flame/Cel_2 { 0s steps(1, end) { visibility: hidden } 0.167s steps(1, end) { visibility: visible }
|
|
121
|
+
0.333s steps(1, end) { visibility: hidden } }
|
|
122
|
+
#Flame/Cel_3 { 0s steps(1, end) { visibility: hidden } 0.333s steps(1, end) { visibility: visible }
|
|
123
|
+
0.5s steps(1, end) { visibility: hidden } }
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Without the `@timeline` block the editor shows equal cels over the timeline and writes the keys on
|
|
128
|
+
the first cel edit (xtui-editor: `cel.list`, `cel.add`, `cel.setRange`). A cel group can also be
|
|
129
|
+
a plain container (`<div data-xt-cels="1">` with one child container per cel); then the tracks
|
|
130
|
+
are `#<cel id>`.
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
## Skeletons and skinning (bones, weights, image meshes)
|
|
134
|
+
|
|
135
|
+
For a mascot, a breathing portrait or a small character reaction (nod, blink, hit), put a
|
|
136
|
+
skeleton inside the `<svg>` and skin the shapes to it. Bones bend the shapes; the editor and
|
|
137
|
+
the runtime do the deformation. This is not a Spine replacement: no skins, one skeleton per
|
|
138
|
+
character, at most 4 bones per vertex.
|
|
139
|
+
|
|
140
|
+
Pose vs rest: a bone's `rotate` / `translate` / `scale` / `length` are its current static
|
|
141
|
+
pose. The optional `rest-rotate` / `rest-translate` / `rest-scale` / `rest-length` are the bind
|
|
142
|
+
pose the weights were computed against (default: the same values). Write only the pose
|
|
143
|
+
attributes; the editor writes `rest-*` when it binds. To ship a character already posed, keep
|
|
144
|
+
`rest-*` at the bind pose and change the plain attributes. An image mesh takes `x` / `y`
|
|
145
|
+
(image origin, default 0) and `transform` like any shape; its pins are in that local space.
|
|
146
|
+
|
|
147
|
+
Write, inside the `<svg>` (close every element explicitly; the board is HTML):
|
|
148
|
+
|
|
149
|
+
```html
|
|
150
|
+
<svg id="Mascot" viewBox="0 0 200 200" style="width:200px;height:200px">
|
|
151
|
+
<path id="Body" d="M60 128 L120 128 L180 128 L180 152 L120 152 L60 152 Z" fill="#3366cc"
|
|
152
|
+
xt-skin="Rig">
|
|
153
|
+
<xt-weights bones="Spine Head" version="1">
|
|
154
|
+
0 0:1
|
|
155
|
+
1 0:.5 1:.5
|
|
156
|
+
2 1:1
|
|
157
|
+
3 1:1
|
|
158
|
+
4 0:.5 1:.5
|
|
159
|
+
5 0:1
|
|
160
|
+
</xt-weights>
|
|
161
|
+
</path>
|
|
162
|
+
<xt-skeleton id="Rig">
|
|
163
|
+
<xt-bone id="Spine" length="60" translate="60 140">
|
|
164
|
+
<xt-bone id="Head" length="60">
|
|
165
|
+
<xt-constraint id="Reach" kind="ik" target="#Paw"></xt-constraint>
|
|
166
|
+
</xt-bone>
|
|
167
|
+
</xt-bone>
|
|
168
|
+
</xt-skeleton>
|
|
169
|
+
<circle id="Paw" cx="0" cy="0" r="5" fill="#dd2222" transform="translate(170 100)"></circle>
|
|
170
|
+
</svg>
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
- `<xt-skeleton id>`: no transform of its own (it is ignored with a warning). Its space is the
|
|
174
|
+
`<svg>`'s group space; one `<svg>` per skinned character.
|
|
175
|
+
- `<xt-bone id length rotate? translate? scale?>`: only a root bone takes `translate` (its
|
|
176
|
+
origin, group coordinates); a child bone always starts at its parent's tip. `rotate` is in
|
|
177
|
+
degrees relative to the parent (y points down, so positive turns clockwise). These attribute
|
|
178
|
+
values are the rest pose.
|
|
179
|
+
- `<xt-constraint kind target ...>` under a bone, applied in document order: `ik` (`target`,
|
|
180
|
+
`strength` 0..1, `invert` 0/1 bend direction, `chain` default 2), `transform` / `rotation`
|
|
181
|
+
(`target`, `mix`, `space="local|world"`), `spring` (no target; `inertia`, `strength`,
|
|
182
|
+
`damping`, `gravity`, `mix`). `target` is `#id` of an element in the same `<svg>`.
|
|
183
|
+
- `xt-skin="<skeleton id>"` on a `<path>` (not on `<rect>` / `<circle>` / `<xt-star>`; write them
|
|
184
|
+
as a `<path>` to skin them) plus one `<xt-weights bones="<bone ids>">` child. Each line is
|
|
185
|
+
`<vertex> <p weights> [| <in weights> [| <out weights>]]`, a weight is `<bone index>:<weight>`
|
|
186
|
+
(an index into `bones`), at most 4 per column; weights are normalized when compiled. `=` or a
|
|
187
|
+
missing column means "same as p" (most vertices). A vertex without a line goes all to the
|
|
188
|
+
first bone.
|
|
189
|
+
- **Vertex order** (the `<vertex>` numbers): count the on-curve points of `d` contour by
|
|
190
|
+
contour. The `M` point is vertex 0 of its contour, every following segment's end point the
|
|
191
|
+
next vertex; the count continues across contours. A closed contour whose last segment ends back on
|
|
192
|
+
its start point does not count that end again (it is vertex 0). In the example `M60 128` is 0,
|
|
193
|
+
`L120 128` 1, ... `L60 152` 5 and `Z` adds nothing.
|
|
194
|
+
- Bind-time: the shape's own `transform` is folded into the bind; do not animate a skinned
|
|
195
|
+
shape's own transform (lint `skin.ownTransform`), move the bones instead.
|
|
196
|
+
- Image meshes: `<xt-mesh id href width height xt-skin?>` inside the `<svg>`, with
|
|
197
|
+
`<xt-pins>x,y x,y ...</xt-pins>` (group coordinates; the first four are the image corners) and
|
|
198
|
+
optionally `<xt-tris>` (pin indices; leave it out and the compiler triangulates). A mesh's
|
|
199
|
+
`<xt-weights>` has only the p column, one line per pin. Meshes are not exported to Lottie.
|
|
200
|
+
- Animate bones like any layer: `#Mascot/Head { 0s { transform: translate(60px, 0px)
|
|
201
|
+
rotate(-8deg) } 1s { transform: translate(60px, 0px) rotate(8deg) } }` in an `@timeline`
|
|
202
|
+
(give the rest translate; a child bone's translate is ignored at runtime).
|
|
203
|
+
- Bones publish out ports `<bone id>.world` (vec2, screen coordinates) and `<bone id>.angle`
|
|
204
|
+
(screen angle): `bind:translate-x="Head.world | x"` on another element follows the bone (a
|
|
205
|
+
rigid attachment; that is how a separate `<svg>` rides on a bone). `world-anchor="<port>"` on a
|
|
206
|
+
bone takes a screen point from the game: a root bone moves there, a child bone reaches for it
|
|
207
|
+
(two-bone IK). `bind:rotate="<port>"` on a bone sets its angle.
|
|
208
|
+
|
|
209
|
+
Rules:
|
|
210
|
+
|
|
211
|
+
1. **Bones first, weights second.** Write the skeleton and its rest pose, then the weights; the
|
|
212
|
+
weights are meaningless until the bones sit where the shape is.
|
|
213
|
+
2. **Let the editor make the weights.** Write `xt-skin` with a minimal
|
|
214
|
+
`<xt-weights bones="<root bone id>">0 0:1</xt-weights>` (unlisted vertices go to the first
|
|
215
|
+
bone), then bind with auto weights in the editor (xtui-editor `skin.bind`) and fine-tune with
|
|
216
|
+
`skin.set` / Smooth / Prune. Hand-written weights are for
|
|
217
|
+
small shapes and rigid parts only.
|
|
218
|
+
3. **Springs for follow-through.** Hair, ears, tails, antennae: a child bone with
|
|
219
|
+
`<xt-constraint kind="spring">` follows its parent's motion; key only the parent.
|