stitch-kit 1.5.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.
Files changed (98) hide show
  1. package/AGENTS.md +139 -0
  2. package/CHANGELOG.md +86 -0
  3. package/README.md +167 -0
  4. package/agents/stitch-kit.md +93 -0
  5. package/bin/stitch-kit.mjs +430 -0
  6. package/docs/architecture.md +118 -0
  7. package/docs/color-prompt-guide.md +119 -0
  8. package/docs/mcp-naming-convention.md +64 -0
  9. package/docs/mcp-schemas/README.md +130 -0
  10. package/docs/mcp-schemas/apply_design_system.json +36 -0
  11. package/docs/mcp-schemas/create_design_system.json +78 -0
  12. package/docs/mcp-schemas/create_project.json +290 -0
  13. package/docs/mcp-schemas/delete_project.json +20 -0
  14. package/docs/mcp-schemas/edit_screens.json +46 -0
  15. package/docs/mcp-schemas/generate_screen_from_text.json +242 -0
  16. package/docs/mcp-schemas/generate_variants.json +77 -0
  17. package/docs/mcp-schemas/get_project.json +137 -0
  18. package/docs/mcp-schemas/get_screen.json +92 -0
  19. package/docs/mcp-schemas/list_design_systems.json +32 -0
  20. package/docs/mcp-schemas/list_projects.json +136 -0
  21. package/docs/mcp-schemas/list_screens.json +56 -0
  22. package/docs/mcp-schemas/update_design_system.json +32 -0
  23. package/docs/mcp-schemas/upload_screens_from_images.json +52 -0
  24. package/docs/prd-to-stitch-workflow.md +137 -0
  25. package/docs/skills-index.md +108 -0
  26. package/docs/tailwind-reference.md +207 -0
  27. package/package.json +41 -0
  28. package/skills/stitch-a11y/SKILL.md +428 -0
  29. package/skills/stitch-a11y/resources/audit-checklist.md +102 -0
  30. package/skills/stitch-animate/SKILL.md +371 -0
  31. package/skills/stitch-animate/resources/animation-patterns.md +248 -0
  32. package/skills/stitch-design-md/SKILL.md +215 -0
  33. package/skills/stitch-design-md/examples/DESIGN.md +54 -0
  34. package/skills/stitch-design-md/examples/usage.md +67 -0
  35. package/skills/stitch-design-md/scripts/fetch-stitch.sh +35 -0
  36. package/skills/stitch-design-system/SKILL.md +314 -0
  37. package/skills/stitch-design-system/resources/tokens-template.css +237 -0
  38. package/skills/stitch-html-components/SKILL.md +344 -0
  39. package/skills/stitch-html-components/resources/architecture-checklist.md +74 -0
  40. package/skills/stitch-html-components/scripts/fetch-stitch.sh +45 -0
  41. package/skills/stitch-loop/SKILL.md +183 -0
  42. package/skills/stitch-loop/examples/SITE.md +39 -0
  43. package/skills/stitch-loop/examples/next-prompt.md +24 -0
  44. package/skills/stitch-loop/examples/usage.md +77 -0
  45. package/skills/stitch-mcp-apply-design-system/SKILL.md +82 -0
  46. package/skills/stitch-mcp-create-design-system/SKILL.md +117 -0
  47. package/skills/stitch-mcp-create-project/SKILL.md +77 -0
  48. package/skills/stitch-mcp-delete-project/SKILL.md +62 -0
  49. package/skills/stitch-mcp-edit-screens/SKILL.md +121 -0
  50. package/skills/stitch-mcp-generate-screen-from-text/SKILL.md +102 -0
  51. package/skills/stitch-mcp-generate-screen-from-text/examples/desktop.md +53 -0
  52. package/skills/stitch-mcp-generate-screen-from-text/examples/mobile.md +71 -0
  53. package/skills/stitch-mcp-generate-variants/SKILL.md +124 -0
  54. package/skills/stitch-mcp-get-project/SKILL.md +67 -0
  55. package/skills/stitch-mcp-get-screen/SKILL.md +117 -0
  56. package/skills/stitch-mcp-get-screen/scripts/fetch-stitch.sh +35 -0
  57. package/skills/stitch-mcp-list-design-systems/SKILL.md +84 -0
  58. package/skills/stitch-mcp-list-projects/SKILL.md +77 -0
  59. package/skills/stitch-mcp-list-screens/SKILL.md +69 -0
  60. package/skills/stitch-mcp-update-design-system/SKILL.md +82 -0
  61. package/skills/stitch-mcp-upload-screens-from-images/SKILL.md +95 -0
  62. package/skills/stitch-mcp-upload-screens-from-images/scripts/encode-image.sh +43 -0
  63. package/skills/stitch-nextjs-components/SKILL.md +181 -0
  64. package/skills/stitch-nextjs-components/resources/architecture-checklist.md +65 -0
  65. package/skills/stitch-nextjs-components/resources/component-template.tsx +101 -0
  66. package/skills/stitch-nextjs-components/scripts/fetch-stitch.sh +45 -0
  67. package/skills/stitch-orchestrator/SKILL.md +337 -0
  68. package/skills/stitch-orchestrator/examples/workflow.md +173 -0
  69. package/skills/stitch-react-components/SKILL.md +236 -0
  70. package/skills/stitch-react-components/references/tailwind-to-react.md +117 -0
  71. package/skills/stitch-react-components/resources/architecture-checklist.md +34 -0
  72. package/skills/stitch-react-components/resources/component-template.tsx +35 -0
  73. package/skills/stitch-react-components/scripts/fetch-stitch.sh +35 -0
  74. package/skills/stitch-react-native-components/SKILL.md +333 -0
  75. package/skills/stitch-react-native-components/resources/architecture-checklist.md +74 -0
  76. package/skills/stitch-react-native-components/resources/component-template.tsx +104 -0
  77. package/skills/stitch-react-native-components/scripts/fetch-stitch.sh +45 -0
  78. package/skills/stitch-remotion/SKILL.md +280 -0
  79. package/skills/stitch-setup/SKILL.md +183 -0
  80. package/skills/stitch-shadcn-ui/SKILL.md +255 -0
  81. package/skills/stitch-skill-creator/SKILL.md +257 -0
  82. package/skills/stitch-skill-creator/references/output-patterns.md +71 -0
  83. package/skills/stitch-skill-creator/scripts/init_stitch_skill.py +229 -0
  84. package/skills/stitch-svelte-components/SKILL.md +282 -0
  85. package/skills/stitch-svelte-components/resources/architecture-checklist.md +62 -0
  86. package/skills/stitch-svelte-components/resources/component-template.svelte +193 -0
  87. package/skills/stitch-svelte-components/scripts/fetch-stitch.sh +36 -0
  88. package/skills/stitch-swiftui-components/SKILL.md +424 -0
  89. package/skills/stitch-swiftui-components/resources/architecture-checklist.md +83 -0
  90. package/skills/stitch-swiftui-components/resources/component-template.swift +131 -0
  91. package/skills/stitch-swiftui-components/resources/layout-mapping.md +155 -0
  92. package/skills/stitch-swiftui-components/scripts/fetch-stitch.sh +45 -0
  93. package/skills/stitch-ued-guide/SKILL.md +124 -0
  94. package/skills/stitch-ui-design-spec-generator/SKILL.md +115 -0
  95. package/skills/stitch-ui-design-spec-generator/examples/usage.md +79 -0
  96. package/skills/stitch-ui-design-variants/SKILL.md +127 -0
  97. package/skills/stitch-ui-prompt-architect/SKILL.md +196 -0
  98. package/skills/stitch-ui-prompt-architect/references/KEYWORDS.md +170 -0
package/skills/stitch-html-components/SKILL.md ADDED
@@ -0,0 +1,344 @@
1
+ ---
2
+ name: stitch-html-components
3
+ description: Converts Stitch designs into clean, platform-agnostic HTML5 + CSS — semantic markup, CSS custom properties for theming, dark mode via prefers-color-scheme, mobile-first responsive, zero framework dependencies. Works in browsers, WebViews, Capacitor, and Ionic.
4
+ allowed-tools:
5
+ - "stitch*:*"
6
+ - "Bash"
7
+ - "Read"
8
+ - "Write"
9
+ ---
10
+
11
+ # Stitch → HTML5 + CSS (Platform-Agnostic)
12
+
13
+ You are a frontend engineer specializing in clean, dependency-free HTML and CSS. You convert Stitch designs into semantic HTML5 with CSS custom properties — no React, no Svelte, no build step. The output runs anywhere: desktop browsers, mobile browsers, iOS WebView, Android WebView, Capacitor apps, and Ionic shells.
14
+
15
+ ## When to use this skill
16
+
17
+ Use this skill when:
18
+ - The user wants **platform-agnostic** output — "just HTML", "no framework", "works everywhere"
19
+ - The target is a **WebView** in a mobile app (Capacitor, Ionic, Cordova)
20
+ - Building a **static site** or embedding in a CMS
21
+ - The user hasn't chosen a framework yet and wants a working prototype
22
+ - Generating the **HTML base** before wrapping with Capacitor for native mobile
23
+
24
+ ## Prerequisites
25
+
26
+ - Access to Stitch MCP server
27
+ - A Stitch project with at least one generated screen
28
+
29
+ ## Step 1: Retrieve the design
30
+
31
+ 1. **Namespace discovery** — `list_tools` to find the Stitch MCP prefix
32
+ 2. **Fetch metadata** — `[prefix]:get_screen` for the design JSON
33
+ 3. **Download HTML** — GCS URLs need the reliable downloader:
34
+ ```bash
35
+ bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"
36
+ ```
37
+ 4. **Visual audit** — check `screenshot.downloadUrl` before rewriting
38
+
39
+ ## Step 2: File structure
40
+
41
+ ```
42
+ output/
43
+ ├── index.html ← Main page (or rename per screen)
44
+ ├── css/
45
+ │ ├── tokens.css ← CSS custom properties (light + dark)
46
+ │ ├── base.css ← Reset, body defaults, typography
47
+ │ └── components.css ← Component styles
48
+ ├── js/
49
+ │ └── main.js ← Minimal JS (theme toggle, mobile menu only)
50
+ └── assets/
51
+ └── images/
52
+ ```
53
+
54
+ For multi-screen projects, each screen gets its own HTML file. Shared CSS lives in `tokens.css` and `base.css`.
55
+
56
+ ## Step 3: CSS custom properties
57
+
58
+ Map Stitch colors to semantic tokens. Always generate **both light and dark** at the same time.
59
+
60
+ ```css
61
+ /* css/tokens.css */
62
+
63
+ :root {
64
+ /* Extract these from the Stitch HTML's tailwind.config in <head> */
65
+ --color-background: [hex];
66
+ --color-surface: [hex];
67
+ --color-primary: [hex];
68
+ --color-primary-fg: [hex];
69
+ --color-text: [hex];
70
+ --color-text-muted: [hex];
71
+ --color-border: [hex];
72
+
73
+ --font-sans: [font-stack];
74
+ --font-mono: ui-monospace, monospace;
75
+
76
+ --radius-sm: [value];
77
+ --radius-md: [value];
78
+ --radius-lg: [value];
79
+
80
+ --shadow-sm: 0 1px 3px rgb(0 0 0 / 0.1);
81
+ --shadow-md: 0 4px 12px rgb(0 0 0 / 0.1);
82
+
83
+ --transition: 150ms cubic-bezier(0.4, 0, 0.2, 1);
84
+ }
85
+
86
+ /* Dark mode — system preference */
87
+ @media (prefers-color-scheme: dark) {
88
+ :root {
89
+ --color-background: [dark-hex];
90
+ --color-surface: [dark-hex];
91
+ --color-primary: [dark-adjusted-hex];
92
+ --color-primary-fg: [dark-hex];
93
+ --color-text: [dark-hex];
94
+ --color-text-muted: [dark-hex];
95
+ --color-border: [dark-hex];
96
+ }
97
+ }
98
+
99
+ /* Dark mode — manual toggle via data-theme="dark" on <html> */
100
+ [data-theme="dark"] {
101
+ --color-background: [dark-hex];
102
+ --color-surface: [dark-hex];
103
+ /* ... same values as above */
104
+ }
105
+ ```
106
+
107
+ If the project already has a `design-tokens.css` (from `stitch-design-system`), import it instead of recreating tokens.
108
+
109
+ ## Step 4: Base CSS
110
+
111
+ ```css
112
+ /* css/base.css */
113
+
114
+ *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
115
+
116
+ html {
117
+ font-size: 16px;
118
+ /* Safe area insets for notched phones */
119
+ padding: env(safe-area-inset-top) env(safe-area-inset-right)
120
+ env(safe-area-inset-bottom) env(safe-area-inset-left);
121
+ -webkit-text-size-adjust: 100%; /* Prevent font scaling on iOS rotation */
122
+ }
123
+
124
+ body {
125
+ font-family: var(--font-sans);
126
+ background-color: var(--color-background);
127
+ color: var(--color-text);
128
+ line-height: 1.5;
129
+ -webkit-font-smoothing: antialiased;
130
+ }
131
+
132
+ /* Skip link for accessibility */
133
+ .sr-only {
134
+ position: absolute; width: 1px; height: 1px;
135
+ padding: 0; margin: -1px; overflow: hidden;
136
+ clip: rect(0,0,0,0); white-space: nowrap; border-width: 0;
137
+ }
138
+
139
+ .skip-link { /* ... see stitch-a11y skill */ }
140
+
141
+ /* Focus ring — keyboard only */
142
+ *:focus-visible {
143
+ outline: 2px solid var(--color-primary);
144
+ outline-offset: 2px;
145
+ border-radius: 2px;
146
+ }
147
+
148
+ /* Reduced motion */
149
+ @media (prefers-reduced-motion: reduce) {
150
+ *, *::before, *::after {
151
+ animation-duration: 0.01ms !important;
152
+ transition-duration: 0.01ms !important;
153
+ }
154
+ }
155
+ ```
156
+
157
+ ## Step 5: Semantic HTML structure
158
+
159
+ Convert Stitch layout to semantic HTML5. Never use `<div>` where a semantic element fits:
160
+
161
+ | Stitch element | → HTML element |
162
+ |---|---|
163
+ | Page shell / app chrome | `<body>` → `<header>` + `<main>` + `<footer>` |
164
+ | Navigation bar | `<nav aria-label="Main navigation">` |
165
+ | Primary content area | `<main id="main-content">` |
166
+ | Article/post/card content | `<article>` |
167
+ | Sidebar | `<aside>` |
168
+ | Section of page | `<section aria-labelledby="section-id">` |
169
+ | Button (no href) | `<button type="button">` |
170
+ | Link with navigation | `<a href="...">` |
171
+ | Form container | `<form>` with `<label>` for every input |
172
+ | Images | `<img alt="descriptive text">` |
173
+
174
+ **Mobile HTML template:**
175
+ ```html
176
+ <!DOCTYPE html>
177
+ <html lang="en" data-theme="light">
178
+ <head>
179
+ <meta charset="UTF-8">
180
+ <!-- Critical for mobile: prevent zoom, respect viewport -->
181
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
182
+ <!-- iOS PWA meta tags -->
183
+ <meta name="apple-mobile-web-app-capable" content="yes">
184
+ <meta name="apple-mobile-web-app-status-bar-style" content="default">
185
+ <!-- Theme color (top browser bar on Android) -->
186
+ <meta name="theme-color" content="[--color-background hex]">
187
+
188
+ <title>[Screen title]</title>
189
+ <link rel="preconnect" href="https://fonts.googleapis.com">
190
+ <link rel="stylesheet" href="css/tokens.css">
191
+ <link rel="stylesheet" href="css/base.css">
192
+ <link rel="stylesheet" href="css/components.css">
193
+ </head>
194
+ <body>
195
+ <!-- Skip nav for keyboard users -->
196
+ <a href="#main-content" class="skip-link">Skip to content</a>
197
+
198
+ <!-- App shell -->
199
+ <div class="app-shell">
200
+ <header class="app-header" role="banner">
201
+ <nav aria-label="Main navigation">
202
+ <!-- Nav content -->
203
+ </nav>
204
+ </header>
205
+
206
+ <main id="main-content" class="app-main">
207
+ <!-- Page content -->
208
+ </main>
209
+
210
+ <!-- Bottom nav (mobile) -->
211
+ <nav class="bottom-nav" aria-label="Tab navigation">
212
+ <!-- Tab items -->
213
+ </nav>
214
+ </div>
215
+
216
+ <script src="js/main.js" type="module"></script>
217
+ </body>
218
+ </html>
219
+ ```
220
+
221
+ ## Step 6: Mobile-first CSS rules
222
+
223
+ Every component must follow these mobile constraints:
224
+
225
+ ### Touch targets
226
+ ```css
227
+ /* All interactive elements: minimum 44×44px tap area */
228
+ button, a, [role="button"] {
229
+ min-height: 44px;
230
+ min-width: 44px;
231
+ display: inline-flex;
232
+ align-items: center;
233
+ justify-content: center;
234
+ }
235
+ ```
236
+
237
+ ### Scrolling
238
+ ```css
239
+ /* Smooth scroll on iOS */
240
+ .scrollable {
241
+ overflow-y: scroll;
242
+ -webkit-overflow-scrolling: touch;
243
+ overscroll-behavior: contain; /* Prevent scroll chaining */
244
+ }
245
+ ```
246
+
247
+ ### Bottom navigation bar
248
+ ```css
249
+ .bottom-nav {
250
+ position: fixed;
251
+ bottom: 0;
252
+ left: 0;
253
+ right: 0;
254
+ /* Account for iOS home indicator */
255
+ padding-bottom: env(safe-area-inset-bottom);
256
+ background: var(--color-surface);
257
+ border-top: 1px solid var(--color-border);
258
+ display: flex;
259
+ justify-content: space-around;
260
+ z-index: 100;
261
+ }
262
+
263
+ /* Push main content above bottom nav */
264
+ .app-main {
265
+ padding-bottom: calc(60px + env(safe-area-inset-bottom));
266
+ }
267
+ ```
268
+
269
+ ### Responsive breakpoints
270
+ ```css
271
+ /* Mobile-first: base styles are for mobile */
272
+
273
+ /* Tablet (768px+) */
274
+ @media (min-width: 768px) {
275
+ .container { max-width: 720px; margin: 0 auto; }
276
+ }
277
+
278
+ /* Desktop (1024px+) */
279
+ @media (min-width: 1024px) {
280
+ .container { max-width: 1200px; }
281
+ .bottom-nav { display: none; } /* Hide bottom nav, use sidebar */
282
+ .sidebar { display: block; } /* Show desktop sidebar */
283
+ }
284
+ ```
285
+
286
+ ## Step 7: Minimal JavaScript
287
+
288
+ Keep JS to an absolute minimum. The only things that need JS:
289
+ 1. Theme toggle (dark/light)
290
+ 2. Mobile menu open/close
291
+ 3. Accordion/tabs interactive behavior
292
+
293
+ ```js
294
+ // js/main.js
295
+
296
+ // Dark mode toggle
297
+ const html = document.documentElement;
298
+ const savedTheme = localStorage.getItem('theme') || 'light';
299
+ html.setAttribute('data-theme', savedTheme);
300
+
301
+ document.getElementById('theme-toggle')?.addEventListener('click', () => {
302
+ const next = html.getAttribute('data-theme') === 'dark' ? 'light' : 'dark';
303
+ html.setAttribute('data-theme', next);
304
+ localStorage.setItem('theme', next);
305
+ });
306
+
307
+ // Mobile menu toggle
308
+ document.getElementById('menu-toggle')?.addEventListener('click', () => {
309
+ const nav = document.getElementById('mobile-nav');
310
+ const expanded = nav.getAttribute('aria-expanded') === 'true';
311
+ nav.setAttribute('aria-expanded', String(!expanded));
312
+ nav.classList.toggle('is-open');
313
+ });
314
+ ```
315
+
316
+ ## Step 8: Capacitor / WebView notes
317
+
318
+ If this HTML will be embedded in a Capacitor or Ionic app:
319
+ - All asset paths must be **relative** (no `/` prefix): `./css/tokens.css`, `./assets/logo.png`
320
+ - Capacitor reads from the `www/` or `dist/` directory — output there
321
+ - Capacitor's `capacitor.config.json` sets the WebDir: `"webDir": "www"`
322
+ - To call native APIs (camera, filesystem), use the Capacitor plugin JS APIs — beyond this skill's scope
323
+
324
+ ## Troubleshooting
325
+
326
+ | Issue | Fix |
327
+ |-------|-----|
328
+ | Fonts look zoomed on iOS rotation | Add `-webkit-text-size-adjust: 100%` to `html` |
329
+ | Content under notch | Add `env(safe-area-inset-*)` padding |
330
+ | Scrolling feels laggy on iOS | Add `-webkit-overflow-scrolling: touch` |
331
+ | Bottom nav overlaps content | Add `padding-bottom` to `<main>` equal to nav height + safe area |
332
+ | Click delay on mobile (300ms) | Add `touch-action: manipulation` to buttons |
333
+
334
+ ## Integration
335
+
336
+ - Run `stitch-design-system` first to generate `design-tokens.css` — import it instead of recreating tokens
337
+ - Run `stitch-a11y` after for an accessibility pass
338
+ - Run `stitch-animate` to add CSS-only transitions (zero JS needed for most animations)
339
+
340
+ ## References
341
+
342
+ - `resources/mobile-template.html` — Full mobile HTML boilerplate
343
+ - `resources/architecture-checklist.md` — Pre-ship checklist
344
+ - `scripts/fetch-stitch.sh` — Reliable GCS HTML downloader
package/skills/stitch-html-components/resources/architecture-checklist.md ADDED
@@ -0,0 +1,74 @@
1
+ # HTML Components — Architecture Checklist
2
+
3
+ Run through this checklist before marking the task complete.
4
+
5
+ ## Structure
6
+
7
+ - [ ] Components are in `src/components/` — one HTML partial per component (or standalone `.html` files)
8
+ - [ ] Static content is in a data layer (`src/data/` or inline JSON) — not hardcoded in markup
9
+ - [ ] CSS custom properties are defined in `src/styles/tokens.css` (or `globals.css`)
10
+ - [ ] Component styles are co-located: `ComponentName.html` + `ComponentName.css`
11
+
12
+ ## Semantic HTML
13
+
14
+ - [ ] Page structure uses `<header>`, `<main>`, `<nav>`, `<footer>`, `<section>`, `<article>`
15
+ - [ ] Heading hierarchy is correct: one `<h1>` per page, `<h2>` for sections, `<h3>` for subsections
16
+ - [ ] Interactive elements are `<button>` or `<a>` — not `<div onclick>` or `<span>`
17
+ - [ ] Lists use `<ul>` / `<ol>` / `<dl>` — not `<div>` wrappers
18
+ - [ ] Forms have `<label for="id">` on all inputs, with matching `id` attributes
19
+
20
+ ## CSS custom properties (tokens)
21
+
22
+ - [ ] No hardcoded hex colors in CSS — all colors use `var(--color-*)`
23
+ - [ ] Light mode tokens defined in `:root {}`
24
+ - [ ] Dark mode tokens defined in `@media (prefers-color-scheme: dark) {}` or `[data-theme="dark"] {}`
25
+ - [ ] Both light and dark mode tested visually
26
+ - [ ] Token names are semantic: `--color-surface`, `--color-primary` (not `--color-blue-500`)
27
+
28
+ ## Mobile-first and responsive
29
+
30
+ - [ ] Layout starts mobile-first — base styles are for 320px, `@media (min-width: ...)` adds desktop
31
+ - [ ] No fixed pixel widths that cause horizontal overflow on small screens
32
+ - [ ] Touch targets are at least 44×44px (`min-height: 44px; min-width: 44px`)
33
+ - [ ] Text is readable at 16px without zooming (no `font-size < 16px` on body text)
34
+ - [ ] Tested at 320px, 375px, 768px, and 1280px viewport widths
35
+
36
+ ## Safe area (mobile WebView)
37
+
38
+ - [ ] `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">` in `<head>`
39
+ - [ ] Fixed bottom elements use `padding-bottom: env(safe-area-inset-bottom)`
40
+ - [ ] Fixed top elements use `padding-top: env(safe-area-inset-top)`
41
+ - [ ] No content hidden behind notch or home indicator
42
+
43
+ ## Images
44
+
45
+ - [ ] All `<img>` have `alt=""` (descriptive text for content images, empty string for decorative)
46
+ - [ ] Images have explicit `width` and `height` attributes to prevent layout shift
47
+ - [ ] Remote images are loaded with `loading="lazy"` (except above-the-fold)
48
+ - [ ] SVG icons are accessible: `aria-hidden="true"` on decorative SVGs
49
+
50
+ ## Accessibility
51
+
52
+ - [ ] `<html lang="en">` (or correct language) is set
53
+ - [ ] Skip-to-content link: `<a href="#main" class="sr-only focus:not-sr-only">Skip to content</a>`
54
+ - [ ] All interactive elements are keyboard reachable (Tab key)
55
+ - [ ] Focus styles are visible — no `outline: none` without a replacement
56
+ - [ ] Color contrast meets WCAG AA: 4.5:1 for body text, 3:1 for large text
57
+ - [ ] Icon-only buttons have `aria-label` or `title`
58
+ - [ ] `<dialog>` or `role="dialog"` elements trap focus when open
59
+
60
+ ## Performance
61
+
62
+ - [ ] No inline `<style>` for anything that belongs in a stylesheet
63
+ - [ ] No `console.log` in production code
64
+ - [ ] CSS is minified for production (or bundler handles it)
65
+ - [ ] Images are compressed and served at appropriate sizes
66
+ - [ ] External resources (fonts, icons) are loaded asynchronously
67
+
68
+ ## WebView / Capacitor compatibility (if applicable)
69
+
70
+ - [ ] No `window.open()` — use Capacitor's Browser plugin for external links
71
+ - [ ] `localStorage` used for simple persistence (Capacitor has access)
72
+ - [ ] File paths are relative — no `http://localhost:*` hardcoded
73
+ - [ ] `-webkit-overflow-scrolling: touch` on scrollable containers (iOS WebView)
74
+ - [ ] Camera / GPS APIs routed through Capacitor plugins, not direct browser APIs
package/skills/stitch-html-components/scripts/fetch-stitch.sh ADDED
@@ -0,0 +1,45 @@
1
+ #!/usr/bin/env bash
2
+ # fetch-stitch.sh
3
+ # Reliably downloads Stitch HTML from Google Cloud Storage URLs.
4
+ # GCS URLs require redirect handling and specific security handshakes that
5
+ # AI fetch tools often fail on. This script handles both.
6
+ #
7
+ # Usage:
8
+ # bash scripts/fetch-stitch.sh "<url>" "<output-path>"
9
+ #
10
+ # Example:
11
+ # bash scripts/fetch-stitch.sh "$htmlCode_downloadUrl" "temp/source.html"
12
+
13
+ set -euo pipefail
14
+
15
+ URL="${1:?Usage: fetch-stitch.sh <url> <output-path>}"
16
+ OUTPUT="${2:?Usage: fetch-stitch.sh <url> <output-path>}"
17
+
18
+ # Create output directory if it doesn't exist
19
+ mkdir -p "$(dirname "$OUTPUT")"
20
+
21
+ # Use curl with:
22
+ # -L : follow redirects (GCS uses multiple redirect hops)
23
+ # -A : set User-Agent to avoid bot blocking
24
+ # --compressed : handle gzip responses
25
+ # --retry 3 : retry on transient failures
26
+ # --retry-delay 1 : wait 1s between retries
27
+ # --max-time 30 : don't hang forever
28
+ curl -L \
29
+ -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
30
+ --compressed \
31
+ --retry 3 \
32
+ --retry-delay 1 \
33
+ --max-time 30 \
34
+ --silent \
35
+ --show-error \
36
+ --output "$OUTPUT" \
37
+ "$URL"
38
+
39
+ # Verify the download succeeded and is not empty
40
+ if [ ! -s "$OUTPUT" ]; then
41
+ echo "Error: Downloaded file is empty. URL may be expired or invalid." >&2
42
+ exit 1
43
+ fi
44
+
45
+ echo "Downloaded to: $OUTPUT ($(wc -c < "$OUTPUT") bytes)"
package/skills/stitch-loop/SKILL.md ADDED
@@ -0,0 +1,183 @@
1
+ ---
2
+ name: stitch-loop
3
+ description: Iteratively build multi-page websites using Stitch. Reads next-prompt.md (the baton), generates the next page with Stitch MCP, integrates it into the site, then updates next-prompt.md to continue the loop. Works with stitch-design-md and stitch-ui-prompt-architect for consistent multi-page output.
4
+ allowed-tools:
5
+ - "stitch*:*"
6
+ - "Bash"
7
+ - "Read"
8
+ - "Write"
9
+ ---
10
+
11
+ # Stitch Build Loop
12
+
13
+ **Constraint:** Only use this skill when the user explicitly mentions "Stitch" and multi-page or iterative site building.
14
+
15
+ You are an **autonomous frontend builder** in an iterative site-building loop. Each iteration: (1) Read the baton, (2) Generate a page with Stitch MCP, (3) Integrate into the site, (4) Write the next baton so the loop continues.
16
+
17
+ ## Prerequisites
18
+
19
+ - Stitch MCP Server (see `stitch-setup` skill or https://stitch.withgoogle.com/docs/mcp/guide/)
20
+ - `DESIGN.md` — generate with `stitch-design-system` from an existing screen (required for consistency)
21
+ - `SITE.md` — site vision, Stitch project ID, sitemap, roadmap (create if missing)
22
+
23
+ ## The baton system
24
+
25
+ `next-prompt.md` is the relay baton between iterations. It tells the loop what page to build next.
26
+
27
+ ### Baton format
28
+
29
+ ```markdown
30
+ ---
31
+ page: about
32
+ ---
33
+
34
+ **DESIGN SYSTEM (REQUIRED):**
35
+ [Paste DESIGN.md Section 6 here verbatim]
36
+
37
+ **Page request:**
38
+ About page with company mission, team section (3 people), and timeline.
39
+ ```
40
+
41
+ **Rules:**
42
+ - `page` frontmatter → output filename (`about.html`)
43
+ - The body **must** include the design system block from `DESIGN.md` Section 6
44
+ - You **must** update `next-prompt.md` at the end of every iteration — the loop stops if this is missing
45
+
46
+ ---
47
+
48
+ ## Execution protocol
49
+
50
+ ### Step 1 — Read the baton
51
+
52
+ Parse `next-prompt.md`:
53
+ - Extract `page` from YAML frontmatter
54
+ - Extract the full prompt body (including the design system block)
55
+
56
+ ### Step 2 — Consult context files
57
+
58
+ | File | What to look for |
59
+ |------|-----------------|
60
+ | `SITE.md` | Stitch project ID (Section 2), sitemap (Section 3), roadmap / next pages (Section 4), creative freedom (Section 5) |
61
+ | `DESIGN.md` | Section 6 — copy this into every prompt, not just the current one |
62
+
63
+ **Check:** Do not rebuild pages already in `SITE.md` sitemap. Do not deviate from the visual language in `DESIGN.md`.
64
+
65
+ ### Step 3 — Generate with Stitch
66
+
67
+ 1. Run `list_tools` → find Stitch MCP prefix
68
+ 2. If `stitch.json` exists, use stored `projectId` — do not create a new project
69
+ 3. If no `stitch.json`, call `create_project` → save numeric ID to `stitch.json`
70
+ 4. Call `generate_screen_from_text`:
71
+ - `projectId`: numeric ID (no `projects/` prefix)
72
+ - `prompt`: full baton content including DESIGN SYSTEM block
73
+ - `deviceType`: match what's in `SITE.md` or `DESIGN.md`
74
+ 5. Call `get_screen` with numeric projectId + screenId
75
+ 6. Download HTML: `bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "queue/[page].html"`
76
+ 7. Download screenshot: save to `queue/[page].png`
77
+
78
+ ### Step 4 — Integrate into site
79
+
80
+ 1. Move `queue/[page].html` → `site/public/[page].html`
81
+ 2. Fix asset paths (make relative to `site/public/`)
82
+ 3. Wire navigation: replace `href="#"` placeholders with real paths to existing pages
83
+ 4. Ensure the header/footer matches other pages in the site
84
+
85
+ ### Step 4.5 — Visual verification (if Chrome DevTools MCP available)
86
+
87
+ If `chrome*` tools are in `list_tools`:
88
+ 1. Start local server: `npx serve site/public -p 3000`
89
+ 2. Navigate to `http://localhost:3000/[page].html`
90
+ 3. Take screenshot, compare against `queue/[page].png`
91
+ 4. Stop server
92
+
93
+ ### Step 5 — Update SITE.md
94
+
95
+ - Add `[x] [page].html` to the sitemap
96
+ - Remove consumed ideas from creative freedom section
97
+ - Update roadmap if a backlog item was completed
98
+
99
+ ### Step 6 — Write the next baton (CRITICAL)
100
+
101
+ **You must update `next-prompt.md` before completing — the loop stalls if you skip this.**
102
+
103
+ 1. Pick next page from: sitemap → roadmap → creative freedom → or invent one that fits
104
+ 2. Write `next-prompt.md` with:
105
+ - Valid YAML frontmatter (`page: <next-page-name>`)
106
+ - `**DESIGN SYSTEM (REQUIRED):**` block copied verbatim from `DESIGN.md` Section 6
107
+ - Clear page description
108
+
109
+ ---
110
+
111
+ ## File structure
112
+
113
+ ```
114
+ project/
115
+ ├── next-prompt.md ← Baton (current task; updated each iteration)
116
+ ├── stitch.json ← Stitch project ID (persist between loops!)
117
+ ├── DESIGN.md ← From stitch-design-system
118
+ ├── SITE.md ← Vision, sitemap, roadmap
119
+ ├── queue/ ← Staging: [page].html, [page].png
120
+ └── site/
121
+ └── public/ ← Production: index.html, about.html, etc.
122
+ ```
123
+
124
+ ---
125
+
126
+ ## SITE.md template
127
+
128
+ ```markdown
129
+ # Site Vision
130
+
131
+ [One paragraph describing the site's purpose, audience, and overall feeling]
132
+
133
+ ## Stitch Project
134
+
135
+ - **Project ID (numeric):** [ID from stitch-mcp-create-project]
136
+
137
+ ## Sitemap
138
+
139
+ - [ ] index.html — Home
140
+ - [ ] about.html — About
141
+ - [ ] contact.html — Contact
142
+
143
+ ## Roadmap
144
+
145
+ 1. index.html — main landing page
146
+ 2. about.html — company/team info
147
+ 3. contact.html — contact form
148
+
149
+ ## Creative freedom
150
+
151
+ Additional pages or sections not yet planned...
152
+ ```
153
+
154
+ ---
155
+
156
+ ## Common pitfalls
157
+
158
+ - ❌ Forgetting to update `next-prompt.md` (loop stops)
159
+ - ❌ Rebuilding a page already in SITE.md sitemap
160
+ - ❌ Omitting `DESIGN.md` Section 6 from the prompt (causes visual drift)
161
+ - ❌ Using `projects/ID` format instead of numeric in `generate_screen_from_text`
162
+ - ❌ Leaving `href="#"` instead of wiring real page links
163
+ - ❌ Not persisting `stitch.json` (creates new project every iteration)
164
+
165
+ ---
166
+
167
+ ## Troubleshooting
168
+
169
+ | Issue | Fix |
170
+ |-------|-----|
171
+ | Inconsistent visual styles across pages | Keep DESIGN.md updated; always copy Section 6 into baton |
172
+ | Loop stalls at next iteration | Check `next-prompt.md` has valid frontmatter and non-empty body |
173
+ | Stitch generation fails | Ensure baton includes DESIGN SYSTEM block and a specific page request |
174
+ | Broken navigation | Use relative paths for internal links; check `site/public/` structure |
175
+
176
+ ---
177
+
178
+ ## References
179
+
180
+ - `scripts/fetch-stitch.sh` — Reliable GCS HTML downloader
181
+ - `stitch-design-system` — Generate DESIGN.md from an existing screen
182
+ - `stitch-ui-prompt-architect` — Enhance vague baton text into structured prompts
183
+ - `docs/prd-to-stitch-workflow.md` — PRD-driven multi-screen workflow
package/skills/stitch-loop/examples/SITE.md ADDED
@@ -0,0 +1,39 @@
1
+ ---
2
+ stitch-project-id: 13534454087919359824
3
+ ---
4
+ # Project Vision & Constitution
5
+
6
+ > **AGENT:** Read this before every iteration. If `next-prompt.md` is empty, pick from Section 5 or Section 6.
7
+
8
+ ## 1. Core Identity
9
+ * **Project Name:** Oakwood Furniture Co.
10
+ * **Stitch Project ID:** `13534454087919359824`
11
+ * **Mission:** Premium online furniture showroom; handcrafted, sustainable wood.
12
+ * **Voice:** Warm, refined, artisanal, trustworthy.
13
+
14
+ ## 2. Visual Language (Stitch Prompt Strategy)
15
+ * **Vibe:** Warm, minimal, artisanal.
16
+ * **Colors:** Warm cream (#FCFAFA), teal-navy (#294056), charcoal (#2C2C2C), soft gray (#6B6B6B).
17
+
18
+ ## 3. Architecture
19
+ * **Root:** `site/public/`
20
+ * **Flow:** Stitch → `queue/` → validate → `site/public/`
21
+ * **Nav:** Global header (Logo, Shop, Collections, About, Contact); footer (Sustainability, Craftsmanship, Shipping, Social).
22
+
23
+ ## 4. Live Sitemap
24
+ * [x] `index.html` - Homepage
25
+ * [x] `collections.html` - Furniture categories
26
+ * [x] `about.html` - Our story
27
+ * [ ] `contact.html` - Contact form and showroom
28
+
29
+ ## 5. Roadmap
30
+ - [ ] Product Detail Page
31
+ - [ ] Contact Page
32
+ - [ ] Sustainability Page
33
+
34
+ ## 6. Creative Freedom (when roadmap empty)
35
+ - [ ] `materials.html` - Wood types and finishes
36
+ - [ ] `custom.html` - Custom ordering
37
+ - [ ] `gallery.html` - Customer homes
38
+
39
+ **Rules:** Do not recreate Section 4 pages. Always update `next-prompt.md` before completing.