@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.
Files changed (35) 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 +218 -0
  7. package/payload/plugins/xtframe/skills/xtui/references/canvas.md +90 -0
  8. package/payload/plugins/xtframe/skills/xtui/references/dialect.md +799 -0
  9. package/payload/plugins/xtframe/skills/xtui/references/flow.md +338 -0
  10. package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
  11. package/payload/plugins/xtframe/skills/xtui/references/performance.md +162 -0
  12. package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
  13. package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +378 -0
  14. package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
  15. package/payload/plugins/xtframe/skills/xtui/references/tokens.json +42 -0
  16. package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +161 -0
  17. package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +140 -0
  18. package/payload/plugins/xtframe/skills/xtui/references/vector.md +219 -0
  19. package/payload/plugins/xtframe/skills/xtui/references/verify.md +327 -0
  20. package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +209 -0
  21. package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
  22. package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +849 -0
  23. package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
  24. package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +180 -0
  25. package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +167 -0
  26. package/src/agents.mjs +73 -0
  27. package/src/bin.mjs +4 -0
  28. package/src/cli.mjs +286 -0
  29. package/src/converter.mjs +73 -0
  30. package/src/fsutil.mjs +76 -0
  31. package/src/install.mjs +154 -0
  32. package/src/packs.mjs +150 -0
  33. package/src/plugins.mjs +109 -0
  34. package/src/proc.mjs +66 -0
  35. 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.18.0",
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.18.0",
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.18.0",
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.18.0",
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,218 @@
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/style-groups.md` | the editor's style names (Fill, Stroke, Corners, Opacity & Blend, ...) and the CSS properties each covers: talk to the user in style names, write CSS on the board (generated; the dialect is unchanged) |
34
+
35
+ The user never has to know the dialect, pick a tool or fix a lint finding. Compliance is your job:
36
+ if the lint or the compile complains, fix the board and run again (at most three rounds, see
37
+ `references/verify.md`).
38
+
39
+ ## 0. Locate XTFrame
40
+
41
+ Find the XTFrame checkout `<xtframe>`: the directory holding `Docs/design/00-overview.md` (ask the
42
+ user if it is not the current directory or an obvious parent). The converters (`xtframe-import`,
43
+ `xtframe-compile`, `xtframe-view`) are used from PATH when they are on it (installed by the npm
44
+ converter package from the skills repo (see the shereware/xtframe-skills README) or the
45
+ `xtframe-tools` plugin; no checkout needed), otherwise from
46
+ `<xtframe>/bin/win_x64/Release/`. Build whichever of them is missing, from `<xtframe>`, naming only
47
+ the targets to build (`Tools/Scripts/dev_check.sh` builds what it is given and runs no suite after
48
+ the `--`):
49
+
50
+ ```
51
+ bash Tools/Scripts/dev_check.sh --release xtframe-import xtframe-view xtframe-compile --
52
+ bash Tools/Scripts/dev_check.sh --release xtframe-editor -- # needs XT_QT_DIR (a Qt install)
53
+ ```
54
+
55
+ `xtframe-editor` is only needed for the last step; `references/verify.md` step 8 covers a missing
56
+ Qt.
57
+
58
+ **Check the converter before you start, not after you wrote the board.** Decide the mode now:
59
+
60
+ - **Convert mode** -- `xtframe-import`, `xtframe-compile` and `xtframe-view` are on PATH (the npm
61
+ converter package from the skills repo (see the shereware/xtframe-skills README) or the
62
+ `xtframe-tools` plugin; no XTFrame checkout needed; the package's `xtframe-import` may be the
63
+ Node.js/wasm build, which behaves exactly like the native one), or
64
+ `xtframe-import` exists under `<xtframe>/bin/win_x64/Release/`,
65
+ or the checkout is here with a working C++ toolchain and you can build it (try the
66
+ `dev_check.sh` line once; a missing compiler, CMake or network for FetchContent means no).
67
+ Then every entry ends in `references/verify.md` as usual.
68
+ - **Deliver mode** -- no converters on PATH, no XTFrame checkout, no build tree and no way to
69
+ build (typical of a cloud or sandboxed session, or a machine that only has the user's game).
70
+ Do not try to emulate the converter and never hand-write `.xt` / `.xts`: write the board exactly
71
+ as in convert mode, then deliver the **importable dump** (`references/verify.md` "Deliver mode").
72
+ Say which mode you are in once, up front.
73
+
74
+ ## 1. Decide the entry
75
+
76
+ First, if the editor is running with this UI open (`%LOCALAPPDATA%/XTFrame/service.json` exists
77
+ and the user talks about "this UI", a panel, the timeline or a symbol in it), stop: that is
78
+ `xtui-editor`. Otherwise look at what the user gave you and take exactly one row. Before writing
79
+ or changing any board, look for a UI Project (`references/ui-project.md` step 1); when there is
80
+ one, its tokens and conventions replace `references/tokens.json`.
81
+
82
+ | Input | Do this first | Then |
83
+ |---|---|---|
84
+ | 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 |
85
+ | A `claude.ai/.../artifact/...` URL (a canvas) | Read `references/canvas.md` (b) and download it into a local dump. | step 2 |
86
+ | A directory holding `project/canvas.json` | Nothing to fetch: it already is a dump. | step 2 |
87
+ | 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 |
88
+
89
+ ## 1b. Pick the symbol library and group
90
+
91
+ Every UI is drawn from a **symbol group** of a **symbol library** (Docs/design/49-symbol-sets.md):
92
+ the buttons, bars, lists and sheets the board instantiates with `data-xt-symbol`, with their tokens,
93
+ fonts and textures. Decide the group before writing the board, and make sure the UI Project has
94
+ its symbols:
95
+
96
+ 1. **Which library, which group.** When an editor can be reached (`xtframe-mcp --project <dir>`,
97
+ or `xtframe-mcp --spawn-headless <dir>` when none is open; `references/ui-project.md` names the
98
+ project), call `symbols_libraries`, then `symbols_library` (every mounted library with its groups
99
+ and each group's symbols, contracts and lint state). No style asked for: use the preset library's
100
+ `default` group (`broadsheet-2026`, the standard library the shipped `tokens.json` and
101
+ `template.dc.html` follow). "Use my X group": that group (`symbols_library {"library": "mine"}`
102
+ lists the user's own groups; a group whose `lint.errors` is not 0 is listed but should be fixed in
103
+ the editor first -- say so). Without any editor (deliver mode, or a machine without one),
104
+ `xtframe-symbols libraries` and `xtframe-symbols lint <group dir>` list the same; the import then
105
+ relies on the preset group, which `xtframe-import` / `xtframe-pack` resolve by themselves.
106
+ 2. **Put the group into the project before importing.** `symbols_useGroup {"group": "<id>"}` (or
107
+ `symbols_use {"names": [...]}` for the few symbols the board needs) copies the symbols, their
108
+ fonts and textures and the tokens they read into the UI Project (49.3), one undo step, inside a
109
+ `create` scenario of the editor. After that every `<symbols src>` the import writes
110
+ resolves, and the project owns its copies. Skip it when the project already has them
111
+ (`symbols_library` shows nothing new; `project_syncSymbols` lists the copies).
112
+ 3. **Draw with those names.** `data-xt-symbol` values are the group's symbol names (`symbols_get
113
+ {"name"}` has the contract: required states, slots, ports, timelines); keep the board element's
114
+ structure and slot names as the symbol has them (`references/ui-project.md` item 7).
115
+ 4. **Tokens from the group.** `xtframe-symbols tokens-json <group dir> -o
116
+ <dump>/project/ds/xtframe/tokens.json` once per group when the skill starts (cache it for the
117
+ session): the board's palette is the group's. A UI Project's own `shared/tokens.xts` still wins
118
+ (`references/ui-project.md` step 3).
119
+
120
+ This is the one place this skill talks to the editor, and only through these `symbols_*`
121
+ operations (the `xtui-editor` skill has the full list); it still writes no `.xt` / `.xts`. The
122
+ library-write operations (`symbols_import`, `symbols_saveAsGroup`, `symbols_loadPreset`, ...) are
123
+ `xtui-editor`'s `library` scenario, never part of making a UI.
124
+
125
+ **Writing a local board.** Agree on the ids first: map the description onto role names
126
+ (`hp-fill`, `btn-menu`, `panel-quest`; lowercase, digits, `-`), the root id being the UI id. Show
127
+ the table once and let the user rename before you write anything; ids are what the game and the
128
+ flow bind to. Then write under `<dump>/project/`:
129
+
130
+ - `canvas.json`, the minimal shape:
131
+
132
+ ```json
133
+ {
134
+ "name": "Authored HUD",
135
+ "boards": { "Main.dc.html": { "x": 0, "y": 0, "w": 1280, "h": 720,
136
+ "title": "Authored HUD", "page": "main" } },
137
+ "order": ["Main.dc.html"],
138
+ "pages": ["main"],
139
+ "designSystems": ["xtframe"]
140
+ }
141
+ ```
142
+
143
+ - one `<Name>.dc.html` per screen (one `boards` + one `order` entry each), started from
144
+ `references/template.dc.html`, with root `<div id="<ui-id>">` at the board size;
145
+ - `ds/xtframe/tokens.json`, a copy of `references/tokens.json` -- or, in a UI Project,
146
+ `ds/project/tokens.json` made from its `shared/tokens.xts` (`references/ui-project.md` step 3).
147
+
148
+ Write the intent with tags while you write the board (`references/dialect.md`, **Intent tags**):
149
+ `data-xt-name` on every layer that matters, `data-xt-symbol` for repeated components,
150
+ `data-xt-state` elements for hover/pressed/selected looks, `data-xt-timeline` +
151
+ `data-xt-trigger` for intro/hover animations, `data-xt-port` + `data-xt-bind` for game values,
152
+ `data-xt-anchor` for anything at a screen edge, `data-xt-token` for themed colours.
153
+
154
+ Use `{{hole}}` only where the game supplies the value, always with a `data-props` default. Images
155
+ are `<img src="/_blob/<file>">` with the file in `<dump>/_blob/`. Keep the dump: it is how the UI
156
+ changes later.
157
+
158
+ ## 2. Verify and open the editor
159
+
160
+ Convert mode: read `references/verify.md` and follow it step by step on `<dump>`: lint, import
161
+ into `<project-dir>`, compile every UI, headless screenshot, report the degradations and missing
162
+ ids. Its last step opens `<project-dir>` (its `<name>.xtui`) in `xtframe-editor` in the
163
+ background. Every entry ends there; finish with the UI Project path and "editor opened".
164
+
165
+ Deliver mode: follow `references/verify.md` "Deliver mode" instead -- self-check the board against
166
+ `references/dialect.md`, package the dump, and finish with the dump path plus the one command the
167
+ user runs where the tools are. Never claim the UI was linted, compiled or screenshotted when it
168
+ was not.
169
+
170
+ ## 3. Interactivity (when the user asks)
171
+
172
+ **Tags first.** Hover and press looks, a click that plays an animation or toggles a state, an
173
+ intro on show, a bar or a number that follows a game value, a button that sends an event to the
174
+ game: write them on the board as `data-xt-state`, `data-xt-trigger`, `data-xt-timeline`,
175
+ `data-xt-sound`, `data-xt-port` and `data-xt-bind` (`references/dialect.md`, **Intent tags**), then
176
+ re-import (step 2). The import turns them into `on:`, `@timeline` (in `<timelines>`), `:hover` /
177
+ `:state()` rules, `<ports>` lines and `bind:`; its lint (`tag.triggerWithoutTimeline`, `tag.stateNoDiff`,
178
+ `tag.portUnbound`) says what does not line up -- fix the board and import again.
179
+
180
+ **`.xtflow` only when a tag cannot say it**: logic across several UIs, or computation (counters,
181
+ timers, random, pointer parallax, a demo mode). Then read `references/flow.md`, write
182
+ `<project-dir>/<ui>/<ui>.xtflow` and check it with `xtframe-view` as it describes. When the editor
183
+ has the UI open, the flow is changed through `xtui-editor` (`flow_set`) instead. Missing authored ids
184
+ go back to the board (step 1) and through step 2 again. A re-import never overwrites the
185
+ `.xtflow`.
186
+
187
+ ## 4. Seeing or changing it in Claude Design (when the user asks)
188
+
189
+ If the user wants to look at or edit the board in Claude Design, read `references/canvas.md` (a):
190
+ it creates a canvas with the board on it and reads it back into the dump. Later canvas edits come
191
+ back through `references/canvas.md` (b) into the same dump and UI Project. Changes made in the editor
192
+ do not flow back to the board or the canvas yet; say so if the user expects it.
193
+
194
+ ## 5. After this skill: changes in the editor are `xtui-editor`
195
+
196
+ The UI Project is open in the editor now. **To keep changing it in the editor, use `xtui-editor`**:
197
+ that skill works on the open UI through the Editor Service (layers, styles, timelines, triggers,
198
+ symbols, states, scenarios, checkpoints) and never writes files; it starts by taking over (its
199
+ section 2: the work site, what the user did since, `ifRevision` on every write), because the user may
200
+ already be editing what you imported. Come back to this skill when the
201
+ board is the thing to change (a new screen, a canvas edit, a redesign), and re-import: the merge
202
+ keeps what the editor changed (`references/verify.md` step 3).
203
+
204
+ What each side reads: this skill reads and writes the board (the dump, its `.dc.html`) -- material
205
+ before the import, not an editor document. Once the UI is open in the editor, its files belong to
206
+ the editor; read them through it, not from disk:
207
+
208
+ | To read | Ask the editor with |
209
+ |---|---|
210
+ | the `.xt` / `.xts` text | `doc.source` |
211
+ | class and shared rules | `style.getRules` |
212
+ | the flow graph | `flow.get` (change it with `flow.set`) |
213
+ | the import report | `project.importReport` |
214
+ | the spec and conventions | `project.get` |
215
+ | the symbol libraries, a group's symbols, a symbol's contract, the lint of a set | `symbols.libraries`, `symbols.library`, `symbols.get`, `symbols.lint` |
216
+
217
+ After an import or re-import from the command line while the editor has the UI open, the editor
218
+ must reload it (`doc.reload`; it does so by itself when the UI has no unsaved edits).
@@ -0,0 +1,90 @@
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 the `.xtflow` (see **(c)** below and
30
+ `references/verify.md` step 3).
31
+
32
+ ## (c) Round trip: re-import, and carry editor changes back to the canvas
33
+
34
+ The canvas and the editor are two copies. The importer merges one way (canvas -> editor) and keeps
35
+ what the editor changed; nothing is synced live.
36
+
37
+ - **Keep layers findable.** A re-import pairs every layer by its `data-xt-name` (or `id`) first,
38
+ then, for unnamed ones, by position, size, order, nesting and text. When more than 20% of the old
39
+ layers cannot be found again, it refuses to merge (`fallback: "one-way"`, exit 3). So when you
40
+ write or fix a board, give every layer that matters a `data-xt-name` or an `id`, and never rename
41
+ one the editor already knows.
42
+ - **Editor changes back to the canvas.** Before re-importing a canvas the user also changed, ask
43
+ the importer what the editor side changed since the last import:
44
+
45
+ ```
46
+ xtframe-import dc -o <project-dir> --diff-out <changes.json>
47
+ ```
48
+
49
+ (no dump: it only writes the list). The file is
50
+ `{"tokens": [{ui, name, old, new}], "texts": [{ui, name, source, old, new}],
51
+ "colors": [{ui, name, source, prop, old, new}]}`:
52
+ - `tokens`: `name` is a custom property (`--accent`); set it to `new` in the board's `:root`
53
+ (or the design system's tokens) on the canvas.
54
+ - `texts`: `name` is the layer id -- the element whose `data-xt-name` or `id` slugifies to it;
55
+ `source` is `<board>.dc.html:<path>` when it has neither. Replace its text `old` -> `new`.
56
+ - `colors`: same element; set the inline style's `prop` to `new` (`old` is what the canvas
57
+ should still have; if it does not, the canvas changed too -- ask the user which one wins).
58
+ - An empty `new` means the editor removed the value.
59
+ Apply the three lists to the `.dc.html` in the dump, publish the boards back to the canvas (the
60
+ Design type's instructions), then re-import. Everything else the editor added (timelines,
61
+ triggers, ports, bindings, effects) stays in the editor and is kept by the merge; do not try to
62
+ write it onto the canvas.
63
+
64
+ ## (b) Read an existing canvas
65
+
66
+ Input: a canvas URL (`https://claude.ai/code/artifact/<uuid>` or `https://claude.ai/artifact/<id>`)
67
+ and a local `<dump>` directory to write into.
68
+
69
+ 1. `Artifact` `action: "list"`, `scope: "files"`, `url: <canvas-url>` to see the published tree.
70
+ 2. `Artifact` `action: "read"`, `url: <canvas-url>`, with `paths` (several per call) and `out_dir`
71
+ pointing into `<dump>/`, keeping the published paths:
72
+ - `project/canvas.json`
73
+ - every `*.dc.html` its `order` lists
74
+ - `project/ds/*/tokens.json` if present
75
+ - every `/_blob/<id>` a board references: `path: "_blob/<id>"`, saved as `<dump>/_blob/<id>`.
76
+ `<img src>` is not the only source; `@font-face` `src` can point at a blob too.
77
+ 3. Parse `boards` and `order` from `canvas.json`, and look at `designSystems`. If no entry mentions
78
+ XTFrame, **tell the user** (do not stop, do not ask for permission):
79
+
80
+ > This canvas was not built on the XTFrame dialect, so expect degradations (grid layout,
81
+ > unsupported units, unsupported properties). The lint in the next step lists them; fixing the
82
+ > boards against the dialect is cheaper than explaining the damage afterwards.
83
+
84
+ Then continue. The lint in `references/verify.md` is what actually decides.
85
+ 4. If `project/ds/*/tokens.json` was not published, copy `references/tokens.json` to
86
+ `<dump>/project/ds/xtframe/tokens.json` so `var(--...)` resolves without `--tokens`.
87
+
88
+ Go to `references/verify.md`. When the lint or compile needs a board fix, fix the `.dc.html` in the
89
+ dump; if the user wants the canvas to stay the source, also publish the fixed board back to the
90
+ canvas (the way the Design type's instructions describe) and say so.