Update to latest version
This commit is contained in:
Mårten Angner
parent
9cd83242fa
commit
044c83eeda
|
|
@ -31,7 +31,7 @@ The HTML to Design workflow focuses on:
|
|||
### Key Components Built
|
||||
|
||||
#### 1. Dev Mode JavaScript Component
|
||||
- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js`
|
||||
- **Location**: `src/modules/wds/workflows/4-ux-design/agentic-development/templates/components/dev-mode.js`
|
||||
- **Purpose**: Interactive tool for extracting Object IDs from live prototypes
|
||||
- **Features**:
|
||||
- Toggle dev mode with button or Ctrl+E
|
||||
|
|
@ -42,7 +42,7 @@ The HTML to Design workflow focuses on:
|
|||
- Form field protection (Shift disabled when typing)
|
||||
|
||||
#### 2. Work File Template
|
||||
- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/work-file-template.yaml`
|
||||
- **Location**: `src/modules/wds/workflows/4-ux-design/agentic-development/templates/work-file-template.yaml`
|
||||
- **Purpose**: Complete planning document for section-by-section implementation
|
||||
- **Structure**:
|
||||
- Metadata and device compatibility
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ This document summarizes the work done on the HTML to Design side of the WDS v6
|
|||
- ESLint rule compliance (`unicorn/prefer-module`, `no-unused-vars`, etc.)
|
||||
|
||||
### 2. Dev Mode JavaScript Component
|
||||
- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js`
|
||||
- **Location**: `src/modules/wds/workflows/4-ux-design/agentic-development/templates/components/dev-mode.js`
|
||||
- **Purpose**: Developer/feedback mode for copying Object IDs in prototypes
|
||||
- **Features Implemented**:
|
||||
- Toggle dev mode with button or Ctrl+E
|
||||
|
|
@ -24,7 +24,7 @@ This document summarizes the work done on the HTML to Design side of the WDS v6
|
|||
- Form field protection (Shift disabled when typing)
|
||||
|
||||
### 3. Work File Template
|
||||
- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/work-file-template.yaml`
|
||||
- **Location**: `src/modules/wds/workflows/4-ux-design/agentic-development/templates/work-file-template.yaml`
|
||||
- **Purpose**: Complete planning document for section-by-section implementation
|
||||
- **Structure**:
|
||||
- Metadata and device compatibility
|
||||
|
|
|
|||
|
|
@ -118,9 +118,9 @@ Choose a workflow to start:
|
|||
```
|
||||
*Define your product vision and goals*
|
||||
|
||||
### 🎨 **Interactive Prototypes**
|
||||
### 🎨 **Agentic Development**
|
||||
```
|
||||
@wds/workflows/interactive-prototypes
|
||||
@wds/workflows/agentic-development
|
||||
```
|
||||
*Build clickable prototypes for testing*
|
||||
|
||||
|
|
@ -158,7 +158,7 @@ Choose a workflow to start:
|
|||
|----------|---------|-----------|
|
||||
| **Trigger Map** | User pain points | `@wds/workflows/trigger-map` |
|
||||
| **Product Brief** | Product vision | `@wds/workflows/product-brief` |
|
||||
| **Prototypes** | Interactive demos | `@wds/workflows/interactive-prototypes` |
|
||||
| **Prototypes** | Interactive demos | `@wds/workflows/agentic-development` |
|
||||
| **Scenario Init** | User journeys | `@wds/workflows/scenario-init` |
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -0,0 +1,193 @@
|
|||
# Getting Things Done (GTD)
|
||||
|
||||
**By:** David Allen (2001)
|
||||
**Source:** "Getting Things Done: The Art of Stress-Free Productivity"
|
||||
|
||||
---
|
||||
|
||||
## Core Concept
|
||||
|
||||
GTD is a personal productivity methodology that helps manage commitments, information, and action. The core insight: your mind is for having ideas, not holding them. Capture everything externally, then organize and act systematically.
|
||||
|
||||
---
|
||||
|
||||
## The Five Steps
|
||||
|
||||
### 1. Capture
|
||||
Collect everything that has your attention into a trusted system. Don't rely on memory.
|
||||
|
||||
### 2. Clarify
|
||||
Process what you've captured:
|
||||
- Is it actionable?
|
||||
- What's the next action?
|
||||
- What's the desired outcome?
|
||||
|
||||
### 3. Organize
|
||||
Put things where they belong:
|
||||
- Next Actions (by context)
|
||||
- Projects (multi-step outcomes)
|
||||
- Waiting For (delegated)
|
||||
- Someday/Maybe (future ideas)
|
||||
- Reference (information)
|
||||
|
||||
### 4. Reflect
|
||||
Review your system regularly:
|
||||
- Daily: Check calendar, review next actions
|
||||
- Weekly: Full review of all lists, projects, commitments
|
||||
|
||||
### 5. Engage
|
||||
Do the work with confidence, knowing your system has captured everything.
|
||||
|
||||
---
|
||||
|
||||
## The 2-Minute Rule
|
||||
|
||||
**If an action takes less than 2 minutes, do it immediately.**
|
||||
|
||||
This is one of GTD's most powerful and widely-adopted principles:
|
||||
|
||||
- The overhead of tracking a 2-minute task exceeds doing it
|
||||
- Immediate completion clears mental clutter
|
||||
- Builds momentum through quick wins
|
||||
- Prevents small tasks from accumulating
|
||||
|
||||
### In Practice
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Quick email reply | Send now |
|
||||
| Simple file rename | Do now |
|
||||
| Brief clarification | Ask now |
|
||||
| Small fix | Fix now |
|
||||
|
||||
### The Threshold
|
||||
|
||||
2 minutes is a guideline, not a strict rule. The principle is:
|
||||
|
||||
> **Planning overhead should not exceed task complexity.**
|
||||
|
||||
If documenting, categorizing, and scheduling a task takes longer than doing it — just do it.
|
||||
|
||||
---
|
||||
|
||||
## Applied in WDS Agentic Development
|
||||
|
||||
### Task Complexity Assessment
|
||||
|
||||
Before adding something to the plan, ask:
|
||||
|
||||
| Question | If Yes → |
|
||||
|----------|----------|
|
||||
| Can I fix this in < 2 minutes? | Do it now, log as sub-step |
|
||||
| Does it need context I don't have? | Add to plan |
|
||||
| Does it affect architecture? | Add to plan |
|
||||
| Is it outside current scope? | Level 4 change request |
|
||||
|
||||
### Bug Fixes vs. Features
|
||||
|
||||
**Bugs (2-minute candidates):**
|
||||
- Missing condition check
|
||||
- Wrong variable name
|
||||
- Off-by-one error
|
||||
- Missing translation
|
||||
|
||||
**Features (need planning):**
|
||||
- New component
|
||||
- New state handling
|
||||
- Architectural changes
|
||||
- Multi-file refactors
|
||||
|
||||
### Sub-Step Pattern
|
||||
|
||||
When a 2-minute fix arises during planned work:
|
||||
|
||||
1. **Do** the fix immediately
|
||||
2. **Log** it as a sub-step (e.g., 20a-1)
|
||||
3. **Continue** with the main task
|
||||
|
||||
This maintains traceability without planning overhead.
|
||||
|
||||
---
|
||||
|
||||
## Why This Matters for AI Collaboration
|
||||
|
||||
Agentic development involves constant micro-decisions:
|
||||
- Should I plan this?
|
||||
- Should I do this now?
|
||||
- Should I defer this?
|
||||
|
||||
The 2-minute rule provides a clear heuristic:
|
||||
|
||||
```
|
||||
IF task_complexity < 2_minutes:
|
||||
execute_immediately()
|
||||
log_as_substep()
|
||||
ELSE:
|
||||
add_to_plan()
|
||||
```
|
||||
|
||||
This prevents:
|
||||
- Analysis paralysis on trivial tasks
|
||||
- Planning overhead exceeding task value
|
||||
- Context switching from minor interruptions
|
||||
- Accumulated technical debt from deferred tiny fixes
|
||||
|
||||
---
|
||||
|
||||
## Related Concepts
|
||||
|
||||
### Inbox Zero
|
||||
Process everything to zero — don't leave items in limbo.
|
||||
|
||||
### Next Actions
|
||||
Define the very next physical action for every project.
|
||||
|
||||
### Waiting For
|
||||
Track delegated items so nothing falls through cracks.
|
||||
|
||||
### Weekly Review
|
||||
Regular system maintenance keeps it trustworthy.
|
||||
|
||||
---
|
||||
|
||||
## Source Materials
|
||||
|
||||
### Book
|
||||
- **"Getting Things Done: The Art of Stress-Free Productivity"** by David Allen (2001, revised 2015)
|
||||
|
||||
### Website
|
||||
- [GettingThingsDone.com](https://gettingthingsdone.com)
|
||||
|
||||
### Key Articles
|
||||
- "The 2-Minute Rule" — David Allen
|
||||
- "GTD in 15 minutes" — Various summaries online
|
||||
|
||||
---
|
||||
|
||||
## WDS Integration Points
|
||||
|
||||
| WDS Context | GTD Application |
|
||||
|-------------|-----------------|
|
||||
| **Agentic Development** | 2-minute rule for bug fixes, sub-step logging |
|
||||
| **Agent Dialogs** | Capture system for ideas (dialog files) |
|
||||
| **Change Requests** | Someday/Maybe list for outside-scope items |
|
||||
| **Progress Logs** | Review and reflect on completed work |
|
||||
| **Session Start Protocol** | Weekly review concept (check reality vs. plan) |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### The 2-Minute Rule
|
||||
> If it takes less than 2 minutes, do it now.
|
||||
|
||||
### The Core Principle
|
||||
> Planning overhead should not exceed task complexity.
|
||||
|
||||
### Applied to Development
|
||||
> Quick fixes → Do and log as sub-step
|
||||
> Complex changes → Add to plan first
|
||||
|
||||
---
|
||||
|
||||
*Getting Things Done - Stress-free productivity through systematic capture and action.*
|
||||
|
|
@ -93,7 +93,7 @@ Used in Trigger Mapping Workshop 1 to transform vision (visionary statements) in
|
|||
|
||||
### [Kathy Sierra Badass Users](./kathy-sierra-badass-users.md)
|
||||
|
||||
**By:** Kathy Sierra (2000s-2015)
|
||||
**By:** Kathy Sierra (2000s-2015)
|
||||
**Core Idea:** Don't make a better product. Make users better at what they want to do. Focus on user capability.
|
||||
|
||||
**Applied in WDS:**
|
||||
|
|
@ -106,6 +106,21 @@ Used in Trigger Mapping Workshop 1 to transform vision (visionary statements) in
|
|||
|
||||
---
|
||||
|
||||
### [Getting Things Done (GTD)](./gtd-getting-things-done.md)
|
||||
|
||||
**By:** David Allen (2001)
|
||||
**Core Idea:** Your mind is for having ideas, not holding them. Capture everything, then process and act systematically.
|
||||
|
||||
**Applied in WDS:**
|
||||
- **2-Minute Rule:** If it takes < 2 minutes, do it now (don't plan trivial tasks)
|
||||
- Agent Dialogs as capture system (externalize all ideas)
|
||||
- Change Requests as "Someday/Maybe" list
|
||||
- Session Start Protocol as weekly review concept
|
||||
|
||||
**When to Use:** Deciding whether to plan or act, managing task complexity, avoiding planning overhead
|
||||
|
||||
---
|
||||
|
||||
## Models vs. Methods
|
||||
|
||||
### Models (This Folder)
|
||||
|
|
@ -227,6 +242,7 @@ These models represent decades of insight from brilliant thinkers who've shaped
|
|||
- **Mijo Balic & Ingrid Domingues** - Connecting goals to user behavior
|
||||
- **Gojko Adzic** - Making strategic planning accessible
|
||||
- **Simon Sinek** - Teaching us to start with WHY
|
||||
- **David Allen** - Systematic productivity and the 2-minute rule
|
||||
- **George T. Doran** - Creating measurable, achievable objectives
|
||||
- **Cathy Moore** - Focusing on action over information
|
||||
- **Kathy Sierra** - Championing user capability
|
||||
|
|
|
|||
|
|
@ -59,9 +59,10 @@ agent:
|
|||
**Micro-Guides (load when needed):**
|
||||
- Strategic Design → data/agent-guides/freya/strategic-design.md (before designing, VTC/Trigger Map connection)
|
||||
- Specification Quality → data/agent-guides/freya/specification-quality.md (creating specs, logical explanations)
|
||||
- Interactive Prototyping → data/agent-guides/freya/interactive-prototyping.md (HTML prototypes, validation)
|
||||
- Agentic Development → data/agent-guides/freya/agentic-development.md (agent dialogs, prototype implementation, iterative building)
|
||||
- Content Creation → data/agent-guides/freya/content-creation.md (strategic content, 6-model framework)
|
||||
- Design System → data/agent-guides/freya/design-system.md (Phase 5, organic growth, Figma integration)
|
||||
- Stitch Generation → workflows/4-ux-design/stitch-generation/workflow.md (AI-assisted UI generation with Google Stitch)
|
||||
|
||||
**Collaboration:**
|
||||
- My domain: Phases 4 (UX Design), 5 (Design System - optional), 7 (Testing)
|
||||
|
|
@ -74,6 +75,7 @@ agent:
|
|||
- Prototypes validate before production (micro-guide: interactive-prototyping.md)
|
||||
- Content is strategic, not decorative (micro-guide: content-creation.md)
|
||||
- Design systems grow organically (micro-guide: design-system.md if Phase 5)
|
||||
- AI-assisted design via Google Stitch when spec + sketch ready (workflow: stitch-generation)
|
||||
- Visual refinement via Figma when design system incomplete (automated MCP integration)
|
||||
|
||||
**Project Tracking:**
|
||||
|
|
@ -88,12 +90,20 @@ agent:
|
|||
|
||||
- trigger: ux-design
|
||||
exec: "{project-root}/{bmad_folder}/wds/workflows/4-ux-design/workflow.md"
|
||||
description: Create interactive prototypes and scenarios (Phase 4)
|
||||
description: Create specifications and scenarios (Phase 4)
|
||||
|
||||
- trigger: agentic-development
|
||||
exec: "{project-root}/{bmad_folder}/wds/workflows/9-agent-dialogs/workflow.md"
|
||||
description: Build features iteratively with agent dialogs (prototypes, implementations, bug fixes)
|
||||
|
||||
- trigger: audit-spec
|
||||
exec: "{project-root}/{bmad_folder}/wds/workflows/4-ux-design/specification-audit-workflow.md"
|
||||
description: "[AS] Audit page or scenario specifications for completeness and quality"
|
||||
|
||||
- trigger: stitch-generation
|
||||
exec: "{project-root}/{bmad_folder}/wds/workflows/4-ux-design/stitch-generation/workflow.md"
|
||||
description: Generate UI designs with Google Stitch AI from specifications and sketches
|
||||
|
||||
- trigger: design-system
|
||||
exec: "{project-root}/{bmad_folder}/wds/workflows/5-design-system/workflow.md"
|
||||
description: Build component library with design tokens (Phase 5 - optional)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,200 @@
|
|||
# Freya's Agentic Development Guide
|
||||
|
||||
**When to load:** When implementing features, building prototypes, or fixing bugs through structured agent dialogs
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Agentic Development uses structured dialogs to build incrementally with full traceability.**
|
||||
|
||||
Agent Dialogs bridge the gap between specifications and working code. Each step is self-contained, allowing fresh context while maintaining continuity.
|
||||
|
||||
---
|
||||
|
||||
## What is Agentic Development?
|
||||
|
||||
Agentic Development is a **workflow approach** that produces various outputs:
|
||||
|
||||
| Output Type | Description | When to Use |
|
||||
|-------------|-------------|-------------|
|
||||
| **Interactive Prototypes** | HTML prototypes that let users FEEL the design | Validating UX before production |
|
||||
| **Prototype Implementation** | Building features from specifications | Feature development |
|
||||
| **Bug Fixes** | Structured debugging and fixing | Issue resolution |
|
||||
| **Design Exploration** | Exploring visual/UX directions | Creative iteration |
|
||||
|
||||
**Key Insight:** By structuring work into documented dialog folders, we create:
|
||||
- **Isolation** — Each step can run in a fresh context
|
||||
- **Traceability** — Clear record of what was planned and executed
|
||||
- **Replayability** — Instructions can be rerun if needed
|
||||
- **Handoff** — Different agents or humans can continue the work
|
||||
|
||||
---
|
||||
|
||||
## Agent Startup Protocol
|
||||
|
||||
**When awakened, always check for pending dialogs:**
|
||||
|
||||
```
|
||||
1. Check: docs/F-Agent-Dialogs/
|
||||
2. Find dialogs where:
|
||||
- Status = "Not Started" or "In Progress"
|
||||
- Agent matches the awakened agent
|
||||
3. Present pending dialogs to user
|
||||
```
|
||||
|
||||
This ensures no captured work is forgotten.
|
||||
|
||||
---
|
||||
|
||||
## The Bridge Role
|
||||
|
||||
Agent Dialogs bridge **specifications** and **development**:
|
||||
|
||||
```
|
||||
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
|
||||
│ SPECIFICATION │ │ AGENT DIALOG │ │ DEVELOPMENT │
|
||||
│ │ │ │ │ │
|
||||
│ • What to build │────────▶│ • What's in scope │────────▶│ • How to build │
|
||||
│ • Object IDs │ │ • Step breakdown │ │ • Code files │
|
||||
│ • Requirements │ │ • Traceability │ │ • Components │
|
||||
│ • Translations │ │ • Progress tracking │ │ • Tests │
|
||||
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
|
||||
Single Source Navigation Implementation
|
||||
of Truth Layer
|
||||
```
|
||||
|
||||
**The specification is the single source of truth.** Dialogs do not duplicate spec content — they map implementation tasks to spec sections via Object IDs.
|
||||
|
||||
---
|
||||
|
||||
## Dialog Folder Structure
|
||||
|
||||
```
|
||||
docs/F-Agent-Dialogs/
|
||||
└── {DATE}-{agent}-{feature-name}/
|
||||
├── {DATE}-{agent}-{feature-name}-dialog.md ← Main file
|
||||
└── steps/
|
||||
├── 01-{step-name}.md ← Self-contained steps
|
||||
├── 02-{step-name}.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feedback Protocol
|
||||
|
||||
During implementation, classify and handle feedback naturally:
|
||||
|
||||
| Type | What It Is | When to Address |
|
||||
|------|------------|-----------------|
|
||||
| **Bug/Issue** | Something broken or not working as expected | Now — iterate until fixed |
|
||||
| **Quick Adjustment** | Small tweak to current work | Now — implement immediately |
|
||||
| **Addition** | New requirement that fits current scope | Later step — add to plan |
|
||||
| **Change Request** | Outside current dialog scope | Future session — document in Change Requests |
|
||||
|
||||
**Response Pattern:**
|
||||
1. **Classify** — Note what kind of feedback this is
|
||||
2. **Timing** — State when it should be addressed
|
||||
3. **Confirm** — For additions and change requests, confirm before proceeding
|
||||
4. **Execute** — Implement or document as appropriate
|
||||
|
||||
---
|
||||
|
||||
## Interactive Prototypes (Output Type)
|
||||
|
||||
Interactive Prototypes are **one output** of Agentic Development.
|
||||
|
||||
### Why HTML Prototypes?
|
||||
|
||||
**Static Specs Can't Show:**
|
||||
- How it FEELS to interact
|
||||
- Where users get confused
|
||||
- What's missing in the flow
|
||||
- If the pacing feels right
|
||||
|
||||
**HTML Prototypes Reveal:**
|
||||
- Interaction feels natural or awkward
|
||||
- Information appears when needed
|
||||
- Flow has logical gaps
|
||||
- Users understand next steps
|
||||
|
||||
### Fidelity Levels
|
||||
|
||||
| Level | Focus | Use When |
|
||||
|-------|-------|----------|
|
||||
| **Wireframe** | Information architecture | Testing flow logic only |
|
||||
| **Interactive** | User experience | Validating UX (standard) |
|
||||
| **Design System** | Component-based | Phase 5 enabled |
|
||||
|
||||
### Prototype vs Production
|
||||
|
||||
**Prototypes ARE:**
|
||||
- Thinking tools
|
||||
- Communication tools
|
||||
- Validation tools
|
||||
- Specification supplements
|
||||
|
||||
**Prototypes are NOT:**
|
||||
- Production code
|
||||
- Pixel-perfect mockups
|
||||
- Final design
|
||||
|
||||
---
|
||||
|
||||
## Prototype Implementation (Output Type)
|
||||
|
||||
Building features from specifications through structured dialog steps.
|
||||
|
||||
### Step File Structure
|
||||
|
||||
Each step links to specifications (doesn't duplicate):
|
||||
|
||||
```markdown
|
||||
## Object ID Implementation Map
|
||||
|
||||
| Object ID | Spec Section | Lines |
|
||||
|-----------|--------------|-------|
|
||||
| `booking-detail-header` | Drawer Header | L149-L158 |
|
||||
| `booking-detail-close` | Close Button | L159-L168 |
|
||||
```
|
||||
|
||||
### Implementation Checklist Pattern
|
||||
|
||||
For each Object ID:
|
||||
1. **Read** — Load the spec section
|
||||
2. **Implement** — Build to match spec
|
||||
3. **Verify** — Confirm Object ID present and behavior correct
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Single Source of Truth
|
||||
- **Never duplicate spec content** — Link to spec sections with line numbers
|
||||
- **Object IDs are the contract** — Every implementation maps to an Object ID
|
||||
- **Spec changes update the spec** — Not the dialog or step files
|
||||
|
||||
### Dialog Files
|
||||
- **Be thorough in Setup Context** — Assume zero prior knowledge
|
||||
- **Include file paths** — Always use absolute or project-relative paths
|
||||
- **Track progress** — Update the Steps Overview table after each step
|
||||
|
||||
### Execution
|
||||
- **Read spec first** — Before implementing any Object ID
|
||||
- **Fresh context is fine** — Steps are designed to work in isolation
|
||||
- **Update as you go** — Don't wait to update progress
|
||||
- **Capture discoveries** — Note spec changes or issues found
|
||||
|
||||
---
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **Agent Dialog Workflow:** `workflows/9-agent-dialogs/workflow.md`
|
||||
- **Dialog Template:** `workflows/9-agent-dialogs/templates/dialog.template.md`
|
||||
- **Step Template:** `workflows/9-agent-dialogs/templates/step.template.md`
|
||||
- **Phase 4 UX Design:** `workflows/4-ux-design/workflow.md`
|
||||
|
||||
---
|
||||
|
||||
*Build incrementally. Document thoroughly. Let users FEEL the design before committing to production.*
|
||||
|
|
@ -1,259 +0,0 @@
|
|||
# Freya's Interactive Prototyping Guide
|
||||
|
||||
**When to load:** When creating HTML prototypes or interactive mockups
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**HTML prototypes are THINKING TOOLS, not final products.**
|
||||
|
||||
Prototypes let users FEEL the design before we commit to production code. They reveal gaps in logic that static specs might miss.
|
||||
|
||||
---
|
||||
|
||||
## Why HTML Prototypes?
|
||||
|
||||
### Static Specs Can't Show
|
||||
- ❌ How it FEELS to interact
|
||||
- ❌ Where users get confused
|
||||
- ❌ What's missing in the flow
|
||||
- ❌ If the pacing feels right
|
||||
- ❌ Whether copy actually works
|
||||
|
||||
### HTML Prototypes Reveal
|
||||
- ✅ Interaction feels natural or awkward
|
||||
- ✅ Information appears when needed
|
||||
- ✅ Flow has logical gaps
|
||||
- ✅ Users understand next steps
|
||||
- ✅ Content triggers emotions
|
||||
|
||||
---
|
||||
|
||||
## Prototypes as Validation
|
||||
|
||||
**Think of prototypes as:**
|
||||
- **Thinking tools** - Help us understand what we're building
|
||||
- **Communication tools** - Show stakeholders/users the vision
|
||||
- **Validation tools** - Catch problems before coding
|
||||
- **Specification supplements** - Demonstrate what words can't
|
||||
|
||||
**NOT:**
|
||||
- ❌ Production code (that's Phase 4 → BMM handoff)
|
||||
- ❌ Pixel-perfect mockups (that's Figma's job)
|
||||
- ❌ Final design (they're meant to evolve)
|
||||
|
||||
---
|
||||
|
||||
## When to Create Prototypes
|
||||
|
||||
### Always Create For
|
||||
- Complex interactions (multi-step forms, wizards)
|
||||
- Novel UI patterns (users haven't seen before)
|
||||
- Critical flows (signup, purchase, onboarding)
|
||||
- Content-heavy pages (validate information hierarchy)
|
||||
|
||||
### Optional For
|
||||
- Simple pages (standard layouts)
|
||||
- Repetitive patterns (once validated, reuse)
|
||||
- Admin interfaces (if similar to known patterns)
|
||||
|
||||
**When in doubt → Prototype.** 30 minutes of HTML saves hours of rework.
|
||||
|
||||
---
|
||||
|
||||
## Prototype Fidelity Levels
|
||||
|
||||
### 1. Wireframe Prototype (Fastest)
|
||||
- Basic HTML structure
|
||||
- Placeholder content
|
||||
- No styling (browser defaults)
|
||||
- Focus: Information architecture
|
||||
|
||||
**Use when:** Testing flow logic only
|
||||
|
||||
---
|
||||
|
||||
### 2. Interactive Prototype (Standard)
|
||||
- Structured HTML
|
||||
- Actual content (multi-language)
|
||||
- Basic CSS (layout, spacing, typography)
|
||||
- Interactive elements (buttons, forms, navigation)
|
||||
|
||||
**Use when:** Validating user experience
|
||||
|
||||
---
|
||||
|
||||
### 3. Design System Prototype (If Enabled)
|
||||
- Component-based HTML
|
||||
- Design System classes
|
||||
- Design tokens (colors, spacing)
|
||||
- Real interactions
|
||||
|
||||
**Use when:** Phase 5 (Design System) is enabled
|
||||
|
||||
---
|
||||
|
||||
## Using Design System Components
|
||||
|
||||
### If Design System Enabled (Phase 5)
|
||||
|
||||
**Check first:**
|
||||
1. Does this component exist in the Design System?
|
||||
2. If yes → Use it
|
||||
3. If similar → Assess opportunity/risk of creating variant
|
||||
4. If no → Mark for future extraction
|
||||
|
||||
**In prototype:**
|
||||
```html
|
||||
<!-- Reference existing component -->
|
||||
<button class="ds-button ds-button--primary">
|
||||
Sign Up
|
||||
</button>
|
||||
|
||||
<!-- Or note for future -->
|
||||
<!-- TODO: Extract as ds-card-feature component -->
|
||||
<div class="temp-feature-card">
|
||||
...
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### If Design System Disabled
|
||||
|
||||
**Use page-specific classes:**
|
||||
```html
|
||||
<!-- Page-specific, won't be reused -->
|
||||
<button class="landing-cta-primary">
|
||||
Sign Up
|
||||
</button>
|
||||
```
|
||||
|
||||
**Developers know:** No design system = implement as-is, no abstraction needed.
|
||||
|
||||
---
|
||||
|
||||
## What to Include in Prototypes
|
||||
|
||||
### Must Have
|
||||
- ✅ All sections in correct order
|
||||
- ✅ Actual content (headlines, copy, CTAs)
|
||||
- ✅ Multi-language versions (separate HTML files or language toggle)
|
||||
- ✅ Interactive elements (buttons, forms, links)
|
||||
- ✅ Key states (default, hover, active, disabled)
|
||||
|
||||
### Optional
|
||||
- Form validation (unless testing UX)
|
||||
- Backend integration (never)
|
||||
- Pixel-perfect design (Figma's job)
|
||||
- Production-quality code (it's a prototype!)
|
||||
|
||||
---
|
||||
|
||||
## Prototype Validation Process
|
||||
|
||||
### 1. Internal Check
|
||||
- Click through the flow yourself
|
||||
- Does it feel natural?
|
||||
- Any confusing moments?
|
||||
- Missing information?
|
||||
- Logical gaps?
|
||||
|
||||
### 2. Stakeholder Review
|
||||
- Show prototype in conversation
|
||||
- Watch where they pause or ask questions
|
||||
- Note confusion points
|
||||
- Validate assumptions
|
||||
|
||||
### 3. User Testing (Optional)
|
||||
- If critical flow, test with 3-5 users
|
||||
- Watch, don't explain
|
||||
- Note where they struggle
|
||||
- Identify patterns
|
||||
|
||||
### 4. Iterate
|
||||
- Fix gaps revealed by validation
|
||||
- Update specification accordingly
|
||||
- Re-prototype if major changes
|
||||
|
||||
---
|
||||
|
||||
## Prototype → Specification Flow
|
||||
|
||||
**Prototypes inform specs, not replace them:**
|
||||
|
||||
1. **Create prototype** - Think through interaction
|
||||
2. **Validate prototype** - Catch issues early
|
||||
3. **Update specification** - Document what works
|
||||
4. **Generate final spec** - With prototype insights
|
||||
|
||||
**Result:** Specification is battle-tested before development.
|
||||
|
||||
---
|
||||
|
||||
## Common Prototype Mistakes
|
||||
|
||||
### ❌ Over-Engineering
|
||||
"Let me make this perfect production code..."
|
||||
- **Why bad:** Wastes time, misses the point
|
||||
- **Instead:** Quick and dirty is fine - it's a prototype
|
||||
|
||||
### ❌ Under-Engineering
|
||||
"Just some divs with text..."
|
||||
- **Why bad:** Can't validate actual experience
|
||||
- **Instead:** Make it interactive enough to feel real
|
||||
|
||||
### ❌ Skipping Validation
|
||||
"I know this works, no need to test..."
|
||||
- **Why bad:** Your assumptions might be wrong
|
||||
- **Instead:** Always validate with at least one other person
|
||||
|
||||
### ❌ Treating as Final
|
||||
"This prototype IS the spec..."
|
||||
- **Why bad:** Missing critical specification details
|
||||
- **Instead:** Prototype → insights → specification
|
||||
|
||||
---
|
||||
|
||||
## Technical Notes
|
||||
|
||||
### File Structure
|
||||
```
|
||||
docs/C-Scenarios/[scenario-name]/prototypes/
|
||||
├── landing-page-en.html
|
||||
├── landing-page-se.html
|
||||
├── signup-flow-en.html
|
||||
└── styles.css (shared)
|
||||
```
|
||||
|
||||
### Basic Template
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>[Page Name] - Prototype</title>
|
||||
<link rel="stylesheet" href="styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<!-- Prototype content -->
|
||||
|
||||
<!-- Note: This is a UX prototype, not production code -->
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **Phase 4 Workflow:** `../../workflows/4-ux-design/`
|
||||
- **Design System:** `../../workflows/5-design-system/`
|
||||
- **Page Specification Template:** `../../workflows/4-ux-design/templates/page-specification.template.md`
|
||||
|
||||
---
|
||||
|
||||
*Show, don't tell. Let users FEEL the design before we build it.*
|
||||
|
||||
|
|
@ -28,7 +28,7 @@
|
|||
## ✅ DO Use Specific Names
|
||||
|
||||
### Always Create:
|
||||
- ✅ `INTERACTIVE-PROTOTYPES-GUIDE.md` (specific topic)
|
||||
- ✅ `AGENTIC-DEVELOPMENT-GUIDE.md` (specific topic)
|
||||
- ✅ `FREYA-WORKFLOW-INSTRUCTIONS.md` (specific agent + purpose)
|
||||
- ✅ `PROTOTYPE-ROADMAP.md` (specific purpose)
|
||||
- ✅ `PROJECT-ANALYSIS-ROUTER.md` (specific function)
|
||||
|
|
@ -43,7 +43,7 @@
|
|||
### Pattern 1: [TOPIC]-GUIDE.md
|
||||
**When**: Overview/introduction to a topic
|
||||
**Examples**:
|
||||
- `INTERACTIVE-PROTOTYPES-GUIDE.md`
|
||||
- `AGENTIC-DEVELOPMENT-GUIDE.md`
|
||||
- `DESIGN-SYSTEM-GUIDE.md`
|
||||
- `TESTING-GUIDE.md`
|
||||
|
||||
|
|
@ -199,7 +199,7 @@ project-analysis/
|
|||
- `-ROADMAP.md` - Status/plan tracking
|
||||
|
||||
**Examples**:
|
||||
- `INTERACTIVE-PROTOTYPES-GUIDE.md`
|
||||
- `AGENTIC-DEVELOPMENT-GUIDE.md`
|
||||
- `FREYA-WORKFLOW-INSTRUCTIONS.md`
|
||||
- `page-template.html`
|
||||
- `PROTOTYPE-ANALYSIS.md`
|
||||
|
|
@ -228,7 +228,7 @@ project-analysis/
|
|||
|
||||
| ❌ Generic | ✅ Specific |
|
||||
|-----------|------------|
|
||||
| `README.md` | `INTERACTIVE-PROTOTYPES-GUIDE.md` |
|
||||
| `README.md` | `AGENTIC-DEVELOPMENT-GUIDE.md` |
|
||||
| `INSTRUCTIONS.md` | `FREYA-WORKFLOW-INSTRUCTIONS.md` |
|
||||
| `GUIDE.md` | `DESIGN-SYSTEM-GUIDE.md` |
|
||||
| `template.yaml` | `work-file-template.yaml` |
|
||||
|
|
|
|||
|
|
@ -141,8 +141,8 @@ topic/
|
|||
|
||||
**Example**:
|
||||
```
|
||||
interactive-prototypes/
|
||||
├── INTERACTIVE-PROTOTYPES-GUIDE.md (complete system overview)
|
||||
agentic-development/
|
||||
├── AGENTIC-DEVELOPMENT-GUIDE.md (complete system overview)
|
||||
├── CREATION-GUIDE.md (detailed technical reference)
|
||||
└── PROTOTYPE-ANALYSIS.md (case study)
|
||||
```
|
||||
|
|
|
|||
|
|
@ -0,0 +1,212 @@
|
|||
# Agentic Development - File Index
|
||||
|
||||
**Location**: `src/workflows/4-ux-design/agentic-development/`
|
||||
|
||||
---
|
||||
|
||||
## 📁 Complete File Structure
|
||||
|
||||
```
|
||||
agentic-development/
|
||||
│
|
||||
├── AGENTIC-DEVELOPMENT-GUIDE.md ← START HERE (overview & quick reference)
|
||||
├── workflow.md ← Workflow overview with phase links
|
||||
├── PROTOTYPE-INITIATION-DIALOG.md ← Conversation scripts for initiation
|
||||
├── CREATION-GUIDE.md ← Original detailed guide (reference)
|
||||
├── PROTOTYPE-ANALYSIS.md ← Dog Week analysis (examples)
|
||||
│
|
||||
├── steps-c/ ← Micro-step workflow files
|
||||
│ ├── 1-prototype-setup.md ← Phase 1: Environment setup
|
||||
│ ├── 2-scenario-analysis.md ← Phase 2: Analyze spec & create views
|
||||
│ ├── 3-logical-view-breakdown.md ← Phase 3: Break view into sections
|
||||
│ ├── 4a-announce-and-gather.md ← Phase 4a: Announce section
|
||||
│ ├── 4b-create-story-file.md ← Phase 4b: Create story file
|
||||
│ ├── 4c-implement-section.md ← Phase 4c: Implement code
|
||||
│ ├── 4d-present-for-testing.md ← Phase 4d: Present for testing
|
||||
│ ├── 4e-handle-issue.md ← Phase 4e: Fix issues (loop)
|
||||
│ ├── 4f-handle-improvement.md ← Phase 4f: Handle improvements (loop)
|
||||
│ ├── 4g-section-approved.md ← Phase 4g: Section approved
|
||||
│ └── 5-finalization.md ← Phase 5: Integration test & approval
|
||||
│
|
||||
├── templates/
|
||||
│ ├── work-file-template.yaml ← Planning document template
|
||||
│ ├── story-file-template.md ← Section implementation template
|
||||
│ ├── page-template.html ← Complete HTML page template
|
||||
│ ├── PROTOTYPE-ROADMAP-template.md ← Scenario roadmap template
|
||||
│ ├── demo-data-template.json ← Demo data structure template
|
||||
│ └── components/
|
||||
│ ├── dev-mode.html ← Dev mode toggle button
|
||||
│ ├── dev-mode.js ← Dev mode logic (Shift+Click to copy IDs)
|
||||
│ ├── dev-mode.css ← Dev mode styles
|
||||
│ └── DEV-MODE-GUIDE.md ← Dev mode usage guide
|
||||
│
|
||||
└── examples/
|
||||
└── (Dog Week prototypes as reference)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 What Each File Does
|
||||
|
||||
### Core Documentation
|
||||
|
||||
#### `AGENTIC-DEVELOPMENT-GUIDE.md`
|
||||
**Purpose**: Complete system overview
|
||||
**For**: All agents (Freya, Saga, Idunn)
|
||||
**Contains**:
|
||||
- System overview
|
||||
- Folder structure
|
||||
- Complete workflow summary
|
||||
- Key principles
|
||||
- Quick reference
|
||||
- Success metrics
|
||||
|
||||
**Read this**: To understand the complete system
|
||||
|
||||
---
|
||||
|
||||
#### `workflow.md`
|
||||
**Purpose**: Workflow overview with phase navigation
|
||||
**For**: Freya (primary), other agents (reference)
|
||||
**Contains**:
|
||||
- Overview of all phases
|
||||
- Clear links to step files
|
||||
- When to use each phase
|
||||
- What each phase creates
|
||||
|
||||
**Read this**: To understand the workflow structure
|
||||
|
||||
---
|
||||
|
||||
### Step Files
|
||||
|
||||
#### `steps-c/1-prototype-setup.md`
|
||||
**Purpose**: Environment setup instructions
|
||||
**Contains**: Device compatibility, design fidelity, languages, demo data creation
|
||||
**Next**: Phase 2
|
||||
|
||||
---
|
||||
|
||||
#### `steps-c/2-scenario-analysis.md`
|
||||
**Purpose**: Scenario analysis and view identification
|
||||
**Contains**: Spec analysis, logical view mapping
|
||||
**Next**: Phase 3
|
||||
|
||||
---
|
||||
|
||||
#### `steps-c/3-logical-view-breakdown.md`
|
||||
**Purpose**: Break view into implementable sections
|
||||
**Contains**: Section breakdown, work file creation
|
||||
**Next**: Phase 4
|
||||
|
||||
---
|
||||
|
||||
#### `steps-c/4a-4g-*.md` (Phase 4 Loop)
|
||||
**Purpose**: Section-by-section implementation
|
||||
**Contains**: Announce, create story, implement, test, handle feedback, approve
|
||||
**Flow**: 4a → 4b → 4c → 4d → [4e/4f loop] → 4g → [next section]
|
||||
|
||||
---
|
||||
|
||||
#### `steps-c/5-finalization.md`
|
||||
**Purpose**: Integration test and completion
|
||||
**Contains**: Final test, quality checklist, next steps
|
||||
**Next**: New page (Phase 3) or new scenario (Phase 1)
|
||||
|
||||
---
|
||||
|
||||
### Templates
|
||||
|
||||
#### `templates/work-file-template.yaml`
|
||||
**Purpose**: Planning document
|
||||
**When to use**: Start of EVERY implementation
|
||||
**Created**: Once per page at beginning
|
||||
**Contains**:
|
||||
- Metadata (page info, device compatibility)
|
||||
- Design tokens (Tailwind config)
|
||||
- Page requirements (from spec)
|
||||
- Demo data needs
|
||||
- Object ID map
|
||||
- Section breakdown (4-8 sections)
|
||||
- Testing checklist
|
||||
|
||||
**Use this**: To create work file (plan BEFORE coding)
|
||||
|
||||
---
|
||||
|
||||
#### `templates/story-file-template.md`
|
||||
**Purpose**: Section implementation guide
|
||||
**When to use**: Just-in-time (right before implementing each section)
|
||||
**Created**: Once per section (4-8 per page)
|
||||
**Contains**:
|
||||
- Section goal
|
||||
- What to build (HTML/JS)
|
||||
- Tailwind classes to use
|
||||
- Dependencies
|
||||
- Acceptance criteria
|
||||
- Test instructions
|
||||
- Common issues
|
||||
|
||||
**Use this**: To create story file before each section
|
||||
|
||||
---
|
||||
|
||||
#### `templates/page-template.html`
|
||||
**Purpose**: Complete HTML page structure
|
||||
**When to use**: Creating new HTML page
|
||||
**Created**: Once per page (at start of Section 1)
|
||||
**Contains**:
|
||||
- Complete HTML structure
|
||||
- Tailwind CDN setup
|
||||
- Tailwind config inline
|
||||
- Component examples
|
||||
- Shared script includes
|
||||
|
||||
**Use this**: As starting point for new page HTML
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Which File When?
|
||||
|
||||
### Starting New Scenario
|
||||
1. Read: `workflow.md` (understand phases)
|
||||
2. Follow: `steps-c/1-prototype-setup.md` (setup)
|
||||
3. Use: `PROTOTYPE-ROADMAP-template.md` → Create roadmap
|
||||
4. Use: `demo-data-template.json` → Create demo data
|
||||
|
||||
### Starting New Page
|
||||
1. Follow: `steps-c/2-scenario-analysis.md` (analyze)
|
||||
2. Follow: `steps-c/3-logical-view-breakdown.md` (break down)
|
||||
3. Use: `work-file-template.yaml` → Create work file
|
||||
4. Get approval
|
||||
|
||||
### Implementing Each Section
|
||||
1. Follow: `steps-c/4a-4g-*.md` (loop)
|
||||
2. Use: `story-file-template.md` → Create story file (just-in-time)
|
||||
3. Implement in HTML (incrementally)
|
||||
4. Test
|
||||
5. Get approval
|
||||
6. Repeat for next section
|
||||
|
||||
### Finishing Page
|
||||
1. Follow: `steps-c/5-finalization.md` (integration test)
|
||||
2. Get final approval
|
||||
3. Choose: New page, new scenario, or done
|
||||
|
||||
---
|
||||
|
||||
## 📝 Template Usage Summary
|
||||
|
||||
| Template | When Created | How Many | Purpose |
|
||||
|----------|--------------|----------|---------|
|
||||
| work-file | Start of page | 1 per page | Complete plan |
|
||||
| story-file | Before each section | 4-8 per page | Section implementation |
|
||||
| page | Start of Section 1 | 1 per page | HTML structure |
|
||||
| roadmap | Start of scenario | 1 per scenario | Scenario overview |
|
||||
| demo-data | Setup scenario | 1 per scenario | Auto-loading data |
|
||||
|
||||
---
|
||||
|
||||
**All templates and micro-step instructions are ready!**
|
||||
|
||||
Next step: Activate Freya and follow `workflow.md` → `steps-c/1-prototype-setup.md`
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
validationDate: 2026-01-22
|
||||
workflowName: interactive-prototypes
|
||||
workflowPath: c:\dev\WDS\bmad-method-wds-expansion\src\workflows\4-ux-design\interactive-prototypes
|
||||
workflowName: agentic-development
|
||||
workflowPath: c:\dev\WDS\bmad-method-wds-expansion\src\workflows\4-ux-design\agentic-development
|
||||
validationStatus: COMPLETE
|
||||
overallStatus: PASS - FIXED
|
||||
criticalIssues: 2
|
||||
|
|
@ -10,7 +10,7 @@ warnings: 1
|
|||
warningsFixed: 1
|
||||
---
|
||||
|
||||
# Validation Report: Interactive Prototypes
|
||||
# Validation Report: Agentic Development
|
||||
|
||||
**Validation Started:** 2026-01-22
|
||||
**Validator:** Wendy - BMAD Workflow Validation System
|
||||
|
|
@ -30,7 +30,7 @@ warningsFixed: 1
|
|||
### Current Structure
|
||||
|
||||
```
|
||||
interactive-prototypes/
|
||||
agentic-development/
|
||||
├── phases/ ← ❌ Should be steps-c/
|
||||
│ ├── 1-prototype-setup.md (95 lines) ✅
|
||||
│ ├── 2-scenario-analysis.md (174 lines) ✅
|
||||
|
|
@ -46,7 +46,7 @@ interactive-prototypes/
|
|||
├── templates/ (template files) ✅
|
||||
├── CREATION-GUIDE.md (1,148 lines)
|
||||
├── FILE-INDEX.md (365 lines)
|
||||
├── INTERACTIVE-PROTOTYPES-GUIDE.md (380 lines)
|
||||
├── AGENTIC-DEVELOPMENT-GUIDE.md (380 lines)
|
||||
├── PROTOTYPE-ANALYSIS.md (832 lines)
|
||||
├── PROTOTYPE-INITIATION-DIALOG.md (409 lines)
|
||||
└── PROTOTYPE-WORKFLOW.md (137 lines) ← ❌ Should be workflow.md
|
||||
|
|
@ -87,7 +87,7 @@ interactive-prototypes/
|
|||
|
||||
**Current:** Guide files in root folder
|
||||
- CREATION-GUIDE.md
|
||||
- INTERACTIVE-PROTOTYPES-GUIDE.md
|
||||
- AGENTIC-DEVELOPMENT-GUIDE.md
|
||||
- PROTOTYPE-ANALYSIS.md
|
||||
- PROTOTYPE-INITIATION-DIALOG.md
|
||||
- FILE-INDEX.md
|
||||
|
|
@ -147,7 +147,7 @@ interactive-prototypes/
|
|||
**Action:** Move guide files to `guides/` subfolder
|
||||
**Files to move:**
|
||||
- CREATION-GUIDE.md
|
||||
- INTERACTIVE-PROTOTYPES-GUIDE.md
|
||||
- AGENTIC-DEVELOPMENT-GUIDE.md
|
||||
- PROTOTYPE-ANALYSIS.md
|
||||
- PROTOTYPE-INITIATION-DIALOG.md
|
||||
- FILE-INDEX.md
|
||||
|
|
@ -207,7 +207,7 @@ This is a **well-designed workflow** with **structural compliance issues**. The
|
|||
3. ✅ **Organized guides into guides/ subfolder**
|
||||
- Moved 5 guide files:
|
||||
- CREATION-GUIDE.md
|
||||
- INTERACTIVE-PROTOTYPES-GUIDE.md
|
||||
- AGENTIC-DEVELOPMENT-GUIDE.md
|
||||
- PROTOTYPE-ANALYSIS.md
|
||||
- PROTOTYPE-INITIATION-DIALOG.md
|
||||
- FILE-INDEX.md
|
||||
|
|
@ -219,7 +219,7 @@ This is a **well-designed workflow** with **structural compliance issues**. The
|
|||
### New Structure:
|
||||
|
||||
```
|
||||
interactive-prototypes/
|
||||
agentic-development/
|
||||
├── workflow.md (entry point) ✅
|
||||
├── steps-c/ (BMAD v6 compliant) ✅
|
||||
│ ├── 1-prototype-setup.md
|
||||
|
|
@ -236,7 +236,7 @@ interactive-prototypes/
|
|||
├── guides/ (organized documentation) ✅
|
||||
│ ├── CREATION-GUIDE.md
|
||||
│ ├── FILE-INDEX.md
|
||||
│ ├── INTERACTIVE-PROTOTYPES-GUIDE.md
|
||||
│ ├── AGENTIC-DEVELOPMENT-GUIDE.md
|
||||
│ ├── PROTOTYPE-ANALYSIS.md
|
||||
│ └── PROTOTYPE-INITIATION-DIALOG.md
|
||||
└── templates/ (existing templates) ✅
|
||||
|
|
@ -0,0 +1,631 @@
|
|||
---
|
||||
name: Agentic Development
|
||||
description: AI-assisted development for non-technical designers using Agent Dialogs and structured collaboration
|
||||
web_bundle: true
|
||||
---
|
||||
|
||||
# Agentic Development Workflow
|
||||
|
||||
**Goal:** Enable non-technical designers to build production-ready code through structured AI collaboration
|
||||
|
||||
**Your Role:** Implementation partner guiding step-by-step development with clear feedback protocols and approval gates
|
||||
|
||||
---
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
Agentic Development is about **how** you work with AI — not **what** you build.
|
||||
|
||||
Use this workflow to build a prototype, extend a production app, create a new feature, or anything else. The AI handles implementation while you focus on what to build and how it should behave.
|
||||
|
||||
This workflow enables:
|
||||
- ✅ Direct implementation from specifications
|
||||
- ✅ Step-by-step development with approval gates
|
||||
- ✅ Clear feedback protocol with timing guidance
|
||||
- ✅ Agent Dialog structure for context and handoff
|
||||
- ✅ Dynamic planning that adapts as we learn
|
||||
|
||||
**Note:** We use "scenario step" instead of "page" - a step can be a full page, modal, overlay, state change, or any UI change requiring a new sketch.
|
||||
|
||||
---
|
||||
|
||||
## WHEN TO USE
|
||||
|
||||
Use this workflow when:
|
||||
- ✅ Page specifications are complete and approved
|
||||
- ✅ Ready to build working implementations
|
||||
- ✅ Working with AI to develop production-ready code
|
||||
- ✅ Want iterative development with approval gates
|
||||
- ✅ Need structured collaboration with clear feedback handling
|
||||
|
||||
Skip this workflow when:
|
||||
- ❌ Specifications not complete yet
|
||||
- ❌ Still in sketching or wireframe phase
|
||||
- ❌ Simple one-file changes that don't need documentation
|
||||
- ❌ Pure exploration where the path is unclear
|
||||
|
||||
---
|
||||
|
||||
## USER FEEDBACK PROTOCOL
|
||||
|
||||
During development, the designer provides feedback. **CRITICAL: Never implement feedback without first classifying it and stating when it should be addressed.**
|
||||
|
||||
### Feedback Types
|
||||
|
||||
| Type | What It Is | When to Address |
|
||||
|------|------------|-----------------|
|
||||
| **Bug/Issue** | Something broken, error, not working | Now — fix immediately, iterate until resolved |
|
||||
| **Quick Adjustment** | Small tweak, change X to Y | Now — implement immediately |
|
||||
| **Addition** | New requirement that fits current dialog | Later step — add to plan |
|
||||
| **Change Request** | Outside current dialog scope | Future session — document in Change Requests |
|
||||
|
||||
### The 2-Minute Rule (GTD)
|
||||
|
||||
**If a fix takes less than 2 minutes, do it immediately.**
|
||||
|
||||
From David Allen's "Getting Things Done": planning overhead should not exceed task complexity. See [GTD Model](../../../docs/models/gtd-getting-things-done.md).
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Missing condition check | Fix now, log as sub-step |
|
||||
| Wrong variable name | Fix now, log as sub-step |
|
||||
| Needs new component | Add to plan |
|
||||
| Architectural change | Add to plan |
|
||||
|
||||
**Pattern:** Do the fix → Log as sub-step (e.g., 20a-1) → Continue main task
|
||||
|
||||
### Response Flow
|
||||
|
||||
**When user reports something:**
|
||||
|
||||
1. **CLASSIFY** — What type of feedback is this?
|
||||
2. **TIMING** — When should it be addressed?
|
||||
3. **DOCUMENT** — For bugs, add to plan BEFORE fixing
|
||||
4. **CONFIRM** — For additions and change requests, confirm before proceeding
|
||||
5. **EXECUTE** — Implement or document as appropriate
|
||||
|
||||
### Bug/Issue (Document First, Then Fix)
|
||||
|
||||
**User says:** "This is broken" / "Error occurred" / "Not working"
|
||||
|
||||
**Agent response:**
|
||||
```
|
||||
This is a bug — [brief description of issue].
|
||||
Let's call it 10A and let me add it to the plan, then fix it.
|
||||
```
|
||||
|
||||
**Required sequence:**
|
||||
1. **Identify** — Understand and describe the bug clearly
|
||||
2. **Document** — Add to dialog plan as sub-step (e.g., 21a, 21b)
|
||||
3. **Execute** — Fix and iterate until resolved
|
||||
4. **Log** — Record resolution in progress log
|
||||
|
||||
**If user reports multiple issues at once:**
|
||||
1. Identify and list each issue separately
|
||||
2. Add ALL to the plan first
|
||||
3. Then work through them one by one
|
||||
|
||||
**Why document first:** Bugs discovered during implementation are valuable context. Recording them ensures traceability, prevents forgotten fixes, and creates a clear record for handoff.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
User: "The drawer appears behind the overlay and the reassign doesn't work"
|
||||
|
||||
Agent: "I see two issues:
|
||||
1. Drawer z-index (appears behind overlay)
|
||||
2. Reassign not working
|
||||
|
||||
Let me add both to the plan as 21a and 21b, then fix them."
|
||||
```
|
||||
|
||||
### Quick Adjustment (Fix Now)
|
||||
|
||||
**User says:** "Change X to Y" / "Make this button go here" / "Use different color"
|
||||
|
||||
**Agent response:**
|
||||
```
|
||||
Quick adjustment — I'll implement this now.
|
||||
```
|
||||
|
||||
Then implement the change.
|
||||
|
||||
### Addition (Add to Plan)
|
||||
|
||||
**User says:** "We should also add X" / "Don't forget to handle Y"
|
||||
|
||||
**Agent response:**
|
||||
```
|
||||
This is an addition that fits the current dialog.
|
||||
I'll add it to Step {N} for later. Confirm?
|
||||
```
|
||||
|
||||
Then add to the appropriate step or To Do section in the dialog file.
|
||||
|
||||
### Change Request (Document for Later)
|
||||
|
||||
**User says:** "The profile button should go to /family" / "We need a settings page"
|
||||
|
||||
**Agent response:**
|
||||
```
|
||||
This is outside the current dialog scope.
|
||||
It doesn't block {feature name}.
|
||||
|
||||
I'll add it to Change Requests for a future session. Confirm?
|
||||
```
|
||||
|
||||
**WAIT for user confirmation.**
|
||||
|
||||
If user confirms → Add to Change Requests section
|
||||
If user says "do it now" → Treat as quick adjustment and implement
|
||||
|
||||
### Anti-Pattern: What NOT to Do
|
||||
|
||||
**NEVER do this:**
|
||||
|
||||
User: "The profile button should go to /family"
|
||||
Agent: *immediately edits the file*
|
||||
|
||||
**ALWAYS do this:**
|
||||
|
||||
User: "The profile button should go to /family"
|
||||
Agent: "This is outside current scope. I'll add it to Change Requests. Confirm?"
|
||||
User: "Yes" or "No, do it now"
|
||||
*then acts accordingly*
|
||||
|
||||
### Why This Matters
|
||||
|
||||
From experience, skipping the classify-and-timing step leads to:
|
||||
- Agent implementing things the user didn't want
|
||||
- User frustration from lack of visibility
|
||||
- Lost context when user wanted to discuss first
|
||||
- Scope creep pulling focus from current implementation
|
||||
|
||||
The extra seconds to classify and confirm build trust and ensure alignment.
|
||||
|
||||
---
|
||||
|
||||
## SESSION START PROTOCOL
|
||||
|
||||
When starting or resuming a session, **always follow this sequence before implementing anything:**
|
||||
|
||||
### 1. Read the Dialog Document
|
||||
|
||||
```
|
||||
Agent: "Let me read the dialog document to understand where we are."
|
||||
```
|
||||
|
||||
Read the dialog file completely to understand:
|
||||
- What steps are done
|
||||
- What steps remain
|
||||
- Any blockers or change requests
|
||||
- Current context and decisions
|
||||
|
||||
### 2. Verify Plan Against Reality
|
||||
|
||||
**The plan may be outdated.** Check if:
|
||||
- Steps marked "To Do" have actually been implemented
|
||||
- Steps marked "Done" are truly complete
|
||||
- The numbering is sequential and accurate
|
||||
|
||||
```
|
||||
Agent: "I see steps 11-18 in To Do, but let me check the code..."
|
||||
Agent: "These are already implemented. Let me update the plan."
|
||||
```
|
||||
|
||||
If the plan is outdated → Update it before proceeding.
|
||||
|
||||
### 3. Present Current Status
|
||||
|
||||
Summarize for the designer:
|
||||
- What's done (with step numbers)
|
||||
- What's remaining (with step numbers)
|
||||
- Any change requests pending
|
||||
|
||||
```
|
||||
Agent: "Here's where we are:
|
||||
Done: Steps 9b, 10, 11-19
|
||||
To Do: Steps 20, 21
|
||||
Ready to continue?"
|
||||
```
|
||||
|
||||
### 4. Before Implementing a Step
|
||||
|
||||
**Always check the specification/sketches first:**
|
||||
|
||||
```
|
||||
Agent: "Before implementing step 20, let me check the sketches..."
|
||||
Agent: "I see this requires a nested drawer pattern, not inline buttons.
|
||||
Should I break this into sub-steps?"
|
||||
```
|
||||
|
||||
This prevents building the wrong thing and wasting effort.
|
||||
|
||||
### Why This Matters
|
||||
|
||||
Sessions can be interrupted. Context can be lost. The dialog document survives — but only if it's kept accurate. This protocol ensures:
|
||||
- No duplicate work (re-implementing what exists)
|
||||
- No missed work (skipping what's actually needed)
|
||||
- Correct understanding of requirements before implementation
|
||||
|
||||
---
|
||||
|
||||
## EXECUTION PRINCIPLES
|
||||
|
||||
### Document Before Acting
|
||||
|
||||
**Every decision, action, and problem must be documented in the dialog file BEFORE acting on it.**
|
||||
|
||||
This ensures:
|
||||
- Full traceability of what was decided and why
|
||||
- Clean handoff if context is lost or session changes
|
||||
- The dialog document is always the source of truth for progress
|
||||
|
||||
### Sketch Fidelity
|
||||
|
||||
**Implement code as close to the provided sketches as possible.**
|
||||
|
||||
Sketches are intentional design decisions, not loose suggestions. Text sizes, proportions, spacing, and layout choices are made for a reason:
|
||||
|
||||
| Element | Approach |
|
||||
|---------|----------|
|
||||
| **Text sizes** | Match relative sizes in sketch (headings vs body vs labels) |
|
||||
| **Proportions** | Preserve ratios between elements |
|
||||
| **Spacing** | Maintain visual rhythm and whitespace |
|
||||
| **Layout** | Follow the arrangement precisely |
|
||||
| **Component style** | Match the visual pattern (pills, cards, buttons) |
|
||||
|
||||
**When in doubt:**
|
||||
1. Ask the designer for clarification
|
||||
2. Reference the sketch directly in your question
|
||||
3. Don't assume "close enough" is acceptable
|
||||
|
||||
**If constraints make exact matching impossible** (e.g., responsive behavior, platform limitations), document the deviation and explain why.
|
||||
|
||||
### Sub-Steps During Execution
|
||||
|
||||
While working on a step, you may discover additional tasks needed. Add these as sub-steps:
|
||||
|
||||
```markdown
|
||||
| # | Section | Status | Notes |
|
||||
|---|---------|--------|-------|
|
||||
| 14 | Book It Button | ✅ | Complete |
|
||||
| 14a | Fix button alignment | ✅ | Added during 14 |
|
||||
| 14b | Add loading state | ✅ | Added during 14 |
|
||||
| 15 | Cancel Button | 🔄 | In progress |
|
||||
```
|
||||
|
||||
Sub-steps use letter suffixes (14a, 14b) to maintain the parent step's position.
|
||||
|
||||
### Dynamic Planning After Step Completion
|
||||
|
||||
**After completing each step, review and adjust the plan:**
|
||||
|
||||
1. **Review remaining steps** — Are they still accurate?
|
||||
2. **Shuffle if needed** — Reorder based on what we learned
|
||||
3. **Add new steps** — If implementation revealed new requirements
|
||||
4. **Remove steps** — If no longer needed
|
||||
5. **Update the dialog file** — Document the changes
|
||||
|
||||
**Numbering Rules:**
|
||||
- **Completed steps:** Fixed numbering (never renumber)
|
||||
- **Future steps:** Dynamic numbering (can change)
|
||||
|
||||
Example:
|
||||
```markdown
|
||||
### Done
|
||||
| 9b | Carousel Refactor | ✅ | ← Fixed, never changes
|
||||
| 10 | Deep Linking | ✅ | ← Fixed
|
||||
|
||||
### To Do
|
||||
| 11 | Wire up handlers | 🔲 | ← Can be renumbered
|
||||
| 12 | Add poop toggle | 🔲 | ← Can be removed or moved
|
||||
| 13 | NEW: Error states | 🔲 | ← Can be inserted
|
||||
```
|
||||
|
||||
### Handoff Always References Dialog
|
||||
|
||||
**Any handoff — to a new session, new agent, or human — MUST reference the dialog document.**
|
||||
|
||||
The dialog document is the single source of truth for:
|
||||
- What has been done
|
||||
- What decisions were made
|
||||
- What remains to be done
|
||||
- Any issues or blockers
|
||||
|
||||
Never hand off by describing the task verbally. Always point to the dialog.
|
||||
|
||||
### Plan-then-Execute Pattern
|
||||
|
||||
**Separate planning from execution into distinct sessions.**
|
||||
|
||||
Context windows are finite. Long sessions accumulate noise and risk context loss mid-implementation. The solution: end planning sessions deliberately, start execution sessions fresh.
|
||||
|
||||
**Planning Session:**
|
||||
1. Explore the codebase and requirements
|
||||
2. Discuss approach with the designer
|
||||
3. Write the plan to the dialog file
|
||||
4. End with a clear handoff: *"The plan is documented. Hasta la vista!"*
|
||||
|
||||
**Execution Session:**
|
||||
1. Start fresh (new conversation)
|
||||
2. Read the product brief for overall context
|
||||
3. Read the page specification for requirements
|
||||
4. Read the dialog document to understand the plan and progress
|
||||
5. Execute the steps one by one
|
||||
|
||||
**Why This Works:**
|
||||
- Fresh context window for execution = maximum working memory
|
||||
- Dialog document carries all decisions and context forward
|
||||
- No risk of context loss mid-implementation
|
||||
- Each session has a clear, focused purpose
|
||||
|
||||
**When to Split:**
|
||||
- After complex exploration or analysis
|
||||
- When the plan is complete and approved
|
||||
- When current session is getting long
|
||||
- Before starting a major implementation phase
|
||||
|
||||
**The Dialog is the Bridge:**
|
||||
```
|
||||
┌─────────────────────┐ Dialog ┌─────────────────────┐
|
||||
│ PLANNING SESSION │─────File────▶│ EXECUTION SESSION │
|
||||
│ │ │ │
|
||||
│ • Explore codebase │ │ • Fresh context │
|
||||
│ • Discuss approach │ │ • Read brief + spec │
|
||||
│ • Write plan │ │ • Read dialog │
|
||||
│ • "Hasta la vista!" │ │ • Execute steps │
|
||||
└─────────────────────┘ └─────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **multi-phase architecture** with iterative loops:
|
||||
|
||||
### Phase Structure
|
||||
|
||||
**Sequential Phases (1-3, 5):** Setup → Analysis → Selection → Finalization
|
||||
|
||||
**Iterative Phase (4):** Section implementation loop with 7 micro-tasks
|
||||
|
||||
### Critical Rules
|
||||
|
||||
- 🎯 **ALWAYS** complete Phase 1 setup before starting
|
||||
- 📊 **ALWAYS** analyze scenario before selecting views
|
||||
- 🔁 **ALWAYS** use section-by-section approach (Phase 4 loop)
|
||||
- ✅ **ALWAYS** get approval before moving to next section
|
||||
- 📝 **ALWAYS** create story files just-in-time (not upfront)
|
||||
|
||||
---
|
||||
|
||||
## THE 5 PHASES
|
||||
|
||||
### Phase 1: Prototype Setup
|
||||
**When:** Starting new scenario prototype (one-time per scenario)
|
||||
|
||||
**What:** Set up prototype environment and folder structure
|
||||
|
||||
**Creates:**
|
||||
- Prototype folder with complete structure
|
||||
- Demo data files
|
||||
- Roadmap document
|
||||
- All working folders (work/, stories/, shared/, components/, etc.)
|
||||
|
||||
**Go to:** [steps-c/1-prototype-setup.md](steps-c/1-prototype-setup.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Scenario Analysis
|
||||
**When:** Setup complete, ready to start building (one-time per scenario)
|
||||
|
||||
**What:** Analyze all scenario steps and identify logical views
|
||||
|
||||
**Creates:**
|
||||
- Logical View Map (maps steps to views)
|
||||
- View identification and relationships
|
||||
|
||||
**Go to:** [steps-c/2-scenario-analysis.md](steps-c/2-scenario-analysis.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Logical View Selection & Breakdown
|
||||
**When:** User selects which logical view to build (per view)
|
||||
|
||||
**What:** Identify all objects and break view into sections
|
||||
|
||||
**Creates:**
|
||||
- Work file with section breakdown
|
||||
- Implementation sequence
|
||||
|
||||
**Go to:** [steps-c/3-logical-view-breakdown.md](steps-c/3-logical-view-breakdown.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Section Story & Implementation Loop
|
||||
**When:** Ready to build sections (iterative per section)
|
||||
|
||||
**What:** For each section - prepare, create story, implement, test, handle feedback, approve
|
||||
|
||||
**The 7 Micro-Tasks:**
|
||||
|
||||
1. **[4a: Announce & Gather](steps-c/4a-announce-and-gather.md)**
|
||||
- Announce section and gather requirements
|
||||
|
||||
2. **[4b: Create Story File](steps-c/4b-create-story-file.md)**
|
||||
- Create focused story file for this section
|
||||
|
||||
3. **[4c: Implement Section](steps-c/4c-implement-section.md)**
|
||||
- Implement code following story
|
||||
|
||||
4. **[4d: Present for Testing](steps-c/4d-present-for-testing.md)**
|
||||
- Present to user with test instructions
|
||||
|
||||
5. **[4e: Handle Issue](steps-c/4e-handle-issue.md)**
|
||||
- Fix issues if user reports problems (loop back to 4d)
|
||||
|
||||
6. **[4f: Handle Improvement](steps-c/4f-handle-improvement.md)**
|
||||
- Implement improvements if user suggests (loop back to 4d)
|
||||
|
||||
7. **[4g: Section Approved](steps-c/4g-section-approved.md)**
|
||||
- Finalize approval and move to next section (back to 4a)
|
||||
|
||||
**Flow:** 4a → 4b → 4c → 4d → [4e or 4f if needed, loops to 4d] → 4g → [back to 4a for next section]
|
||||
|
||||
**Creates (per section):**
|
||||
- Story file (just-in-time)
|
||||
- Incremental updates to view HTML
|
||||
- Learnings captured
|
||||
|
||||
**Key:** One clear task per file → No confusion → Linear execution → Better results!
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Finalization
|
||||
**When:** All sections complete for a logical view (end of view)
|
||||
|
||||
**What:** Integration test all states and final approval
|
||||
|
||||
**Result:** Production-ready logical view handling all its states
|
||||
|
||||
**Go to:** [steps-c/5-finalization.md](steps-c/5-finalization.md)
|
||||
|
||||
---
|
||||
|
||||
## INITIALIZATION
|
||||
|
||||
### Guide References
|
||||
|
||||
**Process Guides:**
|
||||
- [AGENTIC-DEVELOPMENT-GUIDE.md](guides/AGENTIC-DEVELOPMENT-GUIDE.md) - Overview and methodology
|
||||
- [CREATION-GUIDE.md](guides/CREATION-GUIDE.md) - Technical implementation details
|
||||
- [PROTOTYPE-INITIATION-DIALOG.md](guides/PROTOTYPE-INITIATION-DIALOG.md) - Conversation scripts
|
||||
- [PROTOTYPE-ANALYSIS.md](guides/PROTOTYPE-ANALYSIS.md) - Quality standards
|
||||
- [FILE-INDEX.md](guides/FILE-INDEX.md) - Complete file reference
|
||||
|
||||
**Templates:**
|
||||
- templates/work-file-template.yaml
|
||||
- templates/story-file-template.md
|
||||
- templates/page-template.html
|
||||
- templates/components/dev-mode.*
|
||||
|
||||
### First Step Execution
|
||||
|
||||
Load, read and execute `steps-c/1-prototype-setup.md` to begin workflow.
|
||||
|
||||
---
|
||||
|
||||
## OUTPUT
|
||||
|
||||
**Per Scenario:**
|
||||
```
|
||||
[Scenario-Number]-[Scenario-Name]-Prototype/
|
||||
├── [View].html files (in root, one per logical view)
|
||||
├── shared/ (ONE COPY of shared code)
|
||||
├── components/ (ONE COPY of reusable components)
|
||||
├── pages/ (page-specific scripts if complex)
|
||||
├── data/ (demo data JSON files)
|
||||
├── stories/ (section development files - created just-in-time)
|
||||
├── work/ (planning files)
|
||||
└── PROTOTYPE-ROADMAP.md
|
||||
```
|
||||
|
||||
**Result:** Self-contained, production-ready interactive prototypes with:
|
||||
- Clean HTML using Tailwind CSS
|
||||
- Vanilla JavaScript components
|
||||
- Demo data auto-loading
|
||||
- All states implemented and tested
|
||||
|
||||
---
|
||||
|
||||
## PROTOTYPE FOLDER STRUCTURE
|
||||
|
||||
```
|
||||
[Scenario-Number]-[Scenario-Name]-Prototype/
|
||||
├── [Page].html files ← Logical view HTML files (root)
|
||||
├── shared/ ← ONE COPY of shared code
|
||||
├── components/ ← ONE COPY of reusable components
|
||||
├── pages/ ← Page-specific scripts (if complex)
|
||||
├── data/ ← Demo data JSON files
|
||||
├── stories/ ← Section development files (JIT)
|
||||
├── work/ ← Planning files
|
||||
│ ├── Logical-View-Map.md ← Maps steps to views
|
||||
│ └── [View]-Work.yaml ← Section breakdowns per view
|
||||
└── PROTOTYPE-ROADMAP.md ← Overall roadmap
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ITERATIVE WORKFLOW
|
||||
|
||||
**Phase 1-2:** One-time setup and analysis per scenario
|
||||
|
||||
**Phase 3:** Repeat for each logical view in scenario
|
||||
|
||||
**Phase 4:** Repeat for each section in current view
|
||||
- Inner loop: Repeat 4d-4e-4f until approved
|
||||
|
||||
**Phase 5:** Repeat for each logical view (finalization)
|
||||
|
||||
**Pattern:**
|
||||
```
|
||||
Setup → Analysis → [View Selection → [Section Loop*] → Finalization]*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## EXAMPLES
|
||||
|
||||
**Typical Scenarios:**
|
||||
|
||||
1. **E-commerce Checkout:** 5 views (cart, shipping, payment, review, confirmation)
|
||||
2. **SaaS Onboarding:** 4 views (signup, profile, preferences, dashboard)
|
||||
3. **Booking System:** 6 views (search, select, details, confirm, payment, confirmation)
|
||||
|
||||
Each view breaks into 3-8 sections depending on complexity.
|
||||
|
||||
---
|
||||
|
||||
## QUALITY PRINCIPLES
|
||||
|
||||
**Section-by-Section Approval:** Never implement entire view at once - break into sections with approval gates
|
||||
|
||||
**Just-In-Time Stories:** Create story files only when needed (4b), not upfront
|
||||
|
||||
**Incremental Implementation:** Each section builds on previous approved sections
|
||||
|
||||
**Demo Data:** Use realistic demo data for testing and validation
|
||||
|
||||
**Self-Contained:** Each prototype folder is complete and portable
|
||||
|
||||
---
|
||||
|
||||
## TROUBLESHOOTING
|
||||
|
||||
**Issue:** User feedback requires rework
|
||||
**Solution:** Use Phase 4e (issues) or 4f (improvements) to handle, then loop back to 4d
|
||||
|
||||
**Issue:** Section too complex
|
||||
**Solution:** Break down further in Phase 3 before starting Phase 4
|
||||
|
||||
**Issue:** Logical view unclear
|
||||
**Solution:** Revisit Phase 2 analysis to refine view mapping
|
||||
|
||||
---
|
||||
|
||||
## NOTES
|
||||
|
||||
This workflow enables **non-technical designers to build with AI** — whether that's:
|
||||
- A quick prototype for user testing
|
||||
- New features in an existing production app
|
||||
- A complete application from scratch
|
||||
|
||||
The methodology stays the same:
|
||||
- Step-by-step with approval gates
|
||||
- Clear feedback protocol ensures alignment
|
||||
- Agent Dialogs provide structure and traceability
|
||||
- AI handles implementation, designer focuses on what and how
|
||||
|
||||
---
|
||||
|
||||
_Agentic Development - AI-assisted development for non-technical designers_
|
||||
|
|
@ -1,365 +0,0 @@
|
|||
# Interactive Prototypes - File Index
|
||||
|
||||
**Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/`
|
||||
|
||||
---
|
||||
|
||||
## 📁 Complete File Structure
|
||||
|
||||
```
|
||||
interactive-prototypes/
|
||||
│
|
||||
├── INTERACTIVE-PROTOTYPES-GUIDE.md ← START HERE (overview & quick reference)
|
||||
├── PROTOTYPE-WORKFLOW.md ← Workflow overview with phase links
|
||||
├── PROTOTYPE-INITIATION-DIALOG.md ← Conversation scripts for initiation
|
||||
├── CREATION-GUIDE.md ← Original detailed guide (reference)
|
||||
├── PROTOTYPE-ANALYSIS.md ← Dog Week analysis (examples)
|
||||
│
|
||||
├── phases/ ← Micro-step workflow files
|
||||
│ ├── 1-prototype-setup.md ← Phase 1: Prototype environment setup
|
||||
│ ├── 2-per-page-planning.md ← Phase 2: Analyze spec & create work file
|
||||
│ ├── 3-section-implementation.md ← Phase 3: Build section-by-section
|
||||
│ └── 4-finalization.md ← Phase 4: Integration test & approval
|
||||
│
|
||||
├── templates/
|
||||
│ ├── work-file-template.yaml ← Planning document template
|
||||
│ ├── story-file-template.md ← Section implementation template
|
||||
│ ├── page-template.html ← Complete HTML page template
|
||||
│ ├── PROTOTYPE-ROADMAP-template.md ← Scenario roadmap template
|
||||
│ ├── demo-data-template.json ← Demo data structure template
|
||||
│ └── components/
|
||||
│ ├── dev-mode.html ← Dev mode toggle button
|
||||
│ ├── dev-mode.js ← Dev mode logic (Shift+Click to copy IDs)
|
||||
│ ├── dev-mode.css ← Dev mode styles
|
||||
│ └── DEV-MODE-GUIDE.md ← Dev mode usage guide
|
||||
│
|
||||
└── examples/
|
||||
└── (Dog Week prototypes as reference)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 What Each File Does
|
||||
|
||||
### Core Documentation
|
||||
|
||||
#### `INTERACTIVE-PROTOTYPES-GUIDE.md`
|
||||
**Purpose**: Complete system overview
|
||||
**For**: All agents (Freya, Saga, Idunn)
|
||||
**Contains**:
|
||||
- System overview
|
||||
- Folder structure
|
||||
- Complete workflow summary
|
||||
- Key principles
|
||||
- Quick reference
|
||||
- Success metrics
|
||||
|
||||
**Read this**: To understand the complete system
|
||||
|
||||
---
|
||||
|
||||
#### `PROTOTYPE-WORKFLOW.md`
|
||||
**Purpose**: Workflow overview with phase navigation
|
||||
**For**: Freya (primary), other agents (reference)
|
||||
**Contains**:
|
||||
- Overview of all 4 phases
|
||||
- Clear links to phase-specific files
|
||||
- When to use each phase
|
||||
- What each phase creates
|
||||
|
||||
**Read this**: To understand the workflow structure
|
||||
|
||||
---
|
||||
|
||||
#### `phases/1-prototype-setup.md`
|
||||
**Purpose**: Prototype environment setup instructions
|
||||
**Contains**: Device compatibility, design fidelity, languages, demo data creation
|
||||
**Next**: Phase 2
|
||||
|
||||
---
|
||||
|
||||
#### `phases/2-per-page-planning.md`
|
||||
**Purpose**: Page analysis and work file creation
|
||||
**Contains**: Spec analysis, section breakdown, work file creation
|
||||
**Next**: Phase 3
|
||||
|
||||
---
|
||||
|
||||
#### `phases/3-section-implementation.md`
|
||||
**Purpose**: Section-by-section building
|
||||
**Contains**: Story creation, implementation, testing, approval loop
|
||||
**Next**: Phase 4 or repeat for next section
|
||||
|
||||
---
|
||||
|
||||
#### `phases/4-finalization.md`
|
||||
**Purpose**: Integration test and completion
|
||||
**Contains**: Final test, quality checklist, next steps
|
||||
**Next**: New page (Phase 2) or new scenario (Phase 1)
|
||||
|
||||
---
|
||||
|
||||
#### `PROTOTYPE-INITIATION-DIALOG.md`
|
||||
**Purpose**: Conversation scripts for initiation
|
||||
**For**: Freya (exact scripts to follow)
|
||||
**Contains**:
|
||||
- Scenario initiation questions
|
||||
- Per-page section breakdown prompts
|
||||
- Example complete exchange
|
||||
|
||||
**Read this**: For exact conversation patterns
|
||||
|
||||
---
|
||||
|
||||
#### `CREATION-GUIDE.md`
|
||||
**Purpose**: Original detailed guide
|
||||
**For**: Deep dives, specific techniques
|
||||
**Contains**:
|
||||
- Detailed file structure explanations
|
||||
- Step-by-step creation process
|
||||
- Component patterns
|
||||
- Testing strategies
|
||||
- Common patterns library
|
||||
|
||||
**Read this**: For detailed technical reference
|
||||
|
||||
---
|
||||
|
||||
#### `PROTOTYPE-ANALYSIS.md`
|
||||
**Purpose**: Dog Week case study
|
||||
**For**: Learning from examples
|
||||
**Contains**:
|
||||
- Analysis of Dog Week prototypes
|
||||
- What works well
|
||||
- Patterns to follow
|
||||
- Lessons learned
|
||||
- Quality metrics
|
||||
|
||||
**Read this**: To see real-world examples
|
||||
|
||||
---
|
||||
|
||||
### Templates
|
||||
|
||||
#### `templates/work-file-template.yaml`
|
||||
**Purpose**: Planning document
|
||||
**When to use**: Start of EVERY prototype
|
||||
**Created**: Once per page at beginning
|
||||
**Contains**:
|
||||
- Metadata (page info, device compatibility)
|
||||
- Design tokens (Tailwind config)
|
||||
- Page requirements (from spec)
|
||||
- Demo data needs
|
||||
- Object ID map
|
||||
- Section breakdown (4-8 sections)
|
||||
- Testing checklist
|
||||
|
||||
**Use this**: To create work file (plan BEFORE coding)
|
||||
|
||||
---
|
||||
|
||||
#### `templates/story-file-template.md`
|
||||
**Purpose**: Section implementation guide
|
||||
**When to use**: Just-in-time (right before implementing each section)
|
||||
**Created**: Once per section (4-8 per page)
|
||||
**Contains**:
|
||||
- Section goal
|
||||
- What to build (HTML/JS)
|
||||
- Tailwind classes to use
|
||||
- Dependencies
|
||||
- Acceptance criteria
|
||||
- Test instructions
|
||||
- Common issues
|
||||
|
||||
**Use this**: To create story file before each section
|
||||
|
||||
---
|
||||
|
||||
#### `templates/page-template.html`
|
||||
**Purpose**: Complete HTML page structure
|
||||
**When to use**: Creating new HTML page
|
||||
**Created**: Once per page (at start of Section 1)
|
||||
**Contains**:
|
||||
- Complete HTML structure
|
||||
- Tailwind CDN setup
|
||||
- Tailwind config inline
|
||||
- Header example
|
||||
- Form examples (input, textarea, split button)
|
||||
- Submit button with loading state
|
||||
- Toast notification
|
||||
- Error banner
|
||||
- Modal example (commented)
|
||||
- Shared script includes
|
||||
- Inline JavaScript template
|
||||
|
||||
**Use this**: As starting point for new page HTML
|
||||
|
||||
---
|
||||
|
||||
#### `templates/PROTOTYPE-ROADMAP-template.md`
|
||||
**Purpose**: Scenario overview document
|
||||
**When to use**: Start of scenario development
|
||||
**Created**: Once per scenario
|
||||
**Contains**:
|
||||
- Scenario overview
|
||||
- Device compatibility details
|
||||
- Folder structure explanation
|
||||
- Shared resources documentation
|
||||
- Component documentation
|
||||
- Prototype status table
|
||||
- Testing requirements
|
||||
- Troubleshooting guide
|
||||
|
||||
**Use this**: To create roadmap for scenario
|
||||
|
||||
---
|
||||
|
||||
#### `templates/demo-data-template.json`
|
||||
**Purpose**: Demo data structure
|
||||
**When to use**: Setting up scenario demo data
|
||||
**Created**: Once per scenario (modify as needed)
|
||||
**Contains**:
|
||||
- User object
|
||||
- Family object
|
||||
- Members array
|
||||
- Dogs array (or other entities)
|
||||
- All fields with examples
|
||||
|
||||
**Use this**: To create demo-data.json file
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Which File When?
|
||||
|
||||
### Starting New Scenario
|
||||
1. Read: `PROTOTYPE-WORKFLOW.md` (understand phases)
|
||||
2. Follow: `phases/1-prototype-setup.md` (setup)
|
||||
3. Use: `PROTOTYPE-ROADMAP-template.md` → Create roadmap
|
||||
4. Use: `demo-data-template.json` → Create demo data
|
||||
|
||||
### Starting New Page
|
||||
1. Follow: `phases/2-per-page-planning.md` (analyze)
|
||||
2. Use: `work-file-template.yaml` → Create work file
|
||||
3. Get approval
|
||||
4. Follow: `phases/3-section-implementation.md`
|
||||
|
||||
### Implementing Each Section
|
||||
1. Follow: `phases/3-section-implementation.md` (loop)
|
||||
2. Use: `story-file-template.md` → Create story file (just-in-time)
|
||||
3. Implement in HTML (incrementally)
|
||||
4. Test
|
||||
5. Get approval
|
||||
6. Repeat for next section
|
||||
|
||||
### Finishing Page
|
||||
1. Follow: `phases/4-finalization.md` (integration test)
|
||||
2. Get final approval
|
||||
3. Choose: New page, new scenario, or done
|
||||
|
||||
### Need Help
|
||||
1. Check: `PROTOTYPE-WORKFLOW.md` (phase overview)
|
||||
2. Check: `phases/[N]-*.md` (specific phase)
|
||||
3. Check: `CREATION-GUIDE.md` (detailed reference)
|
||||
4. Check: `PROTOTYPE-ANALYSIS.md` (examples)
|
||||
|
||||
---
|
||||
|
||||
## 📊 File Relationships
|
||||
|
||||
```
|
||||
PROTOTYPE-WORKFLOW.md (overview)
|
||||
├─ phases/1-prototype-setup.md
|
||||
├─ phases/2-per-page-planning.md
|
||||
├─ phases/3-section-implementation.md
|
||||
└─ phases/4-finalization.md
|
||||
|
||||
PROTOTYPE-INITIATION-DIALOG.md
|
||||
└─ Referenced by: phases/1-prototype-setup.md (conversation scripts)
|
||||
|
||||
work-file-template.yaml
|
||||
└─ Used in: phases/2-per-page-planning.md
|
||||
└─ Each section becomes: story-file-template.md (later)
|
||||
|
||||
story-file-template.md
|
||||
└─ Used in: phases/3-section-implementation.md (just-in-time)
|
||||
└─ Guides: Implementation in HTML
|
||||
|
||||
page-template.html
|
||||
└─ Used in: phases/3-section-implementation.md (Section 1 only)
|
||||
└─ Modified: Section by section
|
||||
|
||||
PROTOTYPE-ROADMAP-template.md
|
||||
└─ Used in: phases/1-scenario-init.md
|
||||
└─ Updated: As prototypes complete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start Paths
|
||||
|
||||
### Path 1: I want to understand the system
|
||||
1. `INTERACTIVE-PROTOTYPES-GUIDE.md` (overview)
|
||||
2. `PROTOTYPE-WORKFLOW.md` (workflow phases)
|
||||
3. `PROTOTYPE-ANALYSIS.md` (examples)
|
||||
|
||||
### Path 2: I want to create my first prototype
|
||||
1. `PROTOTYPE-WORKFLOW.md` (start here)
|
||||
2. `phases/1-prototype-setup.md` (follow step-by-step)
|
||||
3. `phases/2-per-page-planning.md` (next)
|
||||
4. `phases/3-section-implementation.md` (build loop)
|
||||
5. `phases/4-finalization.md` (finish)
|
||||
|
||||
### Path 3: I need specific technical details
|
||||
1. `CREATION-GUIDE.md` (detailed techniques)
|
||||
2. `PROTOTYPE-ANALYSIS.md` (real examples)
|
||||
3. `page-template.html` (code examples)
|
||||
|
||||
### Path 4: I'm stuck on something
|
||||
1. `phases/[current-phase].md` (specific phase help)
|
||||
2. `CREATION-GUIDE.md` → Common Pitfalls section
|
||||
3. `templates/components/DEV-MODE-GUIDE.md` (if dev mode issue)
|
||||
|
||||
---
|
||||
|
||||
## 📝 Template Usage Summary
|
||||
|
||||
| Template | When Created | How Many | Purpose |
|
||||
|----------|--------------|----------|---------|
|
||||
| work-file | Start of page | 1 per page | Complete plan |
|
||||
| story-file | Before each section | 4-8 per page | Section implementation |
|
||||
| page | Start of Section 1 | 1 per page | HTML structure |
|
||||
| roadmap | Start of scenario | 1 per scenario | Scenario overview |
|
||||
| demo-data | Setup scenario | 1 per scenario | Auto-loading data |
|
||||
|
||||
---
|
||||
|
||||
## ✅ Checklist: Do I Have Everything?
|
||||
|
||||
**For Freya to create prototypes**:
|
||||
- [x] `INTERACTIVE-PROTOTYPES-GUIDE.md` (overview)
|
||||
- [x] `PROTOTYPE-WORKFLOW.md` (workflow overview)
|
||||
- [x] `phases/1-prototype-setup.md` (Phase 1)
|
||||
- [x] `phases/2-per-page-planning.md` (Phase 2)
|
||||
- [x] `phases/3-section-implementation.md` (Phase 3)
|
||||
- [x] `phases/4-finalization.md` (Phase 4)
|
||||
- [x] `PROTOTYPE-INITIATION-DIALOG.md` (conversation scripts)
|
||||
- [x] `work-file-template.yaml`
|
||||
- [x] `story-file-template.md`
|
||||
- [x] `page-template.html`
|
||||
- [x] `PROTOTYPE-ROADMAP-template.md`
|
||||
- [x] `demo-data-template.json`
|
||||
- [x] `templates/components/dev-mode.*` (dev mode feature)
|
||||
|
||||
**For learning**:
|
||||
- [x] `CREATION-GUIDE.md` (detailed)
|
||||
- [x] `PROTOTYPE-ANALYSIS.md` (examples)
|
||||
|
||||
**For reference**:
|
||||
- [x] Dog Week examples (real prototypes)
|
||||
|
||||
---
|
||||
|
||||
**All templates and micro-step instructions are ready!** 🎉
|
||||
|
||||
Next step: Activate Freya and follow `PROTOTYPE-WORKFLOW.md` → `phases/1-prototype-setup.md`
|
||||
|
||||
|
|
@ -1,290 +0,0 @@
|
|||
---
|
||||
name: Interactive Prototypes
|
||||
description: Create production-ready interactive prototypes using phased section-by-section implementation
|
||||
web_bundle: true
|
||||
---
|
||||
|
||||
# Interactive Prototypes Workflow
|
||||
|
||||
**Goal:** Build self-contained, production-ready interactive prototypes from UX specifications
|
||||
|
||||
**Your Role:** Implementation facilitator guiding section-by-section prototype development with approval gates
|
||||
|
||||
---
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
This workflow creates interactive prototypes using:
|
||||
- ✅ Tailwind CSS (no separate CSS files)
|
||||
- ✅ Vanilla JavaScript (components in shared folders)
|
||||
- ✅ Section-by-section implementation (approval gates)
|
||||
- ✅ Just-in-time story files (created as needed)
|
||||
- ✅ Demo data auto-loading
|
||||
|
||||
**Note:** We use "scenario step" instead of "page" - a step can be a full page, modal, overlay, state change, or any UI change requiring a new sketch.
|
||||
|
||||
---
|
||||
|
||||
## WHEN TO USE
|
||||
|
||||
Use this workflow when:
|
||||
- ✅ Page specifications are complete and approved
|
||||
- ✅ Ready to build working interactive prototypes
|
||||
- ✅ Need production-ready HTML/CSS/JS implementations
|
||||
- ✅ Want iterative development with approval gates
|
||||
|
||||
Skip this workflow when:
|
||||
- ❌ Specifications not complete yet
|
||||
- ❌ Still in sketching or wireframe phase
|
||||
- ❌ Using different prototyping tools (Figma, Adobe XD)
|
||||
- ❌ Building final production code (this is prototype stage)
|
||||
|
||||
---
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **multi-phase architecture** with iterative loops:
|
||||
|
||||
### Phase Structure
|
||||
|
||||
**Sequential Phases (1-3, 5):** Setup → Analysis → Selection → Finalization
|
||||
|
||||
**Iterative Phase (4):** Section implementation loop with 7 micro-tasks
|
||||
|
||||
### Critical Rules
|
||||
|
||||
- 🎯 **ALWAYS** complete Phase 1 setup before starting
|
||||
- 📊 **ALWAYS** analyze scenario before selecting views
|
||||
- 🔁 **ALWAYS** use section-by-section approach (Phase 4 loop)
|
||||
- ✅ **ALWAYS** get approval before moving to next section
|
||||
- 📝 **ALWAYS** create story files just-in-time (not upfront)
|
||||
|
||||
---
|
||||
|
||||
## THE 5 PHASES
|
||||
|
||||
### Phase 1: Prototype Setup
|
||||
**When:** Starting new scenario prototype (one-time per scenario)
|
||||
|
||||
**What:** Set up prototype environment and folder structure
|
||||
|
||||
**Creates:**
|
||||
- Prototype folder with complete structure
|
||||
- Demo data files
|
||||
- Roadmap document
|
||||
- All working folders (work/, stories/, shared/, components/, etc.)
|
||||
|
||||
**Go to:** [steps-c/1-prototype-setup.md](steps-c/1-prototype-setup.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Scenario Analysis
|
||||
**When:** Setup complete, ready to start building (one-time per scenario)
|
||||
|
||||
**What:** Analyze all scenario steps and identify logical views
|
||||
|
||||
**Creates:**
|
||||
- Logical View Map (maps steps to views)
|
||||
- View identification and relationships
|
||||
|
||||
**Go to:** [steps-c/2-scenario-analysis.md](steps-c/2-scenario-analysis.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Logical View Selection & Breakdown
|
||||
**When:** User selects which logical view to build (per view)
|
||||
|
||||
**What:** Identify all objects and break view into sections
|
||||
|
||||
**Creates:**
|
||||
- Work file with section breakdown
|
||||
- Implementation sequence
|
||||
|
||||
**Go to:** [steps-c/3-logical-view-breakdown.md](steps-c/3-logical-view-breakdown.md)
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Section Story & Implementation Loop
|
||||
**When:** Ready to build sections (iterative per section)
|
||||
|
||||
**What:** For each section - prepare, create story, implement, test, handle feedback, approve
|
||||
|
||||
**The 7 Micro-Tasks:**
|
||||
|
||||
1. **[4a: Announce & Gather](steps-c/4a-announce-and-gather.md)**
|
||||
- Announce section and gather requirements
|
||||
|
||||
2. **[4b: Create Story File](steps-c/4b-create-story-file.md)**
|
||||
- Create focused story file for this section
|
||||
|
||||
3. **[4c: Implement Section](steps-c/4c-implement-section.md)**
|
||||
- Implement code following story
|
||||
|
||||
4. **[4d: Present for Testing](steps-c/4d-present-for-testing.md)**
|
||||
- Present to user with test instructions
|
||||
|
||||
5. **[4e: Handle Issue](steps-c/4e-handle-issue.md)**
|
||||
- Fix issues if user reports problems (loop back to 4d)
|
||||
|
||||
6. **[4f: Handle Improvement](steps-c/4f-handle-improvement.md)**
|
||||
- Implement improvements if user suggests (loop back to 4d)
|
||||
|
||||
7. **[4g: Section Approved](steps-c/4g-section-approved.md)**
|
||||
- Finalize approval and move to next section (back to 4a)
|
||||
|
||||
**Flow:** 4a → 4b → 4c → 4d → [4e or 4f if needed, loops to 4d] → 4g → [back to 4a for next section]
|
||||
|
||||
**Creates (per section):**
|
||||
- Story file (just-in-time)
|
||||
- Incremental updates to view HTML
|
||||
- Learnings captured
|
||||
|
||||
**Key:** One clear task per file → No confusion → Linear execution → Better results!
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Finalization
|
||||
**When:** All sections complete for a logical view (end of view)
|
||||
|
||||
**What:** Integration test all states and final approval
|
||||
|
||||
**Result:** Production-ready logical view handling all its states
|
||||
|
||||
**Go to:** [steps-c/5-finalization.md](steps-c/5-finalization.md)
|
||||
|
||||
---
|
||||
|
||||
## INITIALIZATION
|
||||
|
||||
### Guide References
|
||||
|
||||
**Process Guides:**
|
||||
- [INTERACTIVE-PROTOTYPES-GUIDE.md](guides/INTERACTIVE-PROTOTYPES-GUIDE.md) - Overview and methodology
|
||||
- [CREATION-GUIDE.md](guides/CREATION-GUIDE.md) - Technical implementation details
|
||||
- [PROTOTYPE-INITIATION-DIALOG.md](guides/PROTOTYPE-INITIATION-DIALOG.md) - Conversation scripts
|
||||
- [PROTOTYPE-ANALYSIS.md](guides/PROTOTYPE-ANALYSIS.md) - Quality standards
|
||||
- [FILE-INDEX.md](guides/FILE-INDEX.md) - Complete file reference
|
||||
|
||||
**Templates:**
|
||||
- templates/work-file-template.yaml
|
||||
- templates/story-file-template.md
|
||||
- templates/page-template.html
|
||||
- templates/components/dev-mode.*
|
||||
|
||||
### First Step Execution
|
||||
|
||||
Load, read and execute `steps-c/1-prototype-setup.md` to begin workflow.
|
||||
|
||||
---
|
||||
|
||||
## OUTPUT
|
||||
|
||||
**Per Scenario:**
|
||||
```
|
||||
[Scenario-Number]-[Scenario-Name]-Prototype/
|
||||
├── [View].html files (in root, one per logical view)
|
||||
├── shared/ (ONE COPY of shared code)
|
||||
├── components/ (ONE COPY of reusable components)
|
||||
├── pages/ (page-specific scripts if complex)
|
||||
├── data/ (demo data JSON files)
|
||||
├── stories/ (section development files - created just-in-time)
|
||||
├── work/ (planning files)
|
||||
└── PROTOTYPE-ROADMAP.md
|
||||
```
|
||||
|
||||
**Result:** Self-contained, production-ready interactive prototypes with:
|
||||
- Clean HTML using Tailwind CSS
|
||||
- Vanilla JavaScript components
|
||||
- Demo data auto-loading
|
||||
- All states implemented and tested
|
||||
|
||||
---
|
||||
|
||||
## PROTOTYPE FOLDER STRUCTURE
|
||||
|
||||
```
|
||||
[Scenario-Number]-[Scenario-Name]-Prototype/
|
||||
├── [Page].html files ← Logical view HTML files (root)
|
||||
├── shared/ ← ONE COPY of shared code
|
||||
├── components/ ← ONE COPY of reusable components
|
||||
├── pages/ ← Page-specific scripts (if complex)
|
||||
├── data/ ← Demo data JSON files
|
||||
├── stories/ ← Section development files (JIT)
|
||||
├── work/ ← Planning files
|
||||
│ ├── Logical-View-Map.md ← Maps steps to views
|
||||
│ └── [View]-Work.yaml ← Section breakdowns per view
|
||||
└── PROTOTYPE-ROADMAP.md ← Overall roadmap
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ITERATIVE WORKFLOW
|
||||
|
||||
**Phase 1-2:** One-time setup and analysis per scenario
|
||||
|
||||
**Phase 3:** Repeat for each logical view in scenario
|
||||
|
||||
**Phase 4:** Repeat for each section in current view
|
||||
- Inner loop: Repeat 4d-4e-4f until approved
|
||||
|
||||
**Phase 5:** Repeat for each logical view (finalization)
|
||||
|
||||
**Pattern:**
|
||||
```
|
||||
Setup → Analysis → [View Selection → [Section Loop*] → Finalization]*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## EXAMPLES
|
||||
|
||||
**Typical Scenarios:**
|
||||
|
||||
1. **E-commerce Checkout:** 5 views (cart, shipping, payment, review, confirmation)
|
||||
2. **SaaS Onboarding:** 4 views (signup, profile, preferences, dashboard)
|
||||
3. **Booking System:** 6 views (search, select, details, confirm, payment, confirmation)
|
||||
|
||||
Each view breaks into 3-8 sections depending on complexity.
|
||||
|
||||
---
|
||||
|
||||
## QUALITY PRINCIPLES
|
||||
|
||||
**Section-by-Section Approval:** Never implement entire view at once - break into sections with approval gates
|
||||
|
||||
**Just-In-Time Stories:** Create story files only when needed (4b), not upfront
|
||||
|
||||
**Incremental Implementation:** Each section builds on previous approved sections
|
||||
|
||||
**Demo Data:** Use realistic demo data for testing and validation
|
||||
|
||||
**Self-Contained:** Each prototype folder is complete and portable
|
||||
|
||||
---
|
||||
|
||||
## TROUBLESHOOTING
|
||||
|
||||
**Issue:** User feedback requires rework
|
||||
**Solution:** Use Phase 4e (issues) or 4f (improvements) to handle, then loop back to 4d
|
||||
|
||||
**Issue:** Section too complex
|
||||
**Solution:** Break down further in Phase 3 before starting Phase 4
|
||||
|
||||
**Issue:** Logical view unclear
|
||||
**Solution:** Revisit Phase 2 analysis to refine view mapping
|
||||
|
||||
---
|
||||
|
||||
## NOTES
|
||||
|
||||
This workflow creates **prototypes**, not final production code. The code is production-ready quality but intended for:
|
||||
- Stakeholder demos
|
||||
- User testing
|
||||
- Design validation
|
||||
- Developer handoff reference
|
||||
|
||||
Final production code will be built in development phase using proper frameworks and architecture.
|
||||
|
||||
---
|
||||
|
||||
_Interactive Prototypes - Section-by-section implementation with approval gates_
|
||||
|
|
@ -572,7 +572,7 @@ This quality workflow integrates with:
|
|||
- [Sketch Analysis](../substeps/4b-sketch-analysis.md) - Identifies page elements
|
||||
|
||||
**After:**
|
||||
- [Interactive Prototypes](../interactive-prototypes/) - Builds HTML demos from specs
|
||||
- [Agentic Development](../agentic-development/) - Builds HTML demos from specs
|
||||
- [Design Deliveries](../../../6-design-deliveries/) - Packages specs for handoff
|
||||
- [PRD Generation](../../../3-prd-platform/) - Creates developer stories from specs
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,174 @@
|
|||
# Stitch Prompt Template
|
||||
|
||||
Use this template to prepare an effective Stitch prompt from a WDS specification.
|
||||
|
||||
---
|
||||
|
||||
## How to Use
|
||||
|
||||
1. **Copy this template** into your Stitch dialog
|
||||
2. **Fill in each section** using your spec and design system
|
||||
3. **Remove Object IDs, translations, technical details** - Stitch doesn't need them
|
||||
4. **Keep one language only** - typically the primary language (English or Swedish)
|
||||
5. **Paste the filled template** as your Stitch prompt
|
||||
|
||||
---
|
||||
|
||||
## Template Structure
|
||||
|
||||
```
|
||||
=== PROJECT CONTEXT ===
|
||||
|
||||
App: {App name} - {One-line description}
|
||||
Target: {Target audience}
|
||||
Brand feel: {2-3 adjectives describing the feel}
|
||||
Market: {Market focus if relevant}
|
||||
|
||||
=== DESIGN SYSTEM ===
|
||||
|
||||
Colors:
|
||||
- Background: {color name} ({hex})
|
||||
- Primary/CTA: {color name} ({hex})
|
||||
- Text: {color name} ({hex})
|
||||
- Secondary text: {color name} ({hex})
|
||||
- Success: {hex}
|
||||
- Error: {hex}
|
||||
|
||||
Typography:
|
||||
- Font: {font family}
|
||||
- Headlines: {weight}, {characteristics}
|
||||
- Body: {weight}, {size}
|
||||
|
||||
Component styles:
|
||||
- Buttons: {style description - rounded, gradient, shadow, etc.}
|
||||
- Inputs: {style description - border, focus state, etc.}
|
||||
- Cards: {style description if relevant}
|
||||
|
||||
=== SCREEN DETAILS ===
|
||||
|
||||
Screen: {Screen name}
|
||||
Purpose: {What this screen does, one sentence}
|
||||
User context: {Where user is coming from, what they need}
|
||||
|
||||
Layout structure:
|
||||
1. {Section 1}: {elements}
|
||||
2. {Section 2}: {elements}
|
||||
3. {Section 3}: {elements}
|
||||
|
||||
Key elements:
|
||||
- {Element 1}: "{Actual content/text}"
|
||||
- {Element 2}: "{Actual content/text}"
|
||||
- {Element 3}: "{Actual content/text}"
|
||||
|
||||
Key interactions:
|
||||
- Primary action: {what happens}
|
||||
- Secondary action: {what happens}
|
||||
|
||||
=== CURRENT STATE NOTES ===
|
||||
|
||||
{Note any elements currently using default/unstyled components}
|
||||
- {Component}: Currently ShadCN default, should match brand style
|
||||
- {Component}: Uses custom gradient button
|
||||
|
||||
=== GENERATION INSTRUCTIONS ===
|
||||
|
||||
Generate this screen matching:
|
||||
- Visual style of the attached reference image
|
||||
- Layout structure of the attached sketch
|
||||
- All content and elements listed above
|
||||
|
||||
Viewport: {Mobile 390px / Desktop 1440px}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example: Dog Week Sign-In
|
||||
|
||||
```
|
||||
=== PROJECT CONTEXT ===
|
||||
|
||||
App: Dog Week - Family dog walk coordination app
|
||||
Target: Swedish families (all ages from teens to grandparents)
|
||||
Brand feel: Warm, friendly, trustworthy
|
||||
Market: Sweden
|
||||
|
||||
=== DESIGN SYSTEM ===
|
||||
|
||||
Colors:
|
||||
- Background: Cream (#FEF3CF), gradient to #FFFBED
|
||||
- Primary/CTA: Orange (#FD6408), gradient #FD8002 to #FF2714
|
||||
- Text: Brown (#2F1A0C)
|
||||
- Secondary text: Gray (#686868)
|
||||
- Success: Green (#28C54A)
|
||||
- Error: Red (#DB0000)
|
||||
|
||||
Typography:
|
||||
- Font: Inter
|
||||
- Headlines: Bold/Extra Bold, tight letter spacing
|
||||
- Body: Regular weight, 16px base
|
||||
|
||||
Component styles:
|
||||
- Buttons: Rounded (8px), orange gradient for primary, subtle shadow
|
||||
- Inputs: Light background, rounded corners, brown text
|
||||
- Cards: Cream background, subtle shadow
|
||||
|
||||
=== SCREEN DETAILS ===
|
||||
|
||||
Screen: Sign In
|
||||
Purpose: Authenticate users with email magic link or Google SSO
|
||||
User context: Coming from Start Page, ready to access the app
|
||||
|
||||
Layout structure:
|
||||
1. Header: Logo (left), Back button (right)
|
||||
2. Main form: Email input, magic link button, divider, Google SSO
|
||||
3. Trust section: Privacy and security messages
|
||||
4. Help links: Support links at bottom
|
||||
|
||||
Key elements:
|
||||
- Email input label: "Email address"
|
||||
- Email placeholder: "your@email.com"
|
||||
- Helper text: "We'll send you a magic link to sign in"
|
||||
- Primary button: "Send magic link"
|
||||
- Divider text: "Or sign in with"
|
||||
- Google button: "Continue with Google"
|
||||
- Trust message 1: "Your information is secure and private"
|
||||
- Trust message 2: "We'll never spam you or share your details"
|
||||
- Trust message 3: "Safe for all family members to use"
|
||||
|
||||
Key interactions:
|
||||
- Primary: Enter email → Send magic link → Check email
|
||||
- Secondary: Click Google → OAuth flow → Signed in
|
||||
|
||||
=== CURRENT STATE NOTES ===
|
||||
|
||||
- Input fields: Currently ShadCN default styling, should use cream background
|
||||
- Google button: Should match brand's rounded style with Google colors
|
||||
- Trust icons: Need checkmark or shield icons in success green
|
||||
|
||||
=== GENERATION INSTRUCTIONS ===
|
||||
|
||||
Generate this sign-in screen matching:
|
||||
- Visual style of the attached Start Page screenshot (warm, cream, orange CTAs)
|
||||
- Layout structure of the attached sketch
|
||||
- All content and elements listed above
|
||||
|
||||
Viewport: Mobile 390px
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist Before Pasting to Stitch
|
||||
|
||||
- [ ] Project context filled (app name, target, brand feel)
|
||||
- [ ] Design system colors accurate (from Color-Palette.md)
|
||||
- [ ] Typography correct (from Typography-System.md)
|
||||
- [ ] Component styles described (buttons, inputs)
|
||||
- [ ] Screen content in ONE language only (no translations)
|
||||
- [ ] No Object IDs included
|
||||
- [ ] No technical implementation details
|
||||
- [ ] Current state notes added (what's ShadCN default)
|
||||
- [ ] Viewport specified
|
||||
|
||||
---
|
||||
|
||||
_Stitch Prompt Template — Freya WDS Designer_
|
||||
|
|
@ -0,0 +1,288 @@
|
|||
---
|
||||
name: Stitch UI Generation
|
||||
description: AI-assisted UI design using Google Stitch from specifications and sketches
|
||||
web_bundle: true
|
||||
---
|
||||
|
||||
# Stitch UI Generation
|
||||
|
||||
**Goal:** Generate production-quality UI designs using Google Stitch AI
|
||||
|
||||
**Your Role:** Guide the user through preparing inputs and creating a Stitch generation dialog
|
||||
|
||||
---
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
Google Stitch is an AI-powered UI design tool that transforms text prompts, sketches, and reference images into responsive interfaces.
|
||||
|
||||
**Input Formula:**
|
||||
```
|
||||
Visual Reference + Sketch + Specification = Stitch Generation
|
||||
```
|
||||
|
||||
**Output:** UI designs exportable to Figma or HTML/CSS
|
||||
|
||||
---
|
||||
|
||||
## WHEN TO USE STITCH
|
||||
|
||||
**Use Stitch when:**
|
||||
- ✅ New page with detailed specification ready
|
||||
- ✅ Have a visual reference (existing design or screenshot)
|
||||
- ✅ Have a sketch showing layout structure
|
||||
- ✅ Want rapid visual design iteration
|
||||
- ✅ Need production-quality mockups quickly
|
||||
|
||||
**Skip Stitch when:**
|
||||
- ❌ Building design system components (use tokens instead)
|
||||
- ❌ Minor updates to existing designs (edit directly)
|
||||
- ❌ No specification exists yet (write spec first)
|
||||
- ❌ Complex multi-screen flows (do 2-3 screens at a time)
|
||||
|
||||
---
|
||||
|
||||
## BEFORE STARTING
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. **Specification exists** for the screen(s) to generate
|
||||
2. **Visual reference available:**
|
||||
- Screenshot of existing implemented page, OR
|
||||
- Approved design that establishes visual language
|
||||
3. **Sketch available** showing layout structure
|
||||
|
||||
### Decision: What Visual Reference?
|
||||
|
||||
| Situation | Reference Choice |
|
||||
|-----------|------------------|
|
||||
| Code exists and looks correct | Screenshot of running code |
|
||||
| Starting fresh, no code | Original sketch or moodboard |
|
||||
| Code exists but needs redesign | Original sketch |
|
||||
| Want style from one page, layout from sketch | Both (upload 2 images) |
|
||||
|
||||
---
|
||||
|
||||
## WORKFLOW
|
||||
|
||||
### Step 1: Create Dialog
|
||||
|
||||
Create a Stitch generation dialog in the project's Agent Dialogs folder.
|
||||
|
||||
**Template:** Use `9-agent-dialogs/templates/dialog-types/stitch-generation.template.md`
|
||||
|
||||
**Location:** `docs/F-Agent-Dialogs/{YYYY-MM-DD}-freya-stitch-{feature}/`
|
||||
|
||||
**Dialog captures:**
|
||||
- Which screens to generate
|
||||
- What visual reference to use
|
||||
- Pre-crafted prompts
|
||||
- Generation results and decisions
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Answer Pre-Generation Questions
|
||||
|
||||
For each potential screen, decide:
|
||||
|
||||
**Question 1: Generate in Stitch?**
|
||||
|
||||
| Screen | Has Code? | Has Sketch? | Generate? | Why |
|
||||
|--------|-----------|-------------|-----------|-----|
|
||||
| {screen} | ✅/❌ | ✅/❌ | ✅/❌ | {reason} |
|
||||
|
||||
**Question 2: What reference?**
|
||||
|
||||
| Screen | Reference | Source |
|
||||
|--------|-----------|--------|
|
||||
| {screen} | Code screenshot / Sketch | {path or action} |
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Gather Inputs
|
||||
|
||||
For each screen to generate:
|
||||
|
||||
| Input | Action |
|
||||
|-------|--------|
|
||||
| **Visual Reference** | Take screenshot OR locate existing design |
|
||||
| **Sketch** | Locate in spec's `Sketches/` folder |
|
||||
| **Prompt** | Prepare using template (see Step 3a) |
|
||||
|
||||
---
|
||||
|
||||
### Step 3a: Prepare the Prompt
|
||||
|
||||
**DO NOT paste raw specifications into Stitch.** They contain:
|
||||
- Object IDs (not useful for design generation)
|
||||
- Multiple translations (confusing)
|
||||
- Technical implementation details
|
||||
|
||||
**Instead, use the prompt template:** [stitch-prompt.template.md](stitch-prompt.template.md)
|
||||
|
||||
The prompt should include:
|
||||
|
||||
| Section | Source |
|
||||
|---------|--------|
|
||||
| **Project Context** | Design System overview, Product Brief |
|
||||
| **Design System** | Color-Palette.md, Typography-System.md |
|
||||
| **Component Styles** | Button/Input specs from Design System |
|
||||
| **Screen Content** | Specification (ONE language, no Object IDs) |
|
||||
| **Current State Notes** | What's ShadCN default vs custom |
|
||||
|
||||
**Important notes:**
|
||||
- Use actual hex colors from your design system
|
||||
- Describe component styles (rounded buttons, gradients, etc.)
|
||||
- Include only ONE language (primary language)
|
||||
- Note what's currently using default styling that needs brand styling
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Generate in Stitch
|
||||
|
||||
1. Go to [stitch.withgoogle.com](https://stitch.withgoogle.com)
|
||||
2. Upload **visual reference** image
|
||||
3. Upload **sketch** image (if different from reference)
|
||||
4. Paste **specification** as prompt
|
||||
5. Add instruction: *"Generate this screen matching the visual style of the reference and layout of the sketch."*
|
||||
6. Generate 2-3 variants
|
||||
7. Select best result
|
||||
|
||||
**Settings:**
|
||||
- Standard Mode: Quick iteration
|
||||
- Pro Mode: Higher fidelity (uses more quota)
|
||||
- Viewport: Mobile 390px or Desktop 1440px
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Review Against Spec
|
||||
|
||||
| Check | Pass? |
|
||||
|-------|-------|
|
||||
| Content/copy matches spec | ✅/❌ |
|
||||
| Layout follows sketch | ✅/❌ |
|
||||
| Visual style matches reference | ✅/❌ |
|
||||
| All key elements present | ✅/❌ |
|
||||
|
||||
**If issues:** Re-prompt with specific corrections or edit in Stitch.
|
||||
|
||||
---
|
||||
|
||||
### Step 6: Export & Store
|
||||
|
||||
| Format | When | Destination |
|
||||
|--------|------|-------------|
|
||||
| **Figma** | Team collaboration, design system work | Figma project |
|
||||
| **HTML/CSS** | Code reference, rapid prototypes | `{spec-folder}/Visual-Design/` |
|
||||
| **Screenshot** | Documentation | `{spec-folder}/Visual-Design/` |
|
||||
|
||||
**Naming:** `{screen-name}-stitch-v{#}.{ext}`
|
||||
|
||||
---
|
||||
|
||||
### Step 7: Update Specification
|
||||
|
||||
Add to the specification file:
|
||||
|
||||
```markdown
|
||||
## Visual Design
|
||||
|
||||
**Stitch Generated:** [sign-in-stitch-v1.png](Visual-Design/sign-in-stitch-v1.png)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## STITCH CAPABILITIES & LIMITS
|
||||
|
||||
### What Stitch Does Well
|
||||
- Single screen generation from prompts
|
||||
- Style matching from reference images
|
||||
- Responsive layouts (mobile/desktop)
|
||||
- Clean HTML/CSS export
|
||||
- Figma-compatible output
|
||||
|
||||
### Current Limitations
|
||||
- Best with 2-3 screens at a time
|
||||
- Layouts can be generic (need refinement)
|
||||
- Doesn't capture deep UX nuance
|
||||
- No built-in design system awareness
|
||||
- Free tier: 350 standard + 200 pro screens/month
|
||||
|
||||
---
|
||||
|
||||
## PROMPT TIPS
|
||||
|
||||
### Effective Prompts Include
|
||||
|
||||
1. **App type:** "Mobile sign-in screen for..."
|
||||
2. **Context:** "...a Swedish family dog walk coordination app"
|
||||
3. **Visual direction:** "Match the attached reference..."
|
||||
4. **Key elements:** List all major UI elements
|
||||
5. **Content:** Include actual copy/text
|
||||
6. **Mood:** "Friendly, trustworthy, family-oriented"
|
||||
|
||||
### Example Prompt Structure
|
||||
|
||||
```
|
||||
[App type] [screen name] for [product description].
|
||||
|
||||
Visual style: Match the attached reference exactly.
|
||||
|
||||
Screen layout:
|
||||
- [Section 1]: [elements and content]
|
||||
- [Section 2]: [elements and content]
|
||||
- [Section 3]: [elements and content]
|
||||
|
||||
Key interactions: [primary action], [secondary action]
|
||||
|
||||
Mood: [brand tone and feel]
|
||||
Viewport: [Mobile 390px / Desktop 1440px]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## INTEGRATION WITH WDS
|
||||
|
||||
### Workflow Position
|
||||
|
||||
```
|
||||
Specification → Stitch Generation → Visual Design → Implementation
|
||||
↓ ↓ ↓ ↓
|
||||
Content AI-Assisted Approved Code
|
||||
& Structure Design Mockups Build
|
||||
```
|
||||
|
||||
### Related Workflows
|
||||
|
||||
- **Before Stitch:** Page Specification workflow (create the spec first)
|
||||
- **After Stitch:** Prototype Implementation dialog (build from the design)
|
||||
- **Alternative:** Design Exploration dialog (if exploring multiple directions)
|
||||
|
||||
---
|
||||
|
||||
## QUICK START
|
||||
|
||||
**Fastest path:**
|
||||
|
||||
1. User: "I want to generate a UI design for [screen name]"
|
||||
2. Freya: Creates Stitch dialog from template
|
||||
3. Freya: Asks pre-generation questions (which screens, what reference)
|
||||
4. User: Provides answers, takes screenshot if needed
|
||||
5. User: Goes to Stitch, uploads inputs, pastes spec
|
||||
6. User: Generates, reviews, exports
|
||||
7. Freya: Updates dialog with results, links in spec
|
||||
|
||||
---
|
||||
|
||||
## SUPPORT
|
||||
|
||||
**Google Stitch:**
|
||||
- [stitch.withgoogle.com](https://stitch.withgoogle.com)
|
||||
- [Google Developers Blog - Introducing Stitch](https://developers.googleblog.com/stitch-a-new-way-to-design-uis/)
|
||||
|
||||
**WDS Templates:**
|
||||
- Dialog template: `9-agent-dialogs/templates/dialog-types/stitch-generation.template.md`
|
||||
|
||||
---
|
||||
|
||||
_Stitch UI Generation Workflow — Freya WDS Designer — Phase 4 UX Design_
|
||||
|
|
@ -434,7 +434,7 @@ Area tags have limitations:
|
|||
|
||||
**Purpose:** Interactive tool for extracting Object IDs and area coordinates from prototypes
|
||||
|
||||
**Location:** `workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js`
|
||||
**Location:** `workflows/4-ux-design/agentic-development/templates/components/dev-mode.js`
|
||||
|
||||
### Features
|
||||
|
||||
|
|
@ -656,9 +656,9 @@ Area tags have limitations:
|
|||
- W3C Spec: <https://www.w3.org/TR/html52/semantics-embedded-content.html#the-area-element>
|
||||
|
||||
**WDS Documentation:**
|
||||
- Prototype Workflow: `workflows/4-ux-design/interactive-prototypes/`
|
||||
- Prototype Workflow: `workflows/4-ux-design/agentic-development/`
|
||||
- Figma Integration: `workflows/5-design-system/figma-integration/`
|
||||
- Dev Mode: `workflows/4-ux-design/interactive-prototypes/templates/components/`
|
||||
- Dev Mode: `workflows/4-ux-design/agentic-development/templates/components/`
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,58 @@
|
|||
|
||||
## CONTEXT
|
||||
|
||||
This is the first step of the Agent Dialog Workflow. We create the folder structure and main dialog file.
|
||||
This is the first step of the Agent Dialog Workflow. Before creating a new dialog, we first check for any existing pending dialogs.
|
||||
|
||||
---
|
||||
|
||||
## CHECK FOR EXISTING DIALOGS
|
||||
|
||||
⚠️ **IMPORTANT: Always check for pending dialogs before creating a new one.**
|
||||
|
||||
<action>
|
||||
**Scan for existing dialogs:**
|
||||
|
||||
1. Check if `docs/F-Agent-Dialogs/` exists
|
||||
2. If it exists, scan all subdirectories for dialog files (*-dialog.md)
|
||||
3. Read the Meta section of each dialog file
|
||||
4. Identify dialogs where:
|
||||
- Status = "Not Started" OR "In Progress"
|
||||
- Agent matches the current agent (if known)
|
||||
</action>
|
||||
|
||||
<conditional>
|
||||
**If pending dialogs found:**
|
||||
|
||||
Present them to the user:
|
||||
|
||||
```
|
||||
📋 **Found {N} pending dialog(s):**
|
||||
|
||||
| # | Date | Agent | Feature | Status |
|
||||
|---|------|-------|---------|--------|
|
||||
| 1 | {date} | {agent} | {feature} | {status} |
|
||||
|
||||
**Options:**
|
||||
[A] Continue existing dialog #{N}
|
||||
[B] Create a new dialog (existing ones remain pending)
|
||||
|
||||
Choice:
|
||||
```
|
||||
|
||||
If user chooses an existing dialog:
|
||||
- Load that dialog file
|
||||
- Check the Steps Overview table for next incomplete step
|
||||
- Continue from there
|
||||
|
||||
If user chooses to create new:
|
||||
- Continue to SELECT DIALOG TYPE below
|
||||
</conditional>
|
||||
|
||||
<conditional>
|
||||
**If no pending dialogs found OR docs/F-Agent-Dialogs/ doesn't exist:**
|
||||
|
||||
Continue to SELECT DIALOG TYPE below.
|
||||
</conditional>
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -70,12 +121,18 @@ Agent:</ask>
|
|||
<action>
|
||||
**Create dialog folder:**
|
||||
|
||||
Path: `docs/F-Agent-Dialogs/{date}-{feature_slug}/`
|
||||
Path: `docs/F-Agent-Dialogs/{date}-{agent_slug}-{feature_slug}/`
|
||||
|
||||
Where:
|
||||
- `{date}` = Today's date in YYYY-MM-DD format
|
||||
- `{agent_slug}` = Agent name, lowercase (e.g., "freya", "saga", "dev")
|
||||
- `{feature_slug}` = Feature name, lowercase, hyphenated
|
||||
|
||||
**Examples:**
|
||||
- `2026-01-23-freya-booking-details-overlay/`
|
||||
- `2026-01-23-saga-course-workflow-integration/`
|
||||
- `2026-01-23-dev-calendar-scroll-fix/`
|
||||
|
||||
**Create subfolders:**
|
||||
- `steps/` — For step instruction files
|
||||
</action>
|
||||
|
|
@ -87,9 +144,9 @@ Where:
|
|||
<action>
|
||||
**Create main dialog file:**
|
||||
|
||||
File: `docs/F-Agent-Dialogs/{date}-{feature_slug}/{date}-{feature_slug}-dialog.md`
|
||||
File: `docs/F-Agent-Dialogs/{date}-{agent_slug}-{feature_slug}/{date}-{agent_slug}-{feature_slug}-dialog.md`
|
||||
|
||||
**Use template from:** `templates/dialog.template.md`
|
||||
**Use template from:** Selected dialog type template (see SELECT DIALOG TYPE step above)
|
||||
|
||||
**Fill in:**
|
||||
- Date: Today's date
|
||||
|
|
@ -158,8 +215,8 @@ Patterns:</ask>
|
|||
✅ **Dialog initialized!**
|
||||
|
||||
**Created:**
|
||||
- Folder: `docs/F-Agent-Dialogs/{date}-{feature_slug}/`
|
||||
- Dialog file: `{date}-{feature_slug}-dialog.md`
|
||||
- Folder: `docs/F-Agent-Dialogs/{date}-{agent_slug}-{feature_slug}/`
|
||||
- Dialog file: `{date}-{agent_slug}-{feature_slug}-dialog.md`
|
||||
- Steps folder: `steps/`
|
||||
|
||||
**Next:** Proceed to Step 2 to analyze scope and create step breakdown.
|
||||
|
|
|
|||
|
|
@ -4,6 +4,8 @@
|
|||
|
||||
Step files are created. Now we execute each step, either in this dialog or in fresh agent dialogs.
|
||||
|
||||
**Note:** For implementation-specific execution details (feedback protocol, dynamic planning), see the **Agentic Development Workflow** in `workflows/4-ux-design/agentic-development/workflow.md`.
|
||||
|
||||
---
|
||||
|
||||
## EXECUTION MODES
|
||||
|
|
@ -34,9 +36,11 @@ Mode:</ask>
|
|||
|
||||
<action>
|
||||
1. **Read the step file** completely
|
||||
2. **Execute the implementation** following the instructions
|
||||
3. **Verify against acceptance criteria**
|
||||
4. **Test using the test instructions**
|
||||
2. **Document any decisions or issues** in the dialog before implementing
|
||||
3. **Execute the implementation** following the instructions
|
||||
4. **Add sub-steps** if needed for things discovered during implementation
|
||||
5. **Verify against acceptance criteria**
|
||||
6. **Test using the test instructions**
|
||||
</action>
|
||||
|
||||
### Step Completion Checklist
|
||||
|
|
@ -73,7 +77,10 @@ Mode:</ask>
|
|||
Choice:</ask>
|
||||
|
||||
<check if="choice == A">
|
||||
<action>Load and execute next step file</action>
|
||||
<action>
|
||||
1. Review and update remaining steps in dialog file
|
||||
2. Load and execute next step file
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<check if="choice == B">
|
||||
|
|
@ -81,6 +88,7 @@ Choice:</ask>
|
|||
Update dialog file:
|
||||
- Status: "In Progress"
|
||||
- Progress Log: Note where we stopped
|
||||
- Ensure all decisions documented
|
||||
|
||||
Output: "Progress saved. The dialog is ready to resume."
|
||||
</action>
|
||||
|
|
@ -90,6 +98,20 @@ Choice:</ask>
|
|||
|
||||
## MODE B: FRESH DIALOG INSTRUCTIONS
|
||||
|
||||
### Handoff Always References Dialog
|
||||
|
||||
<warning>
|
||||
**Any handoff — to a new session, new agent, or human — MUST reference the dialog document.**
|
||||
|
||||
The dialog document is the single source of truth for:
|
||||
- What has been done
|
||||
- What decisions were made
|
||||
- What remains to be done
|
||||
- Any issues or blockers
|
||||
|
||||
Never hand off by describing the task verbally. Always point to the dialog.
|
||||
</warning>
|
||||
|
||||
### For Each Step
|
||||
|
||||
<action>
|
||||
|
|
@ -98,20 +120,24 @@ Choice:</ask>
|
|||
```
|
||||
## Execute Step {N}: {Step Name}
|
||||
|
||||
### Context
|
||||
This is part of the {feature-name} implementation.
|
||||
Dialog: docs/F-Agent-Dialogs/{date}-{feature-name}/
|
||||
### Dialog Document (READ FIRST)
|
||||
`docs/F-Agent-Dialogs/{date}-{feature-name}/{date}-{feature-name}-dialog.md`
|
||||
|
||||
Read the dialog file first to understand:
|
||||
- Overall context and scope
|
||||
- What steps are complete
|
||||
- Current status and any blockers
|
||||
|
||||
### Step File
|
||||
`docs/F-Agent-Dialogs/{date}-{feature-name}/steps/{N}-{step-name}.md`
|
||||
|
||||
### Instructions
|
||||
1. Read the step file: `steps/{N}-{step-name}.md`
|
||||
2. Execute the implementation
|
||||
3. Verify against acceptance criteria
|
||||
4. When complete, update the dialog file:
|
||||
- Change step status to ✅
|
||||
- Add entry to Progress Log
|
||||
|
||||
### Step File Location
|
||||
`docs/F-Agent-Dialogs/{date}-{feature-name}/steps/{N}-{step-name}.md`
|
||||
1. Read the dialog file completely
|
||||
2. Read the step file
|
||||
3. Execute the implementation
|
||||
4. Document decisions in the dialog BEFORE implementing
|
||||
5. Verify against acceptance criteria
|
||||
6. Update dialog file: step status → ✅, add Progress Log entry
|
||||
```
|
||||
</action>
|
||||
|
||||
|
|
@ -197,7 +223,7 @@ Add to Progress Log:
|
|||
|
||||
<check if="all_steps_complete">
|
||||
<output>
|
||||
🎉 **All steps complete!**
|
||||
**All steps complete!**
|
||||
|
||||
Proceed to Step 5 to finalize the dialog.
|
||||
|
||||
|
|
|
|||
|
|
@ -4,11 +4,24 @@ Choose the template that matches your work type.
|
|||
|
||||
---
|
||||
|
||||
## Naming Convention
|
||||
|
||||
```
|
||||
docs/F-Agent-Dialogs/
|
||||
└── {YYYY-MM-DD}-{agent}-{feature-name}/
|
||||
└── {YYYY-MM-DD}-{agent}-{feature-name}-dialog.md
|
||||
```
|
||||
|
||||
**Example:** `2026-01-23-freya-booking-details-overlay-dialog.md`
|
||||
|
||||
---
|
||||
|
||||
## Available Types
|
||||
|
||||
| Type | Icon | Template | Use When |
|
||||
|------|------|----------|----------|
|
||||
| **Prototype Implementation** | 🔧 | [prototype-implementation.template.md](prototype-implementation.template.md) | Building UI from specifications |
|
||||
| **Stitch UI Generation** | 🪡 | [stitch-generation.template.md](stitch-generation.template.md) | AI-assisted UI design with Google Stitch |
|
||||
| **Bug Fix** | 🐛 | [bug-fix.template.md](bug-fix.template.md) | Fixing issues and defects |
|
||||
| **Design Exploration** | 🎨 | [design-exploration.template.md](design-exploration.template.md) | Exploring visual/UX directions |
|
||||
| **Capture** | 💾 | [../dialog-capture.template.md](../dialog-capture.template.md) | Saving ideas for later |
|
||||
|
|
@ -32,6 +45,25 @@ Choose the template that matches your work type.
|
|||
|
||||
---
|
||||
|
||||
### 🪡 Stitch UI Generation
|
||||
|
||||
**Best for:**
|
||||
- Generating UI designs from specifications using Google Stitch AI
|
||||
- Rapid visual design iteration
|
||||
- Creating production-quality screens from sketches
|
||||
|
||||
**Key sections:**
|
||||
- Input formula: Visual Reference + Sketch + Specification
|
||||
- Screen-by-screen generation tracking
|
||||
- Export and integration workflow
|
||||
|
||||
**Input Formula:**
|
||||
```
|
||||
Visual Reference + Sketch + Specification (as prompt) = Stitch Generation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🐛 Bug Fix
|
||||
|
||||
**Best for:**
|
||||
|
|
@ -92,7 +124,9 @@ Choose the template that matches your work type.
|
|||
```
|
||||
Start here:
|
||||
│
|
||||
├── Building from spec? → 🔧 Prototype Implementation
|
||||
├── Building code from spec? → 🔧 Prototype Implementation
|
||||
│
|
||||
├── Generating UI designs with AI? → 🪡 Stitch UI Generation
|
||||
│
|
||||
├── Fixing something broken? → 🐛 Bug Fix
|
||||
│
|
||||
|
|
|
|||
|
|
@ -1,4 +1,14 @@
|
|||
# {DATE} {Feature Name} — Prototype Implementation
|
||||
# {YYYY-MM-DD} {Feature Name} — Prototype Implementation
|
||||
|
||||
<!--
|
||||
FILE NAMING CONVENTION:
|
||||
- Folder: {YYYY-MM-DD}-{agent}-{feature-name}/
|
||||
- File: {YYYY-MM-DD}-{agent}-{feature-name}-dialog.md
|
||||
|
||||
Example:
|
||||
- Folder: 2026-01-23-freya-booking-details-overlay/
|
||||
- File: 2026-01-23-freya-booking-details-overlay-dialog.md
|
||||
-->
|
||||
|
||||
## Meta
|
||||
|
||||
|
|
@ -6,7 +16,7 @@
|
|||
|-------|-------|
|
||||
| **Date** | {YYYY-MM-DD} |
|
||||
| **Type** | 🔧 Prototype Implementation |
|
||||
| **Agent** | Freya (UX Designer) |
|
||||
| **Agent** | {Agent name} ({Role}) |
|
||||
| **Feature** | {Feature name} |
|
||||
| **Specification** | [{Spec name}]({path-to-spec}) |
|
||||
| **Target** | {Where to implement: app path or prototype folder} |
|
||||
|
|
@ -126,24 +136,99 @@ Each section is implemented and approved before moving to the next:
|
|||
|
||||
### Approval Criteria
|
||||
|
||||
- [ ] Matches specification visually
|
||||
- [ ] All Object IDs present
|
||||
- [ ] **Matches sketches precisely** — Text sizes, proportions, spacing, layout
|
||||
- [ ] All Object IDs present as `data-object-id` attributes
|
||||
- [ ] Translations work (SE/EN toggle)
|
||||
- [ ] Accessibility requirements met
|
||||
- [ ] No TypeScript errors
|
||||
|
||||
> **Sketch Fidelity:** Sketches are intentional design decisions. Text sizes, proportions, and spacing are chosen deliberately. Implement as close to the sketch as possible. If constraints prevent exact matching, document the deviation.
|
||||
|
||||
---
|
||||
|
||||
## Feedback Protocol
|
||||
|
||||
How designer feedback is handled during implementation:
|
||||
|
||||
| Type | What It Is | When to Address | Documentation |
|
||||
|------|------------|-----------------|---------------|
|
||||
| **Bug/Issue** | Something broken or not working | Now — iterate until fixed | Part of current step |
|
||||
| **Quick Adjustment** | Small tweak to current work | Now — implement immediately | Note in progress log |
|
||||
| **Addition** | New requirement in scope | Later step — add to plan | Note in step file |
|
||||
| **Change Request** | Outside current scope | Future session — document | Add to Change Requests |
|
||||
|
||||
### The 2-Minute Rule (GTD)
|
||||
|
||||
**If a fix takes less than 2 minutes, do it immediately.**
|
||||
|
||||
Planning overhead should not exceed task complexity. See [GTD Model](../../../../docs/models/gtd-getting-things-done.md).
|
||||
|
||||
**Pattern:** Do the fix → Log as sub-step (e.g., 20a-1) → Continue main task
|
||||
|
||||
### Agent Response Pattern
|
||||
|
||||
**When user reports something:**
|
||||
1. **CLASSIFY** — What type of feedback is this?
|
||||
2. **TIMING** — When should it be addressed?
|
||||
3. **CONFIRM** — For additions and change requests, confirm before proceeding
|
||||
4. **EXECUTE** — Implement or document as appropriate
|
||||
|
||||
### Change Request Flow
|
||||
|
||||
```
|
||||
Designer: "The profile button should go to /family"
|
||||
Agent: "This is outside the current dialog scope.
|
||||
It doesn't block {current feature}.
|
||||
I'll add it to Change Requests for a future session. Confirm?"
|
||||
Designer: "Yes" → Agent adds to Change Requests
|
||||
OR "Do it now" → Agent treats as quick adjustment, implements
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Change Requests
|
||||
|
||||
Structural changes identified during implementation. Assessed for timing.
|
||||
|
||||
| # | Request | Raised | Assessment | Timing | Status |
|
||||
|---|---------|--------|------------|--------|--------|
|
||||
| _None yet_ | | | | | |
|
||||
|
||||
<!--
|
||||
Example:
|
||||
| CR-1 | **Infinite Calendar Scroll** — Calendar should scroll continuously | 2026-01-24 | Structural change to calendar. Significant scope. | Future session | 🔲 Pending |
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
## Steps Overview
|
||||
|
||||
| # | Section | Status | Approved |
|
||||
|---|---------|--------|----------|
|
||||
| 1 | [{Section name}](steps/01-{section}.md) | 🔲 | 🔲 |
|
||||
| 2 | [{Section name}](steps/02-{section}.md) | 🔲 | 🔲 |
|
||||
| 3 | [{Section name}](steps/03-{section}.md) | 🔲 | 🔲 |
|
||||
### Done
|
||||
|
||||
| # | Section | Notes |
|
||||
|---|---------|-------|
|
||||
| _None yet_ | | |
|
||||
|
||||
### In Progress
|
||||
|
||||
| # | Section | Status | Description |
|
||||
|---|---------|--------|-------------|
|
||||
| 1 | [{Section name}](steps/01-{section}.md) | 🔄 | {Brief description} |
|
||||
| 1a | — {Sub-task} | 🔄 | {Sub-step added during execution} |
|
||||
|
||||
### To Do
|
||||
|
||||
| # | Section | Description |
|
||||
|---|---------|-------------|
|
||||
| 2 | [{Section name}](steps/02-{section}.md) | {Brief description} |
|
||||
| 3 | [{Section name}](steps/03-{section}.md) | {Brief description} |
|
||||
|
||||
**Status:** 🔲 Not Started | 🔄 In Progress | ✅ Complete | ⏸️ Blocked
|
||||
**Approved:** 🔲 Pending | ✅ Approved | 🔁 Needs Changes
|
||||
|
||||
**Sub-Step Numbering:**
|
||||
- Main steps: `1`, `2`, `3`...
|
||||
- Sub-steps during execution: `1a`, `1b`...
|
||||
- Bug fixes (2-min rule): `1a-1`, `1a-2`...
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,311 @@
|
|||
# {YYYY-MM-DD} {Feature Name} — Stitch UI Generation
|
||||
|
||||
<!--
|
||||
FILE NAMING CONVENTION:
|
||||
- Folder: {YYYY-MM-DD}-freya-stitch-{feature-name}/
|
||||
- File: {YYYY-MM-DD}-freya-stitch-{feature-name}-dialog.md
|
||||
|
||||
Example:
|
||||
- Folder: 2026-01-26-freya-stitch-signin-flow/
|
||||
- File: 2026-01-26-freya-stitch-signin-flow-dialog.md
|
||||
-->
|
||||
|
||||
## Meta
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Date** | {YYYY-MM-DD} |
|
||||
| **Type** | 🪡 Stitch UI Generation |
|
||||
| **Agent** | Freya (WDS Designer) |
|
||||
| **Feature** | {Feature/flow name} |
|
||||
| **Specifications** | [{Spec 1}]({path}), [{Spec 2}]({path}) |
|
||||
| **Design Reference** | [{Reference design}]({path}) — visual style source |
|
||||
| **Status** | Not Started |
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate production-quality UI designs for {feature name} using Google Stitch AI, based on existing specifications and sketches.
|
||||
|
||||
---
|
||||
|
||||
## About This Dialog
|
||||
|
||||
This dialog guides the **AI-assisted UI generation workflow** using Google Stitch.
|
||||
|
||||
```
|
||||
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
|
||||
│ INPUTS │ │ STITCH PROCESS │ │ OUTPUTS │
|
||||
│ │ │ │ │ │
|
||||
│ • Specifications │────────▶│ • Prompt crafting │────────▶│ • UI designs │
|
||||
│ • Sketches │ │ • Generation │ │ • Figma exports │
|
||||
│ • Reference designs │ │ • Iteration │ │ • HTML/CSS code │
|
||||
│ • Strategic context │ │ • Refinement │ │ • Design decisions │
|
||||
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
|
||||
Source Materials AI Generation Project Assets
|
||||
```
|
||||
|
||||
**Specifications remain the single source of truth.** Stitch generates visual interpretations that must align with spec requirements.
|
||||
|
||||
---
|
||||
|
||||
## When to Use Stitch
|
||||
|
||||
| Scenario | Use Stitch? | Why |
|
||||
|----------|-------------|-----|
|
||||
| New page with detailed spec | ✅ Yes | Accelerates visual design from requirements |
|
||||
| Exploring visual directions | ✅ Yes | Quick iteration on look & feel |
|
||||
| Complex multi-state UI | ⚠️ Partially | Generate base, refine states manually |
|
||||
| Design system components | ❌ No | Build from tokens, not generated |
|
||||
| Minor spec updates | ❌ No | Edit existing designs directly |
|
||||
|
||||
---
|
||||
|
||||
## Stitch Capabilities & Limits
|
||||
|
||||
### What Stitch Does Well
|
||||
- Single screen generation from prompts
|
||||
- Style matching from reference images
|
||||
- Responsive layouts (mobile/desktop)
|
||||
- Clean HTML/CSS export
|
||||
- Figma-compatible output
|
||||
|
||||
### Current Limitations
|
||||
- Best with 2-3 screens at a time
|
||||
- Layouts can be generic (need refinement)
|
||||
- Doesn't capture deep UX nuance
|
||||
- No built-in design system awareness
|
||||
- Requires iteration for production quality
|
||||
|
||||
---
|
||||
|
||||
## Setup Context
|
||||
|
||||
### Project Context
|
||||
|
||||
- **Project:** {Project name}
|
||||
- **Brand:** {Brand characteristics — tone, colors, typography}
|
||||
- **Tech Stack:** {e.g., React, Next.js, Tailwind CSS}
|
||||
- **Design System:** [{Design System}]({path})
|
||||
|
||||
### Strategic Context
|
||||
|
||||
| Document | Path | Key Elements |
|
||||
|----------|------|--------------|
|
||||
| VTC/Trigger Map | [{path}]({path}) | {Key triggers for this feature} |
|
||||
| User Personas | [{path}]({path}) | {Target personas} |
|
||||
| Product Brief | [{path}]({path}) | {Relevant product goals} |
|
||||
|
||||
### Reference Materials
|
||||
|
||||
| Type | File | Purpose |
|
||||
|------|------|---------|
|
||||
| **Style Reference** | [{design}]({path}) | Visual language source for Stitch |
|
||||
| **Sketch** | [{sketch}]({path}) | Layout and structure guide |
|
||||
| **Specification** | [{spec}]({path}) | Requirements and content |
|
||||
|
||||
---
|
||||
|
||||
## Pre-Generation Questions
|
||||
|
||||
Before generating, decide for each screen:
|
||||
|
||||
### Question 1: Which screens need Stitch generation?
|
||||
|
||||
| Screen | Has Code? | Has Sketch? | Generate in Stitch? | Why |
|
||||
|--------|-----------|-------------|---------------------|-----|
|
||||
| {Screen 1} | ✅/❌ | ✅/❌ | ✅/❌ | {reason} |
|
||||
| {Screen 2} | ✅/❌ | ✅/❌ | ✅/❌ | {reason} |
|
||||
|
||||
### Question 2: What visual reference for each screen?
|
||||
|
||||
| Option | When to Use |
|
||||
|--------|-------------|
|
||||
| **Screenshot of existing code** | Code exists and represents the correct visual direction |
|
||||
| **Original sketch** | Starting fresh, or code doesn't match desired direction |
|
||||
| **Both** | Use code as style reference + sketch for layout guidance |
|
||||
|
||||
| Screen | Reference Choice | Source |
|
||||
|--------|------------------|--------|
|
||||
| {Screen 1} | Code screenshot / Sketch / Both | {path or "take screenshot"} |
|
||||
| {Screen 2} | Code screenshot / Sketch / Both | {path or "take screenshot"} |
|
||||
|
||||
---
|
||||
|
||||
## Screens to Generate
|
||||
|
||||
| # | Screen | Specification | Visual Reference | Layout Guide | Priority | Status |
|
||||
|---|--------|---------------|------------------|--------------|----------|--------|
|
||||
| 1 | {Screen name} | [{spec}]({path}) | {screenshot/sketch} | {sketch if different} | High | 🔲 |
|
||||
| 2 | {Screen name} | [{spec}]({path}) | {screenshot/sketch} | {sketch if different} | High | 🔲 |
|
||||
|
||||
**Status:** 🔲 Not Started | 🔄 In Progress | ✅ Generated | 🔁 Needs Refinement | ✅✅ Approved
|
||||
|
||||
---
|
||||
|
||||
## Stitch Input Formula
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ VISUAL REFERENCE│ + │ SKETCH │ + │ SPECIFICATION │ = Stitch Generation
|
||||
│ (style source) │ │ (layout/structure)│ │ (paste as prompt)│
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
**That's it.** Upload the reference + sketch images, paste the spec as prompt text.
|
||||
|
||||
---
|
||||
|
||||
## Stitch Workflow Steps
|
||||
|
||||
### Step 1: Gather Inputs
|
||||
|
||||
| Input | Source | Format |
|
||||
|-------|--------|--------|
|
||||
| **Visual Reference** | Screenshot of existing design (e.g., start page) | Image (PNG/JPG) |
|
||||
| **Sketch** | Wireframe sketch from spec folder | Image (PNG/JPG) |
|
||||
| **Specification** | Full spec markdown or key sections | Text (paste into prompt) |
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Visual reference captured (shows brand style)
|
||||
- [ ] Sketch image ready
|
||||
- [ ] Spec content copied (full doc or key sections)
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Generate in Stitch
|
||||
|
||||
1. Go to [stitch.withgoogle.com](https://stitch.withgoogle.com)
|
||||
2. Upload **visual reference** image
|
||||
3. Upload **sketch** image
|
||||
4. Paste **specification** as prompt text (or key sections)
|
||||
5. Add brief instruction: *"Generate this screen matching the visual style of the reference and layout of the sketch."*
|
||||
6. Generate 2-3 variants
|
||||
7. Select best result
|
||||
|
||||
**Settings:**
|
||||
- Mode: Standard (fast) or Pro (higher fidelity)
|
||||
- Viewport: {Mobile 390px | Desktop 1440px}
|
||||
|
||||
**Results:**
|
||||
| Screen | Variants | Selected | Notes |
|
||||
|--------|----------|----------|-------|
|
||||
| {name} | {#} | v{#} | {observations} |
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Review Against Spec
|
||||
|
||||
Quick check - does the output match spec requirements?
|
||||
|
||||
| Check | ✅/❌ | Fix Needed |
|
||||
|-------|-------|------------|
|
||||
| Content/copy matches spec | | |
|
||||
| Layout follows sketch | | |
|
||||
| Visual style matches reference | | |
|
||||
| All key elements present | | |
|
||||
|
||||
**If refinement needed:** Re-prompt with specific corrections or edit in Stitch.
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Export & Store
|
||||
|
||||
| Format | Destination |
|
||||
|--------|-------------|
|
||||
| **Figma** | Copy to Figma for team/design system work |
|
||||
| **HTML/CSS** | `{spec-folder}/Visual-Design/` |
|
||||
| **Screenshot** | `{spec-folder}/Visual-Design/` |
|
||||
|
||||
**Naming:** `{screen-name}-stitch-v{#}.{ext}`
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Link in Spec
|
||||
|
||||
Add reference to the specification file:
|
||||
|
||||
```markdown
|
||||
## Visual Design
|
||||
|
||||
**Stitch Generated:** [{screen-name}-stitch-v1.png](Visual-Design/{screen-name}-stitch-v1.png)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompts
|
||||
|
||||
Store each screen's prompt in a separate file in the dialog folder.
|
||||
|
||||
**Naming:** Match the scenario numbering: `{scenario#}-{screen-name}-stitch-prompt.md`
|
||||
|
||||
| # | Screen | Prompt File | Status |
|
||||
|---|--------|-------------|--------|
|
||||
| 1 | {Screen 1} | [{scenario#}-{screen-name}-stitch-prompt.md]({scenario#}-{screen-name}-stitch-prompt.md) | 🔲 |
|
||||
| 2 | {Screen 2} | [{scenario#}-{screen-name}-stitch-prompt.md]({scenario#}-{screen-name}-stitch-prompt.md) | 🔲 |
|
||||
|
||||
**Examples:** `1.2-sign-in-stitch-prompt.md`, `1.3-profile-setup-stitch-prompt.md`
|
||||
|
||||
Use the [stitch-prompt.template.md](../../stitch-generation/stitch-prompt.template.md) to create each prompt file.
|
||||
|
||||
---
|
||||
|
||||
## Outputs Log
|
||||
|
||||
| Screen | Version | Format | Path | Approved? |
|
||||
|--------|---------|--------|------|-----------|
|
||||
| {name} | v1 | Figma | {link} | 🔲 |
|
||||
| {name} | v2 | HTML | {path} | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## Design Decisions
|
||||
|
||||
| Decision | Context | Rationale |
|
||||
|----------|---------|-----------|
|
||||
| {what was decided} | {why it came up} | {reasoning} |
|
||||
|
||||
---
|
||||
|
||||
## Spec Deviations
|
||||
|
||||
Issues where Stitch output differs from specification:
|
||||
|
||||
| Screen | Spec Requirement | Stitch Output | Resolution |
|
||||
|--------|------------------|---------------|------------|
|
||||
| {screen} | {requirement} | {what Stitch did} | {how resolved} |
|
||||
|
||||
---
|
||||
|
||||
## Progress Log
|
||||
|
||||
### {YYYY-MM-DD}
|
||||
|
||||
- Created dialog for {feature}
|
||||
- Identified {#} screens to generate
|
||||
- Prepared reference materials
|
||||
|
||||
<!--
|
||||
### {YYYY-MM-DD}
|
||||
- Generated Screen 1: {name} - v1
|
||||
- Refinements needed: {list}
|
||||
- Re-generated with updated prompt
|
||||
- Approved ✅
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
## Learnings
|
||||
|
||||
<!--
|
||||
Capture prompt patterns and techniques that worked well.
|
||||
-->
|
||||
|
||||
| What Worked | Why | Reuse For |
|
||||
|-------------|-----|-----------|
|
||||
| {technique} | {reason} | {future use} |
|
||||
|
||||
---
|
||||
|
||||
_Stitch UI Generation Dialog — Freya WDS Designer — WDS Agent Dialog Workflow_
|
||||
|
|
@ -104,6 +104,33 @@ This dialog **bridges the gap** between the page specification and the developme
|
|||
|
||||
---
|
||||
|
||||
## Implementation Workflow
|
||||
|
||||
### Step-by-Step Process
|
||||
|
||||
1. **Build step** — Implement the code
|
||||
2. **Test step** — Verify against spec
|
||||
3. **User approval** — Confirm it's correct
|
||||
4. **CW status check** — Verify context window has room for next step
|
||||
5. **Next step** — Move forward
|
||||
|
||||
### Context Window (CW) Status Check
|
||||
|
||||
At the end of each completed step, perform a CW status check to ensure the AI session can handle the next step without losing important context.
|
||||
|
||||
| Check | Action |
|
||||
|-------|--------|
|
||||
| **Session length** | If conversation is very long, consider starting fresh for next step |
|
||||
| **Context clarity** | Can the agent still reference earlier decisions accurately? |
|
||||
| **Handoff summary** | If starting new session, document: completed steps, key decisions, current file states |
|
||||
|
||||
**Recommendation thresholds:**
|
||||
- **Continue** — Session is manageable, context is clear
|
||||
- **Consider fresh start** — Session is long but context is still intact
|
||||
- **Fresh start recommended** — Context overflow risk, or major architectural shift in next step
|
||||
|
||||
---
|
||||
|
||||
## Steps Overview
|
||||
|
||||
| # | Step | Status | Notes |
|
||||
|
|
|
|||
|
|
@ -94,4 +94,25 @@ For each Object ID:
|
|||
|
||||
---
|
||||
|
||||
## CW Status Check
|
||||
|
||||
At step completion, assess context window status:
|
||||
|
||||
| Indicator | Status |
|
||||
|-----------|--------|
|
||||
| Session length | {Short / Medium / Long} |
|
||||
| Context clarity | {Clear / Degraded} |
|
||||
| Recommendation | {Continue / Consider fresh start / Fresh start recommended} |
|
||||
|
||||
**If starting fresh session for next step, include handoff summary:**
|
||||
|
||||
```
|
||||
Completed: Step {#} - {Step Name}
|
||||
Key decisions: {list any important decisions made}
|
||||
File states: {list modified files and their current state}
|
||||
Next: Step {#+1} - {Next Step Name}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
_Step {#} of {total} — {Feature Name} Implementation_
|
||||
|
|
|
|||
|
|
@ -388,12 +388,14 @@ To begin, load and execute [steps/step-01-initialize-dialog.md](steps/step-01-in
|
|||
|
||||
Agent Dialogs can be created from:
|
||||
|
||||
- **Interactive Prototypes Workflow** — Each section becomes a step
|
||||
- **UX Design Workflow** — Specification implementation becomes a dialog
|
||||
- **Design System Workflow** — Component creation becomes a dialog
|
||||
- **Testing Workflow** — Validation tasks become a dialog
|
||||
|
||||
The Agent Dialog structure provides a consistent way to document and execute implementation work from any source.
|
||||
|
||||
**Note:** This workflow IS the Agentic Development approach. Interactive Prototypes, Prototype Implementation, Bug Fixes, and Design Exploration are all output types of this workflow.
|
||||
|
||||
---
|
||||
|
||||
_Agent Dialog Workflow — Structured, reproducible implementation with isolated context_
|
||||
|
|
|
|||
|
|
@ -141,8 +141,8 @@ warningsFixed: 6
|
|||
|
||||
---
|
||||
|
||||
### 10. interactive-prototypes ⚠️ EMPTY/INCOMPLETE
|
||||
**Location:** `4-ux-design/interactive-prototypes`
|
||||
### 10. agentic-development ⚠️ EMPTY/INCOMPLETE
|
||||
**Location:** `4-ux-design/agentic-development`
|
||||
**Structure:** Directory exists but appears empty or undeveloped
|
||||
**Issue:** No files found
|
||||
**Recommendation:** Remove or develop workflow
|
||||
|
|
@ -269,7 +269,7 @@ Individual validation reports created:
|
|||
|
||||
### Immediate Actions Required
|
||||
1. **Create workflow.md files** for remaining workflows with step structures
|
||||
2. **Investigate empty workflows** (interactive-prototypes, modular-architecture, object-types) - remove or develop
|
||||
2. **Investigate empty workflows** (agentic-development, modular-architecture, object-types) - remove or develop
|
||||
3. **Clarify guide vs workflow** distinction for excalidraw-integration and scenario-init
|
||||
4. **Complete vtc-workshop** workflow.md creation
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue