WDG Playground - User Experience Design
UX Design DocumentVersion: 1.0 Last Updated: October 2025
Table of Contents
Design Philosophy
Core Principles
1. Visual-First, Terminal-Never
- Every operation accessible via GUI
- No command-line knowledge required
- Visual feedback for all actions
- Clear, non-technical language
2. Safe Exploration
- Undo/redo capabilities
- Automatic backups before changes
- Clear confirmation for destructive actions
- "Playground" mentality - experiment freely
3. Progressive Disclosure
- Simple by default, powerful when needed
- Advanced features behind clear labels
- Guided workflows for complex tasks
- Contextual help always available
4. AI-Augmented, Not AI-Dependent
- AI assistance enhances, doesn't replace
- Manual controls always available
- Clear indication when AI is helping
- Learn through doing
Design Language
UI Framework:
- shadcn/ui components (matching WDG Dashboard)
- Tailwind CSS 3.0+ with dashboard design tokens
- Lucide React icons
- Dark/light mode support
Color Palette (from Dashboard):
- Tonal Black: #1A1A1A (dark mode base)
- WDG Gray: #E5E7EB (light mode base)
- Primary: Tonal black with opacity variations
- Accent: Brand accent colors
- Border: CSS variables (--color-border-hover)
- Semantic: Success (green), Warning (amber), Error (red)
Typography:
- Font Family: Inter (system font stack)
- Headings: Inter, 600 weight
- Body: Inter, 400 weight
- Code: JetBrains Mono, 400 weight
- Button: Inter, 500 weight
Spacing:
- Tailwind default scale (0.5, 1, 2, 3, 4, 6, 8, 12, 16, 20, 24...)
- Component padding: Consistent with shadcn/ui defaults
User Personas
Primary Personas
1. Sarah - Visual Designer
yaml
Age: 28
Role: UI/UX Designer at marketing agency
Technical Level: Low (HTML/CSS basics)
Goals:
- Explore Wikit blocks for client projects
- Create mockups with real WordPress data
- Test layout variations quickly
Pain Points:
- Intimidated by terminal and Docker
- Fears "breaking" things
- Needs visual feedback
Key Workflows:
- Browse available blocks
- Create test pages with blocks
- Export designs/screenshots2. Marcus - Project Manager
yaml
Age: 35
Role: Digital PM at web agency
Technical Level: Very Low (no coding)
Goals:
- Demo features to clients
- Plan project scope and timelines
- Communicate with developers
Pain Points:
- Can't prototype without developer help
- Unclear what's technically possible
- Needs realistic demos
Key Workflows:
- Create quick prototypes
- Show clients feature possibilities
- Export/share project states3. Elena - Content Strategist
yaml
Age: 32
Role: Content Strategist at enterprise company
Technical Level: Low (WordPress editor experience)
Goals:
- Plan content architecture
- Test custom post types
- Visualize taxonomy structures
Pain Points:
- Limited technical knowledge
- Needs realistic content modeling
- Can't set up WordPress alone
Key Workflows:
- Create custom post types via AI
- Set up taxonomies and relationships
- Test content structuresUser Journeys
Journey 1: First Launch
%%{init:{'theme':'neutral'}}%%
graph LR
A[Download App] --> B[Double-Click to Install]
B --> C[First Launch]
C --> D{API Key Configured?}
D -->|No| E[Welcome Wizard]
E --> F[Enter API Key]
F --> G[Choose Preferences]
G --> H[Setup Complete]
D -->|Yes| H
H --> I[Main Interface]
Step-by-Step:
- Welcome Screen
Welcome to WDG Playground!
Create WordPress sites with AI
No technical setup required
[Get Started] [Learn More]- API Key Setup
Connect Your AI Assistant
Anthropic API Key:
[sk-ant-... ]
Get your key at:
console.anthropic.com
[Skip for Now] [Continue]- Preferences
Customize Your Experience
[x] Auto-save projects
[x] Show helpful tips
[ ] Advanced mode
Theme: Light Dark Auto
[Back] [Finish Setup]Journey 2: Creating First Project
%%{init:{'theme':'neutral'}}%%
sequenceDiagram
actor User as Sarah
participant UI as Main Interface
participant Wizard as Project Wizard
participant AI as AI Assistant
participant System as Backend
User->>UI: Click "New Project"
UI->>Wizard: Show wizard
User->>Wizard: Enter "Portfolio Site"
User->>Wizard: Select "Designer Template"
Wizard->>System: Create project
System->>System: Install WordPress
System->>System: Install Wikit framework
System->>System: Apply template
System->>UI: Project ready
UI->>User: Show project dashboard
User->>AI: "Show me available blocks"
AI->>User: Display block gallery
Project Creation Wizard:
Create New Project
Step 1: Project Details
Project Name: [Portfolio Site ]
URL: portfolio-site.localhost
(automatically generated)
Step 2: Choose Template
Blank Designer Business
Step 3: AI Features
[x] Enable AI assistant
[x] Index code for search
[ ] Advanced git features
[Cancel] [Create Project]Journey 3: Exploring Wikit Blocks
%%{init:{'theme':'neutral'}}%%
graph TD
A["Click Explore Blocks"] --> B[Block Gallery Opens]
B --> C[Browse Categories]
C --> D{Find Interesting Block}
D --> E[Click Block Card]
E --> F[View Block Details]
F --> G{Action}
G -->|Preview| H[Live Preview]
G -->|Insert| I[Add to Page]
G -->|Learn More| J[View Documentation]
H --> K[Close Preview]
I --> L[Edit Block Settings]
Block Explorer Interface:
Wikit Block Explorer [x]
Search: [hero section ]
Categories: [All] [Content] [Layout] [Media] [Forms]
Hero Hero Split Hero Video
[Preview] [Preview] [Preview]
[Insert] [Insert] [Insert]
Hero Carousel Hero Overlay Hero CTA
[Preview] [Preview] [Preview]
[Insert] [Insert] [Insert]
Ask AI: "Create a hero section with video bg"Journey 4: AI-Assisted Development
%%{init:{'theme':'neutral'}}%%
sequenceDiagram
actor User as Marcus (PM)
participant Chat as AI Chat
participant AI as Claude
participant Tools as MCP Tools
participant System as Backend
User->>Chat: "Add a team members section"
Chat->>AI: Send message
AI->>Tools: search_wikit_blocks("team")
Tools->>AI: Found Team Grid block
AI->>Tools: search_codebase("custom post type")
Tools->>AI: Found CPT examples
AI->>Chat: "I found a Team Grid block..."
Chat->>User: Show suggestion
User->>Chat: "Yes, do that"
AI->>System: Create team CPT
AI->>System: Insert Team Grid block
System->>Chat: Success
Chat->>User: "Done! View at /team"
Interface Design
Main Application Window
WDG Playground
Projects Portfolio Site
Portfolio Status: Running
Landing URL: https://portfolio-site.localhost:8443
Blog
Quick Actions:
AI Chat [Open Site] [Edit] [Settings] [Stop]
Blocks Recent Activity:
• Modified homepage.php - 2 mins ago
Tools • AI created Team CPT - 15 mins ago
• Indexed codebase - 1 hour ago
Settings
Project Statistics:
• Themes: 1
• Plugins: 5
• Pages: 12
• Posts: 8AI Chat Interface
AI Assistant - Portfolio Site
You: Show me available hero blocks
2:30 PM
Claude: I found 6 hero blocks in Wikit:
1. **Hero** - Standard hero with image/text
2. **Hero Split** - Two-column hero layout
3. **Hero Video** - Hero with background video
4. **Hero Carousel** - Rotating hero images
5. **Hero Overlay** - Text overlay on image
6. **Hero CTA** - Hero with prominent call-to-action
Would you like me to:
• Show previews of these blocks
• Add one to your homepage
• Create a custom hero variation
Used: search_wikit_blocks
2:30 PM
Type your message... (Shift+Enter for new line)
[↑]
Suggestions:
• "Add a contact form"
• "Create a testimonials slider"
• "Show me layout blocks"Block Gallery
Block Gallery
Search: [ ]
Filter: [All] [Content] [Layout] [Media] [Forms] [Custom]
Sort: [A-Z ]
Accordion Alert Blockquote
Warning " Quote here
Item 1 Alert text... — Author
Content
Item 2 [Learn More] [Learn More]
[Preview] [Preview] [Preview]
[Insert] [Insert] [Insert]
Button Group Card Carousel
[Btn] [Btn] [ Image ]
Title
Content
[Learn More]
[Preview] [Learn More] [Learn More]
[Insert] [Preview] [Preview]
[Insert] [Insert]
Showing 6 of 50+ blocks
[Load More]Project Settings
Project Settings - Portfolio Site
General General Settings
WordPress Project Name:
Git [Portfolio Site ]
AI Features
Backups Project URL:
Advanced [https://portfolio-site.localhost:8443]
Changing URL requires restart
Description:
[Personal portfolio website with... ]
[ ]
[ ]
WordPress Settings
Site Title:
[Sarah's Portfolio ]
Tagline:
[Designer & Creative ]
Admin Email:
[sarah@example.com ]
Timezone:
[America/New_York ]
[Cancel] [Save Changes]Feature Specifications
1. Visual Project Creation
Requirements:
- Wizard-based interface (3 steps max)
- Template gallery with previews
- Real-time name → URL conversion
- Estimated setup time shown
- Progress indicator during creation
Acceptance Criteria:
- User can create project in < 2 minutes
- Clear error messages if something fails
- Option to cancel mid-creation
- Success screen shows project URL + next steps
2. Block Explorer
Requirements:
- Grid layout with block previews
- Search by name/description
- Filter by category and tags
- Live preview on hover (optional)
- One-click insert to page
- Favorites/recents tracking
Acceptance Criteria:
- All 50+ Wikit blocks discoverable
- Search returns results in < 200ms
- Preview loads in < 1 second
- Insert action provides confirmation
3. AI Chat Assistant
Requirements:
- Persistent chat history per project
- Streaming responses
- Tool use visualization (show when searching code)
- Syntax highlighting in code blocks
- Copy code button on blocks
- Session management (new/load/delete chats)
Acceptance Criteria:
- Messages stream in < 2 seconds
- Tool use shown in real-time
- Code blocks formatted correctly
- Chat history loads instantly
- Can handle 1000+ messages per session
4. Visual Git Operations
Requirements:
- Show current branch visually
- Commit with message field (no terminal)
- Push/pull with progress indicator
- Visual diff viewer for changes
- Undo last commit (with warning)
- Branch switcher dropdown
Acceptance Criteria:
- Commit works with single button click
- Progress shown for network operations
- Diffs displayed with color coding
- Errors shown in plain language
5. Project Dashboard
Requirements:
- Service status indicators (green/red/yellow)
- Quick actions (open, edit, settings, stop)
- Recent activity feed
- Project statistics (pages, posts, etc.)
- Resource usage meters (RAM, disk)
Acceptance Criteria:
- Status updates every 5 seconds
- Actions complete in < 3 seconds
- Activity feed shows last 20 items
- Resource meters accurate to ±5%
6. Onboarding Flow
Requirements:
- Welcome screen on first launch
- API key input with validation
- Preference selection
- Optional tutorial
- Skip option always available
Acceptance Criteria:
- Wizard completable in < 3 minutes
- API key validated before proceeding
- Can skip and configure later
- Tutorial covers key features
Accessibility
WCAG 2.1 Level AA Compliance
Keyboard Navigation:
- All features accessible via keyboard
- Logical tab order throughout app
- Focus indicators clearly visible
- Keyboard shortcuts documented
Screen Reader Support:
- Semantic HTML in all views
- ARIA labels on interactive elements
- Status announcements for async actions
- Alt text on all images
Color & Contrast:
- Minimum 4.5:1 contrast ratio for text
- Color not sole indicator of state
- Dark mode with adjusted contrasts
- Colorblind-friendly palette
Motion & Animation:
- Respect prefers-reduced-motion
- Option to disable animations
- No auto-playing video
- Warnings for flashing content
Usability Testing Plan
Test Scenarios
Scenario 1: New User Creates First Project
- Task: Download app, create "My Portfolio" project
- Success: Project running, able to view site in browser
- Metrics: Time to completion, error rate, satisfaction
Scenario 2: Designer Explores Blocks
- Task: Find and preview Hero Video block
- Success: Block previewed, inserted into page
- Metrics: Time to find block, ease of use rating
Scenario 3: PM Uses AI to Add Feature
- Task: Use AI to add testimonials slider
- Success: Slider added via AI assistant
- Metrics: Chat turns needed, success rate
Scenario 4: Content Strategist Creates CPT
- Task: Create "Team Members" custom post type via AI
- Success: CPT created, able to add team members
- Metrics: Clarity of AI responses, result quality
Success Metrics
| Metric | Target | Measurement |
|---|---|---|
| Task Completion Rate | > 90% | Users complete primary tasks |
| Time on Task | < 5 min | For common workflows |
| Error Rate | < 10% | User-initiated errors |
| Satisfaction (SUS) | > 70 | System Usability Scale |
| Net Promoter Score | > 30 | Would recommend to peer |
Future UX Enhancements
Phase 2
- Collaboration - Share projects with team members
- Templates Marketplace - User-created templates
- Visual Page Builder - Drag-drop page creation
- Performance Insights - Visual performance metrics
Phase 3
- Real-Time Preview - See changes as you type in AI chat
- Component Library - Save custom block combinations
- Deployment - One-click deploy to hosting
- Analytics - Built-in site analytics dashboard
Document Status: Complete UX Specification Next Steps: Review with design team, create high-fidelity mockups Related Docs: Technical Architecture, Implementation Roadmap