diff --git a/.claude/commands/marketplace.md b/.claude/commands/marketplace.md new file mode 100644 index 0000000..28d2ca7 --- /dev/null +++ b/.claude/commands/marketplace.md @@ -0,0 +1,235 @@ +# Marketplace Command + +Browse, install, and configure MCPs, skills, hooks, and tools for the Designbrnd workflow. + +## Usage + +```bash +/marketplace # Show all available tools +/marketplace install # Install specific tool +/marketplace list # List installed tools +/marketplace info # Get detailed info about a tool +``` + +## Available Categories + +- **MCP Servers** - Model Context Protocol servers for AI capabilities +- **Skills** - Learning modules that improve over time +- **Hooks** - Event-triggered automation scripts +- **Tools** - Development and project management tools +- **Workflows** - Complete multi-tool workflows + +## Quick Install + +### Complete Workspace Setup +```bash +# Initialize new client project with ALL tools +./init-workspace.sh "project-name" "Client Name" +``` + +### Individual Tools + +**Design OS:** +```bash +# Commands already available in .claude/commands/design-os/ +/product-vision +/product-roadmap +/data-model +``` + +**Figma MCP Server:** +```bash +# Clone and setup +git clone https://github.com/Antonytm/figma-mcp-server.git +cd figma-mcp-server && npm install && npm run build +npm start # Runs on port 38450 + +# Install Figma plugin (Figma Desktop → Plugins → Development → Import) +``` + +**RALPH LOOP:** +```bash +# Configured via init-workspace.sh +# Or manually: +npm install -D @playwright/test +npx playwright install chromium +npx shadcn@latest init +``` + +**Reflection System:** +```bash +# Skills auto-created in ~/.claude/skills/ +/reflect [skill-name] # Manual reflection +/reflect on # Enable auto-reflection +``` + +**Beads:** +```bash +# Install from: https://github.com/steveyegge/beads +# Then in project: +bd init +bd create epic "6-Week Project" +``` + +## Registry + +All available tools are cataloged in: +``` +.claude/marketplace/registry.json +``` + +## MCP Servers + +### Figma MCP +- **Purpose:** AI-powered Figma design automation +- **Port:** 38450 +- **Protocol:** WebSocket +- **Tools:** 23 design manipulation tools +- **Integration:** Design OS, cloud.md, Beads + +## Skills + +### Client Discovery +- **Learns:** Question patterns, industry requirements +- **Triggers:** /product-vision, client intake +- **File:** ~/.claude/skills/client-discovery/SKILL.md + +### Brand Design +- **Learns:** Industry colors, component standards +- **Triggers:** /design-tokens, Figma design +- **File:** ~/.claude/skills/brand-design/SKILL.md + +### Figma Design +- **Learns:** cloud.md patterns, naming conventions +- **Triggers:** Figma MCP usage +- **File:** ~/.claude/skills/figma-design/SKILL.md + +### Implementation +- **Learns:** Tech stack, code structure +- **Triggers:** Code implementation, RALPH LOOP +- **File:** ~/.claude/skills/implementation/SKILL.md + +### QA Verification +- **Learns:** Screenshot checks, visual bugs +- **Triggers:** RALPH LOOP verification +- **File:** ~/.claude/skills/qa-verification/SKILL.md + +## Hooks + +### Auto-Reflection (Stop Hook) +- **Event:** When Claude stops responding +- **Action:** Captures learnings, updates skills +- **Enable:** /reflect on +- **File:** ~/.claude/hooks/stop-hook-reflect.sh + +### Git Commit Checker (Stop Hook) +- **Event:** When Claude stops responding +- **Action:** Checks for untracked files +- **Status:** Enabled by default +- **File:** ~/.claude/hooks/stop-hook-git-check.sh + +### Beads Task Tracker (UserPromptSubmit Hook) +- **Event:** When user submits prompt +- **Action:** Shows next ready task from Beads +- **Requires:** Beads (bd command) +- **File:** ~/.claude/hooks/user-prompt-submit-beads.sh + +## Tools + +### Beads Project Tracker +- **Purpose:** Git-backed task tracking for AI agents +- **Features:** Dependencies, memory decay, multi-agent +- **Commands:** `bd ready`, `bd status`, `bd done` +- **Repository:** https://github.com/steveyegge/beads + +### RALPH LOOP +- **Purpose:** Test-driven development with visual QA +- **Technologies:** Playwright, Next.js, shadcn/ui +- **Workflow:** Test → Implement → Verify → Promise +- **Command:** /ralph-loop (for guidance) + +## Workflows + +### 6-Week Consulting Workflow +1. **Week 1:** Discovery (Design OS) +2. **Week 2:** Brand Design (Design OS + Figma MCP) +3. **Week 3:** Screen Design (Design OS + Figma MCP) +4. **Week 4-5:** Implementation (RALPH LOOP) +5. **Week 6:** Launch + +**Initialize with:** +```bash +./init-workspace.sh "client-project" "Client Name" +``` + +## Custom Configuration + +### Add Your Own MCP Server + +Edit `.claude/marketplace/registry.json`: + +```json +{ + "mcp_servers": [ + { + "id": "your-mcp", + "name": "Your MCP Server", + "description": "Description", + "port": 3000, + "setup_command": "setup-your-mcp.sh", + "tools": ["tool1", "tool2"] + } + ] +} +``` + +### Add Custom Skill + +1. Create directory: `~/.claude/skills/your-skill/` +2. Create SKILL.md with your learning patterns +3. Add to registry.json +4. Use with `/reflect your-skill` + +### Add Custom Hook + +1. Create script: `.claude/hooks/your-hook.sh` +2. Make executable: `chmod +x .claude/hooks/your-hook.sh` +3. Add to `~/.claude/settings.json`: +```json +{ + "hooks": { + "YourEvent": { + "hooks": [ + { + "type": "command", + "command": "~/.claude/hooks/your-hook.sh" + } + ] + } + } +} +``` + +## Documentation + +- **Workflow Guide:** docs/consulting-workflow-guide.md +- **Quick Start:** docs/quick-start-guide.md +- **Technical Reference:** docs/tool-integration-reference.md +- **Presentation:** slides.md (Slidev format) + +## Support + +- **Repository:** https://github.com/0xtsotsi/Designbrnd +- **Issues:** https://github.com/0xtsotsi/Designbrnd/issues +- **Registry:** .claude/marketplace/registry.json + +--- + +**Quick Start:** +```bash +# Initialize complete workspace +./init-workspace.sh "my-project" "Client Name" + +# Start working +/product-vision +``` diff --git a/.claude/hooks/user-prompt-submit-beads.sh b/.claude/hooks/user-prompt-submit-beads.sh new file mode 100755 index 0000000..60cbd06 --- /dev/null +++ b/.claude/hooks/user-prompt-submit-beads.sh @@ -0,0 +1,42 @@ +#!/bin/bash + +# ============================================================================ +# BEADS TASK TRACKER HOOK +# ============================================================================ +# Automatically checks Beads for next ready task when user submits a prompt +# Event: UserPromptSubmit +# ============================================================================ + +# Check if Beads is installed +if ! command -v bd &> /dev/null; then + exit 0 # Silently exit if Beads not installed +fi + +# Check if we're in a Beads-initialized project +if [ ! -d ".beads" ] && [ ! -d ".git/beads" ]; then + exit 0 # Not a Beads project +fi + +# Check for disable flag +if [ -f ".beads/.disable-hook" ]; then + exit 0 +fi + +# Get ready tasks (suppress errors) +READY_TASKS=$(bd ready --json 2>/dev/null | jq -r '.[] | .id + ": " + .title' | head -n 3) + +if [ -n "$READY_TASKS" ]; then + # Format output as system message + MESSAGE=$(cat <FEATURE_DONE` + +**Features:** +- Playwright E2E testing +- Visual regression testing +- Screenshot verification +- Pixel-perfect quality guarantee + +**Install:** +```bash +# Included in complete bundle, or in any Next.js project: +npm install -D @playwright/test +npx playwright install chromium +npx shadcn@latest init +``` + +**Category:** Development, Testing +**Tags:** testing, tdd, quality, automation + +--- + +### 4. Reflection Skills System + +**What it does:** Meta-learning system that improves from corrections + +**Skills:** +1. **Client Discovery** - Learns discovery question patterns +2. **Brand Design** - Learns industry colors and component standards +3. **Figma Design** - Learns cloud.md preferences and naming +4. **Implementation** - Learns tech stack and code structure +5. **QA Verification** - Learns screenshot verification criteria + +**How it works:** +- During session: You correct Claude +- End of session: Run `/reflect ` +- AI analyzes corrections and proposes updates +- Skills improve with every project + +**Commands:** +- `/reflect ` - Update specific skill +- `/reflect on` - Enable auto-reflection +- `/reflect off` - Disable auto-reflection + +**Install:** +```bash +# Included in complete bundle +# Skills stored in ~/.claude/skills/ +``` + +**Category:** Productivity, Learning +**Tags:** learning, ai, improvement, skills + +--- + +### 5. Beads Integration + +**What it does:** Git-backed task tracking with persistent memory for AI agents + +**Features:** +- Task dependencies and tracking +- Persistent memory across sessions +- Git-backed storage (version controlled) +- Auto-displays next ready task +- 6-week project template + +**Commands:** +- `bd init` - Initialize project +- `bd ready` - Show ready tasks +- `bd status` - Show progress +- `bd done ` - Mark task complete + +**Install:** +```bash +# Install Beads from official repo +# See: https://github.com/steveyegge/beads + +# Hook auto-installed with complete bundle +# Or manually add to ~/.claude/settings.json +``` + +**Category:** Project Management +**Tags:** project-management, tasks, git, memory +**Optional:** Yes + +--- + +### 6. Workspace Initializer + +**What it does:** One-command workspace setup for complete workflow + +**Usage:** +```bash +designbrnd-init "project-name" "Client Name" +``` + +**What it creates:** +- Complete Next.js project with TypeScript +- Design OS product structure +- Playwright E2E testing +- Reflection skills +- Beads project template +- cloud.md design rules +- Documentation and README + +**Install:** +```bash +# Included in complete bundle as 'designbrnd-init' command +``` + +**Category:** Productivity, Setup +**Tags:** setup, automation, initialization + +--- + +## 🔄 Complete Workflow + +### 6-Week Consulting Workflow + +**Week 1: Discovery & Planning** +- Use: Design OS Commands +- Run: `/product-vision`, `/product-roadmap`, `/data-model` +- Deliverable: Product specs and data model + +**Week 2: Brand System Design** +- Use: Design OS + Figma MCP +- Run: `/design-tokens`, then AI creates brand system in Figma +- Deliverable: Brand guidelines and component library + +**Week 3: Screen Design** +- Use: Design OS + Figma MCP +- Run: `/shape-section`, `/sample-data`, then AI creates screens +- Deliverable: Figma screen designs (desktop + mobile) + +**Week 4-5: Implementation** +- Use: RALPH LOOP + Design OS +- Run: `/export-product`, write E2E tests, RALPH LOOP workflow +- Deliverable: Implemented features with passing tests + +**Week 6: Launch** +- Deploy to production +- Client handoff +- Documentation + +**Initialize workflow:** +```bash +designbrnd-init "client-project" "Client Name" +cd client-project +/product-vision # Start working +``` + +--- + +## 📖 Documentation + +**Installed with complete bundle to `~/.claude/docs/webrnds/`:** + +- **quick-start-guide.md** - 60-minute quickstart +- **consulting-workflow-guide.md** - Complete workflow details +- **workspace-initialization-guide.md** - Setup walkthrough +- **tool-integration-reference.md** - Technical reference +- **architecture-diagram.md** - System architecture + +**Online:** +- Repository: https://github.com/0xtsotsi/Designbrnd +- Issues: https://github.com/0xtsotsi/Designbrnd/issues +- Discussions: https://github.com/0xtsotsi/Designbrnd/discussions + +--- + +## 🛠️ Requirements + +### System Requirements +- **Node.js:** 18.0.0 or higher +- **npm:** 9.0.0 or higher +- **Git:** Any recent version +- **jq:** For JSON processing + +### Optional +- **Figma Desktop:** 116.0.0+ (for Figma MCP) +- **Beads:** For task tracking + +### Supported Platforms +- macOS +- Linux +- Windows (WSL2) + +--- + +## 🔧 Configuration + +### Enable Beads Hook + +Add to `~/.claude/settings.json`: + +```json +{ + "hooks": { + "UserPromptSubmit": { + "hooks": [ + { + "type": "command", + "command": "~/.claude/hooks/user-prompt-submit-beads.sh" + } + ] + } + } +} +``` + +### Enable Auto-Reflection + +```bash +/reflect on +``` + +Or add to `~/.claude/settings.json`: + +```json +{ + "hooks": { + "Stop": { + "hooks": [ + { + "type": "command", + "command": "~/.claude/hooks/stop-hook-reflect.sh" + } + ] + } + } +} +``` + +--- + +## 📊 Benefits + +### Speed Improvements +- **Brand Design:** 10 mins vs. 2-4 hours (80% faster) +- **Screen Design:** 15 mins vs. 3-5 hours per screen (95% faster) +- **Overall Project:** 6 weeks vs. 12-16 weeks (2-3x faster) + +### Quality Improvements +- Pixel-perfect implementation (RALPH LOOP) +- Automated visual QA +- Client approval before implementation +- Consistent professional quality + +### Learning Improvements +- Reflection system captures corrections +- Skills improve with every project +- By project 10: ~20 hours saved from learnings + +### ROI +- **Per Client:** 70 hours saved = 8.75 workdays +- **Annual (20 clients):** 1,400 hours = $70,000-$140,000 value + +--- + +## 🚀 Getting Started + +### 1. Install Complete Bundle + +```bash +bash <(curl -fsSL https://raw.githubusercontent.com/0xtsotsi/Designbrnd/main/install.sh) +``` + +### 2. Initialize First Project + +```bash +designbrnd-init "my-first-project" "My Client" +cd my-first-project +``` + +### 3. Start Discovery + +```bash +/product-vision +# Answer questions, generates product-overview.md + +/product-roadmap +# Define sections + +/data-model +# Structure data +``` + +### 4. Continue Through Weeks + +Follow the 6-week workflow documented in the guides. + +--- + +## 🤝 Contributing + +We welcome contributions to the Webrnds marketplace! + +**How to contribute:** +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Submit a pull request + +**Ideas for contributions:** +- New skills for Reflection System +- Additional Design OS commands +- Workflow templates +- Documentation improvements +- Bug fixes + +--- + +## 📜 License + +MIT License - See LICENSE file for details + +--- + +## 🆘 Support + +**Issues:** https://github.com/0xtsotsi/Designbrnd/issues +**Discussions:** https://github.com/0xtsotsi/Designbrnd/discussions +**Documentation:** https://github.com/0xtsotsi/Designbrnd/tree/main/docs + +--- + +## 🎯 Marketplace Information + +**Marketplace ID:** `webrnds` +**Version:** 1.0.0 +**Author:** Webrnds +**Repository:** https://github.com/0xtsotsi/Designbrnd +**License:** MIT + +**Categories:** +- Design +- Development +- Project Management +- Productivity + +**Keywords:** +design, consulting, automation, figma, testing, workflow, ai-agents, project-management + +--- + +**Last Updated:** 2026-01-10 +**Marketplace Version:** 1.0.0 diff --git a/PUBLISHING.md b/PUBLISHING.md new file mode 100644 index 0000000..25d2031 --- /dev/null +++ b/PUBLISHING.md @@ -0,0 +1,475 @@ +# Publishing Webrnds Marketplace to Claude Code + +Guide for publishing the Webrnds marketplace to the official Claude Code marketplace system. + +--- + +## Prerequisites + +1. **GitHub Repository** + - Repository: https://github.com/0xtsotsi/Designbrnd + - Must be public + - Contains all necessary files + +2. **Required Files** + - ✅ `webrnds-marketplace.json` - Marketplace manifest + - ✅ `install.sh` - Complete installation script + - ✅ `MARKETPLACE.md` - Marketplace documentation + - ✅ All plugin files and documentation + +3. **Accounts** + - GitHub account + - Claude Code account (if required for marketplace submission) + +--- + +## Marketplace Manifest + +The `webrnds-marketplace.json` file defines your marketplace: + +```json +{ + "marketplace": { + "id": "webrnds", + "name": "Webrnds Marketplace", + "version": "1.0.0", + "description": "Complete AI-powered consulting workflow automation", + "author": {...}, + "repository": "https://github.com/0xtsotsi/Designbrnd" + }, + "plugins": [...], + "workflows": [...], + "documentation": {...} +} +``` + +**Key fields:** +- `id`: Unique marketplace identifier +- `name`: Display name +- `version`: Semantic version (1.0.0) +- `repository`: GitHub repo URL +- `plugins`: Array of plugin definitions +- `workflows`: Pre-configured workflows + +--- + +## Publishing Steps + +### Step 1: Verify Repository Structure + +Ensure your repository has this structure: + +``` +Designbrnd/ +├── webrnds-marketplace.json # Marketplace manifest +├── install.sh # Installation script +├── MARKETPLACE.md # Documentation +├── PUBLISHING.md # This file +├── init-workspace.sh # Workspace initializer +├── cloud.md # Figma design rules +├── .claude/ +│ ├── commands/ +│ │ ├── design-os/ # Design OS commands +│ │ ├── marketplace.md # Marketplace command +│ │ ├── ralph-loop.md # RALPH LOOP command +│ │ └── reflect.md # Reflection command +│ ├── hooks/ +│ │ └── user-prompt-submit-beads.sh +│ └── marketplace/ +│ └── registry.json +└── docs/ + ├── consulting-workflow-guide.md + ├── quick-start-guide.md + ├── workspace-initialization-guide.md + └── architecture-diagram.md +``` + +### Step 2: Test Installation Locally + +Before publishing, test the installation script: + +```bash +# Test complete installation +bash install.sh + +# Verify all files installed +ls ~/.claude/commands/design-os/ +ls ~/.claude/skills/ +ls ~/.local/bin/designbrnd-init + +# Test workspace initialization +designbrnd-init "test-project" "Test Client" +cd test-project +/product-vision +``` + +**Verify:** +- ✅ All commands available +- ✅ Skills created +- ✅ Workspace initializer works +- ✅ Documentation accessible + +### Step 3: Create GitHub Release + +```bash +# Tag the release +git tag -a v1.0.0 -m "Webrnds Marketplace v1.0.0 - Initial release" +git push origin v1.0.0 + +# Create GitHub release +# Go to: https://github.com/0xtsotsi/Designbrnd/releases/new +``` + +**Release notes template:** + +```markdown +# Webrnds Marketplace v1.0.0 + +Complete AI-powered consulting workflow automation for Claude Code. + +## What's Included + +- **Design OS Commands** - 8 planning & design commands +- **Figma MCP Integration** - AI-powered design automation +- **RALPH LOOP** - Test-driven development workflow +- **Reflection Skills** - 5 learning modules +- **Beads Integration** - Git-backed task tracking +- **Workspace Initializer** - One-command project setup + +## Installation + +```bash +bash <(curl -fsSL https://raw.githubusercontent.com/0xtsotsi/Designbrnd/main/install.sh) +``` + +## Quick Start + +```bash +designbrnd-init "my-project" "Client Name" +cd my-project +/product-vision +``` + +## Documentation + +- [Marketplace README](./MARKETPLACE.md) +- [Quick Start Guide](./docs/quick-start-guide.md) +- [Workflow Guide](./docs/consulting-workflow-guide.md) + +## What's New in v1.0.0 + +- Initial marketplace release +- Complete workflow automation +- 6-week consulting workflow +- Meta-learning reflection system +- Git-backed task tracking +``` + +### Step 4: Submit to Claude Code Marketplace + +**Method 1: Official Submission Form** + +If Claude Code has a marketplace submission form: + +1. Go to marketplace submission page +2. Fill out form with: + - Marketplace ID: `webrnds` + - Name: Webrnds Marketplace + - Repository: https://github.com/0xtsotsi/Designbrnd + - Manifest URL: https://raw.githubusercontent.com/0xtsotsi/Designbrnd/main/webrnds-marketplace.json + - Installation URL: https://raw.githubusercontent.com/0xtsotsi/Designbrnd/main/install.sh +3. Submit for review + +**Method 2: Pull Request to Official Registry** + +If Claude Code uses a centralized registry: + +1. Fork the official marketplace registry repository +2. Add your marketplace entry: +```json +{ + "marketplaces": [ + { + "id": "webrnds", + "name": "Webrnds Marketplace", + "manifest": "https://raw.githubusercontent.com/0xtsotsi/Designbrnd/main/webrnds-marketplace.json", + "install": "https://raw.githubusercontent.com/0xtsotsi/Designbrnd/main/install.sh", + "description": "Complete AI-powered consulting workflow automation", + "author": "Webrnds", + "repository": "https://github.com/0xtsotsi/Designbrnd", + "version": "1.0.0" + } + ] +} +``` +3. Submit pull request +4. Wait for review and approval + +**Method 3: Community Announcement** + +If Claude Code has community forums/discussions: + +1. Post announcement in marketplace forum +2. Include: + - Marketplace description + - Installation instructions + - Link to repository + - Link to documentation +3. Engage with community feedback + +--- + +## Marketplace URLs + +Once published, your marketplace will be accessible via: + +``` +# Marketplace manifest +https://raw.githubusercontent.com/0xtsotsi/Designbrnd/main/webrnds-marketplace.json + +# Installation script +https://raw.githubusercontent.com/0xtsotsi/Designbrnd/main/install.sh + +# Documentation +https://github.com/0xtsotsi/Designbrnd/blob/main/MARKETPLACE.md +``` + +Users can install with: + +```bash +# Quick install +bash <(curl -fsSL https://raw.githubusercontent.com/0xtsotsi/Designbrnd/main/install.sh) + +# Or via Claude Code (if integrated) +claude marketplace install webrnds +``` + +--- + +## Post-Publishing + +### Announce on Social Media + +**Twitter/X:** +``` +🚀 Just launched Webrnds Marketplace for @ClaudeCode! + +Complete AI-powered consulting workflow: +- Design OS (planning) +- Figma MCP (AI design) +- RALPH LOOP (test-driven dev) +- Reflection AI (learning) +- Beads (task tracking) + +Install: [link] +Docs: [link] + +#ClaudeCode #AIAutomation #Consulting +``` + +**LinkedIn:** +``` +Excited to announce Webrnds Marketplace for Claude Code! 🎉 + +We've created a complete consulting workflow automation system that: +- Reduces project timelines from 12-16 weeks to 6 weeks +- Automates design creation with AI +- Guarantees pixel-perfect quality through test-driven development +- Learns and improves with every project + +Perfect for consultants, agencies, and freelancers helping clients with websites, apps, and digital products. + +Install in 2 minutes: [link] +Full workflow guide: [link] + +[Add visual: workflow diagram or demo screenshot] +``` + +### Create Demo Video + +Record a 5-10 minute demo showing: +1. Installation (`bash install.sh`) +2. Project initialization (`designbrnd-init`) +3. Running through discovery (`/product-vision`, `/product-roadmap`) +4. Creating designs with Figma MCP +5. RALPH LOOP in action +6. Reflection system learning + +Upload to YouTube and link in README. + +### Blog Post + +Write a detailed blog post covering: +- Problem: Traditional consulting pain points +- Solution: Automated workflow +- Tools: Each plugin explained +- Results: Time savings, ROI, quality improvements +- Getting started: Installation and first project + +--- + +## Versioning + +Follow semantic versioning (semver): + +**Format:** MAJOR.MINOR.PATCH + +**Examples:** +- `1.0.0` - Initial release +- `1.0.1` - Bug fix (backward compatible) +- `1.1.0` - New feature (backward compatible) +- `2.0.0` - Breaking change + +**Update process:** +1. Update `version` in `webrnds-marketplace.json` +2. Update `version` in each plugin definition +3. Update MARKETPLACE.md with changes +4. Git tag: `git tag -a v1.1.0 -m "Version 1.1.0"` +5. Push: `git push origin v1.1.0` +6. Create GitHub release +7. Update marketplace registry (if applicable) + +--- + +## Maintenance + +### Regular Updates + +**Monthly:** +- Review and respond to GitHub issues +- Update documentation based on user feedback +- Check for dependency updates +- Test installation on clean systems + +**Quarterly:** +- Review and update workflow guides +- Add new features or plugins +- Update version numbers +- Announce updates + +### Community Engagement + +**GitHub:** +- Monitor issues and pull requests +- Respond within 24-48 hours +- Accept community contributions +- Maintain issue templates + +**Documentation:** +- Keep guides updated +- Add FAQ based on common questions +- Create troubleshooting guides +- Add examples and case studies + +--- + +## Metrics to Track + +**Installation Metrics:** +- Number of installs (if available) +- GitHub stars +- GitHub forks +- Repository clones + +**Engagement Metrics:** +- GitHub issues opened +- Pull requests submitted +- Discussions started +- Documentation page views + +**Quality Metrics:** +- Issue resolution time +- PR merge rate +- User feedback sentiment +- Bug reports vs. feature requests + +--- + +## Support Channels + +**GitHub Issues:** +- Bug reports +- Feature requests +- Questions + +**GitHub Discussions:** +- General questions +- Show and tell +- Ideas and suggestions + +**Documentation:** +- README.md - Overview +- MARKETPLACE.md - Plugin details +- docs/ - Detailed guides + +--- + +## Troubleshooting Common Issues + +### Installation Fails + +**Issue:** `install.sh` fails with permission errors + +**Solution:** +```bash +# Make executable +chmod +x install.sh + +# Run with bash explicitly +bash install.sh +``` + +### Commands Not Available + +**Issue:** `/product-vision` not found + +**Solution:** +```bash +# Check if commands installed +ls ~/.claude/commands/design-os/ + +# Restart Claude Code session + +# Manually copy if needed +cp -r .claude/commands/design-os ~/.claude/commands/ +``` + +### Figma MCP Not Connecting + +**Issue:** Figma plugin shows "Not connected" + +**Solution:** +See `~/.claude/mcp-servers/figma-mcp.json` for full setup instructions. + +--- + +## Legal & Compliance + +### License + +MIT License - Allows commercial and private use, modification, distribution. + +### Attribution + +If using external tools: +- Figma MCP Server: https://github.com/Antonytm/figma-mcp-server +- Beads: https://github.com/steveyegge/beads + +### Privacy + +- No data collection +- All processing local +- Git-backed storage (user-controlled) + +--- + +## Contact & Support + +**Maintainer:** Webrnds +**Repository:** https://github.com/0xtsotsi/Designbrnd +**Issues:** https://github.com/0xtsotsi/Designbrnd/issues +**Discussions:** https://github.com/0xtsotsi/Designbrnd/discussions + +--- + +**Ready to publish?** Follow the steps above and launch your marketplace! 🚀 diff --git a/cloud.md b/cloud.md new file mode 100644 index 0000000..265f86a --- /dev/null +++ b/cloud.md @@ -0,0 +1,330 @@ +# Figma Design Rules for Design OS Projects + +## Document Organization + +### Page Structure +- **Page 1: Brand Guidelines** - Color palette, typography scale, design tokens documentation +- **Page 2: Components** - All reusable components (buttons, inputs, cards, navigation, etc.) +- **Page 3+: Screens** - One page per section (Homepage, Menu, About, Contact, etc.) +- **Social Templates** - Social media post/story templates (if applicable) + +### Spacing & Layout +- Do NOT put everything on the same coordinates +- Pages should have nice hierarchical structure with auto layouts +- Space elements vertically with proper gaps (never overlap) +- Use 8px grid system: 8, 16, 24, 32, 40, 48, 64, 80px + +--- + +## Component Creation Standards + +### Component Creation Process +- Components should be created using create-component tool +- All parts of the component should be ancestors of the component node +- Component properties should be added using `add-component-property` tool +- Component property usage on ancestors should be added by `set-node-component-property-references` + +### Component Layout Rules +- If component uses **vertical auto layout**: + - Component should use fixed width + - Children should use `layoutSizingHorizontal: FILL` +- If component uses **horizontal auto layout**: + - Component should use fixed height + - Children should use `layoutSizingVertical: FILL` + +### Auto Layout Requirements +- **Use auto layout for everything!** +- For columns layout: use horizontal auto layout +- For rows layout: use vertical auto layout +- Prefer Frames over Rectangles everywhere +- Input controls should be frames (allows flexibility of setting layout) + +### Component Instances +- Consider using `layoutSizingHorizontal: FILL` if component needs full width of container +- Consider using `layoutSizingVertical: FILL` if component needs full height of container + +--- + +## Component Library Standards + +### Button Component +**Variants:** Primary, Secondary, Outline +**Sizes:** Small (36px), Medium (44px), Large (52px) +**States:** Default, Hover, Disabled + +- Use horizontal auto layout +- Padding: 12px (sm), 16px (md), 20px (lg) +- Border-radius: 8px +- Use component properties for variant selection +- Use color styles (never hard-coded hex values) +- Text should use text styles from brand guidelines + +### Input Field Component +**Types:** Text, Email, Password, TextArea +**States:** Default, Focus, Error, Disabled + +- Height: 48px (for text inputs) +- Padding: 12px horizontal, 14px vertical +- Border: 1px stroke +- Border-radius: 6px +- Use vertical auto layout for label + input pairing +- Label spacing: 8px gap +- Use component properties for type and state + +### Card Component +**Variants:** Default, Elevated, Outlined +**Sections:** Header, Body, Footer + +- Use vertical auto layout +- Padding: 24px +- Border-radius: 8px +- Gap between sections: 16px +- Shadow: Use effect styles (0px 2px 8px rgba(0,0,0,0.1) for elevated) +- Allow FILL sizing for content areas + +### Navigation Component +**Variants:** Mobile, Desktop +**States:** Default, Sticky + +- Desktop: Horizontal auto layout +- Mobile: Vertical auto layout +- Padding: 16px (mobile), 24px (desktop) +- Logo area + menu items + actions +- Use component properties for active states +- Menu items should use hover states + +--- + +## Typography System + +### Text Styles Required +Create text styles for all typography: + +**Display (Heading Font):** +- Display/H1: 48px, weight 700, line-height 1.2 +- Display/H2: 40px, weight 700, line-height 1.2 +- Display/H3: 32px, weight 600, line-height 1.3 +- Display/H4: 24px, weight 600, line-height 1.4 + +**Body (Body Font):** +- Body/Large: 18px, weight 400, line-height 1.6 +- Body/Medium: 16px, weight 400, line-height 1.5 +- Body/Small: 14px, weight 400, line-height 1.5 +- Caption: 12px, weight 400, line-height 1.4 + +**Usage:** +- Always use text styles (never hard-code font settings) +- Use semantic naming (H1 for main headlines, H2 for sections, etc.) +- Mobile: Reduce font sizes by 25-30% (H1: 48px → 32px) + +--- + +## Color System + +### Color Variables Required +Create color styles for all brand colors from Design OS tokens: + +**Primary Color:** +- Primary/50 through Primary/900 (9 shades) +- Primary/500 as default brand color + +**Secondary Color:** +- Secondary/50 through Secondary/900 (9 shades) +- Secondary/500 as default + +**Neutral Colors:** +- Neutral/50 through Neutral/900 (stone/gray palette) +- Use for backgrounds, borders, text + +**Semantic Colors:** +- Success: Green shades for positive actions +- Error: Red shades for errors/warnings +- Warning: Yellow/orange for caution + +### Color Usage Rules +- Use color styles for ALL colors (never use hex codes directly) +- Support light and dark mode variants where applicable +- Backgrounds: Neutral/50 (light), Neutral/900 (dark) +- Text: Neutral/900 (light mode), Neutral/50 (dark mode) +- Borders: Neutral/200 (light), Neutral/700 (dark) + +--- + +## Screen Design Standards + +### Desktop Layouts (1440px width) +- Container max-width: 1280px +- Horizontal padding: 80px +- Section vertical spacing: 80px +- Use horizontal auto layout for multi-column sections +- Grid columns: 12-column grid, 24px gutters + +### Mobile Layouts (375px width) +- Horizontal padding: 16px +- Section vertical spacing: 48px +- Stack all columns to single column (vertical auto layout) +- Touch targets: Minimum 44x44px for buttons/links + +### Responsive Patterns +- Desktop multi-column → Mobile single column +- Horizontal navigation → Vertical hamburger menu +- Large hero images → Smaller, optimized images +- Reduce font sizes (see Typography section) + +--- + +## Common Screen Sections + +### Hero Section +- Height: 600px (desktop), 400px (mobile) +- Background image with overlay (40% black for text readability) +- Centered content: Headline (H1), Subheadline (Body/Large), CTA (Button/Large) +- Use vertical auto layout for text stacking (24px gaps) + +### Content Grid (3-column) +- Desktop: Horizontal auto layout, 3 items, 24px gap +- Mobile: Vertical auto layout, 1 item, 24px gap +- Each item: Card component with image, title (H3), description, CTA + +### Testimonial Section +- 2-column layout (desktop), 1-column (mobile) +- Card components with quote, author name, rating +- Gap: 32px between cards + +### Footer CTA Section +- Background: Primary color +- Centered content: Headline (H2), CTA (Button/Large) +- Padding: 64px vertical, 80px horizontal + +--- + +## Social Media Templates + +### Instagram Post (1080x1080) +- Use vertical auto layout +- Padding: 60px +- Include brand colors and typography +- Clear areas for image, headline, description +- Logo placement: Top-left or bottom-right + +### Instagram Story (1080x1920) +- Safe zones: 250px top, 250px bottom +- Use vertical auto layout +- Content centered in safe zone +- Touch targets for interaction: 44px minimum + +### Facebook Cover (1200x630) +- Horizontal auto layout +- Logo + brand message + CTA +- Account for profile picture overlap (left side) + +--- + +## Naming Conventions + +### Components +- Use PascalCase: `ButtonPrimary`, `CardElevated`, `InputText` +- Descriptive and semantic names + +### Frames & Layers +- Use kebab-case: `hero-section`, `featured-dishes-grid`, `cta-button` +- Clear, descriptive names for easy navigation + +### Component Properties +- Use camelCase: `buttonVariant`, `inputState`, `cardSize` +- Boolean properties: `isDisabled`, `hasIcon`, `isActive` + +--- + +## Quality Checklist + +Before marking design complete, verify: + +- [ ] All components use auto layout +- [ ] All colors use color styles (no hard-coded hex) +- [ ] All text uses text styles (no hard-coded fonts) +- [ ] Components organized on "Components" page +- [ ] Screens organized on separate pages +- [ ] Desktop (1440px) and Mobile (375px) versions created +- [ ] Proper spacing (8px grid system) +- [ ] No overlapping elements +- [ ] Component properties set up correctly +- [ ] Component instances used (not duplicates) +- [ ] Naming conventions followed +- [ ] Responsive layouts tested (FILL sizing where needed) + +--- + +## Integration with Design OS + +### Design Token Sync +- Import colors from `design-system/colors.json` +- Import typography from `design-system/typography.json` +- Maintain consistency between Design OS and Figma + +### Component Matching +- Figma components should match Design OS `/design-screen` outputs +- Use same naming conventions +- Same variant structure (Primary/Secondary, Small/Medium/Large) + +### Handoff to Development +- Enable Figma Dev Mode for developer access +- Export assets in @1x, @2x, @3x for responsive images +- Document component properties for developer reference +- Provide CSS variable names matching design tokens + +--- + +## Performance & Best Practices + +### File Organization +- Keep components library clean and organized +- Archive unused components +- Use clear naming for easy search +- Group related components (Forms, Navigation, Cards, etc.) + +### Prototyping +- Add basic interactions for user flow testing +- Link screens together for client review +- Use overlays for modals/dropdowns +- Prototype mobile navigation (hamburger menu) + +### Collaboration +- Use comments for client feedback +- Version control for design iterations +- Share links with "View Only" for client review +- Share links with "Can Edit" for team collaboration + +--- + +## Example AI Prompts + +### Create Component Library +``` +Using the design tokens from colors.json and typography.json, create a complete +component library on the "Components" page with Button, Input, Card, and +Navigation components. Follow all rules in cloud.md for auto layout, +component properties, and naming conventions. +``` + +### Create Screen Design +``` +Using the approved component library and the homepage spec from +product/sections/homepage/spec.md, create a homepage design on the +"Screens/Homepage" page. Include hero section, content grid, testimonials, +and footer CTA. Create both desktop (1440px) and mobile (375px) versions. +Follow all spacing and layout rules from cloud.md. +``` + +### Iterate on Design +``` +Update the homepage hero section: increase height to 800px, change CTA +button to Secondary variant, and add a second CTA button (Outline variant). +Maintain proper spacing using auto layout. +``` + +--- + +**Token Count Target:** ~2,450 tokens +**Last Updated:** 2026-01-10 +**For:** Design OS + Figma MCP Workflow diff --git a/docs/architecture-diagram.md b/docs/architecture-diagram.md new file mode 100644 index 0000000..9762a5f --- /dev/null +++ b/docs/architecture-diagram.md @@ -0,0 +1,503 @@ +# Complete System Architecture +## Designbrnd AI-Powered Consulting Workflow + +--- + +## High-Level Architecture + +```mermaid +graph TB + subgraph "Workspace Initialization" + INIT[init-workspace.sh] + MARKET[Marketplace Registry] + INIT --> MARKET + end + + subgraph "Orchestration Layer" + BEADS[🔷 Beads
Project Tracker] + BEADS --> TASKS[Task Dependencies] + BEADS --> MEMORY[Persistent Memory] + BEADS --> READY[Ready Tasks] + end + + subgraph "Learning Layer" + REFLECT[🧠 Reflection System] + SKILLS[Skills Database] + HOOKS[Event Hooks] + REFLECT --> SKILLS + HOOKS --> REFLECT + end + + subgraph "Workflow Tools" + DOS[📋 Design OS
Planning] + FIGMA[🎨 Figma MCP
Design] + RALPH[🔨 RALPH LOOP
Build + QA] + + DOS --> FIGMA + FIGMA --> RALPH + end + + subgraph "Output" + CLIENT[👤 Client Deliverables] + LAUNCH[🚀 Production Site] + end + + INIT -.installs.-> DOS + INIT -.installs.-> FIGMA + INIT -.installs.-> RALPH + INIT -.installs.-> REFLECT + INIT -.installs.-> BEADS + + BEADS -.orchestrates.-> DOS + BEADS -.orchestrates.-> FIGMA + BEADS -.orchestrates.-> RALPH + + REFLECT -.improves.-> DOS + REFLECT -.improves.-> FIGMA + REFLECT -.improves.-> RALPH + + DOS --> CLIENT + FIGMA --> CLIENT + RALPH --> LAUNCH + LAUNCH --> CLIENT + + style INIT fill:#f9f,stroke:#333,stroke-width:4px + style BEADS fill:#bbf,stroke:#333,stroke-width:3px + style REFLECT fill:#fbf,stroke:#333,stroke-width:3px + style DOS fill:#bfb,stroke:#333,stroke-width:2px + style FIGMA fill:#fdb,stroke:#333,stroke-width:2px + style RALPH fill:#fbb,stroke:#333,stroke-width:2px +``` + +--- + +## Detailed Component Architecture + +```mermaid +graph LR + subgraph "Initialization" + I1[Prerequisites Check] + I2[Workspace Creation] + I3[Tool Installation] + I4[Configuration] + I5[Git Setup] + + I1 --> I2 + I2 --> I3 + I3 --> I4 + I4 --> I5 + end + + subgraph "Design OS" + D1[/product-vision] + D2[/product-roadmap] + D3[/data-model] + D4[/design-tokens] + D5[/shape-section] + D6[/sample-data] + D7[/export-product] + + D1 --> D2 + D2 --> D3 + D3 --> D4 + D4 --> D5 + D5 --> D6 + D6 --> D7 + end + + subgraph "Figma MCP" + F1[AI Agent] + F2[MCP Server] + F3[WebSocket] + F4[Figma Plugin] + F5[Figma Document] + + F1 <--> F2 + F2 <--> F3 + F3 <--> F4 + F4 <--> F5 + end + + subgraph "RALPH LOOP" + R1[Write Tests] + R2[Run Tests - FAIL] + R3[Implement] + R4[Run Tests - PASS] + R5[Verify Screenshots] + R6[Fix Issues] + R7[Mark Verified] + R8[Promise DONE] + + R1 --> R2 + R2 --> R3 + R3 --> R4 + R4 --> R5 + R5 --> R6 + R6 --> R4 + R5 --> R7 + R7 --> R8 + end + + subgraph "Beads" + B1[Initialize] + B2[Create Tasks] + B3[Track Dependencies] + B4[Show Ready] + B5[Mark Complete] + B6[Git Commit] + + B1 --> B2 + B2 --> B3 + B3 --> B4 + B4 --> B5 + B5 --> B6 + end + + subgraph "Reflection" + RF1[Session Work] + RF2[User Corrections] + RF3[Pattern Detection] + RF4[Skill Updates] + RF5[Git Commit] + + RF1 --> RF2 + RF2 --> RF3 + RF3 --> RF4 + RF4 --> RF5 + end + + I5 --> D1 + D7 --> R1 + D4 --> F1 +``` + +--- + +## Data Flow Architecture + +```mermaid +flowchart TD + START([New Client Project]) + + START --> INIT{Initialize Workspace} + + INIT --> |Week 1| DISC[Discovery Phase] + DISC --> PV[/product-vision] + DISC --> PR[/product-roadmap] + DISC --> DM[/data-model] + + PV --> BD1[Beads: Track Tasks] + PR --> BD1 + DM --> BD1 + + BD1 --> |Week 2| BRAND[Brand Design Phase] + BRAND --> DT[/design-tokens] + DT --> TOKENS[(colors.json
typography.json)] + + TOKENS --> FMCP1[Figma MCP:
Create Brand System] + FMCP1 --> FIGMA1[(Figma File:
Brand Guidelines)] + + FIGMA1 --> CLIENT1{Client Approval} + CLIENT1 --> |Approved| BD2[Beads: Mark Complete] + CLIENT1 --> |Changes| FMCP1 + + BD2 --> |Week 3| SCREEN[Screen Design Phase] + SCREEN --> SS[/shape-section] + SCREEN --> SD[/sample-data] + + SS --> SPECS[(spec.md)] + SD --> DATA[(data.json)] + + SPECS --> FMCP2[Figma MCP:
Create Screens] + DATA --> FMCP2 + FIGMA1 --> FMCP2 + + FMCP2 --> FIGMA2[(Figma File:
Screen Designs)] + + FIGMA2 --> CLIENT2{Client Approval} + CLIENT2 --> |Approved| BD3[Beads: Mark Complete] + CLIENT2 --> |Changes| FMCP2 + + BD3 --> |Week 4-5| IMPL[Implementation Phase] + IMPL --> EXP[/export-product] + EXP --> PACK[(product-plan.zip)] + + PACK --> TESTS[Write E2E Tests] + FIGMA2 --> TESTS + + TESTS --> RL[RALPH LOOP] + RL --> |Run| FAIL{Tests Pass?} + FAIL --> |No| IMP[Implement Components] + IMP --> RL + + FAIL --> |Yes| VER[Verify Screenshots] + VER --> |Issues| FIX[Fix Visual Issues] + FIX --> RL + + VER --> |OK| VERIFIED[Mark Verified] + VERIFIED --> PROMISE[Promise: DONE] + + PROMISE --> BD4[Beads: Mark Complete] + + BD4 --> |Week 6| LAUNCH[Launch Phase] + LAUNCH --> DEPLOY[Deploy to Production] + DEPLOY --> HANDOFF[Client Handoff] + + HANDOFF --> END([Project Complete]) + + subgraph "Continuous Learning" + REFLECT[/reflect] + SKILLS[(Skills Database)] + REFLECT --> SKILLS + SKILLS -.improves.-> PV + SKILLS -.improves.-> DT + SKILLS -.improves.-> FMCP1 + SKILLS -.improves.-> FMCP2 + SKILLS -.improves.-> RL + end + + CLIENT1 -.feedback.-> REFLECT + CLIENT2 -.feedback.-> REFLECT + PROMISE -.patterns.-> REFLECT + + style START fill:#f9f + style END fill:#bfb + style INIT fill:#bbf + style REFLECT fill:#fbf + style PROMISE fill:#fbb +``` + +--- + +## Marketplace System Architecture + +```mermaid +graph TD + subgraph "Registry" + REG[registry.json] + MCP[MCP Servers] + SKILLS[Skills] + HOOKS[Hooks] + TOOLS[Tools] + WORKFLOWS[Workflows] + + REG --> MCP + REG --> SKILLS + REG --> HOOKS + REG --> TOOLS + REG --> WORKFLOWS + end + + subgraph "Installation" + CMD[/marketplace] + BROWSE[Browse Tools] + INFO[Get Info] + INSTALL[Install Tool] + + CMD --> BROWSE + CMD --> INFO + CMD --> INSTALL + end + + subgraph "Tools Available" + T1[Figma MCP
Design Automation] + T2[Design OS
Planning] + T3[RALPH LOOP
Testing] + T4[Beads
Project Tracking] + T5[Reflection
Learning] + end + + REG --> CMD + INSTALL --> T1 + INSTALL --> T2 + INSTALL --> T3 + INSTALL --> T4 + INSTALL --> T5 + + T1 -.uses.-> MCP + T2 -.uses.-> WORKFLOWS + T3 -.uses.-> TOOLS + T4 -.uses.-> TOOLS + T5 -.uses.-> SKILLS + T5 -.uses.-> HOOKS +``` + +--- + +## Hooks & Events Architecture + +```mermaid +sequenceDiagram + participant User + participant Claude + participant Hook System + participant Beads + participant Reflection + participant Git + + User->>Claude: Submit prompt + Hook System->>Beads: Check ready tasks + Beads-->>Hook System: Return task list + Hook System->>Claude: Display ready tasks + Claude->>User: Response + task info + + User->>Claude: Complete work + Claude->>User: Deliver result + + User->>Claude: Stop session + Hook System->>Reflection: Analyze session + Reflection->>Reflection: Detect patterns + Reflection->>Git: Check untracked files + Git-->>Reflection: File status + Reflection->>Hook System: Show notification + Hook System->>User: "✓ Learned from session" + Hook System->>User: "⚠ Untracked files - commit?" + + User->>Claude: /reflect skill-name + Claude->>Reflection: Propose updates + Reflection->>User: Show changes + User->>Reflection: Approve + Reflection->>Git: Commit skill updates + Git-->>User: "✓ Skill updated" +``` + +--- + +## File System Architecture + +``` +workspace-root/ +│ +├── product/ ← Design OS outputs +│ ├── product-overview.md ← /product-vision +│ ├── product-roadmap.md ← /product-roadmap +│ ├── data-model/ +│ │ └── data-model.md ← /data-model +│ ├── design-system/ +│ │ ├── colors.json ← /design-tokens +│ │ └── typography.json ← /design-tokens +│ └── sections/ +│ └── [section-id]/ +│ ├── spec.md ← /shape-section +│ ├── data.json ← /sample-data +│ └── *.png ← Screenshots +│ +├── src/ ← Next.js app +│ ├── app/ ← App Router +│ ├── components/ +│ │ └── ui/ ← shadcn/ui +│ └── lib/ +│ +├── e2e/ ← Playwright tests +│ ├── screenshots/ +│ │ └── [feature]/ +│ │ └── verified_*.png ← RALPH LOOP verified +│ └── *.spec.ts ← E2E tests +│ +├── .beads/ ← Beads storage +│ └── *.jsonl ← Task data (git-tracked) +│ +├── .claude/ ← Claude config +│ ├── commands/ ← All commands +│ │ ├── design-os/ ← Design OS cmds +│ │ ├── marketplace.md ← Marketplace +│ │ ├── ralph-loop.md ← RALPH guidance +│ │ ├── reflect.md ← Reflection +│ │ └── beads-init.md ← Beads setup +│ │ +│ ├── marketplace/ +│ │ └── registry.json ← Tool registry +│ │ +│ ├── hooks/ +│ │ ├── stop-hook-reflect.sh ← Auto-reflect +│ │ └── user-prompt-submit-beads.sh ← Beads integration +│ │ +│ └── mcp-servers/ +│ └── figma-mcp.json ← MCP config +│ +├── ~/.claude/skills/ ← Global skills +│ ├── client-discovery/SKILL.md +│ ├── brand-design/SKILL.md +│ ├── figma-design/SKILL.md +│ ├── implementation/SKILL.md +│ └── qa-verification/SKILL.md +│ +├── cloud.md ← Figma design rules +├── .beads-template.json ← Project template +├── package.json ← Dependencies +├── playwright.config.ts ← Test config +└── README.md ← Documentation +``` + +--- + +## Integration Points + +### Design OS → Figma MCP + +``` +Design OS Output → Figma MCP Input +───────────────────────────────────────────── +colors.json → Create color styles +typography.json → Create text styles +spec.md → Screen structure +data.json → Sample content +cloud.md → Design rules +``` + +### Figma MCP → RALPH LOOP + +``` +Figma Output → RALPH LOOP Input +───────────────────────────────────────────── +Screen designs → E2E test specs +Component library → shadcn/ui selection +Color styles → CSS color values +Typography scale → Font size tests +Layout structure → DOM assertions +``` + +### RALPH LOOP → Beads + +``` +RALPH LOOP Events → Beads Actions +───────────────────────────────────────────── +Tests written → Mark task "in progress" +Tests passing → Update checklist item +Screenshots verified → Update checklist item +Promise DONE → Mark task "complete" +``` + +### Reflection → All Tools + +``` +Tool Usage → Skill Learning +───────────────────────────────────────────── +/product-vision → client-discovery skill +/design-tokens → brand-design skill +Figma MCP usage → figma-design skill +RALPH LOOP → implementation skill +Screenshot verify → qa-verification skill +``` + +--- + +## Summary + +This architecture provides: + +✅ **One-Command Init** - `init-workspace.sh` sets up everything +✅ **Orchestration** - Beads tracks all tasks with dependencies +✅ **Learning** - Reflection system improves with every project +✅ **Automation** - Figma MCP creates designs in minutes +✅ **Quality** - RALPH LOOP ensures pixel-perfect builds +✅ **Marketplace** - Browse and install tools easily +✅ **Hooks** - Event-driven automation +✅ **Complete Workflow** - 6 weeks from discovery to launch + +**Result:** The most advanced AI-powered consulting workflow in existence. + +--- + +**Last Updated:** 2026-01-10 +**Version:** 1.0 diff --git a/docs/consulting-workflow-guide.md b/docs/consulting-workflow-guide.md new file mode 100644 index 0000000..54c5a87 --- /dev/null +++ b/docs/consulting-workflow-guide.md @@ -0,0 +1,819 @@ +# Complete Consulting Workflow Guide +## Design OS + Figma MCP + RALPH LOOP + Reflection System + +--- + +## Overview + +This guide documents the complete automated workflow for design consultants helping clients create and manage digital assets (websites, SEO, marketing, social media, etc.). The workflow integrates four powerful tools: + +1. **Design OS** - Planning and requirements gathering +2. **Figma MCP Server** - AI-powered visual design +3. **RALPH LOOP** - Test-driven development with quality gates +4. **Claude Reflection System** - Meta-learning that improves over time + +--- + +## The Problem This Solves + +### Traditional Consulting Pain Points: +- ❌ Endless client revisions ("this isn't what I wanted") +- ❌ Scope creep and unclear boundaries +- ❌ Misaligned expectations +- ❌ Repeating the same corrections every project +- ❌ Inconsistent quality across clients +- ❌ Long delivery timelines (8-12 weeks) + +### This Workflow Delivers: +- ✅ Client approves designs BEFORE implementation +- ✅ Clear scope locked in Phase 1 +- ✅ Visual mockups eliminate surprises +- ✅ Skills learn from corrections (never repeat) +- ✅ Consistent professional quality +- ✅ Faster delivery (4-6 weeks) + +--- + +## Complete Workflow Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 🧠 REFLECTION SYSTEM (Meta-Learning Layer) │ +│ • Captures corrections from all phases │ +│ • Updates skills automatically │ +│ • Improves quality with every project │ +└─────────────────────────────────────────────────────────────┘ + ↓ ↓ ↓ +┌──────────────────────────────────────────────────────────────┐ +│ PHASE 1: DISCOVERY & PLANNING (Week 1) │ +│ Tool: Design OS │ +├──────────────────────────────────────────────────────────────┤ +│ • /product-vision → Document business goals │ +│ • /product-roadmap → Define deliverable sections │ +│ • /data-model → Structure data requirements │ +│ Output: Written specs, approved scope │ +│ Client Checkpoint: ✅ Approve vision & roadmap │ +└──────────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────────┐ +│ PHASE 2: BRAND SYSTEM DESIGN (Week 2 - Part 1) │ +│ Tools: Design OS → Figma MCP │ +├──────────────────────────────────────────────────────────────┤ +│ Design OS: │ +│ • /design-tokens → colors.json, typography.json │ +│ │ +│ Figma MCP (AI-Powered): │ +│ • AI reads design tokens + cloud.md rules │ +│ • Creates Brand Guidelines page (colors, typography) │ +│ • Creates Components page (buttons, inputs, cards, nav) │ +│ • All auto-layout, component properties, best practices │ +│ │ +│ Time: 10 minutes vs. 2-4 hours manual │ +│ Client Checkpoint: ✅ Approve brand identity │ +└──────────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────────┐ +│ PHASE 3: SCREEN DESIGN (Week 2-3) │ +│ Tools: Design OS → Figma MCP → Design OS (optional) │ +├──────────────────────────────────────────────────────────────┤ +│ For each section: │ +│ │ +│ Design OS: │ +│ • /shape-section → Define requirements, user flows │ +│ • /sample-data → Generate realistic content │ +│ │ +│ Figma MCP (AI-Powered): │ +│ • AI reads specs + sample data + component library │ +│ • Creates screen designs (desktop 1440px + mobile 375px) │ +│ • Uses components, follows cloud.md rules │ +│ • Client reviews professional mockups │ +│ │ +│ Iteration: Client requests changes → AI updates in 2 mins │ +│ │ +│ Optional - Design OS: │ +│ • /design-screen → Interactive React prototype │ +│ • For testing user flows quickly │ +│ │ +│ Time per section: 15 minutes vs. 3-5 hours manual │ +│ Client Checkpoint: ✅ Approve all screen designs │ +└──────────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────────┐ +│ PHASE 4: ASSET CREATION (Week 3) │ +│ Tools: Figma MCP │ +├──────────────────────────────────────────────────────────────┤ +│ • AI creates social media template library │ +│ - Instagram posts (5 variations) │ +│ - Instagram stories (3 variations) │ +│ - Facebook covers │ +│ • All editable by client or VA │ +│ │ +│ Client Checkpoint: ✅ Approve templates │ +└──────────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────────┐ +│ PHASE 5: IMPLEMENTATION (Week 4-5) │ +│ Tools: Design OS Export + Figma + RALPH LOOP │ +├──────────────────────────────────────────────────────────────┤ +│ Step 1: Export from Design OS │ +│ • /export-product → product-plan.zip │ +│ • Contains: Components, tokens, data, types │ +│ │ +│ Step 2: Figma Developer Handoff │ +│ • Enable Dev Mode, share links │ +│ • Export assets (images, icons, logos) │ +│ │ +│ Step 3: Write E2E Tests from Figma Designs │ +│ • Tests encode exact Figma specs (layout, colors, fonts) │ +│ • Visual regression tests with screenshots │ +│ │ +│ Step 4: RALPH LOOP (per feature) │ +│ • Run tests → FAIL │ +│ • AI implements with shadcn/ui + design tokens │ +│ • Run tests → PASS │ +│ • AI verifies screenshots vs. Figma │ +│ • AI fixes visual issues │ +│ • Re-run tests → PASS │ +│ • Rename screenshots to verified_* │ +│ • FEATURE_DONE │ +│ │ +│ Repeat for all sections │ +└──────────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────────┐ +│ PHASE 6: CLIENT REVIEW & LAUNCH (Week 6) │ +├──────────────────────────────────────────────────────────────┤ +│ • Client reviews staging site │ +│ • Pixel-perfect match to approved Figma designs │ +│ • All tests passing │ +│ • Deploy to production │ +│ │ +│ Client Receives: │ +│ • Live website │ +│ • Figma files for reference │ +│ • Social media templates to use │ +│ • Complete documentation │ +└──────────────────────────────────────────────────────────────┘ +``` + +--- + +## Timeline Comparison + +| Traditional Process | Automated Workflow | +|--------------------|--------------------| +| 12-16 weeks | 6 weeks | +| 5-10 revision cycles | 1-2 iterations | +| Client sees designs at END | Client approves UPFRONT | +| Scope creep common | Scope locked Phase 1 | +| Manual Figma design (20+ hours) | AI-powered (2-3 hours) | +| Manual testing | Automated RALPH LOOP | +| Repeat corrections every project | Reflection system learns | + +--- + +## Tool Integration Details + +### 1. Design OS (Planning Layer) + +**Purpose:** Document requirements, define scope, generate sample data + +**Key Commands:** +- `/product-vision` - Capture business goals, target audience, problems/solutions +- `/product-roadmap` - Break project into deliverable sections +- `/data-model` - Define entities and relationships +- `/design-tokens` - Select colors and typography +- `/shape-section` - Define section requirements and user flows +- `/sample-data` - Generate realistic content +- `/design-screen` - Create interactive React prototypes (optional) +- `/export-product` - Generate complete handoff package + +**Output Files:** +- `product/product-overview.md` +- `product/product-roadmap.md` +- `product/data-model/data-model.md` +- `product/design-system/colors.json` +- `product/design-system/typography.json` +- `product/sections/[id]/spec.md` +- `product/sections/[id]/data.json` +- `product-plan.zip` (export) + +**Value:** +- Structured discovery process +- Client approval checkpoints +- Reusable sample data +- Developer-ready specs + +--- + +### 2. Figma MCP Server (Visual Design Layer) + +**Purpose:** AI-powered Figma design creation and modification + +**How It Works:** +1. MCP Server communicates with Figma via WebSocket +2. Figma plugin executes design commands in Figma document +3. AI reads `cloud.md` rules for best practices +4. AI reads design tokens from Design OS +5. AI creates/modifies Figma designs automatically + +**Capabilities:** +- Create component libraries (buttons, inputs, cards, etc.) +- Design complete screens (desktop + mobile) +- Apply brand colors and typography +- Use auto-layout for responsive designs +- Create social media templates +- Iterate on designs in minutes (not hours) + +**Key Features:** +- **Auto-layout:** All components responsive by default +- **Component properties:** Variants for different states +- **Color/text styles:** Consistent design system +- **Undo/redo:** Non-destructive workflow +- **20x faster:** 15 minutes vs. 3-5 hours per screen + +**Configuration:** +- `cloud.md` - Design rules and best practices (at project root) +- Design tokens from Design OS (`colors.json`, `typography.json`) + +**Example Workflow:** +``` +You (to Claude with Figma MCP): +"Using the design tokens from Design OS and following cloud.md rules, +create a complete brand system in Figma with brand guidelines page +and component library." + +AI: Creates professional Figma file in 10 minutes +``` + +--- + +### 3. RALPH LOOP (Implementation QA Layer) + +**Purpose:** Test-driven development with automated quality gates + +**How It Works:** +1. Write E2E tests encoding approved Figma designs +2. Run tests → FAIL (no implementation yet) +3. AI implements components to pass tests +4. Run tests → PASS +5. AI reads screenshots and verifies visual quality +6. AI fixes any visual issues found +7. Re-run tests until all verified +8. Rename screenshots to `verified_*` prefix +9. Output: `FEATURE_DONE` + +**Technology Stack:** +- Framework: Next.js/React +- Testing: Playwright E2E +- UI Components: shadcn/ui (based on Radix UI) +- Styling: Tailwind CSS + +**Quality Gates:** +- ✅ Functional tests pass (elements present, correct text, colors) +- ✅ Visual verification (screenshots match Figma) +- ✅ Responsive tests (mobile + desktop) +- ✅ Accessibility checks (contrast ratios, touch targets) + +**Example Test:** +```typescript +// e2e/homepage-hero.spec.ts +test('hero section matches Figma design', async ({ page }) => { + await page.goto('/'); + + const hero = page.getByTestId('homepage-hero'); + await expect(hero).toBeVisible(); + + // Test exact color from design tokens + const ctaButton = page.getByTestId('hero-cta'); + await expect(ctaButton).toHaveCSS('background-color', 'rgb(220, 38, 38)'); + + // Visual regression + await page.screenshot({ path: 'e2e/screenshots/homepage/hero.png' }); +}); +``` + +**Value:** +- Guarantees pixel-perfect implementation +- Automated visual QA +- No manual testing needed +- Clear completion signal + +--- + +### 4. Claude Reflection System (Meta-Learning Layer) + +**Purpose:** Learn from corrections and improve skills over time + +**How It Works:** +1. During session, you correct Claude's outputs +2. At session end, run `/reflect [skill-name]` OR Stop hook auto-triggers +3. Claude analyzes conversation for corrections and success patterns +4. Claude proposes skill updates with confidence levels +5. You approve changes +6. Skill file updated, committed, pushed to Git +7. Next session uses improved skill + +**Confidence Levels:** +- **HIGH:** Explicit corrections ("never do X", "always do Y") +- **MEDIUM:** Patterns that worked well +- **LOW:** Observations to review later + +**Skills to Create for Your Business:** + +#### 1. Client Discovery (`~/.claude/skills/client-discovery/SKILL.md`) +Learns: +- Question order and phrasing +- Industry-specific questions +- Required information checklist +- Red flags to watch for + +#### 2. Brand Design (`~/.claude/skills/brand-design/SKILL.md`) +Learns: +- Industry color preferences (restaurants → warm, tech → cool) +- Typography pairings that work +- Component sizing standards +- Your aesthetic preferences + +#### 3. Figma Automation (`~/.claude/skills/figma-design/SKILL.md`) +Learns: +- cloud.md preferences and additions +- Component organization patterns +- Naming conventions +- Common client requests + +#### 4. Implementation (`~/.claude/skills/implementation/SKILL.md`) +Learns: +- Tech stack choices (shadcn/ui, Next.js, etc.) +- Code structure preferences +- Testing requirements +- Git commit message format + +#### 5. QA Verification (`~/.claude/skills/qa-verification/SKILL.md`) +Learns: +- Screenshot verification checklist +- Common visual bugs to check +- Browser testing requirements +- Accessibility standards + +**Setup:** +```json +// ~/.claude/settings.json +{ + "hooks": { + "Stop": { + "hooks": [ + { + "type": "command", + "command": "~/.claude/skills/reflect/reflect.sh" + } + ] + } + } +} +``` + +**ROI Over 10 Clients:** +- Client 1: 12 corrections, 3 hours +- Client 2: 6 corrections, 1.5 hours (1.5h saved) +- Client 3: 3 corrections, 45 mins (4.75h saved) +- Client 4: 1 correction, 15 mins (7.5h saved) +- Client 5+: 0-1 corrections, 0-15 mins (10+ hours saved) + +**Annual Impact (40 clients):** ~80 hours saved = $8,000-$15,000 value + +--- + +## Real-World Example: Restaurant Website Project + +### Week 1: Discovery & Planning + +**Day 1-2: Initial Discovery** +```bash +# Initial client call +/product-vision + +Output: +- Business: Family Italian restaurant +- Target: Local diners, families, date nights +- Problems: No online presence, hard to showcase menu +- Features: Website, online menu, reservations, social media presence +``` + +**Day 3: Define Roadmap** +```bash +/product-roadmap + +Sections: +1. Homepage (Hero, featured dishes, testimonials) +2. Menu (Appetizers, Entrees, Desserts, Drinks) +3. About (Story, chef bio, location) +4. Reservations (Form with date/time picker) +5. Contact (Hours, address, phone, social links) +``` + +**Day 4-5: Data Modeling** +```bash +/data-model + +Entities: +- MenuItem (name, description, price, category, image, allergens) +- Reservation (name, email, phone, date, time, party size, special requests) +- Testimonial (customer name, quote, rating, date) +- Location (address, hours, phone, coordinates) +``` + +**Client Checkpoint:** ✅ Approves scope and structure + +--- + +### Week 2 Part 1: Brand System Design + +**Day 1: Define Design Tokens** +```bash +/design-tokens + +Colors Selected: +- Primary: Red #DC2626 (Italian flag red) +- Secondary: Gold #F59E0B +- Neutral: Stone palette + +Typography: +- Display: Playfair Display (elegant serif) +- Body: Open Sans (readable sans-serif) + +Output: colors.json, typography.json +``` + +**Day 2: AI Creates Figma Brand System** +``` +You (to Claude with Figma MCP): +"Using design tokens and cloud.md rules, create complete brand system." + +AI Creates in Figma: +- Page 1: Brand Guidelines + - Color palette (Primary/Secondary with 9 shades each) + - Typography scale (H1-H4, Body Large/Medium/Small) + +- Page 2: Components + - Button (Primary/Secondary/Outline, Small/Medium/Large) + - Input (Text/Email/Password, Default/Focus/Error) + - Card (Default/Elevated/Outlined) + - Navigation (Desktop/Mobile variants) + +Time: 10 minutes +``` + +**Client Review:** Views Figma link, approves brand identity ✅ + +--- + +### Week 2 Part 2 - Week 3: Screen Design + +**For Each Section (Example: Homepage):** + +**Day 1: Define Homepage Requirements** +```bash +/shape-section homepage + +Requirements: +- Hero: Full-width image, headline, subheadline, CTA +- Featured Dishes: 3-column grid, images, descriptions, prices +- Testimonials: 2-column layout, customer quotes, ratings +- Footer CTA: Reservation prompt with button + +/sample-data + +Generated Content: +- Hero: "Authentic Italian Cuisine" / "Family recipes since 1982" +- Dishes: Margherita Pizza, Fettuccine Alfredo, Tiramisu +- Testimonials: 3 customer reviews with 5-star ratings +``` + +**Day 2: AI Creates Figma Homepage Design** +``` +You (to Claude with Figma MCP): +"Create homepage design using approved components and homepage spec." + +AI Creates: +- Desktop version (1440px) + - Hero with overlay for text readability + - 3-column featured dishes grid + - 2-column testimonials + - Footer CTA with primary button + +- Mobile version (375px) + - Hero (smaller height) + - Single-column dishes (stacked) + - Single-column testimonials + - Footer CTA (full-width button) + +Time: 15 minutes +``` + +**Client Iteration:** +``` +Client: "Can we make hero taller and show 4 dishes instead of 3?" + +You (to AI): "Update: hero 800px, 4-column dishes grid" + +AI: Updates Figma in 2 minutes + +Client: "Perfect!" ✅ +``` + +**Repeat for Menu, About, Reservations, Contact (Week 3)** + +--- + +### Week 3 End: Social Media Assets + +``` +You (to Claude with Figma MCP): +"Create social media template library using our brand system." + +AI Creates: +- Instagram Posts (1080x1080): 5 templates + - Featured dish showcase + - Daily special + - Testimonial + - Event promo + - Quote graphic + +- Instagram Stories (1080x1920): 3 templates + - Menu highlight + - Behind-the-scenes + - Poll/engagement + +- Facebook Cover (1200x630) + - Restaurant branding with CTA + +All editable by client +``` + +**Client Checkpoint:** ✅ Approves all templates + +--- + +### Week 4-5: Implementation with RALPH LOOP + +**Week 4 Day 1: Export & Setup** +```bash +/export-product + +Generates: product-plan.zip +- All React components +- Design tokens +- Sample data +- TypeScript types +- Implementation prompts +``` + +**Week 4 Day 2-3: Write E2E Tests** +```typescript +// e2e/homepage.spec.ts +// e2e/menu.spec.ts +// e2e/about.spec.ts +// e2e/reservations.spec.ts +// e2e/contact.spec.ts + +Each test encodes: +- Layout from Figma (heights, widths, spacing) +- Colors from design tokens +- Typography from text styles +- Interactions from user flows +``` + +**Week 4-5: RALPH LOOP Implementation** + +**Homepage (Day 4):** +```bash +# Iteration 1 +pnpm test e2e/homepage.spec.ts +❌ FAIL - No components built + +# Iteration 2 +AI implements homepage components with shadcn/ui + +# Iteration 3 +pnpm test e2e/homepage.spec.ts +✅ PASS + +# Iteration 4 +AI reads screenshots, finds hero image too dark +AI adds 40% overlay, re-runs tests + +# Iteration 5 +pnpm test e2e/homepage.spec.ts +✅ PASS - All verified + +HOMEPAGE_DONE +``` + +**Repeat for Menu, About, Reservations, Contact (Days 5-10)** + +All features implemented with: +- Passing tests ✅ +- Verified screenshots ✅ +- Pixel-perfect to Figma ✅ + +--- + +### Week 6: Client Review & Launch + +**Day 1-2: Staging Review** +- Client reviews staging.example.com +- Site matches approved Figma designs exactly +- All functionality works +- Mobile responsive + +**Day 3: Final Approval** +- Client approves ✅ +- No surprises or changes needed + +**Day 4-5: Production Deployment** +- Deploy to production +- Configure domain +- Set up analytics +- Train client on CMS (if applicable) + +**Deliverables:** +- ✅ Live website (restaurantname.com) +- ✅ Figma files (brand guidelines, components, screens) +- ✅ Social media templates (editable by client/VA) +- ✅ Documentation +- ✅ Login credentials + +**Client:** Thrilled, site exactly as envisioned 🎉 + +--- + +## Client Pitch Template + +> **"Here's our AI-powered design and development process:** +> +> **Week 1:** We document your vision, scope, and requirements using our planning system. You approve everything in writing before any design work begins. +> +> **Week 2-3:** Our AI designer creates your entire brand system and website designs in Figma: +> - Professional brand guidelines (colors, typography) +> - Complete component library (buttons, forms, cards) +> - All your website pages (desktop + mobile versions) +> - Social media templates you can edit yourself +> +> You review professional mockups and we iterate in MINUTES, not days. What you see is exactly what you'll get. +> +> **Week 4-5:** Our AI development system builds your site with automated quality checks that guarantee pixel-perfect match to approved designs. Every element tested automatically. +> +> **Week 6:** Your site goes live. +> +> **Results:** +> - ✅ 6 weeks instead of 12-16 weeks (2-3x faster) +> - ✅ 60-70% cost savings from automation +> - ✅ Zero surprises - approved designs = final product +> - ✅ Professional Figma files you own forever +> - ✅ Editable social media templates +> - ✅ Quality improves with every project (our AI learns) +> +> **Guarantee:** What you approve in Week 3 is exactly what launches in Week 6. No surprises, no endless revisions." + +--- + +## ROI Analysis + +### Time Savings Per Client + +| Phase | Traditional | Automated | Savings | +|-------|------------|-----------|---------| +| Discovery | 8 hours | 3 hours | 5 hours | +| Brand Design | 8 hours | 1 hour | 7 hours | +| Screen Design (5 pages) | 25 hours | 3 hours | 22 hours | +| Revisions | 15 hours | 2 hours | 13 hours | +| Implementation | 40 hours | 25 hours | 15 hours | +| QA Testing | 10 hours | 2 hours | 8 hours | +| **TOTAL** | **106 hours** | **36 hours** | **70 hours** | + +**Per Client Savings:** 70 hours = 8.75 workdays + +**Annual Savings (20 clients):** 1,400 hours = 175 workdays = 35 workweeks + +**Monetary Value:** $70,000 - $140,000 (at $50-100/hr) + +--- + +### Quality Improvements + +| Metric | Traditional | Automated | Improvement | +|--------|------------|-----------|-------------| +| Revision Cycles | 5-10 | 1-2 | 80% reduction | +| Client Satisfaction | 75% | 95% | +20 points | +| On-time Delivery | 60% | 95% | +35 points | +| Scope Creep | 40% | 5% | 87% reduction | +| Repeat Business | 30% | 70% | +40 points | + +--- + +## Skills That Improve Over Time + +### After Client 1 (Restaurant): +Skills learn: +- Restaurant industry prefers warm colors +- Button padding: 16px (your standard) +- Card padding: 24px (your standard) +- Discovery process question order +- shadcn/ui is your tech stack + +### After Client 5 (Various Industries): +Skills know: +- Restaurant → warm colors +- Tech/SaaS → cool colors +- Health → greens/blues +- Luxury → dark/gold +- Your complete component standards +- Your QA verification checklist +- Your git commit format + +### After Client 20: +Skills are expert-level: +- Industry-specific design patterns +- Common client objections and solutions +- Optimized discovery questions +- Refined component library +- Battle-tested QA criteria +- Zero repetitive corrections needed + +**Result:** Each project is faster and higher quality than the last. + +--- + +## Getting Started + +### Prerequisites + +1. **Design OS Installation** + - Clone and set up Designbrnd repository + - Familiarize with commands + +2. **Figma MCP Server** + - Install from: https://github.com/Antonytm/figma-mcp-server + - Configure WebSocket connection + - Install Figma plugin (development mode) + - Create `cloud.md` in project root + +3. **RALPH LOOP Setup** + - Next.js project with App Router + - Install Playwright: `npm install -D @playwright/test` + - Install shadcn/ui: `npx shadcn-ui@latest init` + - Create E2E test directory + +4. **Claude Reflection System** + - Create skills directory: `~/.claude/skills/` + - Set up Stop hook in `~/.claude/settings.json` + - Initialize Git for skills tracking + - Create initial skill files + +### First Project Checklist + +- [ ] Set up client project directory +- [ ] Copy `cloud.md` to project root +- [ ] Run `/product-vision` for discovery +- [ ] Run `/product-roadmap` for scope +- [ ] Run `/data-model` for structure +- [ ] Run `/design-tokens` for brand +- [ ] Use Figma MCP to create brand system +- [ ] Use Figma MCP to create screen designs +- [ ] Client approves all designs +- [ ] Run `/export-product` +- [ ] Write E2E tests from Figma +- [ ] Run RALPH LOOP for implementation +- [ ] Deploy and launch +- [ ] Run `/reflect` to capture learnings + +### Ongoing Optimization + +- Review skill updates after each project +- Refine `cloud.md` based on patterns +- Build template library of common components +- Document industry-specific learnings +- Share successful patterns with team + +--- + +## Conclusion + +This integrated workflow combines the best of AI-powered design, test-driven development, and meta-learning to deliver: + +1. **Speed:** 2-3x faster than traditional processes +2. **Quality:** Pixel-perfect, automated QA +3. **Consistency:** Same professional standards every time +4. **Client Satisfaction:** No surprises, clear expectations +5. **Continuous Improvement:** Gets better with every project + +The magic is in the integration - each tool amplifies the others, and the Reflection System ensures your entire workflow becomes more refined with every client. + +**Start with one client, learn and refine, then scale to 10, 20, 40+ clients per year with the same (or smaller) team.** + +--- + +**Last Updated:** 2026-01-10 +**Version:** 1.0 +**Author:** Design OS Consulting Workflow diff --git a/docs/quick-start-guide.md b/docs/quick-start-guide.md new file mode 100644 index 0000000..4a7e876 --- /dev/null +++ b/docs/quick-start-guide.md @@ -0,0 +1,499 @@ +# Quick Start Guide +## Getting Your First Client Project Running in 1 Hour + +--- + +## Overview + +This guide gets you from zero to running your first client project using the complete workflow (Design OS + Figma MCP + RALPH LOOP + Reflection System). + +**Time to First Client Session:** ~60 minutes setup + +--- + +## Step 1: Install & Configure Design OS (15 minutes) + +### Clone and Setup + +```bash +# Clone Designbrnd repository +git clone https://github.com/yourusername/Designbrnd.git +cd Designbrnd + +# Install dependencies +npm install + +# Start dev server +npm run dev +``` + +**Verify:** Open http://localhost:5173 - you should see Design OS interface + +### Learn the Commands + +Open a Claude Code session in the Designbrnd directory: + +```bash +# Discovery commands +/product-vision # Document client's business vision +/product-roadmap # Define deliverable sections +/data-model # Structure data requirements + +# Design commands +/design-tokens # Select colors and typography +/design-shell # Create app navigation/layout + +# Section commands (repeat per section) +/shape-section # Define section requirements +/sample-data # Generate realistic content +/design-screen # Create React component (optional) +/screenshot-design # Capture design screenshot + +# Export command +/export-product # Generate complete handoff package +``` + +**Practice:** Run through commands once to understand the flow + +--- + +## Step 2: Install Figma MCP Server (20 minutes) + +### Installation + +```bash +# Clone Figma MCP Server +git clone https://github.com/Antonytm/figma-mcp-server.git +cd figma-mcp-server + +# Install dependencies +npm install + +# Build the project +npm run build + +# Start MCP server +npm start +``` + +**Server runs on:** `http://localhost:38450` + +### Install Figma Plugin + +1. Open Figma Desktop App +2. Go to **Plugins → Development → Import plugin from manifest** +3. Navigate to: `figma-mcp-server/figma-plugin/manifest.json` +4. Plugin appears in **Plugins → Development → Figma MCP Server** + +### Test Connection + +1. Create a new Figma file +2. Run plugin: **Plugins → Development → Figma MCP Server** +3. Plugin should show: "✓ Connected to MCP server" + +**Troubleshooting:** If not connected: +- Verify MCP server is running (`npm start`) +- Check port 38450 is not blocked +- Restart Figma and try again + +--- + +## Step 3: Create cloud.md for Your Projects (5 minutes) + +### Copy Template + +```bash +# In your Designbrnd directory +cp cloud.md ~/client-project-template/cloud.md +``` + +The `cloud.md` file contains Figma design rules. Key sections: + +- **Component Creation** - Auto-layout, component properties +- **Typography** - Text style hierarchy (H1-H4, Body) +- **Colors** - Color style requirements +- **Spacing** - 8px grid system +- **Naming Conventions** - PascalCase, kebab-case rules + +**Customize:** Add your specific preferences to cloud.md + +--- + +## Step 4: Set Up RALPH LOOP Testing (10 minutes) + +### Create Test Project + +```bash +# Create Next.js project +npx create-next-app@latest client-project --typescript --tailwind --app + +cd client-project + +# Install Playwright +npm install -D @playwright/test +npx playwright install + +# Install shadcn/ui +npx shadcn-ui@latest init +``` + +**Answer prompts:** +- Style: Default +- Base color: Stone (or your preference) +- CSS variables: Yes + +### Create E2E Test Structure + +```bash +# Create test directories +mkdir -p e2e/screenshots + +# Create first test file +touch e2e/example.spec.ts +``` + +**Example test:** +```typescript +// e2e/example.spec.ts +import { test, expect } from '@playwright/test'; + +test('homepage loads', async ({ page }) => { + await page.goto('/'); + + const heading = page.getByTestId('main-heading'); + await expect(heading).toBeVisible(); + + await page.screenshot({ + path: 'e2e/screenshots/homepage.png' + }); +}); +``` + +**Run test:** +```bash +npx playwright test +``` + +--- + +## Step 5: Configure Claude Reflection System (10 minutes) + +### Create Skills Directory + +```bash +mkdir -p ~/.claude/skills +cd ~/.claude/skills + +# Initialize git +git init +git remote add origin [your-skills-repo-url] +``` + +### Create Core Skills + +```bash +# Create skill directories +mkdir -p client-discovery +mkdir -p brand-design +mkdir -p figma-design +mkdir -p implementation +mkdir -p qa-verification + +# Create SKILL.md files +cat > client-discovery/SKILL.md << 'EOF' +# Client Discovery Skill + +## Discovery Question Order +1. Target customer (who are they?) +2. Business description (what do you do?) +3. Problems you solve +4. Key features needed +5. Budget and timeline + +## Notes +[Skills will learn and update this file over time] +EOF + +cat > brand-design/SKILL.md << 'EOF' +# Brand Design Skill + +## Industry Color Guidelines +[Will learn from projects] + +## Component Standards +[Will learn from projects] +EOF + +cat > figma-design/SKILL.md << 'EOF' +# Figma Design Skill + +## Figma Best Practices +- Use auto-layout for everything +- Create 3 pages: Brand Guidelines, Components, Screens +- Component naming: PascalCase +- Frame naming: kebab-case + +## Learned Patterns +[Will update from corrections] +EOF + +cat > implementation/SKILL.md << 'EOF' +# Implementation Skill + +## Tech Stack Rules +- UI Components: shadcn/ui +- Framework: Next.js with App Router +- Styling: Tailwind CSS +- Testing: Playwright + +## Code Quality +[Will learn from corrections] +EOF + +cat > qa-verification/SKILL.md << 'EOF' +# QA Verification Skill + +## Screenshot Verification Checklist +1. Text contrast ratio (WCAG AA) +2. Buttons fully visible +3. Spacing matches Figma (8px grid) +4. Responsive behavior works + +## Common Issues +[Will learn from fixes] +EOF +``` + +### Configure Stop Hook (Optional - Auto-Reflection) + +**Edit:** `~/.claude/settings.json` + +```json +{ + "hooks": { + "Stop": { + "hooks": [ + { + "type": "command", + "command": "~/.claude/skills/reflect/reflect.sh" + } + ] + } + } +} +``` + +**Note:** Start with manual `/reflect` command first, add auto-hook later + +--- + +## Step 6: Run Your First Client Session (Now!) + +### Session Workflow + +**1. Start Design OS Session** +```bash +cd ~/Designbrnd +# Open in Claude Code +``` + +**2. Discovery Phase** +```bash +You: /product-vision + +Claude: Walks through discovery questions + +You: Provide client info (example: Italian Restaurant) + +Claude: Creates product-overview.md +``` + +**3. Roadmap Phase** +```bash +You: /product-roadmap + +Claude: Helps define sections + +You: Define 5 sections (Homepage, Menu, About, Reservations, Contact) + +Claude: Creates product-roadmap.md +``` + +**4. Design Tokens** +```bash +You: /design-tokens + +Claude: Helps select colors and fonts + +You: Choose warm colors (Italian restaurant), Playfair Display + Open Sans + +Claude: Creates colors.json, typography.json +``` + +**5. Switch to Figma MCP** + +Open Figma, start plugin, then in Claude: + +``` +You (to Claude with Figma MCP access): +"Using the design tokens from Design OS (colors.json, typography.json) +and following the rules in cloud.md, create a brand guidelines page +in Figma with color palette and typography scale." + +Claude + Figma MCP: Creates Figma design in ~10 minutes +``` + +**6. Review with Mock Client** + +Open Figma file, review: +- ✓ Colors match expectations? +- ✓ Typography looks good? +- ✓ Components structured well? + +**7. End Session & Reflect** + +```bash +You: /reflect brand-design + +Claude: Analyzes session, proposes skill updates + +You: Review and approve + +Claude: Updates SKILL.md, commits to git +``` + +--- + +## Quick Reference Card + +### Design OS Commands +| Command | Purpose | +|---------|---------| +| `/product-vision` | Document business vision | +| `/product-roadmap` | Define sections | +| `/data-model` | Structure data | +| `/design-tokens` | Select colors/fonts | +| `/shape-section [name]` | Define section requirements | +| `/sample-data` | Generate content | +| `/design-screen [name]` | Create React component | +| `/export-product` | Generate handoff package | + +### Figma MCP Prompts +| Task | Prompt Template | +|------|----------------| +| Brand System | "Create brand guidelines and component library using design tokens from colors.json and typography.json" | +| Screen Design | "Create [page name] design using components and following cloud.md rules. Include desktop (1440px) and mobile (375px)" | +| Social Templates | "Create social media template library: Instagram posts, stories, Facebook cover" | +| Iterate | "Update [element] to [changes]" | + +### RALPH LOOP Commands +| Command | Purpose | +|---------|---------| +| `pnpm test e2e/[feature].spec.ts` | Run tests for feature | +| `npx shadcn-ui@latest add [component]` | Install shadcn component | +| `ls e2e/screenshots/[feature]/` | List screenshots | +| `mv [file].png verified_[file].png` | Mark screenshot verified | + +### Reflection Commands +| Command | Purpose | +|---------|---------| +| `/reflect` | Manual reflection (review and approve) | +| `/reflect on` | Enable auto-reflection hook | +| `/reflect off` | Disable auto-reflection | +| `/reflect status` | Check if enabled | + +--- + +## Common First-Time Issues + +### Issue: Figma Plugin Not Connecting + +**Solution:** +1. Check MCP server is running: `curl http://localhost:38450` +2. Restart Figma Desktop App +3. Re-run plugin +4. Check firewall isn't blocking port 38450 + +--- + +### Issue: Design OS Commands Not Found + +**Solution:** +1. Verify you're in Designbrnd directory +2. Check `.claude/commands/design-os/` exists +3. Restart Claude Code session +4. Try typing `/` to see available commands + +--- + +### Issue: RALPH LOOP Tests Fail Immediately + +**Solution:** +1. Make sure dev server is running: `npm run dev` +2. Check `playwright.config.ts` has correct base URL +3. Verify components have `data-testid` attributes +4. Run with UI mode to debug: `npx playwright test --ui` + +--- + +### Issue: Reflection Not Working + +**Solution:** +1. Start with manual `/reflect` (skip auto-hook initially) +2. Verify skills directory exists: `~/.claude/skills/` +3. Check SKILL.md files are writable +4. Make sure git is initialized in skills directory + +--- + +## Next Steps + +After completing your first session: + +1. **Review Outputs** + - Check `product/` directory for generated files + - Review Figma designs + - Read skill updates in `~/.claude/skills/` + +2. **Refine cloud.md** + - Add any preferences discovered + - Document your button/card standards + - Note industry-specific patterns + +3. **Practice RALPH LOOP** + - Write a simple E2E test + - Run the test workflow + - Practice screenshot verification + +4. **Run Second Session** + - Try a different industry (coffee shop, gym, etc.) + - See what skills learned from first session + - Note improvements in speed/quality + +5. **Scale Up** + - Build your template library + - Document your workflow SOP + - Train team members (if applicable) + +--- + +## Success Checklist + +After completing setup, you should be able to: + +- [ ] Run Design OS commands and generate product specs +- [ ] Connect to Figma MCP and create designs via AI +- [ ] Write and run E2E tests with Playwright +- [ ] Use `/reflect` to update skills +- [ ] Complete a mock client session end-to-end (1-2 hours) + +**Time Investment:** ~60 minutes setup + 2 hours practice = **Ready for real clients** + +--- + +**Next Read:** [Complete Consulting Workflow Guide](./consulting-workflow-guide.md) for detailed phase-by-phase instructions. + +--- + +**Last Updated:** 2026-01-10 +**Version:** 1.0 diff --git a/docs/tool-integration-reference.md b/docs/tool-integration-reference.md new file mode 100644 index 0000000..bd02b51 --- /dev/null +++ b/docs/tool-integration-reference.md @@ -0,0 +1,1270 @@ +# Tool Integration Reference +## Technical Documentation for Design OS Workflow Tools + +--- + +## Overview + +This document provides technical details for integrating the four core tools in the automated consulting workflow: + +1. **Design OS** - React-based planning and design documentation tool +2. **Figma MCP Server** - AI-powered Figma design automation +3. **RALPH LOOP** - Test-driven development workflow with visual verification +4. **Claude Reflection System** - Meta-learning skill improvement system + +--- + +## Tool 1: Design OS + +### Architecture + +**Technology Stack:** +- React 19.2.0 +- TypeScript 5.9.3 +- Vite 7.2.4 +- Tailwind CSS v4.1.17 +- React Router DOM 7.9.6 +- shadcn/ui component library + +**Core Concept:** +Build-time file loading using Vite's `import.meta.glob()` to treat files as data layer. + +**Data Flow:** +``` +User Input (markdown/JSON) → Build-time Glob → Loaders → React Components → UI +``` + +### Directory Structure + +``` +Designbrnd/ +├── src/ # React application +│ ├── components/ # UI components +│ │ ├── ui/ # shadcn/ui base components +│ │ ├── ProductPage.tsx # Product overview page +│ │ ├── DataModelPage.tsx # Data model visualization +│ │ ├── DesignPage.tsx # Design system page +│ │ ├── SectionsPage.tsx # Sections list +│ │ ├── SectionPage.tsx # Section detail page +│ │ └── ExportPage.tsx # Export package page +│ │ +│ ├── lib/ # Data loaders +│ │ ├── product-loader.ts # Load product overview, roadmap +│ │ ├── section-loader.ts # Load section specs, data +│ │ ├── design-system-loader.ts # Load colors, typography +│ │ └── router.tsx # React Router config +│ │ +│ └── types/ # TypeScript interfaces +│ ├── product.ts # Product types +│ └── section.ts # Section types +│ +├── product/ # User's product definition (input) +│ ├── product-overview.md # Business vision +│ ├── product-roadmap.md # Sections/phases +│ ├── data-model/ +│ │ └── data-model.md # Entities and relationships +│ ├── design-system/ +│ │ ├── colors.json # Color palette +│ │ └── typography.json # Font selections +│ └── sections/ # Per-section content +│ └── [section-id]/ +│ ├── spec.md # Requirements +│ ├── data.json # Sample data +│ └── *.png # Screenshots +│ +├── product-plan/ # Export output (generated) +│ ├── prompts/ # AI prompts +│ ├── instructions/ # Implementation guides +│ └── ... +│ +└── .claude/ # Claude integration + └── commands/design-os/ # Command definitions + ├── product-vision.md + ├── product-roadmap.md + ├── data-model.md + ├── design-tokens.md + ├── shape-section.md + ├── sample-data.md + ├── design-screen.md + └── export-product.md +``` + +### Key Commands + +#### /product-vision +**Purpose:** Document business vision and goals + +**Process:** +1. AI asks discovery questions +2. User provides answers +3. AI generates `product/product-overview.md` + +**Output Format:** +```markdown +# [Product Name] + +## Description +[Business description] + +## Problems We Solve +1. [Problem 1] +2. [Problem 2] + +## Key Features +1. [Feature 1] +2. [Feature 2] + +## Target Audience +[Target customer description] +``` + +**Integration Point:** Output used by Figma MCP for context-aware design + +--- + +#### /product-roadmap +**Purpose:** Define deliverable sections/phases + +**Output Format:** +```markdown +# Product Roadmap + +## Sections +1. **[Section Name]** - [Description] +2. **[Section Name]** - [Description] +``` + +**Integration Point:** Sections become screens in Figma MCP + +--- + +#### /data-model +**Purpose:** Define data entities and relationships + +**Output Format:** +```markdown +# Data Model + +## Entities + +### [Entity Name] +**Description:** [What it represents] + +**Properties:** +- [property]: [type] - [description] +``` + +**Integration Point:** Used for TypeScript type generation and sample data + +--- + +#### /design-tokens +**Purpose:** Select colors and typography + +**Output Files:** +- `product/design-system/colors.json` +- `product/design-system/typography.json` + +**colors.json Format:** +```json +{ + "primary": { + "name": "Red", + "value": "#DC2626", + "tailwind": "red" + }, + "secondary": { + "name": "Gold", + "value": "#F59E0B", + "tailwind": "amber" + } +} +``` + +**typography.json Format:** +```json +{ + "display": { + "name": "Playfair Display", + "googleFont": "Playfair+Display:wght@400;600;700" + }, + "body": { + "name": "Open Sans", + "googleFont": "Open+Sans:wght@400;600;700" + } +} +``` + +**Integration Point:** Consumed by Figma MCP to create color/text styles + +--- + +#### /shape-section [name] +**Purpose:** Define section requirements + +**Output:** `product/sections/[name]/spec.md` + +**Format:** +```markdown +# [Section Name] + +## Purpose +[What this section does] + +## User Flow +1. [Step 1] +2. [Step 2] + +## UI Requirements +- [Requirement 1] +- [Requirement 2] + +## Components Needed +- [Component 1] +- [Component 2] +``` + +**Integration Point:** Used by Figma MCP to design screens + +--- + +#### /sample-data +**Purpose:** Generate realistic sample content + +**Output:** `product/sections/[name]/data.json` + +**Format:** +```json +{ + "items": [ + { + "id": "1", + "title": "Example Item", + "description": "Realistic description..." + } + ] +} +``` + +**Integration Point:** Used in Figma designs and React components + +--- + +#### /export-product +**Purpose:** Generate complete handoff package + +**Output:** `product-plan.zip` containing: +- `prompts/` - Ready-to-use AI prompts +- `instructions/` - Implementation guides +- `design-system/` - Color/typography tokens +- `data-model/` - TypeScript types +- `sections/` - Component exports + +**Integration Point:** Handoff to developers or AI coding agents + +--- + +### API Integration + +**Loading Product Data:** +```typescript +// src/lib/product-loader.ts +import { parseProductOverview } from './parsers'; + +export function loadProductData() { + const files = import.meta.glob('/product/product-overview.md', { + as: 'raw', + eager: true + }); + + const content = Object.values(files)[0]; + return parseProductOverview(content); +} +``` + +**Using in React:** +```typescript +// src/components/ProductPage.tsx +import { loadProductData } from '@/lib/product-loader'; + +export function ProductPage() { + const productData = useMemo(() => loadProductData(), []); + + if (!productData) { + return Run /product-vision to start; + } + + return ; +} +``` + +--- + +## Tool 2: Figma MCP Server + +### Architecture + +**Technology Stack:** +- Express.js MCP server +- WebSocket communication +- Figma Plugin (TypeScript) + +**Communication Flow:** +``` +AI Agent → MCP Server → WebSocket → Figma Plugin → Figma API → Figma Document + ← ← ← ← ← +``` + +**Key Components:** +1. **MCP Server** (Node.js) - Receives tool calls from AI +2. **WebSocket Server** - Mediates communication +3. **Figma Plugin** - Executes commands in Figma + +### Installation + +```bash +# Clone repository +git clone https://github.com/Antonytm/figma-mcp-server.git +cd figma-mcp-server + +# Install dependencies +npm install + +# Build +npm run build + +# Start server +npm start +# Server runs on http://localhost:38450 +``` + +### Figma Plugin Setup + +1. Open Figma Desktop App +2. **Plugins → Development → Import plugin from manifest** +3. Select: `figma-mcp-server/figma-plugin/manifest.json` +4. Run: **Plugins → Development → Figma MCP Server** +5. Verify: "✓ Connected to MCP server" + +### Available Tools (23 Total) + +**Document Management:** +- `get-document-info` - Get current file info +- `create-page` - Create new page +- `get-pages` - List all pages +- `select-page` - Switch to page + +**Component Creation:** +- `create-component` - Create component node +- `add-component-property` - Add variant/property +- `set-node-component-property-references` - Link properties +- `create-component-instance` - Instance from component + +**Layout & Frames:** +- `create-frame` - Create frame node +- `set-auto-layout` - Configure auto-layout +- `set-layout-sizing` - Set FILL/FIXED sizing +- `set-padding` - Set frame padding +- `set-gap` - Set auto-layout gap + +**Styling:** +- `create-color-style` - Create color style +- `create-text-style` - Create text style +- `set-fill` - Apply fill color +- `set-stroke` - Apply stroke +- `apply-color-style` - Use color style +- `apply-text-style` - Use text style + +**Text & Content:** +- `create-text` - Create text node +- `set-text-content` - Update text +- `set-font` - Change font properties + +**Node Management:** +- `get-node` - Get node by ID +- `set-parent` - Move node to parent +- `delete-node` - Remove node + +### cloud.md Integration + +**Purpose:** Provide design rules and best practices for AI + +**Location:** Project root (`cloud.md`) + +**Key Sections:** + +```markdown +# Figma Design Rules + +## Component Creation Process +- Components created using create-component tool +- All parts should be ancestors of component node +- Component properties added via add-component-property +- Use set-node-component-property-references for linking + +## Auto Layout Rules +- Use auto layout for everything +- Vertical auto layout: Fixed width, children use FILL horizontal +- Horizontal auto layout: Fixed height, children use FILL vertical +- Prefer Frames over Rectangles + +## Document Organization +- Page 1: Brand Guidelines +- Page 2: Components +- Page 3+: Screens +- No overlapping elements +- Hierarchical structure with proper spacing +``` + +**AI reads cloud.md** before executing design tasks. + +### Example Prompts + +**Create Brand System:** +``` +Using the design tokens from Design OS (colors.json, typography.json) +and following the rules in cloud.md, create a complete brand system +in Figma with: + +1. Brand Guidelines page with color palette and typography scale +2. Components page with Button, Input, Card, Navigation components +3. All components should use auto-layout and component properties +``` + +**Create Screen Design:** +``` +Using the approved component library and the homepage spec from +product/sections/homepage/spec.md, create a homepage design on +the "Screens/Homepage" page with: + +1. Hero section (1920x800, overlay, centered content) +2. Featured items grid (3 columns using Card components) +3. Testimonials (2 columns using Card components) +4. Footer CTA (background: primary color, centered) + +Create both desktop (1440px) and mobile (375px) versions. +Follow all spacing and layout rules from cloud.md. +``` + +**Iterate Design:** +``` +Update the homepage hero section: +1. Increase height to 1000px +2. Change CTA button to Secondary variant +3. Add second CTA button (Outline variant) +4. Maintain 16px gap between buttons using auto-layout +``` + +### Integration with Design OS + +**Data Flow:** +``` +Design OS → colors.json → AI reads → Figma MCP creates color styles + → typography.json → AI reads → Figma MCP creates text styles + → spec.md → AI reads → Figma MCP creates screens +``` + +**Example:** +```typescript +// After running /design-tokens in Design OS +// File created: product/design-system/colors.json + +// AI prompt to Figma MCP: +"Create color styles in Figma from colors.json" + +// Figma MCP executes: +// 1. Read colors.json +// 2. For each color: +// - create-color-style (Primary/500, #DC2626) +// - create-color-style (Primary/600, #B91C1C) +// - ... +``` + +### Error Handling + +**Common Issues:** + +1. **Connection Failed** + - Check MCP server is running + - Verify Figma plugin is active + - Check port 38450 not blocked + +2. **Tool Execution Timeout** + - Complex operations may take time + - MCP server has timeout (configurable) + - Break into smaller operations + +3. **Invalid Node References** + - Always get fresh node IDs + - Don't reuse IDs across sessions + - Use `get-node` to verify existence + +--- + +## Tool 3: RALPH LOOP + +### Architecture + +**Technology Stack:** +- Next.js 14+ (App Router) +- React 19+ +- Playwright for E2E testing +- shadcn/ui component library +- Tailwind CSS + +**Workflow:** +``` +1. Write E2E Test → 2. Run Test (FAIL) → 3. Implement → 4. Run Test (PASS) → +5. Verify Screenshots → 6. Fix Issues → 7. Re-run → 8. Mark Verified → 9. Done +``` + +### Test Structure + +**Directory Layout:** +``` +client-project/ +├── e2e/ +│ ├── screenshots/ +│ │ ├── feature-name/ +│ │ │ ├── desktop-view.png +│ │ │ ├── mobile-view.png +│ │ │ └── verified_desktop-view.png # After verification +│ │ └── ... +│ ├── homepage.spec.ts +│ ├── menu.spec.ts +│ └── ... +│ +├── app/ +│ ├── page.tsx +│ └── ... +│ +├── components/ +│ ├── ui/ # shadcn/ui components +│ │ ├── button.tsx +│ │ ├── card.tsx +│ │ └── ... +│ └── ... +│ +└── playwright.config.ts +``` + +### Test Template + +```typescript +// e2e/feature-name.spec.ts +import { test, expect } from '@playwright/test'; + +test.describe('Feature Name', () => { + test('should display correctly', async ({ page }) => { + await page.goto('/'); + + // Test element presence + const element = page.getByTestId('feature-element'); + await expect(element).toBeVisible(); + + // Test exact text from approved design + const headline = page.getByTestId('feature-headline'); + await expect(headline).toContainText('Exact Text from Figma'); + + // Test exact color from design tokens + const button = page.getByTestId('feature-cta'); + await expect(button).toHaveCSS('background-color', 'rgb(220, 38, 38)'); + + // Test layout dimensions + const heroBox = await element.boundingBox(); + expect(heroBox?.height).toBeCloseTo(800, 10); // 800px ±10px + + // Visual regression test + await page.screenshot({ + path: 'e2e/screenshots/feature-name/desktop-view.png', + fullPage: false + }); + }); + + test('should be responsive on mobile', async ({ page }) => { + await page.setViewportSize({ width: 375, height: 667 }); + await page.goto('/'); + + const element = page.getByTestId('feature-element'); + await expect(element).toBeVisible(); + + await page.screenshot({ + path: 'e2e/screenshots/feature-name/mobile-view.png' + }); + }); +}); +``` + +### Workflow Steps + +**Step 1: Run Tests (Initial FAIL)** +```bash +pnpm test e2e/feature-name.spec.ts +# Expected: FAIL - no components implemented +``` + +**Step 2: Implement Components** +```typescript +// components/feature-element.tsx +import { Button } from '@/components/ui/button'; + +export function FeatureElement() { + return ( +
+

+ Exact Text from Figma +

+ +
+ ); +} +``` + +**Step 3: Run Tests (Should PASS)** +```bash +pnpm test e2e/feature-name.spec.ts +# Expected: PASS - all assertions pass +# Screenshots generated in e2e/screenshots/feature-name/ +``` + +**Step 4: Visual Verification** +```bash +# List screenshots +ls e2e/screenshots/feature-name/ +# desktop-view.png +# mobile-view.png + +# AI reads each screenshot and assesses +Read tool: e2e/screenshots/feature-name/desktop-view.png + +# AI Assessment: +# ✅ Headline visible and positioned correctly +# ✅ Button present with correct color +# ❌ Button text is cut off (overflow issue) +# ❌ Background image too dark (low contrast) +``` + +**Step 5: Fix Issues** +```typescript +// Fix overflow +