@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.
- package/README.md +22 -2
- package/package.json +41 -4
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
- package/payload/plugins/xtframe/gemini-extension.json +5 -0
- package/payload/plugins/xtframe/skills/xtui/SKILL.md +245 -0
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +93 -0
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +874 -0
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +339 -0
- package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +182 -0
- package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +404 -0
- package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +101 -0
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +170 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +141 -0
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +223 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +349 -0
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +219 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +988 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +211 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +175 -0
- package/src/agents.mjs +73 -0
- package/src/bin.mjs +4 -0
- package/src/cli.mjs +286 -0
- package/src/converter.mjs +73 -0
- package/src/fsutil.mjs +76 -0
- package/src/install.mjs +154 -0
- package/src/packs.mjs +150 -0
- package/src/plugins.mjs +109 -0
- package/src/proc.mjs +66 -0
- package/src/tar.mjs +103 -0
package/README.md
CHANGED
|
@@ -1,3 +1,23 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @xtframe/skills
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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,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.
|