@xtframe/skills 0.0.0-stage → 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.
Files changed (36) hide show
  1. package/README.md +22 -2
  2. package/package.json +41 -4
  3. package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
  4. package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
  5. package/payload/plugins/xtframe/gemini-extension.json +5 -0
  6. package/payload/plugins/xtframe/skills/xtui/SKILL.md +245 -0
  7. package/payload/plugins/xtframe/skills/xtui/references/canvas.md +93 -0
  8. package/payload/plugins/xtframe/skills/xtui/references/dialect.md +874 -0
  9. package/payload/plugins/xtframe/skills/xtui/references/flow.md +339 -0
  10. package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
  11. package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
  12. package/payload/plugins/xtframe/skills/xtui/references/performance.md +182 -0
  13. package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
  14. package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +404 -0
  15. package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
  16. package/payload/plugins/xtframe/skills/xtui/references/tokens.json +101 -0
  17. package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +170 -0
  18. package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +141 -0
  19. package/payload/plugins/xtframe/skills/xtui/references/vector.md +223 -0
  20. package/payload/plugins/xtframe/skills/xtui/references/verify.md +349 -0
  21. package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +219 -0
  22. package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
  23. package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +988 -0
  24. package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
  25. package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +211 -0
  26. package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +175 -0
  27. package/src/agents.mjs +73 -0
  28. package/src/bin.mjs +4 -0
  29. package/src/cli.mjs +286 -0
  30. package/src/converter.mjs +73 -0
  31. package/src/fsutil.mjs +76 -0
  32. package/src/install.mjs +154 -0
  33. package/src/packs.mjs +150 -0
  34. package/src/plugins.mjs +109 -0
  35. package/src/proc.mjs +66 -0
  36. package/src/tar.mjs +103 -0
@@ -0,0 +1,101 @@
1
+ {
2
+ "name": "XTFrame game UI",
3
+ "version": 1,
4
+ "themes": {
5
+ "base": {
6
+ "bg": "#e6e2d6",
7
+ "panel": "#ece8dd",
8
+ "panelBorder": "#1f1c18",
9
+ "text": "#1f1c18",
10
+ "textDim": "#4a463f",
11
+ "accent": "#1f1c18",
12
+ "accentText": "#e6e2d6",
13
+ "success": "#3f6b43",
14
+ "danger": "#b3281e",
15
+ "warning": "#a0761f"
16
+ },
17
+ "dark": {
18
+ "bg": "#262320",
19
+ "panel": "#302c27",
20
+ "panelBorder": "#d9d3c4",
21
+ "text": "#d9d3c4",
22
+ "textDim": "#9a9386",
23
+ "accent": "#d9d3c4",
24
+ "accentText": "#262320",
25
+ "success": "#7fa877",
26
+ "danger": "#d7493b",
27
+ "warning": "#c9a24a"
28
+ }
29
+ },
30
+ "font": {
31
+ "family": "\"Noto Serif\", \"Georgia\", \"DejaVu Serif\", \"Times New Roman\"",
32
+ "displayFamily": "\"Noto Serif Display ExtraCondensed\", \"Noto Serif Display\", \"Georgia\", \"Times New Roman\"",
33
+ "label": { "size": 12, "weight": 700, "letterSpacing": 1, "transform": "uppercase" },
34
+ "body": { "size": 14, "weight": 400 },
35
+ "title": { "size": 22, "weight": 700 },
36
+ "display": { "size": 48, "weight": 700 }
37
+ },
38
+ "space": [4, 8, 12, 16, 20, 24, 32, 48],
39
+ "radius": { "chip": 0, "button": 0, "panel": 0, "tile": 0 },
40
+ "shadow": { "panel": "0 0 0 0 #00000000" },
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
+ ]
101
+ }
@@ -0,0 +1,170 @@
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
+ **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.
73
+
74
+ ## 2b. A Claude Design design system from the project
75
+
76
+ When the project has a `design/` directory and the user works in Claude Design, build the Claude
77
+ Design design system from the project first, then draw the boards with it:
78
+
79
+ ```
80
+ xtframe-design export <project> --claude-design <out dir> [--json]
81
+ ```
82
+
83
+ writes `README.md` (identity, voice, colour, type, space and shape, motion, components and
84
+ decisions of `DESIGN.md`), `tokens.json` (the shape of this skill's `references/tokens.json`:
85
+ `themes.base` is the base colour set, every other theme lists only what it changes),
86
+ `palette.json` (the colour library) and `components.md` (the symbol library). Give that folder to
87
+ Claude Design to set up its design system; boards made with it already use the project's colours,
88
+ sizes and component names. Files only: the command never talks to Claude Design. The way back is
89
+ `xtframe-design import <project> --claude-design <dir>` (or `design.importDesignSystem` in the
90
+ editor): everything comes in as drafts and existing values are never overwritten.
91
+
92
+ ## 3. Use the tokens on the board
93
+
94
+ The importer resolves `var(--x)` and `data-xt-token` from a `tokens.json`, so turn the token block
95
+ into one for the dump: a flat JSON object, token name without `--` -> value exactly as written.
96
+
97
+ ```
98
+ :root { --color-accent: #0f7b8a; --font-size-xs: 12px; --radius-button: 8px; }
99
+ ```
100
+
101
+ becomes `<dump>/project/ds/project/tokens.json`:
102
+
103
+ ```json
104
+ { "color-accent": "#0f7b8a", "font-size-xs": "12px", "radius-button": "8px" }
105
+ ```
106
+
107
+ Then write the board with those names: `color: var(--color-accent)`, or the literal value plus
108
+ `data-xt-token="color-accent"` on the element, and import with
109
+ `--tokens <dump>/project/ds/project/tokens.json` (`references/verify.md` step 3) so this file wins
110
+ over any other `ds/*/tokens.json` in the dump. A colour that is not a token is the exception: the
111
+ editor's lint reports literal colours (`lint.literalColor`).
112
+
113
+ The imported UI's own stylesheet (`<ui>/<ui>.xts`, the `.xt`'s appearance `<style src>`; tokens
114
+ are never declared in `<layout>`) declares the tokens it uses in its own `:root` block. Inside a
115
+ UI Project the same names come from `shared/tokens.xts` too; tell the user the UI's copies can be
116
+ deleted once the UI lives in the project (the compiler warns about a token declared twice).
117
+
118
+ ## 3b. Mobile UI (phones and tablets)
119
+
120
+ A project for phones has `spec.platforms` with a `mobile` entry (e.g. 1080x2400), `spec.input`
121
+ `touch` and usually `"uiscaleRule": "shortEdge"` (uiscale = the short screen edge / 1080, so a
122
+ portrait phone scales by its width). When the user asks for a phone UI:
123
+
124
+ - **Portrait.** Draw the board 1080 wide and 2400 tall (Phone 20:9); the editor's device presets
125
+ are Phone 20:9 (1080x2400), Phone 19.5:9 (1170x2532) and Tablet 16:10 (2560x1600).
126
+ - **Safe area.** Keep the status bar / notch and the home indicator clear: on a phone about 4% of
127
+ the height at the top and 3% at the bottom. Bars stick to the edges and pad by the inset
128
+ (`padding-top: 1safe-top`, `bottom: calc(1safe-bottom + 24px)`), never by a fixed number.
129
+ - **Touch sizes.** Nothing tappable under 44 px (`--touch-min`); main actions 88 px
130
+ (`--touch-lg`). Leave at least 8 px between targets. No hover-only affordances.
131
+ - **Thumb zones.** Movement bottom-left, actions bottom-right, status along the top, menus in a
132
+ bottom sheet or a bottom tab bar.
133
+ - **Standard mobile symbols** (`Assets/Symbols/groups/broadsheet-2026/mobile/`, linked like the others as
134
+ `shared/symbols/<Name>.xt`; draw the board element with `data-xt-symbol` of the same name):
135
+ VirtualJoystick (`axis: vec2 out`, `dead`), TouchButton (`pressed`, `held`, `repeat`,
136
+ `cooldown`; slots icon, label), DPad (`dir`, `axis`), SwipeCard (`swipe`, `direction`),
137
+ BottomSheet (`open`; Collapsed / Expanded; slots title, content), TabBar (`value`, `select`;
138
+ 3-5 tabs), TopBar (slots left, title, right), PullIndicator (`progress`), ToggleTouch,
139
+ SliderTouch and PinchZoomView (`scale`, `min`, `max`, `pinch`). Toast stays the toast.
140
+ - The example project `Examples/demos/mobile-hud/` (Mobile HUD demo.xtui) shows a portrait HUD and
141
+ a settings sheet built from them.
142
+
143
+ ## 3c. Image compression when publishing
144
+
145
+ `<name>.xtui` `publish.images.compress` decides how `xtframe-pack` (and the editor's Publish)
146
+ writes bitmaps into the Bundle (10 §10.13; T-687):
147
+
148
+ ```json
149
+ "publish": { "images": { "compress": "auto" } }
150
+ ```
151
+
152
+ - `none` -- the default, also when the key is missing: images are packed as they are.
153
+ - `bc7` -- every bitmap and atlas page becomes a BC7 DDS.
154
+ - `auto` -- BC7 only for images and atlas pages with both sides at least 256 px; smaller ones stay
155
+ as they are.
156
+
157
+ Any other value makes the project fail to load. `xtframe-pack --compress` overrides the key for one
158
+ run (`references/verify.md`, **Packing a Bundle**); one asset can opt out with `compress: none` in
159
+ `manifest/assets.yaml`. With compression on, every packed DDS carries its full mip chain whatever
160
+ `publish.atlas.mipmaps` says (that setting no longer affects compressed images). The layout keeps
161
+ each image's own size. When to use which: `references/performance.md`, **Images**. The key is the
162
+ project's setting (section 4): suggest it to the user before a publish, do not write it yourself.
163
+
164
+ ## 4. What not to do
165
+
166
+ - Do not edit anything under `<project>` except through the import (`xtframe-import dc -o ...`):
167
+ tokens, contracts, conventions and symbols are the humans' (or `xtui-editor`'s) to change.
168
+ - Do not invent tokens. When the board needs a colour the project does not have, use the closest
169
+ token and list the gap in your report.
170
+ - Do not copy `references/tokens.json` into a dump that belongs to a UI Project.
@@ -0,0 +1,141 @@
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`. 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.
72
+
73
+ ## 6. Verify
74
+
75
+ All of `references/verify.md` steps 2-5, and the upgrade is done only when:
76
+
77
+ - the lint has **0** findings left that you can fix on the board (list any you deliberately keep);
78
+ - every UI compiles with **0** errors (`xtframe-compile`; list the warnings);
79
+ - screenshots at the aspect set (`references/responsive.md` section 4; at least 16:9 at the board
80
+ size and 21:9 for a non-responsive request) look like the board;
81
+ - the flow still runs (`xtframe-view` prints `loaded flow`; click/hover paths you changed behave).
82
+
83
+ ## 7. Report what you did not change
84
+
85
+ An upgrade fixes structure, not the design. Say which of these you saw and left alone, so the user
86
+ decides:
87
+
88
+ - `motion.ambient` (looping ambient animations) outside the project's motion spec;
89
+ - animations of `left` / `top` (they work, but `transform` is cheaper and a dock may be needed);
90
+ - text under the project's minimum font size;
91
+ - literal colours that should be tokens, tokens declared twice, or missing tokens;
92
+ - files in `<project>` or the dump no UI references (old screenshots, unused images);
93
+ - anything you backed up and where the backup is.
94
+
95
+ ## 8. Source format 1 -> 2
96
+
97
+ A UI Project written before source format 2 (Docs/design/54) has `.xt` files without
98
+ `<xt version="2">`: ports as `port:` attributes on `<body>` or the root element, `<link href>` in
99
+ the `<head>`, geometry and appearance mixed in the `.xts`, `@timeline` and `on-<event>` rules in
100
+ the `.xts`. They still compile (the format 1 reader stays until 1.0), but the editor writes only
101
+ format 2 and the current import writes format 2, so a project is upgraded **once, as a whole**
102
+ (a `.xts` linked by both a format 1 and a format 2 file is checked by the format 2 rules):
103
+
104
+ 1. Back up (section 1); the migration writes in place and keeps no backup of its own (git is the
105
+ backup).
106
+ 2. Dry run into a scratch directory and read the report:
107
+
108
+ ```
109
+ xtframe-compile --migrate <project> -o <scratch dir> --anchors --report <scratch>/migrate.json
110
+ ```
111
+
112
+ prints `migrate: N files (N migrated, 0 skipped, 0 with errors); R rules split, A anchors, I ids
113
+ assigned` and the self-check `layer two N equal, 0 differ`. `-o` writes only the rewritten
114
+ files. `--anchors` also turns the three `calc(1safe-...)` anchoring forms into
115
+ `anchor` / `offset` / `size` (what it cannot express stays long-hand).
116
+ 3. When the report has **0 with errors** and **0 differ**, run it in place: the same command
117
+ without `-o` (it writes only when everything is green and exits 1 otherwise). The packer does
118
+ the same with `xtframe-pack --upgrade --format 2 <project>`. The editor is specified to offer
119
+ the same upgrade when it opens a format 1 project (54 §54.10); when your editor build does not
120
+ ask, run the command.
121
+ 4. Re-run section 6 (compile, screenshots, flow).
122
+
123
+ What it does per `.xt` and every `.xts` / symbol library it links (54 §54.10): `<link href>` ->
124
+ `<style src>`, `<link rel="symbols">` -> `<symbols src>`; `port:` -> `<ports>` (declaration order
125
+ kept); `@timeline` -> `<timelines>`; `on-<event>` rules -> `on:<event>` on the element or
126
+ `on:<event>@<inner path>` on the `<use>`, `state-enter` / `state-exit` -> `on:state(X).enter` /
127
+ `.exit`; every rule split by the Section column of `style-groups.md`, **selectors unchanged** (one
128
+ rule can become two, one per section); a linked `<stem>.xts` becomes `<stem>.xts` (appearance) plus
129
+ `<stem>.layout.xts` / `<stem>.timelines.xts`, each pulled in by its own section; inline `style=`
130
+ geometry -> an `#id` rule in `<layout>` (an element without an id gets one); flow endpoints
131
+ `#<root id>.<port>` in the UI's `.xtflow` -> `#document.<port>`. The guarantee: every element's
132
+ computed style, in every pseudo-class combination and every `@media` case, is the same as before
133
+ (`xtframe-compile <ui>.xt --dump-computed` prints it), so the pixels are the same; the `.xtir`
134
+ bytes may differ (a split rule is two style rules).
135
+
136
+ The migrated files keep the project's own file layout (`<ui>.layout.xts` beside the `.xt`); a
137
+ later `--force` re-import from the board writes the import's layout instead (`<layout>` and
138
+ `<timelines>` inline in the `.xt`, the appearance in `<ui>.xts`; `references/dialect.md`, **What
139
+ the import writes**). Both are format 2. Migration errors (a trigger rule inside `@media` or
140
+ under a pseudo-class, a port declared deeper than the root) are listed per file: fix those on
141
+ the board and re-import instead.
@@ -0,0 +1,223 @@
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. 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.
38
+ 6. **Prefer declarative motion to hand-computed keyframes.** Use `path-trim` for strokes that
39
+ draw on, `transform` / `opacity` on shapes, and `d` keyframes only for real morphs. A morph
40
+ needs the same number of vertices in every keyframe.
41
+ 7. **Case is kept inside `<svg>`** (24 §24.14.4): tag and attribute names such as
42
+ `linearGradient`, `viewBox` and `gradientUnits` arrive as written (`data-*` names stay lower
43
+ case).
44
+ 8. **Intent tags on the `<svg>` and its shapes** (24 §24.14.4, T-565 record):
45
+ - `data-xt-timeline` on a **shape** becomes a `#<svg id>/<shape id>` track of that `@timeline`
46
+ (the shape needs an `id`; none is made up for it), with the vector properties (`fill`,
47
+ `stroke`, `path-trim-*`, `d`, `transform`, `opacity` …).
48
+ - `data-xt-timeline` on the **`<svg>` itself** takes only `transform`, `opacity` and
49
+ `visibility`; a vector property there is dropped and reported (`svg.unsupported`) -- move it to
50
+ the shape.
51
+ - `data-xt-bind`, `data-xt-trigger` and `data-xt-state` on the `<svg>` work as on any element;
52
+ a state element's shape differences become `#btn:hover #icon/blade` style rules.
53
+ - `data-xt-symbol`, `data-xt-slot`, `data-xt-glyph` and `data-xt-rich` on an `<svg>` are not
54
+ possible and are reported as `svg.unsupported` (the fix names the attribute or
55
+ `data-xt-vector`).
56
+
57
+ ## Examples
58
+
59
+ Icon, a shield with two shapes:
60
+
61
+ ```html
62
+ <svg id="icon-shield" viewBox="0 0 24 24" style="width:24px;height:24px">
63
+ <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"/>
64
+ <path id="Mark" d="M8 12 L11 15 L16 9" fill="none" stroke="#ffffff" stroke-width="2"
65
+ stroke-linecap="round" stroke-linejoin="round"/>
66
+ </svg>
67
+ ```
68
+
69
+ Progress ring driven by `path-trim` (0..1 of the stroke's length). Bind or animate
70
+ `path-trim-end`:
71
+
72
+ ```html
73
+ <svg id="Progress" viewBox="0 0 64 64" style="width:64px;height:64px">
74
+ <circle id="Track" cx="32" cy="32" r="28" fill="none" stroke="#2a2f3a" stroke-width="6"/>
75
+ <circle id="Ring" cx="32" cy="32" r="28" fill="none" stroke="#2f81f7" stroke-width="6"
76
+ stroke-linecap="round" path-trim="0 0.65" transform="rotate(-90 32 32)"/>
77
+ </svg>
78
+ ```
79
+
80
+ ```css
81
+ /* in the UI's .xts after import */
82
+ @timeline intro {
83
+ #Progress/Ring { 0s { path-trim-end: 0 } 0.8s ease-out { path-trim-end: 0.65 } }
84
+ }
85
+ ```
86
+
87
+ Hover colour change on one shape (scene-target rule plus transition; the pseudo-class sits on
88
+ an ancestor, here the button holding the icon):
89
+
90
+ ```css
91
+ #icon-shield/Body { fill: var(--color-accent); transition: fill 0.15s ease-out; }
92
+ #btn-shield:hover #icon-shield/Body { fill: var(--color-accent-hover); }
93
+ ```
94
+
95
+ A star badge:
96
+
97
+ ```html
98
+ <svg id="Badge" viewBox="0 0 40 40" style="width:40px;height:40px">
99
+ <xt-star id="Star" cx="20" cy="20" points="5" r="18" r2="8" round="0.3" fill="#f5c542"/>
100
+ </svg>
101
+ ```
102
+
103
+ ## Cel animation (frame by frame)
104
+
105
+ For hand-drawn loops (a flame, a spark, a blinking eye), mark the `<svg>` with `data-xt-cels="1"`
106
+ and put one `<g>` per drawing. The `<g>`s are the cels, in order, and only one shows at a time.
107
+ Give every cel an id (`Cel_1`, `Cel_2`, ...). Its timing lives in the `.xt`'s `<timelines>`
108
+ section as `visibility` hold keys, one track per cel, all `steps(1, end)`: cel i is visible from
109
+ `t_i` until `t_(i+1)`.
110
+
111
+ ```html
112
+ <svg id="Flame" viewBox="0 0 32 32" style="width:32px;height:32px" data-xt-cels="1">
113
+ <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>
114
+ <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>
115
+ <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>
116
+ </svg>
117
+ ```
118
+
119
+ ```css
120
+ /* in the .xt's <timelines> after import: three cels of 4 frames at 24 fps, looped by the trigger */
121
+ @timeline idle {
122
+ duration: 0.5s;
123
+ #Flame/Cel_1 { 0s steps(1, end) { visibility: visible } 0.167s steps(1, end) { visibility: hidden } }
124
+ #Flame/Cel_2 { 0s steps(1, end) { visibility: hidden } 0.167s steps(1, end) { visibility: visible }
125
+ 0.333s steps(1, end) { visibility: hidden } }
126
+ #Flame/Cel_3 { 0s steps(1, end) { visibility: hidden } 0.333s steps(1, end) { visibility: visible }
127
+ 0.5s steps(1, end) { visibility: hidden } }
128
+ }
129
+ ```
130
+
131
+ Without the `@timeline` block the editor shows equal cels over the timeline and writes the keys on
132
+ the first cel edit (xtui-editor: `cel.list`, `cel.add`, `cel.setRange`). A cel group can also be
133
+ a plain container (`<div data-xt-cels="1">` with one child container per cel); then the tracks
134
+ are `#<cel id>`.
135
+
136
+
137
+ ## Skeletons and skinning (bones, weights, image meshes)
138
+
139
+ For a mascot, a breathing portrait or a small character reaction (nod, blink, hit), put a
140
+ skeleton inside the `<svg>` and skin the shapes to it. Bones bend the shapes; the editor and
141
+ the runtime do the deformation. This is not a Spine replacement: no skins, one skeleton per
142
+ character, at most 4 bones per vertex.
143
+
144
+ Pose vs rest: a bone's `rotate` / `translate` / `scale` / `length` are its current static
145
+ pose. The optional `rest-rotate` / `rest-translate` / `rest-scale` / `rest-length` are the bind
146
+ pose the weights were computed against (default: the same values). Write only the pose
147
+ attributes; the editor writes `rest-*` when it binds. To ship a character already posed, keep
148
+ `rest-*` at the bind pose and change the plain attributes. An image mesh takes `x` / `y`
149
+ (image origin, default 0) and `transform` like any shape; its pins are in that local space.
150
+
151
+ Write, inside the `<svg>` (close every element explicitly; the board is HTML):
152
+
153
+ ```html
154
+ <svg id="Mascot" viewBox="0 0 200 200" style="width:200px;height:200px">
155
+ <path id="Body" d="M60 128 L120 128 L180 128 L180 152 L120 152 L60 152 Z" fill="#3366cc"
156
+ xt-skin="Rig">
157
+ <xt-weights bones="Spine Head" version="1">
158
+ 0 0:1
159
+ 1 0:.5 1:.5
160
+ 2 1:1
161
+ 3 1:1
162
+ 4 0:.5 1:.5
163
+ 5 0:1
164
+ </xt-weights>
165
+ </path>
166
+ <xt-skeleton id="Rig">
167
+ <xt-bone id="Spine" length="60" translate="60 140">
168
+ <xt-bone id="Head" length="60">
169
+ <xt-constraint id="Reach" kind="ik" target="#Paw"></xt-constraint>
170
+ </xt-bone>
171
+ </xt-bone>
172
+ </xt-skeleton>
173
+ <circle id="Paw" cx="0" cy="0" r="5" fill="#dd2222" transform="translate(170 100)"></circle>
174
+ </svg>
175
+ ```
176
+
177
+ - `<xt-skeleton id>`: no transform of its own (it is ignored with a warning). Its space is the
178
+ `<svg>`'s group space; one `<svg>` per skinned character.
179
+ - `<xt-bone id length rotate? translate? scale?>`: only a root bone takes `translate` (its
180
+ origin, group coordinates); a child bone always starts at its parent's tip. `rotate` is in
181
+ degrees relative to the parent (y points down, so positive turns clockwise). These attribute
182
+ values are the rest pose.
183
+ - `<xt-constraint kind target ...>` under a bone, applied in document order: `ik` (`target`,
184
+ `strength` 0..1, `invert` 0/1 bend direction, `chain` default 2), `transform` / `rotation`
185
+ (`target`, `mix`, `space="local|world"`), `spring` (no target; `inertia`, `strength`,
186
+ `damping`, `gravity`, `mix`). `target` is `#id` of an element in the same `<svg>`.
187
+ - `xt-skin="<skeleton id>"` on a `<path>` (not on `<rect>` / `<circle>` / `<xt-star>`; write them
188
+ as a `<path>` to skin them) plus one `<xt-weights bones="<bone ids>">` child. Each line is
189
+ `<vertex> <p weights> [| <in weights> [| <out weights>]]`, a weight is `<bone index>:<weight>`
190
+ (an index into `bones`), at most 4 per column; weights are normalized when compiled. `=` or a
191
+ missing column means "same as p" (most vertices). A vertex without a line goes all to the
192
+ first bone.
193
+ - **Vertex order** (the `<vertex>` numbers): count the on-curve points of `d` contour by
194
+ contour. The `M` point is vertex 0 of its contour, every following segment's end point the
195
+ next vertex; the count continues across contours. A closed contour whose last segment ends back on
196
+ its start point does not count that end again (it is vertex 0). In the example `M60 128` is 0,
197
+ `L120 128` 1, ... `L60 152` 5 and `Z` adds nothing.
198
+ - Bind-time: the shape's own `transform` is folded into the bind; do not animate a skinned
199
+ shape's own transform (lint `skin.ownTransform`), move the bones instead.
200
+ - Image meshes: `<xt-mesh id href width height xt-skin?>` inside the `<svg>`, with
201
+ `<xt-pins>x,y x,y ...</xt-pins>` (group coordinates; the first four are the image corners) and
202
+ optionally `<xt-tris>` (pin indices; leave it out and the compiler triangulates). A mesh's
203
+ `<xt-weights>` has only the p column, one line per pin. Meshes are not exported to Lottie.
204
+ - Animate bones like any layer: `#Mascot/Head { 0s { transform: translate(60px, 0px)
205
+ rotate(-8deg) } 1s { transform: translate(60px, 0px) rotate(8deg) } }` in an `@timeline`
206
+ (give the rest translate; a child bone's translate is ignored at runtime).
207
+ - Bones publish out ports `<bone id>.world` (vec2, screen coordinates) and `<bone id>.angle`
208
+ (screen angle): `bind:translate-x="Head.world | x"` on another element follows the bone (a
209
+ rigid attachment; that is how a separate `<svg>` rides on a bone). `world-anchor="<port>"` on a
210
+ bone takes a screen point from the game: a root bone moves there, a child bone reaches for it
211
+ (two-bone IK). `bind:rotate="<port>"` on a bone sets its angle.
212
+
213
+ Rules:
214
+
215
+ 1. **Bones first, weights second.** Write the skeleton and its rest pose, then the weights; the
216
+ weights are meaningless until the bones sit where the shape is.
217
+ 2. **Let the editor make the weights.** Write `xt-skin` with a minimal
218
+ `<xt-weights bones="<root bone id>">0 0:1</xt-weights>` (unlisted vertices go to the first
219
+ bone), then bind with auto weights in the editor (xtui-editor `skin.bind`) and fine-tune with
220
+ `skin.set` / Smooth / Prune. Hand-written weights are for
221
+ small shapes and rigid parts only.
222
+ 3. **Springs for follow-through.** Hair, ears, tails, antennae: a child bone with
223
+ `<xt-constraint kind="spring">` follows its parent's motion; key only the parent.