@xtframe/skills 0.0.0-stage → 0.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +22 -2
  2. package/package.json +41 -4
  3. package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
  4. package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
  5. package/payload/plugins/xtframe/gemini-extension.json +5 -0
  6. package/payload/plugins/xtframe/skills/xtui/SKILL.md +245 -0
  7. package/payload/plugins/xtframe/skills/xtui/references/canvas.md +93 -0
  8. package/payload/plugins/xtframe/skills/xtui/references/dialect.md +874 -0
  9. package/payload/plugins/xtframe/skills/xtui/references/flow.md +339 -0
  10. package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
  11. package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
  12. package/payload/plugins/xtframe/skills/xtui/references/performance.md +182 -0
  13. package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
  14. package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +404 -0
  15. package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
  16. package/payload/plugins/xtframe/skills/xtui/references/tokens.json +101 -0
  17. package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +170 -0
  18. package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +141 -0
  19. package/payload/plugins/xtframe/skills/xtui/references/vector.md +223 -0
  20. package/payload/plugins/xtframe/skills/xtui/references/verify.md +349 -0
  21. package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +219 -0
  22. package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
  23. package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +988 -0
  24. package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
  25. package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +211 -0
  26. package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +175 -0
  27. package/src/agents.mjs +73 -0
  28. package/src/bin.mjs +4 -0
  29. package/src/cli.mjs +286 -0
  30. package/src/converter.mjs +73 -0
  31. package/src/fsutil.mjs +76 -0
  32. package/src/install.mjs +154 -0
  33. package/src/packs.mjs +150 -0
  34. package/src/plugins.mjs +109 -0
  35. package/src/proc.mjs +66 -0
  36. package/src/tar.mjs +103 -0
@@ -0,0 +1,158 @@
1
+ Read this when the work is about the project's design system -- palette, semantic variables, type roles, principles, voice, references, decisions -- or when the user asks to set one up, tidy one up from existing screens, generate one from a description, or change it ("warmer", "add rarity colours").
2
+
3
+ # The design system (`design/`, `design.*` operations)
4
+
5
+ A UI Project keeps its design system in `<project>/design/` (Docs/design/35-design-system.md):
6
+ `palette.yaml` (swatches and groups: knowledge, not variables), `tokens.yaml` (metadata of the
7
+ `shared/tokens.xts` variables: category, description, `from`), `type.yaml` (type roles),
8
+ `text/*.md` (principles, voice, screen notes), `text/decisions/NNNN-*.md` (decision records),
9
+ `references/<group>/<file>` + `<file>.meta` (pictures, videos, PDFs, text sources, `.url.yaml`
10
+ links). `DESIGN.md` is generated from all of that and never edited by hand.
11
+
12
+ Entries are addressed `<kind>:<id>`: `swatch:teal`, `group:brand`, `token:color-accent`,
13
+ `type:body`, `text:voice` (`text:voice#numbers` for a heading), `decision:0003`,
14
+ `ref:moodboard/key-art-01` (`ref:...@a1` for an annotation). Links are
15
+ `{rel, to, note}` with `rel` one of `derived-from`, `evidence-for`, `illustrates`, `applies-to`,
16
+ `supersedes`, `conflicts-with`, `see-also`; targets may also be `ui:hud`, `layer:hud#HealthBar`,
17
+ `symbol:Button`, `convention:<file>`, `motion:<key>`.
18
+
19
+ ## When to read DESIGN.md
20
+
21
+ - Before any change to colours, type, spacing, motion or wording in this project -- not only in
22
+ the design-system scenario: `design_get {"forAi": true}` (or one section,
23
+ `design_get {"section": "color"}`), or the MCP resource `xtui://project/design`. It is the
24
+ authority: a colour, size or word the UI uses should come from it.
25
+ - At the start of the `design-system` scenario, always (every entry point begins with it).
26
+
27
+ ## Operations
28
+
29
+ | Operation | Use |
30
+ |---|---|
31
+ | `design.get {section?, id?, resolve?, forAi?}` | the document, a section, or one entry; a `ref:` entry also returns `{path, mimeType, base64}` of its file (counts against `budget.images`) |
32
+ | `design.search {query?, kinds?, tags?, color?, limit?}` | find entries by text, kind, tags, or swatches nearest a colour |
33
+ | `design.list {kind, status?, group?}` | every entry of a kind (status `draft`/`approved`/`deprecated`/`stale`) |
34
+ | `design.usage {id}` | who uses an entry, and the transitive impact (UIs, layers, symbols) |
35
+ | `design.audit {scope?}` | literal colours, sizes and fonts in the UIs / symbols, token coverage, near-duplicate colours |
36
+ | `design.extractPalette {ref, count?}` | dominant colours of a reference picture |
37
+ | `design.deriveScale {swatch? \| value?, steps?}`, `design.contrast {fg, bg}` | a lightness scale; a WCAG ratio (`#hex`, `swatch:`, `token:`) |
38
+ | `design.put {kind, entry}` | add or change an entry -- always written as `draft`. A `decision` without an `id` is a **new** record every time (numbered for you): keep the `ref` the reply returns (`decision:0004`) and pass that `id` to change it |
39
+ | `design.delete {ref, confirm}` | remove an entry and every link to it (refused while a UI, layer or symbol uses it: `design.usage`); only after the user said yes |
40
+ | `design.importReference {path \| url, group, title?, tags?, license?, extract?}` | copy a file into `design/references/<group>/` (a URL is only registered) |
41
+ | `design.link` / `design.unlink {from, rel, to, note?}` | evidence and relations |
42
+ | `design.build` | regenerate `DESIGN.md`; returns the lint with `counts` |
43
+ | `design.lint`, `design.diff {from, to?}` | the checks; a semantic diff against another `design/` directory |
44
+ | `design.export {format, out}` | `html`: one static page; `claude-design`: a Claude Design design-system folder at `out` inside the project (`README.md`, `tokens.json` in the Claude Design token shape, `palette.json`, `components.md`) -- files only |
45
+ | `design.importDesignSystem {dir}` | read such a folder back (`README.md` required): README sections become text entries (`text/imported/<slug>.md`), `tokens.json` colours variable metadata (and values only where the stylesheet has none; other themes fill only missing variables of `shared/themes/<name>.xts`), `palette.json` swatches, `components.md` one text entry. All drafts with `source: import:claude-design`; importing again updates the same entries and puts them back to draft. Allowed in the `design-system` scenario |
46
+
47
+ `design.approve` and `design.deprecate` belong to a person (a decision record keeps its own states: a
48
+ draft is `proposed`, approve makes it `accepted`, deprecate `superseded`). They are gates: every AI
49
+ path -- the AI panel, MCP, the headless editor over stdio -- gets `kForbidden`, unless the user made
50
+ that seat a steward (37.8.1 D1; SKILL.md "Taking over"); no scenario allows them, so even a steward
51
+ calls them only outside one and only when the user asked. A steward's approval records
52
+ `approved.by: "<seat> (steward)"`. `design.put` with `status: approved` or an `approved:` field gets
53
+ `kForbidden` for everyone. `design.export` writes files for people (`html`, `claude-design`); the
54
+ `design-system` scenario allows it (T-372), call it when the user wants that export.
55
+
56
+ ## The four entry points (scenario `design-system`)
57
+
58
+ Call `session_setScenario {"name": "design-system", "entry": "<entry>"}` (`from-references`,
59
+ `from-existing`, `from-prompt` or `update`; the reply returns `entry`; add `"explore": true` only
60
+ when the user wants the drafts on a variant of their own) and `checkpoint_begin`. The contract's `entries` field names the four;
61
+ pick the one the user asked for (the editor's design system toolbar has a button for each and puts
62
+ the entry, the selected references, the audit summary or the prompt text in your prompt). Every one
63
+ follows the same six steps: **read -> audit / extract -> put drafts -> link the evidence -> build ->
64
+ report**.
65
+
66
+ **From references** (the model must see pictures: `model.minCaps: [tools, vision]`).
67
+
68
+ 1. `design_get {"forAi": true}`; `design_list {"kind": "ref"}`; the references the user picked
69
+ (`design_importReference` for new files, `"extract": true` caches their colours).
70
+ 2. `design_get {"id": "ref:<id>"}` for each picture you look at (at most 8: `budget.images`),
71
+ `design_extractPalette` for its dominant colours; text sources are read in full.
72
+ 3. `design_put` the palette (`swatch`, grouped with `group`), semantic variables (`token`
73
+ metadata; a value only when the user asked to change it), principles and voice (`text`), type
74
+ roles (`type`), tags on the references.
75
+ 4. `design_link` every new swatch `derived-from` its reference (or write in its `note` why it has
76
+ none); every principle gets at least one `evidence-for` from a reference.
77
+ 5. `design_build`.
78
+
79
+ **From existing design.**
80
+
81
+ 1. `design_get {"forAi": true}`; `design_audit {"scope": "all"}`.
82
+ 2. Group the audit's colours: near-duplicates (`nearDuplicates`, ΔE2000 < 3) become one swatch.
83
+ 3. `design_put` the swatches and variable metadata; every one names its audit source (the layers
84
+ from `where`) in `source` (`{"kind": "ai:design-system", "ref": "<ui>#<layer>, ..."}`) or a
85
+ `note`. Each merge of near-duplicates is a draft `decision`.
86
+ 4. List "replace this literal with this variable" as restyle suggestions in the report. Do not
87
+ change UI values: `restyle` is forbidden here, and the user ticks the suggestions first.
88
+ 5. `design_build`; report the token coverage before and after.
89
+
90
+ **From a description** ("dark sci-fi, cyan accent, Rajdhani").
91
+
92
+ 1. `design_get {"forAi": true}`.
93
+ 2. `design_put {"kind": "decision", "entry": {"title": ..., "body": ...}}` first: the context, the
94
+ prompt verbatim, the trade-offs (the id is numbered for you: keep the returned `ref` and put
95
+ with its `id` to amend it, or every put makes another decision).
96
+ 3. `design_put` the full draft: palette, type roles, spacing / radius / motion variable metadata,
97
+ principles; `design_deriveScale` for scales, `design_contrast` for text on surfaces.
98
+ 4. `design_link` every choice to that decision: a swatch or variable `{"from": "swatch:x", "rel":
99
+ "derived-from", "to": "decision:0004"}`, a principle `{"from": "decision:0004", "rel":
100
+ "evidence-for", "to": "text:p"}`.
101
+ 5. `design_build`.
102
+
103
+ **Update** ("warmer", "add rarity colours").
104
+
105
+ 1. `design_get`; `design_usage` of every entry you will change (put the impact in the report).
106
+ 2. `design_put` the changed or new entries (drafts); a variable whose value changes lists how
107
+ many UIs use it; a draft `decision` records why.
108
+ 3. `design_link` the new entries to that decision or to their source.
109
+ 4. `design_build`.
110
+
111
+ ## Evidence rules
112
+
113
+ - Every new swatch has at least one `derived-from` link (a reference, a decision) or an audit
114
+ source; otherwise say why in its `note`, and count it as unlinked in the report.
115
+ - Every principle has at least one `evidence-for`.
116
+ - A link's `from` (and `to`) must be a design entry: `ref:`, `decision:`, `text:`, `swatch:`,
117
+ `token:`, `type:`. A UI or a layer (`ui:`, `layer:`) is never an endpoint: name it in the
118
+ `note` or in the entry's `source`. Without a reference to cite, the evidence for a principle is
119
+ a decision: `design_link {"from": "decision:NNNN", "rel": "evidence-for", "to": "text:p"}`.
120
+ - Every decision the prompt drove links to its decision record.
121
+ - Unlinked entries in the report must be 0, or each one explained.
122
+
123
+ ## Never
124
+
125
+ - Approve or deprecate anything inside the scenario (outside it only as a steward the user asked);
126
+ write `status: approved` or `approved:`.
127
+ - Change UI literal values (layers, `.xt`, `.xts` rules) unless the user ticked that suggestion;
128
+ `restyle` is not available in this scenario.
129
+ - Write files under `design/` yourself: only through `design.*` (and `style.setToken` for a
130
+ variable's value).
131
+
132
+ ## Report
133
+
134
+ After `design_build` (and `scenario_check`), report with the contract's keys:
135
+
136
+ ```json
137
+ {
138
+ "entries_added": ["swatch:ember", "decision:0004"],
139
+ "entries_changed": ["token:color-accent"],
140
+ "drafts": 12,
141
+ "coverage": {"before": 0.62, "after": 0.81},
142
+ "unlinked": [],
143
+ "lint": {"error": 0, "warning": 1, "info": 3},
144
+ "chosen": ["..."],
145
+ "omitted": ["..."]
146
+ }
147
+ ```
148
+
149
+ `coverage` is for the from-existing entry point (the audit's `tokenCoverage`); `lint` is the
150
+ `counts` of `design_build`. Add `"variant": "<slug>"` when the scenario ran on one (`explore`).
151
+ Then the usual three lists (SKILL.md section 5): the user approves the drafts in the editor, and
152
+ commits or rolls back the checkpoint. End the work item with `session_endScenario` (with project
153
+ history: the checkpoint "<seat> · design-system · HH:MM", `design/` files included; the user
154
+ compares or goes back from the History panel). An explore run instead commits "AI: design-system
155
+ done" on its variant; `session_setScenario {"name": "", "rollback": true}` discards it, `design/`
156
+ files included. Without history a rollback undoes only the document edits (a
157
+ variable's value set through `design.put` or `style.setToken`); the files `design.*` wrote under
158
+ `design/` stay, so list every entry you wrote.