@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 CHANGED
@@ -1,6 +1,12 @@
1
1
  # @wireweave/agent-prompts
2
2
 
3
- Canonical grammar prompts for LLM agents that generate Wireweave DSL. The package is the single source of truth so consumers (`agent-harness`, `api-server`, future plugins) stay in sync with the multi-page canvas model in `@wireweave/core` 3.x.
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
- ## Use
17
+ ## Usage
12
18
 
13
19
  ```ts
14
20
  import { buildGrammarPrompt, buildCompactGrammarPrompt } from '@wireweave/agent-prompts'
15
21
 
16
- // Full prompt — generation phase.
22
+ // Full guide (~180 lines) — generation phase.
17
23
  const system = buildGrammarPrompt()
18
24
 
19
- // Compact prompt — analyze / plan phases (saves ~800 tokens).
25
+ // Compact guide (~60 lines) — analyze / plan phases, fewer tokens.
20
26
  const compact = buildCompactGrammarPrompt()
21
27
  ```
22
28
 
23
- Both functions return a single Markdown-flavoured string that can be injected verbatim into an LLM system message. No runtime dependencies.
29
+ ## API
30
+
31
+ ### `buildGrammarPrompt(): string`
24
32
 
25
- ## What's covered
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
- - Single-page wireframes (legacy).
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
- ## Why a separate package
37
+ A condensed grammar guide for the analyze / plan phases, where the full guide is more than needed.
34
38
 
35
- Before this package the DSL grammar guide was duplicated in
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
- # LAYOUT: page(at, viewport, width, height, device, centered), 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
231
- # CONTAINERS: card(p, shadow), modal(w), drawer(w, position), accordion
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
- # LAYOUT: page(at, viewport, width, height, device, centered), 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
204
- # CONTAINERS: card(p, shadow), modal(w), drawer(w, position), accordion
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.1.1",
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/agent-prompts.git"
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/agent-prompts/issues"
69
+ "url": "https://github.com/wireweave/wireweave/issues"
86
70
  },
87
- "homepage": "https://github.com/wireweave/agent-prompts#readme"
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
+ }