@wireweave/agent-prompts 0.1.1 → 0.2.0-beta.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 +17 -18
- package/dist/index.cjs +93 -18
- package/dist/index.js +93 -18
- package/package.json +22 -22
package/README.md
CHANGED
|
@@ -1,6 +1,12 @@
|
|
|
1
1
|
# @wireweave/agent-prompts
|
|
2
2
|
|
|
3
|
-
Canonical grammar prompts
|
|
3
|
+
Canonical grammar-guide prompts that teach an LLM to generate Wireweave DSL.
|
|
4
|
+
|
|
5
|
+
## What it does
|
|
6
|
+
|
|
7
|
+
Exports the Wireweave DSL grammar guide as ready-to-inject prompt strings. Each function returns a single Markdown-flavoured string that you drop verbatim into an LLM system message so the model emits valid `.wf` wireframes — including the multi-page canvas model (multiple top-level `page` declarations, `at(x, y)` positioning, `viewport="WxH"`).
|
|
8
|
+
|
|
9
|
+
It is the single source of truth for the grammar guide; downstream consumers (`agent-harness`, `api-server`, future plugins) import it so they stay in sync with `@wireweave/core`. The package has no runtime dependencies.
|
|
4
10
|
|
|
5
11
|
## Install
|
|
6
12
|
|
|
@@ -8,36 +14,29 @@ Canonical grammar prompts for LLM agents that generate Wireweave DSL. The packag
|
|
|
8
14
|
pnpm add @wireweave/agent-prompts
|
|
9
15
|
```
|
|
10
16
|
|
|
11
|
-
##
|
|
17
|
+
## Usage
|
|
12
18
|
|
|
13
19
|
```ts
|
|
14
20
|
import { buildGrammarPrompt, buildCompactGrammarPrompt } from '@wireweave/agent-prompts'
|
|
15
21
|
|
|
16
|
-
// Full
|
|
22
|
+
// Full guide (~180 lines) — generation phase.
|
|
17
23
|
const system = buildGrammarPrompt()
|
|
18
24
|
|
|
19
|
-
// Compact
|
|
25
|
+
// Compact guide (~60 lines) — analyze / plan phases, fewer tokens.
|
|
20
26
|
const compact = buildCompactGrammarPrompt()
|
|
21
27
|
```
|
|
22
28
|
|
|
23
|
-
|
|
29
|
+
## API
|
|
30
|
+
|
|
31
|
+
### `buildGrammarPrompt(): string`
|
|
24
32
|
|
|
25
|
-
|
|
33
|
+
The full grammar guide for the generation phase. Covers syntax structure, the multi-page canvas model, the renderer surface (`render` / `renderCanvas` / `renderPage`), the layout / content / form / nav / data / feedback / overlay / utility component contracts, and how to map common UI concepts to DSL components.
|
|
26
34
|
|
|
27
|
-
|
|
28
|
-
- **Multi-page canvas** — multiple top-level `page` declarations, `at(x, y)` positioning, `viewport="WxH"`.
|
|
29
|
-
- Renderer surface from `@wireweave/core`: `render(doc)` / `renderCanvas(doc)` / `renderPage(page)`.
|
|
30
|
-
- Layout / content / form / nav / data / feedback / overlay / utility component contracts.
|
|
31
|
-
- Mapping common UI concepts to DSL components.
|
|
35
|
+
### `buildCompactGrammarPrompt(): string`
|
|
32
36
|
|
|
33
|
-
|
|
37
|
+
A condensed grammar guide for the analyze / plan phases, where the full guide is more than needed.
|
|
34
38
|
|
|
35
|
-
|
|
36
|
-
`api-server/src/services/guide.ts`, `api-server/src/agent/prompts.ts`, and
|
|
37
|
-
`agent-harness/wireweave/src/guide.ts`. The agent-harness copy drifted to a
|
|
38
|
-
pre-3.0 single-page-only definition, which silently broke multi-screen
|
|
39
|
-
wireframe generation. Pulling the guide into its own package gives a single
|
|
40
|
-
versioned export every downstream consumer can pin.
|
|
39
|
+
Part of the [Wireweave monorepo](https://github.com/wireweave/wireweave).
|
|
41
40
|
|
|
42
41
|
## License
|
|
43
42
|
|
package/dist/index.cjs
CHANGED
|
@@ -78,8 +78,31 @@ Renderer modes (the host picks one; you only need to emit valid pages):
|
|
|
78
78
|
- renderCanvas(doc) \u2014 composes all pages into one bounded canvas.
|
|
79
79
|
- renderPage(page) \u2014 single-page export primitive (1 page = 1 file).
|
|
80
80
|
|
|
81
|
+
# SHARED PAGE LAYOUTS
|
|
82
|
+
When several pages share a shell, define it once as a top-level layout and put
|
|
83
|
+
the varying page content at its slot. Layout definitions and pages are siblings;
|
|
84
|
+
a layout is not a screen by itself.
|
|
85
|
+
|
|
86
|
+
- layout NAME { ... slot ... } \u2014 a named page shell. NAME is a bare identifier.
|
|
87
|
+
- slot \u2014 a bare positional marker inside a layout. It takes no name and no braces.
|
|
88
|
+
- page "Title" uses=NAME { ... } \u2014 draw the page inside layout NAME; the page body
|
|
89
|
+
contains only the content unique to that screen.
|
|
90
|
+
|
|
91
|
+
Example:
|
|
92
|
+
|
|
93
|
+
\`\`\`
|
|
94
|
+
layout app {
|
|
95
|
+
header { title "Acme" }
|
|
96
|
+
slot
|
|
97
|
+
footer { text "\xA9 2026 Acme" }
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
page "Home" uses=app { text "Welcome back" }
|
|
101
|
+
page "Docs" uses=app { text "Getting started" }
|
|
102
|
+
\`\`\`
|
|
103
|
+
|
|
81
104
|
# LAYOUT COMPONENTS
|
|
82
|
-
page: Root container. Attrs: title (string arg), at(x, y), viewport, width, height (pixels), device (mobile/tablet/desktop preset), centered (boolean).
|
|
105
|
+
page: Root container. Attrs: title (string arg), uses (layout name), at(x, y), viewport, width, height (pixels), device (mobile/tablet/desktop preset), centered (boolean).
|
|
83
106
|
header: Top section. Attrs: h (height), p (padding), border (boolean, default true).
|
|
84
107
|
main: Primary content. Attrs: p, scroll (boolean).
|
|
85
108
|
footer: Bottom section. Attrs: h, p, border.
|
|
@@ -91,26 +114,26 @@ stack: Layered container. Attrs: gap.
|
|
|
91
114
|
relative: Positioned container.
|
|
92
115
|
|
|
93
116
|
# CONTENT CONTAINERS
|
|
94
|
-
card: Bordered box. String arg for title. Attrs: p (0-8), w, h, shadow (none/sm/md/lg), border.
|
|
95
|
-
modal: Dialog. String arg for title. Attrs: w, h.
|
|
96
|
-
drawer: Slide panel. String arg for title. Attrs: w, position.
|
|
117
|
+
card: Bordered box. String arg for title. Attrs: p (0-8), w, h, shadow (none/sm/md/lg), border, navigate, opens, toggles, action.
|
|
118
|
+
modal: Dialog. String arg for title. Attrs: w, h, id (opens/toggles target).
|
|
119
|
+
drawer: Slide panel. String arg for title. Attrs: w, position, id (opens/toggles target).
|
|
97
120
|
accordion: Expandable section. String arg for title.
|
|
98
121
|
section: Grouped content. String arg for title.
|
|
99
122
|
|
|
100
123
|
# TEXT COMPONENTS
|
|
101
124
|
text: Inline text. String arg required. Attrs: size (xs/sm/base/md/lg/xl), weight (normal/medium/semibold/bold), muted, align.
|
|
102
125
|
title: Heading. String arg required. Attrs: level (1-6), size, align, mb, mt.
|
|
103
|
-
link: Hyperlink. String arg required. Attrs: href, external, ml, mr.
|
|
126
|
+
link: Hyperlink. String arg required. Attrs: href, external, ml, mr, navigate, opens, toggles, action.
|
|
104
127
|
|
|
105
128
|
# VISUAL COMPONENTS
|
|
106
|
-
icon: Lucide icon. String arg is icon name. Attrs: size (xs/sm/md/lg/xl), muted.
|
|
107
|
-
avatar: User avatar. String arg is name (shows initials). Attrs: size, src.
|
|
108
|
-
badge: Label tag. String arg required. Attrs: variant (default/primary/success/warning/danger), size, pill.
|
|
109
|
-
image: Image element. String arg is src. Attrs: w, h, alt.
|
|
129
|
+
icon: Lucide icon. String arg is icon name \u2014 must be a valid Lucide name in kebab-case (e.g. the overflow/kebab menu is "ellipsis-vertical", horizontal is "ellipsis"; not "more-vertical"). Unknown names render as a "?" placeholder. Attrs: size (xs/sm/md/lg/xl), muted, navigate, opens, toggles, action.
|
|
130
|
+
avatar: User avatar. String arg is name (shows initials). Attrs: size, src, navigate, opens, toggles, action.
|
|
131
|
+
badge: Label tag. String arg required. Attrs: variant (default/primary/success/warning/danger), size, pill, navigate, opens, toggles, action.
|
|
132
|
+
image: Image element. String arg is src. Attrs: w, h, alt, navigate, opens, toggles, action.
|
|
110
133
|
placeholder: Dashed box for images/media. String arg is label. Attrs: h, w.
|
|
111
134
|
|
|
112
135
|
# FORM COMPONENTS
|
|
113
|
-
button: Clickable button. String arg is label (empty "" for icon-only). Attrs: primary/secondary/outline/ghost/danger (boolean variants), icon, size (xs/sm/md/lg), disabled, w.
|
|
136
|
+
button: Clickable button. String arg is label (empty "" for icon-only). Attrs: primary/secondary/outline/ghost/danger (boolean variants), icon, size (xs/sm/md/lg), disabled, w, aria (accessible name for icon-only buttons \u2192 renders aria-label), title (tooltip), navigate, opens, toggles, action.
|
|
114
137
|
input: Text input. String arg is label. Attrs: placeholder, inputType (text/email/password/number/tel/url/search/date), icon, w, size, required, disabled.
|
|
115
138
|
select: Dropdown. String arg is label. Array arg for options. Attrs: placeholder, value.
|
|
116
139
|
checkbox: Checkbox. String arg is label. Attrs: checked, disabled.
|
|
@@ -123,7 +146,7 @@ textarea: Multiline input. String arg is label. Attrs: rows, placeholder.
|
|
|
123
146
|
nav: Menu. Array arg for simple items OR block with item children.
|
|
124
147
|
- Array syntax: nav ["Home", "About", "Contact"]
|
|
125
148
|
- Block syntax: nav { item "Label" icon="name" active }
|
|
126
|
-
item: Nav item (inside nav/dropdown block). String arg is label. Attrs: icon, active, disabled, href.
|
|
149
|
+
item: Nav item (inside nav/dropdown block). String arg is label. Attrs: icon, active, disabled, href, navigate, opens, toggles, action.
|
|
127
150
|
tabs: Tab bar. Array arg for labels. Attrs: active (0-based index).
|
|
128
151
|
- Block syntax: tabs { tab "Label" { children } }
|
|
129
152
|
breadcrumb: Path trail. Array arg for items.
|
|
@@ -184,9 +207,10 @@ col: syntax: col [gap=N] [flex=N] [span=N] [scroll] { children }
|
|
|
184
207
|
stack: syntax: stack [gap=N] { children }
|
|
185
208
|
- Unlike col, stack only takes content height (does not flex to fill space).
|
|
186
209
|
|
|
187
|
-
button: syntax: button "label" [variant] [size=SIZE] [icon="name"]
|
|
210
|
+
button: syntax: button "label" [variant] [size=SIZE] [icon="name"] [aria="Accessible name"]
|
|
188
211
|
- Variants are boolean attrs: primary, secondary, outline, ghost, danger.
|
|
189
|
-
- Icon-only: button "" icon="name" ghost (empty string required).
|
|
212
|
+
- Icon-only: button "" icon="name" aria="Action" ghost (empty string required).
|
|
213
|
+
- ALWAYS give an icon-only button an accessible name via aria="\u2026" (renders aria-label) so screen readers can describe it. title="\u2026" is a fallback.
|
|
190
214
|
- NOT: button icon="name" (missing string arg causes parse error).
|
|
191
215
|
|
|
192
216
|
input: syntax: input ["label"] [inputType=TYPE] [placeholder="text"]
|
|
@@ -198,15 +222,53 @@ nav: syntax: nav ["item1","item2"] [vertical] [active=N] OR nav { item "Label" i
|
|
|
198
222
|
- active: 0-based index of active item.
|
|
199
223
|
- Both array and block syntax are valid.
|
|
200
224
|
|
|
225
|
+
# INTERACTION WIRING
|
|
226
|
+
Every clickable element (button, link, card, icon, avatar, badge, image, nav/dropdown item) declares exactly ONE interaction attr:
|
|
227
|
+
- navigate="Page Title or URL": page transition. A value exactly matching another top-level page title links the screens; anything else is treated as a URL.
|
|
228
|
+
- opens="id": opens the modal/drawer with that id (same page).
|
|
229
|
+
- toggles="id": shows/hides the modal/drawer with that id (same page).
|
|
230
|
+
- action="name": named in-screen behavior (e.g. "submit", "logout", "delete"). action="none" marks a deliberately inert element.
|
|
231
|
+
modal/drawer need id="\u2026" to be reachable by opens/toggles.
|
|
232
|
+
|
|
233
|
+
\`\`\`
|
|
234
|
+
button "Sign in" primary action="submit"
|
|
235
|
+
button "Delete account" danger opens="confirm-delete"
|
|
236
|
+
modal "Confirm delete" id="confirm-delete" { text "Are you sure?" }
|
|
237
|
+
button "" icon="bell" aria="Notifications" ghost toggles="notif-drawer"
|
|
238
|
+
drawer "Notifications" id="notif-drawer" position=right { list ["No new notifications"] }
|
|
239
|
+
card "Order #1042" navigate="Order Detail" { text "2 items" }
|
|
240
|
+
link "Docs" navigate="https://docs.example.com"
|
|
241
|
+
nav vertical {
|
|
242
|
+
item "Dashboard" icon="home" navigate="Dashboard" active
|
|
243
|
+
item "Help" icon="info" opens="help-modal"
|
|
244
|
+
}
|
|
245
|
+
modal "Help" id="help-modal" { text "FAQ" }
|
|
246
|
+
dropdown {
|
|
247
|
+
item "Settings" navigate="Settings"
|
|
248
|
+
item "Logout" action="logout"
|
|
249
|
+
}
|
|
250
|
+
\`\`\`
|
|
251
|
+
|
|
252
|
+
# LAYOUT GUIDANCE
|
|
253
|
+
Wireframes are judged on layout quality, not just valid syntax. Follow these composition rules:
|
|
254
|
+
|
|
255
|
+
- ADAPTIVE TARGET-N GRID: When showing N peer items (cards, tiles, stat boxes, product thumbnails), lay them out as an even grid whose column count fits N \u2014 do NOT stack everything in one column. Use a row with equal-width children: row gap=4 { col flex=1 { \u2026 } col flex=1 { \u2026 } col flex=1 { \u2026 } } gives 3 equal columns. For many items, add wrap so they reflow into rows of equal columns: row gap=4 wrap { /* each item a fixed-width or flex card */ }. Keep every column the same width (flex=1, or span out of 12) and one consistent gap.
|
|
256
|
+
- SYMMETRIC MARGINS & SPACING: Use consistent, symmetric padding and gaps. Give header/main/footer the same horizontal padding (e.g. p=4) so content edges line up. Use ONE gap value within a group rather than ad-hoc per-item margins. Left and right insets should match; avoid lopsided spacing.
|
|
257
|
+
- CHAT-REGION COMPOSITION: A chat / conversation / messaging screen is three stacked regions: (1) header with the contact/title, (2) main scroll holding the message list (alternate alignment \u2014 incoming left, outgoing right), and (3) a bottom input bar as a row pinned below main: row gap=2 { input "" placeholder="Message" flex=1 button "" icon="send" aria="Send" primary }. The composer is its OWN row outside the scroll area, never inside the message list.
|
|
258
|
+
- INPUT SIZING: Inputs, selects and textareas in a form should fill their container \u2014 w="full" when stacked in a col, or flex=1 when sharing a row with a button. Keep a consistent size across one form. A search field uses input with icon="search".
|
|
259
|
+
- ACCESSIBLE ICON BUTTONS: Every icon-only button needs an accessible name: button "" icon="x" aria="Close" ghost.
|
|
260
|
+
|
|
201
261
|
# CONSTRAINTS
|
|
202
|
-
DO: Emit multiple top-level page declarations when the user asks for multiple screens. Use viewport="WxH" or at(x, y) to position them. Use semantic layout (header, main, sidebar, footer). Use row/col for flex layouts. Quote all strings with double quotes. Write booleans without =true. Use inputType NOT type. Use w/h on components (width/height only on page).
|
|
262
|
+
DO: Emit multiple top-level page declarations when the user asks for multiple screens. Use viewport="WxH" or at(x, y) to position them. Use semantic layout (header, main, sidebar, footer). Use row/col for flex layouts. Quote all strings with double quotes. Write booleans without =true. Use inputType NOT type. Use w/h on components (width/height only on page). Wire every clickable element with exactly one interaction attr (navigate/opens/toggles/action).
|
|
203
263
|
DO NOT: Use components not in the spec. Quote numeric values. Quote enum values (start, center, between etc). Write boolean=true. Nest page inside page. Use HTML / CSS / JSX syntax. Collapse multi-view apps into one page with a sidebar tab switcher (use separate top-level pages instead).
|
|
204
264
|
|
|
205
265
|
# MAPPING UI TO COMPONENTS
|
|
206
266
|
- Photos / images / thumbnails -> placeholder with h and w
|
|
207
267
|
- Maps / charts / graphs -> placeholder
|
|
208
268
|
- Filter chips / tags -> badge
|
|
209
|
-
- Icon buttons -> button "" icon="name" ghost
|
|
269
|
+
- Icon buttons -> button "" icon="name" aria="Action" ghost (always give an accessible name)
|
|
270
|
+
- Grid of N peer items -> row [wrap] with equal col flex=1 children (column count fits N)
|
|
271
|
+
- Chat / messaging screen -> header + main scroll (message list) + bottom row { input flex=1 button "" icon="send" aria="Send" }
|
|
210
272
|
- Search box -> input with icon="search"
|
|
211
273
|
- Logo area -> icon or placeholder
|
|
212
274
|
- Multiple distinct screens -> multiple top-level page declarations (one per screen)`;
|
|
@@ -227,8 +289,9 @@ function buildCompactGrammarPrompt() {
|
|
|
227
289
|
- Use viewport="WxH" per page; omit at() to auto-flow, use at(x, y) to pin.
|
|
228
290
|
- Multi-view apps default to separate top-level pages (not sidebar collapse).
|
|
229
291
|
|
|
230
|
-
#
|
|
231
|
-
#
|
|
292
|
+
# SHARED PAGE LAYOUTS: layout NAME { \u2026 slot \u2026 } defines a top-level shell; slot is a bare marker with no name or braces; page "Title" uses=NAME { \u2026 } places that page inside the shell. Layouts and pages are top-level siblings.
|
|
293
|
+
# LAYOUT: page(at, viewport, width, height, device, centered, uses), header(h, border), main(p, scroll), footer(h, border), sidebar(w, border, position), section, row(gap, justify, align, wrap), col(gap, flex, span), stack, relative
|
|
294
|
+
# CONTAINERS: card(p, shadow), modal(w, id), drawer(w, position, id), accordion
|
|
232
295
|
# TEXT: text(size, weight, muted), title(level), link(href)
|
|
233
296
|
# VISUAL: icon(Lucide name), avatar(size), badge(variant), image, placeholder(h, w)
|
|
234
297
|
# FORM: button(primary/danger/outline/ghost, icon, size), input(inputType, placeholder), select, checkbox, radio, switch, slider, textarea
|
|
@@ -237,11 +300,23 @@ function buildCompactGrammarPrompt() {
|
|
|
237
300
|
# FEEDBACK: alert(variant), toast, progress(value), spinner
|
|
238
301
|
# UTILITY: divider
|
|
239
302
|
|
|
303
|
+
# INTERACTIONS
|
|
304
|
+
- Every clickable element (button, link, card, icon, avatar, badge, image, nav/dropdown item) declares exactly ONE of: navigate="Page Title or URL" | opens="modal/drawer id" | toggles="modal/drawer id" | action="name" ("none" = deliberately inert).
|
|
305
|
+
- modal/drawer take id="\u2026" as the opens/toggles target.
|
|
306
|
+
- nav { item "Home" navigate="Home" } dropdown { item "Logout" action="logout" }
|
|
307
|
+
|
|
308
|
+
# LAYOUT GUIDANCE
|
|
309
|
+
- Grid of N peer items: row [wrap] with equal col flex=1 children (column count fits N) \u2014 don't stack peers in one column.
|
|
310
|
+
- Symmetric spacing: same horizontal padding on header/main/footer; one consistent gap per group; match left/right insets.
|
|
311
|
+
- Chat screen: header + main scroll (message list, incoming left / outgoing right) + bottom composer row { input flex=1 button "" icon="send" aria="Send" } OUTSIDE the scroll area.
|
|
312
|
+
- Input sizing: inputs/selects fill their container (w="full" stacked, flex=1 in a row); consistent size per form.
|
|
313
|
+
|
|
240
314
|
# KEY RULES
|
|
241
315
|
- sidebar: direct child of row, w=240, border.
|
|
242
316
|
- nav in sidebar: must have vertical.
|
|
243
317
|
- cards in row: flex=1 for equal width.
|
|
244
|
-
- icon-only button: button "" icon="name" ghost.
|
|
318
|
+
- icon-only button: button "" icon="name" aria="Action" ghost (aria = accessible name).
|
|
319
|
+
- every clickable element: exactly one of navigate/opens/toggles/action.
|
|
245
320
|
- inputType (not type) for inputs.
|
|
246
321
|
- viewport (not width/height) when emitting multi-page canvas.
|
|
247
322
|
- Multiple screens \u2192 multiple top-level pages, not nested pages.
|
package/dist/index.js
CHANGED
|
@@ -51,8 +51,31 @@ Renderer modes (the host picks one; you only need to emit valid pages):
|
|
|
51
51
|
- renderCanvas(doc) \u2014 composes all pages into one bounded canvas.
|
|
52
52
|
- renderPage(page) \u2014 single-page export primitive (1 page = 1 file).
|
|
53
53
|
|
|
54
|
+
# SHARED PAGE LAYOUTS
|
|
55
|
+
When several pages share a shell, define it once as a top-level layout and put
|
|
56
|
+
the varying page content at its slot. Layout definitions and pages are siblings;
|
|
57
|
+
a layout is not a screen by itself.
|
|
58
|
+
|
|
59
|
+
- layout NAME { ... slot ... } \u2014 a named page shell. NAME is a bare identifier.
|
|
60
|
+
- slot \u2014 a bare positional marker inside a layout. It takes no name and no braces.
|
|
61
|
+
- page "Title" uses=NAME { ... } \u2014 draw the page inside layout NAME; the page body
|
|
62
|
+
contains only the content unique to that screen.
|
|
63
|
+
|
|
64
|
+
Example:
|
|
65
|
+
|
|
66
|
+
\`\`\`
|
|
67
|
+
layout app {
|
|
68
|
+
header { title "Acme" }
|
|
69
|
+
slot
|
|
70
|
+
footer { text "\xA9 2026 Acme" }
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
page "Home" uses=app { text "Welcome back" }
|
|
74
|
+
page "Docs" uses=app { text "Getting started" }
|
|
75
|
+
\`\`\`
|
|
76
|
+
|
|
54
77
|
# LAYOUT COMPONENTS
|
|
55
|
-
page: Root container. Attrs: title (string arg), at(x, y), viewport, width, height (pixels), device (mobile/tablet/desktop preset), centered (boolean).
|
|
78
|
+
page: Root container. Attrs: title (string arg), uses (layout name), at(x, y), viewport, width, height (pixels), device (mobile/tablet/desktop preset), centered (boolean).
|
|
56
79
|
header: Top section. Attrs: h (height), p (padding), border (boolean, default true).
|
|
57
80
|
main: Primary content. Attrs: p, scroll (boolean).
|
|
58
81
|
footer: Bottom section. Attrs: h, p, border.
|
|
@@ -64,26 +87,26 @@ stack: Layered container. Attrs: gap.
|
|
|
64
87
|
relative: Positioned container.
|
|
65
88
|
|
|
66
89
|
# CONTENT CONTAINERS
|
|
67
|
-
card: Bordered box. String arg for title. Attrs: p (0-8), w, h, shadow (none/sm/md/lg), border.
|
|
68
|
-
modal: Dialog. String arg for title. Attrs: w, h.
|
|
69
|
-
drawer: Slide panel. String arg for title. Attrs: w, position.
|
|
90
|
+
card: Bordered box. String arg for title. Attrs: p (0-8), w, h, shadow (none/sm/md/lg), border, navigate, opens, toggles, action.
|
|
91
|
+
modal: Dialog. String arg for title. Attrs: w, h, id (opens/toggles target).
|
|
92
|
+
drawer: Slide panel. String arg for title. Attrs: w, position, id (opens/toggles target).
|
|
70
93
|
accordion: Expandable section. String arg for title.
|
|
71
94
|
section: Grouped content. String arg for title.
|
|
72
95
|
|
|
73
96
|
# TEXT COMPONENTS
|
|
74
97
|
text: Inline text. String arg required. Attrs: size (xs/sm/base/md/lg/xl), weight (normal/medium/semibold/bold), muted, align.
|
|
75
98
|
title: Heading. String arg required. Attrs: level (1-6), size, align, mb, mt.
|
|
76
|
-
link: Hyperlink. String arg required. Attrs: href, external, ml, mr.
|
|
99
|
+
link: Hyperlink. String arg required. Attrs: href, external, ml, mr, navigate, opens, toggles, action.
|
|
77
100
|
|
|
78
101
|
# VISUAL COMPONENTS
|
|
79
|
-
icon: Lucide icon. String arg is icon name. Attrs: size (xs/sm/md/lg/xl), muted.
|
|
80
|
-
avatar: User avatar. String arg is name (shows initials). Attrs: size, src.
|
|
81
|
-
badge: Label tag. String arg required. Attrs: variant (default/primary/success/warning/danger), size, pill.
|
|
82
|
-
image: Image element. String arg is src. Attrs: w, h, alt.
|
|
102
|
+
icon: Lucide icon. String arg is icon name \u2014 must be a valid Lucide name in kebab-case (e.g. the overflow/kebab menu is "ellipsis-vertical", horizontal is "ellipsis"; not "more-vertical"). Unknown names render as a "?" placeholder. Attrs: size (xs/sm/md/lg/xl), muted, navigate, opens, toggles, action.
|
|
103
|
+
avatar: User avatar. String arg is name (shows initials). Attrs: size, src, navigate, opens, toggles, action.
|
|
104
|
+
badge: Label tag. String arg required. Attrs: variant (default/primary/success/warning/danger), size, pill, navigate, opens, toggles, action.
|
|
105
|
+
image: Image element. String arg is src. Attrs: w, h, alt, navigate, opens, toggles, action.
|
|
83
106
|
placeholder: Dashed box for images/media. String arg is label. Attrs: h, w.
|
|
84
107
|
|
|
85
108
|
# FORM COMPONENTS
|
|
86
|
-
button: Clickable button. String arg is label (empty "" for icon-only). Attrs: primary/secondary/outline/ghost/danger (boolean variants), icon, size (xs/sm/md/lg), disabled, w.
|
|
109
|
+
button: Clickable button. String arg is label (empty "" for icon-only). Attrs: primary/secondary/outline/ghost/danger (boolean variants), icon, size (xs/sm/md/lg), disabled, w, aria (accessible name for icon-only buttons \u2192 renders aria-label), title (tooltip), navigate, opens, toggles, action.
|
|
87
110
|
input: Text input. String arg is label. Attrs: placeholder, inputType (text/email/password/number/tel/url/search/date), icon, w, size, required, disabled.
|
|
88
111
|
select: Dropdown. String arg is label. Array arg for options. Attrs: placeholder, value.
|
|
89
112
|
checkbox: Checkbox. String arg is label. Attrs: checked, disabled.
|
|
@@ -96,7 +119,7 @@ textarea: Multiline input. String arg is label. Attrs: rows, placeholder.
|
|
|
96
119
|
nav: Menu. Array arg for simple items OR block with item children.
|
|
97
120
|
- Array syntax: nav ["Home", "About", "Contact"]
|
|
98
121
|
- Block syntax: nav { item "Label" icon="name" active }
|
|
99
|
-
item: Nav item (inside nav/dropdown block). String arg is label. Attrs: icon, active, disabled, href.
|
|
122
|
+
item: Nav item (inside nav/dropdown block). String arg is label. Attrs: icon, active, disabled, href, navigate, opens, toggles, action.
|
|
100
123
|
tabs: Tab bar. Array arg for labels. Attrs: active (0-based index).
|
|
101
124
|
- Block syntax: tabs { tab "Label" { children } }
|
|
102
125
|
breadcrumb: Path trail. Array arg for items.
|
|
@@ -157,9 +180,10 @@ col: syntax: col [gap=N] [flex=N] [span=N] [scroll] { children }
|
|
|
157
180
|
stack: syntax: stack [gap=N] { children }
|
|
158
181
|
- Unlike col, stack only takes content height (does not flex to fill space).
|
|
159
182
|
|
|
160
|
-
button: syntax: button "label" [variant] [size=SIZE] [icon="name"]
|
|
183
|
+
button: syntax: button "label" [variant] [size=SIZE] [icon="name"] [aria="Accessible name"]
|
|
161
184
|
- Variants are boolean attrs: primary, secondary, outline, ghost, danger.
|
|
162
|
-
- Icon-only: button "" icon="name" ghost (empty string required).
|
|
185
|
+
- Icon-only: button "" icon="name" aria="Action" ghost (empty string required).
|
|
186
|
+
- ALWAYS give an icon-only button an accessible name via aria="\u2026" (renders aria-label) so screen readers can describe it. title="\u2026" is a fallback.
|
|
163
187
|
- NOT: button icon="name" (missing string arg causes parse error).
|
|
164
188
|
|
|
165
189
|
input: syntax: input ["label"] [inputType=TYPE] [placeholder="text"]
|
|
@@ -171,15 +195,53 @@ nav: syntax: nav ["item1","item2"] [vertical] [active=N] OR nav { item "Label" i
|
|
|
171
195
|
- active: 0-based index of active item.
|
|
172
196
|
- Both array and block syntax are valid.
|
|
173
197
|
|
|
198
|
+
# INTERACTION WIRING
|
|
199
|
+
Every clickable element (button, link, card, icon, avatar, badge, image, nav/dropdown item) declares exactly ONE interaction attr:
|
|
200
|
+
- navigate="Page Title or URL": page transition. A value exactly matching another top-level page title links the screens; anything else is treated as a URL.
|
|
201
|
+
- opens="id": opens the modal/drawer with that id (same page).
|
|
202
|
+
- toggles="id": shows/hides the modal/drawer with that id (same page).
|
|
203
|
+
- action="name": named in-screen behavior (e.g. "submit", "logout", "delete"). action="none" marks a deliberately inert element.
|
|
204
|
+
modal/drawer need id="\u2026" to be reachable by opens/toggles.
|
|
205
|
+
|
|
206
|
+
\`\`\`
|
|
207
|
+
button "Sign in" primary action="submit"
|
|
208
|
+
button "Delete account" danger opens="confirm-delete"
|
|
209
|
+
modal "Confirm delete" id="confirm-delete" { text "Are you sure?" }
|
|
210
|
+
button "" icon="bell" aria="Notifications" ghost toggles="notif-drawer"
|
|
211
|
+
drawer "Notifications" id="notif-drawer" position=right { list ["No new notifications"] }
|
|
212
|
+
card "Order #1042" navigate="Order Detail" { text "2 items" }
|
|
213
|
+
link "Docs" navigate="https://docs.example.com"
|
|
214
|
+
nav vertical {
|
|
215
|
+
item "Dashboard" icon="home" navigate="Dashboard" active
|
|
216
|
+
item "Help" icon="info" opens="help-modal"
|
|
217
|
+
}
|
|
218
|
+
modal "Help" id="help-modal" { text "FAQ" }
|
|
219
|
+
dropdown {
|
|
220
|
+
item "Settings" navigate="Settings"
|
|
221
|
+
item "Logout" action="logout"
|
|
222
|
+
}
|
|
223
|
+
\`\`\`
|
|
224
|
+
|
|
225
|
+
# LAYOUT GUIDANCE
|
|
226
|
+
Wireframes are judged on layout quality, not just valid syntax. Follow these composition rules:
|
|
227
|
+
|
|
228
|
+
- ADAPTIVE TARGET-N GRID: When showing N peer items (cards, tiles, stat boxes, product thumbnails), lay them out as an even grid whose column count fits N \u2014 do NOT stack everything in one column. Use a row with equal-width children: row gap=4 { col flex=1 { \u2026 } col flex=1 { \u2026 } col flex=1 { \u2026 } } gives 3 equal columns. For many items, add wrap so they reflow into rows of equal columns: row gap=4 wrap { /* each item a fixed-width or flex card */ }. Keep every column the same width (flex=1, or span out of 12) and one consistent gap.
|
|
229
|
+
- SYMMETRIC MARGINS & SPACING: Use consistent, symmetric padding and gaps. Give header/main/footer the same horizontal padding (e.g. p=4) so content edges line up. Use ONE gap value within a group rather than ad-hoc per-item margins. Left and right insets should match; avoid lopsided spacing.
|
|
230
|
+
- CHAT-REGION COMPOSITION: A chat / conversation / messaging screen is three stacked regions: (1) header with the contact/title, (2) main scroll holding the message list (alternate alignment \u2014 incoming left, outgoing right), and (3) a bottom input bar as a row pinned below main: row gap=2 { input "" placeholder="Message" flex=1 button "" icon="send" aria="Send" primary }. The composer is its OWN row outside the scroll area, never inside the message list.
|
|
231
|
+
- INPUT SIZING: Inputs, selects and textareas in a form should fill their container \u2014 w="full" when stacked in a col, or flex=1 when sharing a row with a button. Keep a consistent size across one form. A search field uses input with icon="search".
|
|
232
|
+
- ACCESSIBLE ICON BUTTONS: Every icon-only button needs an accessible name: button "" icon="x" aria="Close" ghost.
|
|
233
|
+
|
|
174
234
|
# CONSTRAINTS
|
|
175
|
-
DO: Emit multiple top-level page declarations when the user asks for multiple screens. Use viewport="WxH" or at(x, y) to position them. Use semantic layout (header, main, sidebar, footer). Use row/col for flex layouts. Quote all strings with double quotes. Write booleans without =true. Use inputType NOT type. Use w/h on components (width/height only on page).
|
|
235
|
+
DO: Emit multiple top-level page declarations when the user asks for multiple screens. Use viewport="WxH" or at(x, y) to position them. Use semantic layout (header, main, sidebar, footer). Use row/col for flex layouts. Quote all strings with double quotes. Write booleans without =true. Use inputType NOT type. Use w/h on components (width/height only on page). Wire every clickable element with exactly one interaction attr (navigate/opens/toggles/action).
|
|
176
236
|
DO NOT: Use components not in the spec. Quote numeric values. Quote enum values (start, center, between etc). Write boolean=true. Nest page inside page. Use HTML / CSS / JSX syntax. Collapse multi-view apps into one page with a sidebar tab switcher (use separate top-level pages instead).
|
|
177
237
|
|
|
178
238
|
# MAPPING UI TO COMPONENTS
|
|
179
239
|
- Photos / images / thumbnails -> placeholder with h and w
|
|
180
240
|
- Maps / charts / graphs -> placeholder
|
|
181
241
|
- Filter chips / tags -> badge
|
|
182
|
-
- Icon buttons -> button "" icon="name" ghost
|
|
242
|
+
- Icon buttons -> button "" icon="name" aria="Action" ghost (always give an accessible name)
|
|
243
|
+
- Grid of N peer items -> row [wrap] with equal col flex=1 children (column count fits N)
|
|
244
|
+
- Chat / messaging screen -> header + main scroll (message list) + bottom row { input flex=1 button "" icon="send" aria="Send" }
|
|
183
245
|
- Search box -> input with icon="search"
|
|
184
246
|
- Logo area -> icon or placeholder
|
|
185
247
|
- Multiple distinct screens -> multiple top-level page declarations (one per screen)`;
|
|
@@ -200,8 +262,9 @@ function buildCompactGrammarPrompt() {
|
|
|
200
262
|
- Use viewport="WxH" per page; omit at() to auto-flow, use at(x, y) to pin.
|
|
201
263
|
- Multi-view apps default to separate top-level pages (not sidebar collapse).
|
|
202
264
|
|
|
203
|
-
#
|
|
204
|
-
#
|
|
265
|
+
# SHARED PAGE LAYOUTS: layout NAME { \u2026 slot \u2026 } defines a top-level shell; slot is a bare marker with no name or braces; page "Title" uses=NAME { \u2026 } places that page inside the shell. Layouts and pages are top-level siblings.
|
|
266
|
+
# LAYOUT: page(at, viewport, width, height, device, centered, uses), header(h, border), main(p, scroll), footer(h, border), sidebar(w, border, position), section, row(gap, justify, align, wrap), col(gap, flex, span), stack, relative
|
|
267
|
+
# CONTAINERS: card(p, shadow), modal(w, id), drawer(w, position, id), accordion
|
|
205
268
|
# TEXT: text(size, weight, muted), title(level), link(href)
|
|
206
269
|
# VISUAL: icon(Lucide name), avatar(size), badge(variant), image, placeholder(h, w)
|
|
207
270
|
# FORM: button(primary/danger/outline/ghost, icon, size), input(inputType, placeholder), select, checkbox, radio, switch, slider, textarea
|
|
@@ -210,11 +273,23 @@ function buildCompactGrammarPrompt() {
|
|
|
210
273
|
# FEEDBACK: alert(variant), toast, progress(value), spinner
|
|
211
274
|
# UTILITY: divider
|
|
212
275
|
|
|
276
|
+
# INTERACTIONS
|
|
277
|
+
- Every clickable element (button, link, card, icon, avatar, badge, image, nav/dropdown item) declares exactly ONE of: navigate="Page Title or URL" | opens="modal/drawer id" | toggles="modal/drawer id" | action="name" ("none" = deliberately inert).
|
|
278
|
+
- modal/drawer take id="\u2026" as the opens/toggles target.
|
|
279
|
+
- nav { item "Home" navigate="Home" } dropdown { item "Logout" action="logout" }
|
|
280
|
+
|
|
281
|
+
# LAYOUT GUIDANCE
|
|
282
|
+
- Grid of N peer items: row [wrap] with equal col flex=1 children (column count fits N) \u2014 don't stack peers in one column.
|
|
283
|
+
- Symmetric spacing: same horizontal padding on header/main/footer; one consistent gap per group; match left/right insets.
|
|
284
|
+
- Chat screen: header + main scroll (message list, incoming left / outgoing right) + bottom composer row { input flex=1 button "" icon="send" aria="Send" } OUTSIDE the scroll area.
|
|
285
|
+
- Input sizing: inputs/selects fill their container (w="full" stacked, flex=1 in a row); consistent size per form.
|
|
286
|
+
|
|
213
287
|
# KEY RULES
|
|
214
288
|
- sidebar: direct child of row, w=240, border.
|
|
215
289
|
- nav in sidebar: must have vertical.
|
|
216
290
|
- cards in row: flex=1 for equal width.
|
|
217
|
-
- icon-only button: button "" icon="name" ghost.
|
|
291
|
+
- icon-only button: button "" icon="name" aria="Action" ghost (aria = accessible name).
|
|
292
|
+
- every clickable element: exactly one of navigate/opens/toggles/action.
|
|
218
293
|
- inputType (not type) for inputs.
|
|
219
294
|
- viewport (not width/height) when emitting multi-page canvas.
|
|
220
295
|
- Multiple screens \u2192 multiple top-level pages, not nested pages.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wireweave/agent-prompts",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0-beta.1",
|
|
4
4
|
"description": "Canonical grammar prompts for LLM agents generating Wireweave DSL (multi-page aware)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"sideEffects": false,
|
|
@@ -22,23 +22,6 @@
|
|
|
22
22
|
"files": [
|
|
23
23
|
"dist"
|
|
24
24
|
],
|
|
25
|
-
"scripts": {
|
|
26
|
-
"build": "tsup",
|
|
27
|
-
"test": "vitest run",
|
|
28
|
-
"test:watch": "vitest",
|
|
29
|
-
"typecheck": "tsc --noEmit",
|
|
30
|
-
"lint": "eslint .",
|
|
31
|
-
"lint:fix": "eslint . --fix",
|
|
32
|
-
"format": "prettier --write .",
|
|
33
|
-
"format:check": "prettier --check .",
|
|
34
|
-
"knip": "knip",
|
|
35
|
-
"publint": "publint",
|
|
36
|
-
"packlint": "packlint check",
|
|
37
|
-
"clean": "rm -rf dist",
|
|
38
|
-
"release": "release-it",
|
|
39
|
-
"release:beta": "release-it --preRelease=beta",
|
|
40
|
-
"prepare": "husky"
|
|
41
|
-
},
|
|
42
25
|
"lint-staged": {
|
|
43
26
|
"*.{ts,js,mjs,cjs}": [
|
|
44
27
|
"eslint --fix",
|
|
@@ -79,10 +62,27 @@
|
|
|
79
62
|
"license": "MIT",
|
|
80
63
|
"repository": {
|
|
81
64
|
"type": "git",
|
|
82
|
-
"url": "git+https://github.com/wireweave/
|
|
65
|
+
"url": "git+https://github.com/wireweave/wireweave.git",
|
|
66
|
+
"directory": "packages/agent-prompts"
|
|
83
67
|
},
|
|
84
68
|
"bugs": {
|
|
85
|
-
"url": "https://github.com/wireweave/
|
|
69
|
+
"url": "https://github.com/wireweave/wireweave/issues"
|
|
86
70
|
},
|
|
87
|
-
"homepage": "https://
|
|
88
|
-
|
|
71
|
+
"homepage": "https://docs.wireweave.org",
|
|
72
|
+
"scripts": {
|
|
73
|
+
"build": "tsup",
|
|
74
|
+
"test": "vitest run",
|
|
75
|
+
"test:watch": "vitest",
|
|
76
|
+
"typecheck": "tsc --noEmit",
|
|
77
|
+
"lint": "eslint .",
|
|
78
|
+
"lint:fix": "eslint . --fix",
|
|
79
|
+
"format": "prettier --write .",
|
|
80
|
+
"format:check": "prettier --check .",
|
|
81
|
+
"knip": "knip",
|
|
82
|
+
"publint": "publint",
|
|
83
|
+
"packlint": "packlint check",
|
|
84
|
+
"clean": "rm -rf dist",
|
|
85
|
+
"release": "release-it",
|
|
86
|
+
"release:beta": "release-it --preRelease=beta"
|
|
87
|
+
}
|
|
88
|
+
}
|