@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
package/README.md CHANGED
@@ -1,3 +1,23 @@
1
- # Temporary Holding Version
1
+ # @xtframe/skills
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Search for XTFrame agent skills and install them, with the XTFrame converter, into every coding
4
+ agent on this machine.
5
+
6
+ ```
7
+ npx @xtframe/skills install # all skills -> every detected agent, plus @xtframe/converter (npm -g)
8
+ npx @xtframe/skills install --plugin # Claude Code / Copilot CLI: as a plugin (/xtframe:xtui)
9
+ npx @xtframe/skills install xtui --agent codex,gemini-cli --project
10
+ npx @xtframe/skills search [words] # packs on npm with the keyword xtframe-skill-pack
11
+ npx @xtframe/skills list | update [--tag next] | remove [skill...] | agents | doctor
12
+ ```
13
+
14
+ Skills bundled with this version: `xtui` (make a game UI from a board and convert it with
15
+ `xtframe-import`) and `xtui-editor` (change a UI open in the XTFrame editor). The package version
16
+ is the XTFrame release they come from.
17
+
18
+ Every copy is recorded in `~/.xtframe/skills-lock.json`; `update` and `remove` touch only those
19
+ copies and keep folders you edited unless you pass `--force`. Folders this tool did not install
20
+ are never replaced without `--force`. `--dry-run` shows what would happen.
21
+
22
+ Add agents or correct a path in `~/.xtframe/agents.json`:
23
+ `[{ "id": "my-agent", "name": "My Agent", "detect": ["~/.my-agent"], "global": "~/.my-agent/skills", "project": ".my-agent/skills" }]`.
package/package.json CHANGED
@@ -1,6 +1,43 @@
1
1
  {
2
2
  "name": "@xtframe/skills",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.19.1",
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
+ "type": "module",
6
+ "bin": {
7
+ "xtframe-skills": "src/bin.mjs"
8
+ },
9
+ "files": [
10
+ "src/",
11
+ "payload/",
12
+ "README.md"
13
+ ],
14
+ "engines": {
15
+ "node": ">=20"
16
+ },
17
+ "keywords": [
18
+ "xtframe",
19
+ "xtframe-skills",
20
+ "xtframe-skill-pack",
21
+ "xtui",
22
+ "agent-skills",
23
+ "claude-code",
24
+ "codex",
25
+ "gemini-cli",
26
+ "skills"
27
+ ],
28
+ "xtframe": {
29
+ "skills": "payload/plugins/xtframe/skills",
30
+ "plugin": "payload/plugins/xtframe",
31
+ "converter": "@xtframe/converter",
32
+ "catalog": [
33
+ {
34
+ "name": "xtui",
35
+ "description": "Make a new XTFrame game UI (HUD, menu, screen), or redo one from its board, by writing the board (.dc.html in the XTFrame dialect, with data-xt-* tags for symbols, states, triggers, timelines, ports and bindings) and converting it with xtframe-import (checks for the converter first; without one - e.g. a cloud session - it delivers the importable board dump plus the import command instead) - from a text description, a Claude Design canvas URL (claude.ai artifact), a local board dump (project/canvas.json) or a UI Project directory (holding a .xtui); it lints, imports, compiles, screenshots and ends with the result open in the XTFrame editor. Not for changing a UI that is already open in the running XTFrame editor (panels, timeline, symbols, scenarios, service.json present) - use xtui-editor for that."
36
+ },
37
+ {
38
+ "name": "xtui-editor",
39
+ "description": "Change a UI that is open in the XTFrame editor, through the editor itself (the Editor Service, over xtframe-mcp or a headless editor) - layers, styles and tokens, timelines and keyframes, triggers, states, symbols, ports and bindings, effects, anchors, re-import, symbol libraries (use a group, import a set, save a group), with scene dumps, lint and screenshots as feedback, one of 14 scenario contracts and a checkpoint per change; it never writes .xt/.xts/.dc.html files. Use it when the user wants \"this UI\" in the editor changed, mentions panels, the timeline, symbols or scenarios, or the editor is running (service.json present). To make a new UI or import from Claude Design, use xtui instead."
40
+ }
41
+ ]
42
+ }
43
+ }
@@ -0,0 +1,17 @@
1
+ {
2
+ "name": "xtframe",
3
+ "version": "0.19.1",
4
+ "description": "XTFrame game UI skills: make a UI from a board (xtui) and change a UI open in the XTFrame editor (xtui-editor).",
5
+ "author": {
6
+ "name": "XTFrame"
7
+ },
8
+ "homepage": "https://github.com/shereware/xtframe-skills",
9
+ "repository": "https://github.com/shereware/xtframe-skills",
10
+ "keywords": [
11
+ "xtframe",
12
+ "game-ui",
13
+ "hud",
14
+ "ui-editor",
15
+ "skills"
16
+ ]
17
+ }
@@ -0,0 +1,11 @@
1
+ {
2
+ "name": "xtframe",
3
+ "version": "0.19.1",
4
+ "description": "XTFrame game UI skills: make a UI from a board (xtui) and change a UI open in the XTFrame editor (xtui-editor).",
5
+ "skills": "./skills/",
6
+ "interface": {
7
+ "displayName": "XTFrame",
8
+ "shortDescription": "Game UI from a board, or edited in the XTFrame editor",
9
+ "category": "Design"
10
+ }
11
+ }
@@ -0,0 +1,5 @@
1
+ {
2
+ "name": "xtframe",
3
+ "version": "0.19.1",
4
+ "description": "XTFrame game UI skills: make a UI from a board (xtui) and change a UI open in the XTFrame editor (xtui-editor)."
5
+ }
@@ -0,0 +1,245 @@
1
+ ---
2
+ name: xtui
3
+ description: Make a new XTFrame game UI (HUD, menu, screen), or redo one from its board, by writing the board (.dc.html in the XTFrame dialect, with data-xt-* tags for symbols, states, triggers, timelines, ports and bindings) and converting it with xtframe-import (checks for the converter first; without one - e.g. a cloud session - it delivers the importable board dump plus the import command instead) - from a text description, a Claude Design canvas URL (claude.ai artifact), a local board dump (project/canvas.json) or a UI Project directory (holding a .xtui); it lints, imports, compiles, screenshots and ends with the result open in the XTFrame editor. Not for changing a UI that is already open in the running XTFrame editor (panels, timeline, symbols, scenarios, service.json present) - use xtui-editor for that.
4
+ ---
5
+
6
+ # xtui
7
+
8
+ The board skill: every XTFrame UI that is **made from a board**. The **board**
9
+ (`<dump>/project/*.dc.html`, HTML/CSS in the XTFrame dialect plus `data-xt-*` intent tags) is the
10
+ source of truth; `xtframe-import dc` turns it into a **UI Project** (`<name>.xtui`,
11
+ `<ui>/<ui>.xt` + `.xts`, `shared/`, `import-report.json`; source format 2: the `.xt` holds the
12
+ ports, elements, layout and timelines, the `.xts` the look -- `references/dialect.md`, **What the
13
+ import writes**) -- the editable source. A **Bundle** (the
14
+ published form a game loads) is made from it by `xtframe-pack`; this skill does not need one. This skill never talks to the editor: it writes the
15
+ board and converts it. Changing a UI inside the running editor is the `xtui-editor` skill (the
16
+ Editor Service); see the last section. Details live in `references/`: **read the named reference
17
+ before doing the step**, not after.
18
+
19
+ | Reference | Holds |
20
+ |---|---|
21
+ | `references/not-like-web.md` | **read first**: where XTFrame differs from HTML/CSS (box model, `display`, `layer`, bindings, lists, symbols, keyboard, `@media`, `emit`) and how to write list items |
22
+ | `references/dialect.md` | what a board may contain (elements, properties, units, ids) and the `data-xt-*` intent tags |
23
+ | `references/ui-project.md` | when the UI belongs to a UI Project: its tokens, contracts and conventions come first |
24
+ | `references/tokens.json` | colours, type scale, spacing, radii, board size (only without a UI Project); generated by `xtframe-symbols tokens-json <group dir>` from the symbol group's tokens, the shipped copy being the preset `broadsheet-2026` group's -- regenerate it for the group you chose (section 1b) |
25
+ | `references/template.dc.html` | a working board to start from (lints clean, 16 high-fidelity nodes) |
26
+ | `references/canvas.md` | Claude Design canvas: create one and write the board on it, or read one back |
27
+ | `references/verify.md` | lint, import, compile, screenshot, report, open the editor |
28
+ | `references/flow.md` | cross-UI logic or computation: the `<ui>.xtflow` signal graph |
29
+ | `references/responsive.md` | "fit any window", other aspects: the uiscale rule (`data-xt-uiscale`), full-bleed positions, dock wrappers, the aspect check set |
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
+ | `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
+ | `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 |
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) |
35
+
36
+ The user never has to know the dialect, pick a tool or fix a lint finding. Compliance is your job:
37
+ if the lint or the compile complains, fix the board and run again (at most three rounds, see
38
+ `references/verify.md`).
39
+
40
+ ## 0. Locate XTFrame
41
+
42
+ Find the XTFrame checkout `<xtframe>`: the directory holding `Docs/design/00-overview.md` (ask the
43
+ user if it is not the current directory or an obvious parent). The converters (`xtframe-import`,
44
+ `xtframe-compile`, `xtframe-view`) are used from PATH when they are on it (installed by the npm
45
+ converter package from the skills repo (see the shereware/xtframe-skills README) or the
46
+ `xtframe-tools` plugin; no checkout needed), otherwise from
47
+ `<xtframe>/bin/win_x64/Release/`. Build whichever of them is missing, from `<xtframe>`, naming only
48
+ the targets to build (`Tools/Scripts/dev_check.sh` builds what it is given and runs no suite after
49
+ the `--`):
50
+
51
+ ```
52
+ bash Tools/Scripts/dev_check.sh --release xtframe-import xtframe-view xtframe-compile --
53
+ bash Tools/Scripts/dev_check.sh --release xtframe-editor -- # needs XT_QT_DIR (a Qt install)
54
+ ```
55
+
56
+ `xtframe-editor` is only needed for the last step; `references/verify.md` step 8 covers a missing
57
+ Qt.
58
+
59
+ **Check the converter before you start, not after you wrote the board.** Decide the mode now:
60
+
61
+ - **Convert mode** -- `xtframe-import`, `xtframe-compile` and `xtframe-view` are on PATH (the npm
62
+ converter package from the skills repo (see the shereware/xtframe-skills README) or the
63
+ `xtframe-tools` plugin; no XTFrame checkout needed; the package's `xtframe-import` may be the
64
+ Node.js/wasm build, which behaves exactly like the native one), or
65
+ `xtframe-import` exists under `<xtframe>/bin/win_x64/Release/`,
66
+ or the checkout is here with a working C++ toolchain and you can build it (try the
67
+ `dev_check.sh` line once; a missing compiler, CMake or network for FetchContent means no).
68
+ Then every entry ends in `references/verify.md` as usual.
69
+ - **Deliver mode** -- no converters on PATH, no XTFrame checkout, no build tree and no way to
70
+ build (typical of a cloud or sandboxed session, or a machine that only has the user's game).
71
+ Do not try to emulate the converter and never hand-write `.xt` / `.xts`: write the board exactly
72
+ as in convert mode, then deliver the **importable dump** (`references/verify.md` "Deliver mode").
73
+ Say which mode you are in once, up front.
74
+
75
+ ## 1. Decide the entry
76
+
77
+ First, if the editor is running with this UI open (`%LOCALAPPDATA%/XTFrame/service.json` exists
78
+ and the user talks about "this UI", a panel, the timeline or a symbol in it), stop: that is
79
+ `xtui-editor`. Otherwise look at what the user gave you and take exactly one row. Before writing
80
+ or changing any board, look for a UI Project (`references/ui-project.md` step 1); when there is
81
+ one, its tokens and conventions replace `references/tokens.json`.
82
+
83
+ | Input | Do this first | Then |
84
+ |---|---|---|
85
+ | A text description ("a HUD with a health bar and an ammo counter") | Read `references/not-like-web.md`, `references/dialect.md`, the tokens (`references/ui-project.md`, else `references/tokens.json`) and `references/template.dc.html`, then write a **local** board (below). Asked to fit any window or several aspects: also `references/responsive.md`. Only if the user wants to see or edit it in Claude Design: read `references/canvas.md` (a) instead. | step 2 |
86
+ | A `claude.ai/.../artifact/...` URL (a canvas) | Read `references/canvas.md` (b) and download it into a local dump. | step 2 |
87
+ | A directory holding `project/canvas.json` | Nothing to fetch: it already is a dump. | step 2 |
88
+ | A directory holding a `.xtui` (or an old `ui-project.json` / `bundle.xtproj`) | Find its board: the dump it was imported from (ask if unknown). Read `references/not-like-web.md` and `references/dialect.md`, change the `.dc.html`, never the generated `.xt` / `.xts`. Asked to upgrade or modernize it: follow `references/upgrade.md`; asked to make it responsive: `references/responsive.md`. | step 2, importing into this same UI Project directory |
89
+
90
+ ## 1b. Pick the symbol library and group
91
+
92
+ Every UI is drawn from a **symbol group** of a **symbol library** (Docs/design/49-symbol-sets.md):
93
+ the buttons, bars, lists and sheets the board instantiates with `data-xt-symbol`, with their tokens,
94
+ fonts and textures. Decide the group before writing the board, and make sure the UI Project has
95
+ its symbols:
96
+
97
+ 1. **Which library, which group.** When an editor can be reached (`xtframe-mcp --project <dir>`,
98
+ or `xtframe-mcp --spawn-headless <dir>` when none is open; `references/ui-project.md` names the
99
+ project), call `symbols_libraries`, then `symbols_library` (every mounted library with its groups
100
+ and each group's symbols, contracts and lint state). No style asked for: use the preset library's
101
+ `default` group (`broadsheet-2026`, the standard library the shipped `tokens.json` and
102
+ `template.dc.html` follow). "Use my X group": that group (`symbols_library {"library": "mine"}`
103
+ lists the user's own groups; a group whose `lint.errors` is not 0 is listed but should be fixed in
104
+ the editor first -- say so). Without any editor (deliver mode, or a machine without one),
105
+ `xtframe-symbols libraries` and `xtframe-symbols lint <group dir>` list the same; the import then
106
+ relies on the preset group, which `xtframe-import` / `xtframe-pack` resolve by themselves.
107
+ 2. **Put the group into the project before importing.** `symbols_useGroup {"group": "<id>"}` (or
108
+ `symbols_use {"names": [...]}` for the few symbols the board needs) copies the symbols, their
109
+ fonts and textures and the tokens they read into the UI Project (49.3), one undo step, inside a
110
+ `create` scenario of the editor. After that every `<symbols src>` the import writes
111
+ resolves, and the project owns its copies. Skip it when the project already has them
112
+ (`symbols_library` shows nothing new; `project_syncSymbols` lists the copies).
113
+ 3. **Draw with those names.** `data-xt-symbol` values are the group's symbol names (`symbols_get
114
+ {"name"}` has the contract: required states, slots, ports, timelines); keep the board element's
115
+ structure and slot names as the symbol has them (`references/ui-project.md` item 7).
116
+ 4. **Tokens from the group.** `xtframe-symbols tokens-json <group dir> -o
117
+ <dump>/project/ds/xtframe/tokens.json` once per group when the skill starts (cache it for the
118
+ session): the board's palette is the group's. A UI Project's own `shared/tokens.xts` still wins
119
+ (`references/ui-project.md` step 3).
120
+
121
+ This is the one place this skill talks to the editor, and only through these `symbols_*`
122
+ operations (the `xtui-editor` skill has the full list); it still writes no `.xt` / `.xts`. The
123
+ library-write operations (`symbols_import`, `symbols_saveAsGroup`, `symbols_loadPreset`, ...) are
124
+ `xtui-editor`'s `library` scenario, never part of making a UI.
125
+
126
+ **Writing a local board.** Agree on the ids first: map the description onto role names
127
+ (`hp-fill`, `btn-menu`, `panel-quest`; lowercase, digits, `-`), the root id being the UI id. Show
128
+ the table once and let the user rename before you write anything; ids are what the game and the
129
+ flow bind to. Then write under `<dump>/project/`:
130
+
131
+ - `canvas.json`, the minimal shape:
132
+
133
+ ```json
134
+ {
135
+ "name": "Authored HUD",
136
+ "boards": { "Main.dc.html": { "x": 0, "y": 0, "w": 1280, "h": 720,
137
+ "title": "Authored HUD", "page": "main" } },
138
+ "order": ["Main.dc.html"],
139
+ "pages": ["main"],
140
+ "designSystems": ["xtframe"]
141
+ }
142
+ ```
143
+
144
+ - one `<Name>.dc.html` per screen (one `boards` + one `order` entry each), started from
145
+ `references/template.dc.html`, with root `<div id="<ui-id>">` at the board size;
146
+ - `ds/xtframe/tokens.json`, a copy of `references/tokens.json` -- or, in a UI Project,
147
+ `ds/project/tokens.json` made from its `shared/tokens.xts` (`references/ui-project.md` step 3).
148
+
149
+ Write the intent with tags while you write the board (`references/dialect.md`, **Intent tags**):
150
+ `data-xt-name` on every layer that matters, `data-xt-symbol` for repeated components,
151
+ `data-xt-state` elements for hover/pressed/selected looks, `data-xt-timeline` +
152
+ `data-xt-trigger` for intro/hover animations, `data-xt-port` + `data-xt-bind` for game values,
153
+ `data-xt-anchor` for anything at a screen edge, `data-xt-token` for themed colours.
154
+
155
+ Use `{{hole}}` only where the game supplies the value, always with a `data-props` default. Images
156
+ are `<img src="/_blob/<file>">` with the file in `<dump>/_blob/`. Keep the dump: it is how the UI
157
+ changes later.
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
+
184
+ ## 2. Verify and open the editor
185
+
186
+ Convert mode: read `references/verify.md` and follow it step by step on `<dump>`: lint, import
187
+ into `<project-dir>`, compile every UI, headless screenshot, report the degradations and missing
188
+ ids. Its last step opens `<project-dir>` (its `<name>.xtui`) in `xtframe-editor` in the
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.
191
+
192
+ Deliver mode: follow `references/verify.md` "Deliver mode" instead -- self-check the board against
193
+ `references/dialect.md`, package the dump, and finish with the dump path plus the one command the
194
+ user runs where the tools are. Never claim the UI was linted, compiled or screenshotted when it
195
+ was not.
196
+
197
+ ## 3. Interactivity (when the user asks)
198
+
199
+ **Tags first.** Hover and press looks, a click that plays an animation or toggles a state, an
200
+ intro on show, a bar or a number that follows a game value, a button that sends an event to the
201
+ game: write them on the board as `data-xt-state`, `data-xt-trigger`, `data-xt-timeline`,
202
+ `data-xt-sound`, `data-xt-port` and `data-xt-bind` (`references/dialect.md`, **Intent tags**), then
203
+ re-import (step 2). The import turns them into `on:`, `@timeline` (in `<timelines>`), `:hover` /
204
+ `:state()` rules, `<ports>` lines and `bind:`; its lint (`tag.triggerWithoutTimeline`, `tag.stateNoDiff`,
205
+ `tag.portUnbound`) says what does not line up -- fix the board and import again.
206
+
207
+ **`.xtflow` only when a tag cannot say it**: logic across several UIs, or computation (counters,
208
+ timers, random, pointer parallax, a demo mode). Then read `references/flow.md`, write
209
+ `<project-dir>/<ui>/<ui>.xtflow` and check it with `xtframe-view` as it describes. When the editor
210
+ has the UI open, the flow is changed through `xtui-editor` (`flow_set`) instead. Missing authored ids
211
+ go back to the board (step 1) and through step 2 again. A re-import never overwrites the
212
+ `.xtflow`.
213
+
214
+ ## 4. Seeing or changing it in Claude Design (when the user asks)
215
+
216
+ If the user wants to look at or edit the board in Claude Design, read `references/canvas.md` (a):
217
+ it creates a canvas with the board on it and reads it back into the dump. Later canvas edits come
218
+ back through `references/canvas.md` (b) into the same dump and UI Project. Changes made in the editor
219
+ do not flow back to the board or the canvas yet; say so if the user expects it.
220
+
221
+ ## 5. After this skill: changes in the editor are `xtui-editor`
222
+
223
+ The UI Project is open in the editor now. **To keep changing it in the editor, use `xtui-editor`**:
224
+ that skill works on the open UI through the Editor Service (layers, styles, timelines, triggers,
225
+ symbols, states, scenarios, checkpoints) and never writes files; it starts by taking over (its
226
+ section 2: the work site, what the user did since, `ifRevision` on every write), because the user may
227
+ already be editing what you imported. Come back to this skill when the
228
+ board is the thing to change (a new screen, a canvas edit, a redesign), and re-import: the merge
229
+ keeps what the editor changed (`references/verify.md` step 3).
230
+
231
+ What each side reads: this skill reads and writes the board (the dump, its `.dc.html`) -- material
232
+ before the import, not an editor document. Once the UI is open in the editor, its files belong to
233
+ the editor; read them through it, not from disk:
234
+
235
+ | To read | Ask the editor with |
236
+ |---|---|
237
+ | the `.xt` / `.xts` text | `doc.source` |
238
+ | class and shared rules | `style.getRules` |
239
+ | the flow graph | `flow.get` (change it with `flow.set`) |
240
+ | the import report | `project.importReport` |
241
+ | the spec and conventions | `project.get` |
242
+ | the symbol libraries, a group's symbols, a symbol's contract, the lint of a set | `symbols.libraries`, `symbols.library`, `symbols.get`, `symbols.lint` |
243
+
244
+ After an import or re-import from the command line while the editor has the UI open, the editor
245
+ must reload it (`doc.reload`; it does so by itself when the UI has no unsaved edits).
@@ -0,0 +1,93 @@
1
+ Read this when the UI lives on (or should live on) a Claude Design canvas: (a) the user wants to see or change the board in Claude Design, or (b) the user gave a `claude.ai/.../artifact/...` canvas URL.
2
+
3
+ # Claude Design canvas
4
+
5
+ Both uses end in the same place: a **local dump** (`<dump>/project/canvas.json`, the
6
+ `*.dc.html` boards it lists, `<dump>/_blob/*` for referenced files), which `references/verify.md`
7
+ then takes over. The importer never talks to claude.ai; the `Artifact` tool does the transfer.
8
+
9
+ ## (a) Create a canvas and write the board on it
10
+
11
+ Use this only when the user asks to see or edit the UI in Claude Design. A plain text description
12
+ is written as a local board instead (SKILL.md, entry 1).
13
+
14
+ 1. `Artifact` with `action: "quickstart"`, `intent: "design"`. The result names the Design
15
+ artifact type and its `type_url`.
16
+ 2. Create the canvas: `Artifact` publish with that `type_url` and `title` = the UI's display name
17
+ (for example `Authored HUD`), no files.
18
+ 3. The result of that call carries the type's own instructions: how boards are laid out, which
19
+ files to write and how to publish them to the new artifact's `url`. **Follow them exactly**;
20
+ they are the authority on the canvas format, not this file. Whatever they say about the
21
+ board source, its content is the XTFrame dialect: write each `<Name>.dc.html` against
22
+ `references/dialect.md`, starting from `references/template.dc.html`, with a root
23
+ `<div id="<ui-id>">` at the board size. If the instructions let you attach tokens, attach
24
+ `references/tokens.json`.
25
+ 4. Tell the user the canvas URL: they can now look at it and change it in Claude Design.
26
+ 5. Read it back into a local dump with the steps of (b) below, then go to `references/verify.md`.
27
+
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 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).
32
+
33
+ ## (c) Round trip: re-import, and carry editor changes back to the canvas
34
+
35
+ The canvas and the editor are two copies. The importer merges one way (canvas -> editor) and keeps
36
+ what the editor changed; nothing is synced live.
37
+
38
+ - **Keep layers findable.** A re-import pairs every layer by its `data-xt-name` (or `id`) first,
39
+ then, for unnamed ones, by position, size, order, nesting and text. When more than 20% of the old
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.
45
+ - **Editor changes back to the canvas.** Before re-importing a canvas the user also changed, ask
46
+ the importer what the editor side changed since the last import:
47
+
48
+ ```
49
+ xtframe-import dc -o <project-dir> --diff-out <changes.json>
50
+ ```
51
+
52
+ (no dump: it only writes the list). The file is
53
+ `{"tokens": [{ui, name, old, new}], "texts": [{ui, name, source, old, new}],
54
+ "colors": [{ui, name, source, prop, old, new}]}`:
55
+ - `tokens`: `name` is a custom property (`--accent`); set it to `new` in the board's `:root`
56
+ (or the design system's tokens) on the canvas.
57
+ - `texts`: `name` is the layer id -- the element whose `data-xt-name` or `id` slugifies to it;
58
+ `source` is `<board>.dc.html:<path>` when it has neither. Replace its text `old` -> `new`.
59
+ - `colors`: same element; set the inline style's `prop` to `new` (`old` is what the canvas
60
+ should still have; if it does not, the canvas changed too -- ask the user which one wins).
61
+ - An empty `new` means the editor removed the value.
62
+ Apply the three lists to the `.dc.html` in the dump, publish the boards back to the canvas (the
63
+ Design type's instructions), then re-import. Everything else the editor added (timelines,
64
+ triggers, ports, bindings, effects) stays in the editor and is kept by the merge; do not try to
65
+ write it onto the canvas.
66
+
67
+ ## (b) Read an existing canvas
68
+
69
+ Input: a canvas URL (`https://claude.ai/code/artifact/<uuid>` or `https://claude.ai/artifact/<id>`)
70
+ and a local `<dump>` directory to write into.
71
+
72
+ 1. `Artifact` `action: "list"`, `scope: "files"`, `url: <canvas-url>` to see the published tree.
73
+ 2. `Artifact` `action: "read"`, `url: <canvas-url>`, with `paths` (several per call) and `out_dir`
74
+ pointing into `<dump>/`, keeping the published paths:
75
+ - `project/canvas.json`
76
+ - every `*.dc.html` its `order` lists
77
+ - `project/ds/*/tokens.json` if present
78
+ - every `/_blob/<id>` a board references: `path: "_blob/<id>"`, saved as `<dump>/_blob/<id>`.
79
+ `<img src>` is not the only source; `@font-face` `src` can point at a blob too.
80
+ 3. Parse `boards` and `order` from `canvas.json`, and look at `designSystems`. If no entry mentions
81
+ XTFrame, **tell the user** (do not stop, do not ask for permission):
82
+
83
+ > This canvas was not built on the XTFrame dialect, so expect degradations (grid layout,
84
+ > unsupported units, unsupported properties). The lint in the next step lists them; fixing the
85
+ > boards against the dialect is cheaper than explaining the damage afterwards.
86
+
87
+ Then continue. The lint in `references/verify.md` is what actually decides.
88
+ 4. If `project/ds/*/tokens.json` was not published, copy `references/tokens.json` to
89
+ `<dump>/project/ds/xtframe/tokens.json` so `var(--...)` resolves without `--tokens`.
90
+
91
+ Go to `references/verify.md`. When the lint or compile needs a board fix, fix the `.dc.html` in the
92
+ dump; if the user wants the canvas to stay the source, also publish the fixed board back to the
93
+ canvas (the way the Design type's instructions describe) and say so.