@thready-web/dsh-bot-plugin 0.1.0-beta.10 → 0.1.0-beta.11

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 (43) hide show
  1. package/dist/canvas-http.js +248 -0
  2. package/dist/canvas-skills.js +56 -0
  3. package/dist/canvas-store.js +794 -0
  4. package/dist/canvas-tools.js +211 -0
  5. package/dist/context.js +1 -0
  6. package/dist/http.js +19 -0
  7. package/dist/index.js +11 -0
  8. package/dist/work-http.js +19 -0
  9. package/dist/work-worker.js +5 -0
  10. package/package.json +2 -1
  11. package/public/assets/{SourceEditor-BEQaScgR.js → SourceEditor-uu0G7jsM.js} +3 -3
  12. package/public/assets/{cssMode-gpcjCFFS.js → cssMode-C5DAFF5H.js} +1 -1
  13. package/public/assets/{freemarker2-C1qemGIt.js → freemarker2-DExNwSiZ.js} +1 -1
  14. package/public/assets/{handlebars-sZqIfAlP.js → handlebars-BK7YAvpQ.js} +1 -1
  15. package/public/assets/{html-Bn1WXB8L.js → html-CdDm_zae.js} +1 -1
  16. package/public/assets/{htmlMode-CvQyXnaW.js → htmlMode-CLdn9oa1.js} +1 -1
  17. package/public/assets/index-BB-QDSf2.css +1 -0
  18. package/public/assets/index-CsX-_qbo.js +62 -0
  19. package/public/assets/{javascript-Ox4Jg12j.js → javascript-mLl83_3W.js} +1 -1
  20. package/public/assets/{jsonMode-DMR7R2dQ.js → jsonMode-B1-bihFd.js} +1 -1
  21. package/public/assets/{liquid-B6HxtpBd.js → liquid-Cv8m0HUb.js} +1 -1
  22. package/public/assets/{mdx--jDhmrXq.js → mdx-Q12b91rL.js} +1 -1
  23. package/public/assets/{python-YjG50skX.js → python-Kda811W0.js} +1 -1
  24. package/public/assets/{razor-CEcFE3UK.js → razor-CRuCpdOW.js} +1 -1
  25. package/public/assets/{tsMode-g4kTQl09.js → tsMode-BGHcz-M3.js} +1 -1
  26. package/public/assets/{typescript-CnHeFmPW.js → typescript-Db1e0DCT.js} +1 -1
  27. package/public/assets/{xml-BFXMY9nb.js → xml-H3zzFmnd.js} +1 -1
  28. package/public/assets/{yaml-DNm87nSf.js → yaml-BQrKvmTF.js} +1 -1
  29. package/public/index.html +2 -2
  30. package/skills/ui/baseline-ui/SKILL.md +85 -0
  31. package/skills/ui/bencium-innovative-ux-designer/SKILL.md +227 -0
  32. package/skills/ui/better-ui/SKILL.md +133 -0
  33. package/skills/ui/design-lab/SKILL.md +920 -0
  34. package/skills/ui/frontend-design/SKILL.md +71 -0
  35. package/skills/ui/impeccable/SKILL.md +93 -0
  36. package/skills/ui/interface-design/SKILL.md +320 -0
  37. package/skills/ui/sources.json +66 -0
  38. package/skills/ui/ui-design/SKILL.md +35 -0
  39. package/skills/ui/ui-skills-root/SKILL.md +59 -0
  40. package/skills/ui/visual-design-foundations/SKILL.md +318 -0
  41. package/skills/ui/web-design-guidelines/SKILL.md +39 -0
  42. package/public/assets/index-DRNkUrer.css +0 -1
  43. package/public/assets/index-DhL5Kdlz.js +0 -63
@@ -0,0 +1,920 @@
1
+ ---
2
+ name: design-lab
3
+ description: Conduct design interviews, generate five distinct UI variations in a temporary design lab, collect feedback, and produce implementation plans. Use when the user wants to explore UI design options, redesign existing components, or create new UI with multiple approaches to compare.
4
+ ---
5
+
6
+ # Design Lab Skill
7
+
8
+ This skill implements a complete design exploration workflow: interview, generate variations, collect feedback, refine, preview, and finalize.
9
+
10
+ ## CRITICAL: Cleanup Behavior
11
+
12
+ **All temporary files MUST be deleted when the process ends, whether by:**
13
+ - User confirms final design → cleanup, then generate plan
14
+ - User aborts/cancels → cleanup immediately, no plan generated
15
+
16
+ **Never leave `.claude-design/` or `__design_lab` routes behind.** If the user says "cancel", "abort", "stop", or "nevermind" at any point, confirm and then delete all temporary artifacts.
17
+
18
+ ---
19
+
20
+ ## Phase 0: Preflight Detection
21
+
22
+ Before starting the interview, automatically detect:
23
+
24
+ ### Package Manager
25
+ Check for lock files in the project root:
26
+ - `pnpm-lock.yaml` → use `pnpm`
27
+ - `yarn.lock` → use `yarn`
28
+ - `package-lock.json` → use `npm`
29
+ - `bun.lockb` → use `bun`
30
+
31
+ ### Framework Detection
32
+ Check for config files:
33
+ - `next.config.js` or `next.config.mjs` or `next.config.ts` → **Next.js**
34
+ - Check for `app/` directory → App Router
35
+ - Check for `pages/` directory → Pages Router
36
+ - `vite.config.js` or `vite.config.ts` → **Vite**
37
+ - `remix.config.js` → **Remix**
38
+ - `nuxt.config.js` or `nuxt.config.ts` → **Nuxt**
39
+ - `astro.config.mjs` → **Astro**
40
+
41
+ ### Styling System Detection
42
+ Check `package.json` dependencies and config files:
43
+ - `tailwind.config.js` or `tailwind.config.ts` → **Tailwind CSS**
44
+ - `@mui/material` in dependencies → **Material UI**
45
+ - `@chakra-ui/react` in dependencies → **Chakra UI**
46
+ - `antd` in dependencies → **Ant Design**
47
+ - `styled-components` in dependencies → **styled-components**
48
+ - `@emotion/react` in dependencies → **Emotion**
49
+ - `.css` or `.module.css` files → **CSS Modules**
50
+
51
+ ### Design Memory Check
52
+ Look for existing Design Memory file:
53
+ - `docs/design-memory.md`
54
+ - `DESIGN_MEMORY.md`
55
+ - `.claude-design/design-memory.md`
56
+
57
+ If found, read it and use to prefill defaults and skip redundant questions.
58
+
59
+ ### Visual Style Inference (CRITICAL)
60
+
61
+ **DO NOT use generic/predefined styles. Extract visual language from the project:**
62
+
63
+ **If Tailwind detected**, read `tailwind.config.js` or `tailwind.config.ts`:
64
+ ```javascript
65
+ // Extract and use:
66
+ theme.colors // Color palette
67
+ theme.spacing // Spacing scale
68
+ theme.borderRadius // Radius values
69
+ theme.fontFamily // Typography
70
+ theme.boxShadow // Elevation system
71
+ ```
72
+
73
+ **If CSS Variables exist**, read `globals.css`, `variables.css`, or `:root` definitions:
74
+ ```css
75
+ :root {
76
+ --color-* /* Color tokens */
77
+ --spacing-* /* Spacing tokens */
78
+ --font-* /* Typography tokens */
79
+ --radius-* /* Border radius tokens */
80
+ }
81
+ ```
82
+
83
+ **If UI library detected** (MUI, Chakra, Ant), read the theme configuration:
84
+ - MUI: `theme.ts` or `createTheme()` call
85
+ - Chakra: `theme/index.ts` or `extendTheme()` call
86
+ - Ant: `ConfigProvider` theme prop
87
+
88
+ **Always scan existing components** to understand patterns:
89
+ - Find 2-3 existing buttons → note their styling patterns
90
+ - Find 2-3 existing cards → note padding, borders, shadows
91
+ - Find existing forms → note input styles, label placement
92
+ - Find existing typography → note heading sizes, body text
93
+
94
+ **Store inferred styles in the Design Brief** for consistent use across all variants.
95
+
96
+ ---
97
+
98
+ ## Phase 1: Interview
99
+
100
+ Use the **AskUserQuestion** tool for all interview steps. Adapt questions based on Design Memory if it exists.
101
+
102
+ ### Step 1.1: Scope & Target
103
+
104
+ Ask these questions (can combine into single AskUserQuestion with multiple questions):
105
+
106
+ **Question 1: Scope**
107
+ - Header: "Scope"
108
+ - Question: "Are we designing a single component or a full page?"
109
+ - Options:
110
+ - "Component" - A reusable UI element (button, card, form, modal, etc.)
111
+ - "Page" - A complete page or screen layout
112
+
113
+ **Question 2: New or Redesign**
114
+ - Header: "Type"
115
+ - Question: "Is this a new design or a redesign of something existing?"
116
+ - Options:
117
+ - "New" - Creating something from scratch
118
+ - "Redesign" - Improving an existing component/page
119
+
120
+ If "Redesign" selected, ask:
121
+ **Question 3: Existing Path**
122
+ - Header: "Location"
123
+ - Question: "What is the file path or route of the existing UI?"
124
+ - Options: (let user provide via "Other")
125
+
126
+ If target is unclear, propose a name based on repo patterns and confirm.
127
+
128
+ ### Step 1.2: Pain Points & Inspiration
129
+
130
+ **Question 1: Pain Points**
131
+ - Header: "Problems"
132
+ - Question: "What are the top pain points with the current design (or what should this new design avoid)?"
133
+ - Options:
134
+ - "Too cluttered/dense" - Information overload, hard to scan
135
+ - "Unclear hierarchy" - Primary actions aren't obvious
136
+ - "Poor mobile experience" - Doesn't work well on small screens
137
+ - "Outdated look" - Feels old or inconsistent with brand
138
+ - multiSelect: true
139
+
140
+ **Question 2: Visual Inspiration**
141
+ - Header: "Visual style"
142
+ - Question: "What products or brands should I reference for visual inspiration?"
143
+ - Options:
144
+ - "Stripe" - Clean, minimal, trustworthy
145
+ - "Linear" - Dense, keyboard-first, developer-focused
146
+ - "Notion" - Flexible, content-focused, playful
147
+ - "Apple" - Premium, spacious, refined
148
+ - multiSelect: true
149
+
150
+ **Question 3: Functional Inspiration**
151
+ - Header: "Interactions"
152
+ - Question: "What interaction patterns should I emulate?"
153
+ - Options:
154
+ - "Inline editing" - Edit in place without modals
155
+ - "Progressive disclosure" - Show more as needed
156
+ - "Optimistic updates" - Instant feedback, sync in background
157
+ - "Keyboard shortcuts" - Power user efficiency
158
+
159
+ ### Step 1.3: Brand & Style Direction
160
+
161
+ **Question 1: Brand Adjectives**
162
+ - Header: "Brand tone"
163
+ - Question: "What 3-5 adjectives describe the desired brand feel?"
164
+ - Options:
165
+ - "Minimal" - Clean, simple, uncluttered
166
+ - "Premium" - High-end, polished, refined
167
+ - "Playful" - Fun, friendly, approachable
168
+ - "Utilitarian" - Functional, efficient, no-nonsense
169
+ - multiSelect: true
170
+
171
+ **Question 2: Density**
172
+ - Header: "Density"
173
+ - Question: "What information density do you prefer?"
174
+ - Options:
175
+ - "Compact" - More information visible, tighter spacing
176
+ - "Comfortable" - Balanced spacing, easy scanning
177
+ - "Spacious" - Generous whitespace, focused attention
178
+
179
+ **Question 3: Dark Mode**
180
+ - Header: "Dark mode"
181
+ - Question: "Is dark mode required?"
182
+ - Options:
183
+ - "Yes" - Must support dark mode
184
+ - "No" - Light mode only
185
+ - "Nice to have" - Support if easy, not required
186
+
187
+ ### Step 1.4: Persona & Jobs-to-be-Done
188
+
189
+ **Question 1: Primary User**
190
+ - Header: "User"
191
+ - Question: "Who is the primary end user?"
192
+ - Options:
193
+ - "Developer" - Technical, keyboard-oriented
194
+ - "Designer" - Visual, detail-oriented
195
+ - "Business user" - Efficiency-focused, less technical
196
+ - "End consumer" - General public, varied technical ability
197
+
198
+ **Question 2: Context**
199
+ - Header: "Context"
200
+ - Question: "What's the primary usage context?"
201
+ - Options:
202
+ - "Desktop-first" - Primarily used on larger screens
203
+ - "Mobile-first" - Primarily used on phones
204
+ - "Both equally" - Must work well on all devices
205
+
206
+ **Question 3: Key Tasks**
207
+ - Header: "Key tasks"
208
+ - Question: "What are the top 3 tasks users must complete?"
209
+ - (Let user provide via "Other" - this is open-ended)
210
+
211
+ ### Step 1.5: Constraints
212
+
213
+ **Question 1: Must-Keep Elements**
214
+ - Header: "Keep"
215
+ - Question: "Are there elements that must be preserved?"
216
+ - Options:
217
+ - "Existing copy/labels" - Keep current text
218
+ - "Current fields/inputs" - Keep form structure
219
+ - "Navigation structure" - Keep current nav
220
+ - "None" - Free to change everything
221
+
222
+ **Question 2: Technical Constraints**
223
+ - Header: "Constraints"
224
+ - Question: "Any technical constraints?"
225
+ - Options:
226
+ - "No new dependencies" - Use existing libraries only
227
+ - "Use existing components" - Build on current design system
228
+ - "Must be accessible (WCAG)" - Strict accessibility requirements
229
+ - "None" - No special constraints
230
+ - multiSelect: true
231
+
232
+ ---
233
+
234
+ ## Phase 2: Generate Design Brief
235
+
236
+ After the interview, create a structured Design Brief as JSON and save to `.claude-design/design-brief.json`:
237
+
238
+ ```json
239
+ {
240
+ "scope": "component|page",
241
+ "isRedesign": true|false,
242
+ "targetPath": "src/components/Example.tsx",
243
+ "targetName": "Example",
244
+ "painPoints": ["Too dense", "Primary action unclear"],
245
+ "inspiration": {
246
+ "visual": ["Stripe", "Linear"],
247
+ "functional": ["Inline validation"]
248
+ },
249
+ "brand": {
250
+ "adjectives": ["minimal", "trustworthy"],
251
+ "density": "comfortable",
252
+ "darkMode": true
253
+ },
254
+ "persona": {
255
+ "primary": "Developer",
256
+ "context": "desktop-first",
257
+ "keyTasks": ["Complete checkout", "Review order", "Apply discount"]
258
+ },
259
+ "constraints": {
260
+ "mustKeep": ["existing fields"],
261
+ "technical": ["no new dependencies", "WCAG accessible"]
262
+ },
263
+ "framework": "nextjs-app",
264
+ "packageManager": "pnpm",
265
+ "stylingSystem": "tailwind"
266
+ }
267
+ ```
268
+
269
+ Display a summary to the user before proceeding.
270
+
271
+ ---
272
+
273
+ ## Phase 3: Generate Design Lab
274
+
275
+ ### Directory Structure
276
+
277
+ Create all files under `.claude-design/`:
278
+
279
+ ```
280
+ .claude-design/
281
+ ├── lab/
282
+ │ ├── page.tsx # Main lab page (framework-specific)
283
+ │ ├── variants/
284
+ │ │ ├── VariantA.tsx
285
+ │ │ ├── VariantB.tsx
286
+ │ │ ├── VariantC.tsx
287
+ │ │ ├── VariantD.tsx
288
+ │ │ └── VariantE.tsx
289
+ │ ├── components/
290
+ │ │ └── LabShell.tsx # Lab layout wrapper
291
+ │ ├── feedback/ # Interactive feedback system
292
+ │ │ ├── types.ts # TypeScript interfaces
293
+ │ │ ├── selector-utils.ts # Element identification
294
+ │ │ ├── format-utils.ts # Feedback formatting
295
+ │ │ ├── FeedbackOverlay.tsx # Main overlay component
296
+ │ │ └── index.ts # Module exports
297
+ │ └── data/
298
+ │ └── fixtures.ts # Shared mock data
299
+ ├── design-brief.json
300
+ └── run-log.md
301
+ ```
302
+
303
+ ### Feedback System Setup (CRITICAL - NEVER SKIP)
304
+
305
+ **The FeedbackOverlay is the PRIMARY feature of the Design Lab.** Without it, users cannot provide interactive feedback. NEVER generate a Design Lab without the FeedbackOverlay.
306
+
307
+ **Reliability Strategy:** To avoid import path issues across different project configurations, create the FeedbackOverlay **directly in the route directory** (e.g., `app/design-lab/FeedbackOverlay.tsx`), NOT in `.claude-design/`. This ensures a simple relative import (`./FeedbackOverlay`) always works.
308
+
309
+ **Required Files in Route Directory:**
310
+ ```
311
+ app/design-lab/ # or app/__design_lab/ if underscores work
312
+ ├── page.tsx # Main lab page with variants
313
+ └── FeedbackOverlay.tsx # Self-contained overlay component (copy from templates)
314
+ ```
315
+
316
+ **Template Source:** `design-and-refine/templates/feedback/FeedbackOverlay.tsx`
317
+
318
+ **Why this approach:**
319
+ - `.claude-design/` paths can fail due to bundler configurations
320
+ - Relative imports from the same directory always work
321
+ - The route directory gets deleted during cleanup anyway
322
+
323
+ ### Route Integration
324
+
325
+ **Next.js App Router:**
326
+ Create `app/__design_lab/page.tsx` that imports from `.claude-design/lab/`
327
+
328
+ **Next.js Pages Router:**
329
+ Create `pages/__design_lab.tsx` that imports from `.claude-design/lab/`
330
+
331
+ **Vite React:**
332
+ - If React Router exists: add route to `/__design_lab`
333
+ - If no router: create a conditional render in `App.tsx` based on `?design_lab=true` query param
334
+
335
+ **Other frameworks:**
336
+ Create the most appropriate temporary route for the detected framework.
337
+
338
+ ### Variant Generation Guidelines
339
+
340
+ **IMPORTANT:** Read `DESIGN_PRINCIPLES.md` for UX, interaction, and motion best practices. But **DO NOT use predefined visual styles**—infer them from the project.
341
+
342
+ **Apply universal principles (from DESIGN_PRINCIPLES.md):**
343
+ - **UX**: Nielsen's heuristics, cognitive load reduction, progressive disclosure
344
+ - **Component behavior**: Button states, form anatomy, card structure
345
+ - **Interaction**: Feedback patterns, state handling, optimistic updates
346
+ - **Motion**: Timing (150-300ms), easing (ease-out entrances, ease-in exits)
347
+ - **Accessibility**: Focus states, ARIA patterns, touch targets (44px min)
348
+
349
+ **Infer visual styles from the project:**
350
+ - Colors → from Tailwind config, CSS variables, or existing components
351
+ - Typography → from existing headings, body text in the codebase
352
+ - Spacing → from the project's spacing scale or existing patterns
353
+ - Border radius → from existing cards, buttons, inputs
354
+ - Shadows → from existing elevated components
355
+
356
+ ---
357
+
358
+ Each variant MUST explore a different design axis. Do not create minor variations—make them meaningfully distinct. **Use the project's existing visual language for all variants.**
359
+
360
+ **Variant A: Information Hierarchy Focus**
361
+ - Restructure content hierarchy (what's most important?)
362
+ - Apply Gestalt proximity—group related items closer
363
+ - One primary action per view
364
+ - Use existing typography scale to create clear levels
365
+
366
+ **Variant B: Layout Model Exploration**
367
+ - Try a different layout approach (card vs list vs table vs split-pane)
368
+ - Apply card anatomy or table behavior patterns from DESIGN_PRINCIPLES
369
+ - Consider responsive behavior at each breakpoint
370
+ - Use the project's existing grid/layout system
371
+
372
+ **Variant C: Density Variation**
373
+ - If brief says "comfortable", try a more compact version
374
+ - If brief says "compact", try a more spacious version
375
+ - Use the project's existing spacing tokens—just apply them differently
376
+ - Show the tradeoffs: more visible data vs easier scanning
377
+
378
+ **Variant D: Interaction Model**
379
+ - Different interaction pattern (modal vs inline vs panel vs drawer)
380
+ - Apply feedback patterns: immediate → progress → completion
381
+ - Implement all required states (loading, error, empty, disabled)
382
+ - Consider optimistic updates for non-destructive actions
383
+
384
+ **Variant E: Expressive Direction**
385
+ - Push the brand direction the user described in the interview
386
+ - Explore different uses of the project's existing design tokens
387
+ - More or less use of shadows, borders, background colors
388
+ - Apply motion where it adds meaning (hover, focus, transitions)
389
+
390
+ ### Lab Page Requirements
391
+
392
+ The Design Lab page must include:
393
+
394
+ 1. **Header** with:
395
+ - Design Brief summary (target, scope, key requirements)
396
+ - Instructions for reviewing
397
+
398
+ 2. **Variant Grid** with:
399
+ - Clear labels (A, B, C, D, E)
400
+ - Brief rationale for each variant ("Why this exists")
401
+ - The actual rendered variant
402
+ - Notes highlighting key differences
403
+ - **IMPORTANT:** Each variant container must have `data-variant="X"` attribute (where X is A, B, C, D, E, or F). This is required for the feedback system to identify which variant comments belong to.
404
+
405
+ 3. **Responsive behavior**:
406
+ - Desktop: side-by-side grid (2-3 columns)
407
+ - Mobile: horizontal scroll or tabs
408
+
409
+ 4. **Shared Data**:
410
+ - All variants use the same fixture data from `data/fixtures.ts`
411
+ - Ensures fair comparison
412
+
413
+ 5. **Feedback Overlay** (CRITICAL - NEVER OMIT):
414
+
415
+ ⚠️ **THIS IS THE MOST IMPORTANT REQUIREMENT** ⚠️
416
+
417
+ The FeedbackOverlay enables users to click on elements and leave comments. Without it, the Design Lab is just a static page with no way to collect structured feedback.
418
+
419
+ - Create `FeedbackOverlay.tsx` in the SAME directory as `page.tsx`
420
+ - Import with relative path: `import { FeedbackOverlay } from './FeedbackOverlay'`
421
+ - Render at the END of the page, after all variants
422
+ - Pass `targetName` prop with the component/page name
423
+
424
+ **Example integration:**
425
+
426
+ ```tsx
427
+ import { FeedbackOverlay } from './FeedbackOverlay'; // Relative import - always works
428
+
429
+ export default function DesignLabPage() {
430
+ return (
431
+ <div className="min-h-screen bg-background">
432
+ <header>...</header>
433
+
434
+ <main>
435
+ <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
436
+ <div data-variant="A">
437
+ <VariantA />
438
+ </div>
439
+ <div data-variant="B">
440
+ <VariantB />
441
+ </div>
442
+ {/* ... more variants */}
443
+ </div>
444
+ </main>
445
+
446
+ {/* CRITICAL: FeedbackOverlay must be included */}
447
+ <FeedbackOverlay targetName="ComponentName" />
448
+ </div>
449
+ );
450
+ }
451
+ ```
452
+
453
+ **If you forget the FeedbackOverlay, the user CANNOT provide feedback.** This defeats the entire purpose of the Design Lab.
454
+
455
+ ### Code Quality
456
+
457
+ **Conventions:**
458
+ - Follow the project's existing code conventions (file naming, imports, etc.)
459
+ - Use the detected styling system (Tailwind, CSS modules, etc.)
460
+ - Use existing components from the project where appropriate
461
+
462
+ **Accessibility (from DESIGN_PRINCIPLES):**
463
+ - Semantic HTML: `<button>` not `<div onclick>`, `<nav>`, `<main>`, `<section>`
464
+ - Keyboard navigation: all interactive elements focusable and operable
465
+ - Focus states: visible `:focus-visible` with 2px ring and offset
466
+ - Color contrast: 4.5:1 for text, 3:1 for UI elements
467
+ - Touch targets: minimum 44x44px
468
+ - ARIA only when HTML semantics aren't enough
469
+
470
+ **States (every component needs):**
471
+ - Default, Hover, Focus, Active, Disabled, Loading, Error, Empty
472
+ - See DESIGN_PRINCIPLES "State Handling" section
473
+
474
+ **Motion:**
475
+ - Use appropriate timing: 150-200ms for micro-interactions, 200-300ms for transitions
476
+ - Use ease-out for entrances, ease-in for exits
477
+ - Respect `prefers-reduced-motion`
478
+
479
+ ---
480
+
481
+ ## Phase 4: Present Design Lab to User
482
+
483
+ After generating the lab files, **immediately** present the lab to the user. Do NOT attempt to:
484
+ - Start the dev server yourself (it runs forever and will block)
485
+ - Check if ports are open
486
+ - Open a browser
487
+ - Wait for any server response
488
+
489
+ ### What to Do
490
+
491
+ 1. **Output the lab location and URL:**
492
+ ```
493
+ ✅ Design Lab created!
494
+
495
+ I've generated 5 design variants in `.claude-design/lab/`
496
+
497
+ To view them:
498
+ 1. Make sure your dev server is running (run `pnpm dev` if not)
499
+ 2. Open: http://localhost:3000/__design_lab
500
+
501
+ Take your time reviewing the variants side-by-side, then come back and tell me:
502
+ - Which variant wins (A-E)
503
+ - What you like about it
504
+ - What should change
505
+ ```
506
+
507
+ 2. **Immediately proceed to Phase 5** - ask for feedback. Do NOT wait for the user to say they've opened the browser. Just present the feedback questions right away so they're ready when the user returns.
508
+
509
+ ### Why Not Start the Server
510
+
511
+ Running `pnpm dev` or `npm run dev` starts a long-running process that never exits. If you run it, you'll wait forever. The user likely already has their dev server running, or can start it themselves in another terminal.
512
+
513
+ ---
514
+
515
+ ## Phase 5: Collect Feedback
516
+
517
+ After presenting the lab URL, the user can provide feedback in two ways:
518
+ 1. **Interactive Feedback** (recommended): Using the built-in overlay in the browser
519
+ 2. **Manual Feedback**: Via AskUserQuestion in the terminal
520
+
521
+ ### Interactive Feedback (Primary Method)
522
+
523
+ The Design Lab includes a Figma-like feedback overlay. When presenting the lab, include these instructions:
524
+
525
+ ```
526
+ ✅ Design Lab created!
527
+
528
+ I've generated 5 design variants in `.claude-design/lab/`
529
+
530
+ To view and provide feedback:
531
+ 1. Make sure your dev server is running (run `pnpm dev` if not)
532
+ 2. Open: http://localhost:3000/__design_lab
533
+
534
+ **To add feedback:**
535
+ 1. Click the "Add Feedback" button (bottom-right corner)
536
+ 2. Click any element you want to comment on
537
+ 3. Type your feedback and click "Save"
538
+ 4. Repeat for all elements you want to comment on
539
+ 5. Fill in the "Overall Direction" field (required)
540
+ 6. Click "Submit All Feedback"
541
+ 7. Paste the copied text here in the terminal
542
+
543
+ Or just describe your feedback manually below!
544
+ ```
545
+
546
+ **When the user pastes feedback**, it will be in this format:
547
+
548
+ ```markdown
549
+ ## Design Lab Feedback
550
+
551
+ **Target:** ComponentName
552
+ **Comments:** 3
553
+
554
+ ### Variant A
555
+ 1. **Button** (`[data-testid='submit']`, button with "Submit")
556
+ "Make this more prominent"
557
+
558
+ ### Variant B
559
+ 1. **Card** (`.product-card`, div with "Product Name")
560
+ "Love this layout"
561
+
562
+ ### Overall Direction
563
+ Go with Variant B's structure. Apply Variant A's button styling.
564
+ ```
565
+
566
+ **How to parse and act on this feedback:**
567
+
568
+ 1. **Read the Overall Direction** first - this guides your synthesis
569
+ 2. **For each comment**, locate the element using:
570
+ - Primary: The CSS selector in backticks (e.g., `[data-testid='submit']`)
571
+ - Secondary: The element description (e.g., "button with 'Submit'")
572
+ 3. **Apply the feedback** by editing the corresponding variant file
573
+
574
+ ### Fallback: Manual Feedback via AskUserQuestion
575
+
576
+ If the user prefers not to use the interactive overlay (or pastes manual feedback), use the AskUserQuestion flow below:
577
+
578
+ ### Stage 1: Check for a Winner
579
+
580
+ **Question 1: Ready to pick?**
581
+ - Header: "Decision"
582
+ - Question: "Is there one variant you like as is?"
583
+ - Options:
584
+ - "Yes - I found one I like" - Ready to select a winner and refine
585
+ - "No - I like parts of different ones" - Need to synthesize a new variant
586
+
587
+ ### Stage 2A: If User Found a Winner
588
+
589
+ If user said "Yes", ask:
590
+
591
+ **Question 2a: Which one?**
592
+ - Header: "Winner"
593
+ - Question: "Which variant do you want to go with?"
594
+ - Options:
595
+ - "Variant A" - [brief description of A]
596
+ - "Variant B" - [brief description of B]
597
+ - "Variant C" - [brief description of C]
598
+ - "Variant D" - [brief description of D]
599
+ - "Variant E" - [brief description of E]
600
+
601
+ **Question 3a: Any tweaks?**
602
+ - Header: "Tweaks"
603
+ - Question: "Any small changes needed, or is it good as is?"
604
+ - Options:
605
+ - "Good as is" - No changes needed, proceed to final preview
606
+ - "Minor tweaks needed" - I'll describe what to adjust
607
+
608
+ If "Minor tweaks needed", ask user to describe changes via text input.
609
+
610
+ Then proceed to **Phase 7: Final Preview**.
611
+
612
+ ### Stage 2B: If User Wants to Synthesize
613
+
614
+ If user said "No - I like parts of different ones", ask:
615
+
616
+ **Question 2b: What do you like about each?**
617
+ - Header: "Feedback"
618
+ - Question: "What do you like about each variant? (mention specific elements from A, B, C, D, E)"
619
+ - (Let user provide detailed feedback via "Other" text input)
620
+
621
+ Example response format to guide user:
622
+ ```
623
+ - A: Love the card layout and spacing
624
+ - B: The color scheme feels right
625
+ - C: The interaction on hover is great
626
+ - D: Nothing stands out
627
+ - E: The typography hierarchy is clearest
628
+ ```
629
+
630
+ Then proceed to **Phase 6: Synthesize New Variant**.
631
+
632
+ ---
633
+
634
+ ## Phase 6: Synthesize New Variant
635
+
636
+ Based on the user's feedback about what they liked from each variant:
637
+
638
+ 1. **Create a new hybrid variant** (Variant F) that combines:
639
+ - The specific elements the user called out from each
640
+ - The best structural decisions across all variants
641
+ - Any patterns that appeared in multiple variants
642
+
643
+ 2. **Replace the Design Lab** with a comparison view:
644
+ - Show the new synthesized Variant F prominently
645
+ - Keep 1-2 of the original variants that were closest for comparison
646
+ - Remove variants that had nothing the user liked
647
+
648
+ 3. **Update the `/__design_lab` route** to show the new arrangement
649
+
650
+ 4. **Ask for feedback again:**
651
+
652
+ **Question: How's the new variant?**
653
+ - Header: "Review"
654
+ - Question: "How does the synthesized variant (F) look?"
655
+ - Options:
656
+ - "This is it!" - Proceed to final preview
657
+ - "Getting closer" - Need another iteration
658
+ - "Went the wrong direction" - Let me clarify what I want
659
+
660
+ If "Getting closer" or "Went the wrong direction", gather more specific feedback and iterate. Support multiple synthesis passes until user is satisfied.
661
+
662
+ Then proceed to **Phase 7: Final Preview**.
663
+
664
+ ---
665
+
666
+ ## Phase 7: Final Preview
667
+
668
+ Once user is satisfied:
669
+
670
+ 1. Create `.claude-design/preview/` directory:
671
+ ```
672
+ .claude-design/preview/
673
+ ├── page.tsx # Preview page
674
+ └── FinalDesign.tsx # The winning design
675
+ ```
676
+
677
+ 2. Create route at `/__design_preview`
678
+
679
+ 3. For redesigns, include before/after comparison:
680
+ - Toggle switch or split view
681
+ - Show original alongside proposed
682
+
683
+ 4. Ask for final confirmation:
684
+
685
+ **Question: Confirm final design?**
686
+ - Header: "Confirm"
687
+ - Question: "Ready to finalize this design?"
688
+ - Options:
689
+ - "Yes, finalize it" - Proceed to cleanup and generate implementation plan
690
+ - "No, needs changes" - Tell me what to adjust
691
+ - "Abort - cancel everything" - Delete all temp files, no plan generated
692
+
693
+ If "No, needs changes": gather feedback and iterate.
694
+ If "Abort": proceed to **Abort Handling** below.
695
+
696
+ ---
697
+
698
+ ## Abort Handling
699
+
700
+ If the user wants to cancel/abort at ANY point during the process (not just final confirmation), they may say things like:
701
+ - "cancel"
702
+ - "abort"
703
+ - "stop"
704
+ - "nevermind"
705
+ - "forget it"
706
+ - "I changed my mind"
707
+
708
+ When abort is detected:
709
+
710
+ 1. **Confirm the abort:**
711
+ - "Are you sure you want to cancel? This will delete all the design lab files I created."
712
+
713
+ 2. **If confirmed, clean up immediately:**
714
+ - Delete `.claude-design/` directory entirely
715
+ - Delete temporary route files (`app/__design_lab/`, etc.)
716
+ - Do NOT generate any implementation plan
717
+ - Do NOT update Design Memory
718
+
719
+ 3. **Acknowledge:**
720
+ - "Design exploration cancelled. All temporary files have been cleaned up. Let me know if you want to start fresh later."
721
+
722
+ ---
723
+
724
+ ## Phase 8: Finalize
725
+
726
+ When user confirms (selected "Yes, finalize it"):
727
+
728
+ ### 8.1: Cleanup
729
+
730
+ Delete all temporary files:
731
+ - Remove `.claude-design/` directory entirely
732
+ - Remove temporary route files:
733
+ - `app/__design_lab/` (Next.js App Router)
734
+ - `pages/__design_lab.tsx` (Next.js Pages Router)
735
+ - `app/__design_preview/`
736
+ - `pages/__design_preview.tsx`
737
+ - Revert any `App.tsx` modifications (Vite)
738
+
739
+ **Safety rules:**
740
+ - ONLY delete files inside `.claude-design/`
741
+ - ONLY delete route files that the plugin created
742
+ - NEVER delete user-authored files
743
+ - Verify file paths before deletion
744
+
745
+ ### 8.2: Generate Implementation Plan
746
+
747
+ Create `DESIGN_PLAN.md` in the project root:
748
+
749
+ ```markdown
750
+ # Design Implementation Plan: [TargetName]
751
+
752
+ ## Summary
753
+ - **Scope:** [component/page]
754
+ - **Target:** [file path]
755
+ - **Winner variant:** [A-E]
756
+ - **Key improvements:** [from feedback]
757
+
758
+ ## Files to Change
759
+ - [ ] `src/components/Example.tsx` - Main component refactor
760
+ - [ ] `src/styles/example.css` - Style updates
761
+ - [ ] ... (list all affected files)
762
+
763
+ ## Implementation Steps
764
+ 1. [Specific step with code guidance]
765
+ 2. [Next step]
766
+ 3. ...
767
+
768
+ ## Component API
769
+ - **Props:**
770
+ - `prop1: type` - description
771
+ - ...
772
+ - **State:**
773
+ - Internal state requirements
774
+ - **Events:**
775
+ - Callbacks and handlers
776
+
777
+ ## Required UI States
778
+ - **Loading:** [description]
779
+ - **Empty:** [description]
780
+ - **Error:** [description]
781
+ - **Disabled:** [description]
782
+ - **Validation:** [description]
783
+
784
+ ## Accessibility Checklist
785
+ - [ ] Keyboard navigation works
786
+ - [ ] Focus states visible
787
+ - [ ] Labels and aria-* attributes correct
788
+ - [ ] Color contrast meets WCAG AA
789
+ - [ ] Screen reader tested
790
+
791
+ ## Testing Checklist
792
+ - [ ] Unit tests for logic
793
+ - [ ] Component tests for rendering
794
+ - [ ] Visual regression tests (if applicable)
795
+ - [ ] E2E smoke test (if applicable)
796
+
797
+ ## Design Tokens
798
+ - [Any new tokens to add]
799
+ - [Existing tokens to use]
800
+
801
+ ---
802
+
803
+ *Generated by Design Variations plugin*
804
+ ```
805
+
806
+ ### 8.3: Update Design Memory
807
+
808
+ Create or update `DESIGN_MEMORY.md`:
809
+
810
+ If new file:
811
+ ```markdown
812
+ # Design Memory
813
+
814
+ ## Brand Tone
815
+ - **Adjectives:** [from interview]
816
+ - **Avoid:** [anti-patterns discovered]
817
+
818
+ ## Layout & Spacing
819
+ - **Density:** [preference]
820
+ - **Grid:** [if established]
821
+ - **Corner radius:** [if consistent]
822
+ - **Shadows:** [if consistent]
823
+
824
+ ## Typography
825
+ - **Headings:** [font, weights used]
826
+ - **Body:** [font, size]
827
+ - **Emphasis:** [patterns]
828
+
829
+ ## Color
830
+ - **Primary:** [color tokens]
831
+ - **Secondary:** [color tokens]
832
+ - **Neutral strategy:** [approach]
833
+ - **Semantic colors:** [error, success, warning]
834
+
835
+ ## Interaction Patterns
836
+ - **Forms:** [validation approach, layout]
837
+ - **Modals/Drawers:** [when to use which]
838
+ - **Tables/Lists:** [preferred patterns]
839
+ - **Feedback:** [toast, inline, etc.]
840
+
841
+ ## Accessibility Rules
842
+ - **Focus:** [visible focus approach]
843
+ - **Labels:** [labeling conventions]
844
+ - **Motion:** [reduced motion support]
845
+
846
+ ## Repo Conventions
847
+ - **Component structure:** [file organization]
848
+ - **Styling approach:** [Tailwind classes, CSS modules, etc.]
849
+ - **Existing primitives:** [Button, Input, Card, etc.]
850
+
851
+ ---
852
+
853
+ *Updated by Design Variations plugin*
854
+ ```
855
+
856
+ If updating existing file:
857
+ - Append new patterns discovered
858
+ - Update any conflicting guidance with latest decisions
859
+ - Keep file concise and actionable
860
+
861
+ ---
862
+
863
+ ## Error Handling
864
+
865
+ ### Framework Not Detected
866
+ If framework cannot be determined:
867
+ - Ask user: "I couldn't detect your framework. What are you using?"
868
+ - Provide common options: Next.js, Vite, Create React App, Vue, etc.
869
+
870
+ ### Dev Server Fails
871
+ If dev server won't start:
872
+ - Check for port conflicts
873
+ - Provide manual instructions
874
+ - Suggest user starts server themselves
875
+
876
+ ### Route Integration Fails
877
+ If can't create temporary route:
878
+ - Fall back to creating standalone HTML file
879
+ - Provide instructions for manual preview
880
+
881
+ ### Cleanup Interrupted
882
+ If cleanup is interrupted:
883
+ - Log what was deleted vs remaining
884
+ - Provide manual cleanup instructions
885
+ - Never leave partial state without informing user
886
+
887
+ ---
888
+
889
+ ## Configuration Options
890
+
891
+ The plugin supports these optional configurations (via environment or project config):
892
+
893
+ - `DESIGN_AUTO_IMPLEMENT`: If `true`, implement the plan immediately after confirmation
894
+ - `DESIGN_KEEP_LAB`: If `true`, don't delete lab until explicit cleanup command
895
+ - `DESIGN_MEMORY_PATH`: Custom path for Design Memory file
896
+
897
+ ---
898
+
899
+ ## Example Session Flow
900
+
901
+ 1. User: `/design-variations:design CheckoutSummary`
902
+ 2. Plugin detects: Next.js App Router, Tailwind, pnpm
903
+ 3. Plugin finds: No existing Design Memory
904
+ 4. Plugin asks: Interview questions (5 steps)
905
+ 5. Plugin generates: Design Brief summary
906
+ 6. Plugin creates: `.claude-design/lab/` with 5 variants
907
+ 7. Plugin creates: `app/__design_lab/page.tsx`
908
+ 8. Plugin starts: `pnpm dev`
909
+ 9. Plugin outputs: "Open http://localhost:3000/__design_lab"
910
+ 10. User reviews variants in browser
911
+ 11. Plugin asks: "Which variant wins?"
912
+ 12. User: "Variant C, but change X and Y"
913
+ 13. Plugin refines: Updates Variant C
914
+ 14. User: "Looks good"
915
+ 15. Plugin creates: Final preview at `/__design_preview`
916
+ 16. User: "Confirmed"
917
+ 17. Plugin: Deletes all temp files
918
+ 18. Plugin: Generates `DESIGN_PLAN.md`
919
+ 19. Plugin: Creates `DESIGN_MEMORY.md`
920
+ 20. Plugin: "Done! See DESIGN_PLAN.md for implementation steps"