@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.
- 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 +218 -0
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +90 -0
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +799 -0
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +338 -0
- package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +162 -0
- package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +378 -0
- package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +42 -0
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +161 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +219 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +327 -0
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +209 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +849 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +180 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +167 -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
|
@@ -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.
|