Web Design Builder
This skill creates professional HTML5/JavaScript web designs from specifications, with automatic accessibility and functionality verification using Playwright MCP.
When to Use This Skill
Activate this skill when the user requests:
- Create a web design from a specification or description
- Build a landing page, website, or web application
- Create a design mockup or prototype
- Refactor or improve existing HTML/CSS/JavaScript code
- Build responsive web interfaces
- Create component libraries or design systems
- Generate accessible web designs with WCAG compliance
Core Workflow
Phase 1: Requirements Gathering
When a user requests a web design, start by understanding their needs:
- Clarify the Design Scope
- What type of design? (landing page, dashboard, form, etc.) - Target audience and use case - Required features and functionality - Content and copy (provided or placeholder?) - Brand colors, fonts, or design system - Responsive requirements (mobile-first?)
- Technical Preferences
- Framework preference: - Vanilla HTML/CSS/JS (simple, no dependencies) - Tailwind CSS (utility-first, recommended for rapid development) - React (component-based, for complex interactions) - Vue (progressive framework) - Alpine.js (lightweight reactivity) - Browser support requirements - Accessibility requirements (WCAG level) - Performance constraints
- Check Playwright MCP Availability IMPORTANT: Before starting the design process, check if Playwright MCP is available:
// Check if mcp__playwright tools are available // Look for tools like: mcp__playwright__navigate, mcp__playwright__screenshot, etc.If Playwright MCP is NOT available: If Playwright MCP IS available:
- Inform the user: "Playwright MCP is not installed. Design verification will be skipped." - Provide installation instructions (see MCP Setup section below) - Continue with design generation but skip verification phase - Mark this clearly in the output - Inform the user: "Playwright MCP detected. Design will be automatically verified." - Include verification in the workflow
Phase 2: Design Generation
Step 1: Create Design Mockup
Generate a complete HTML/CSS/JS mockup including:
HTML Structure:
- Semantic HTML5 elements
- Proper heading hierarchy (h1 → h6)
- ARIA landmarks (header, nav, main, aside, footer)
- Accessible form labels and inputs
- Alt text for images
- Unique page title
CSS Styling:
- Responsive design (mobile-first)
- CSS Grid or Flexbox for layouts
- Custom properties (CSS variables) for theming
- Smooth transitions and animations
- Print styles (if applicable)
- Dark mode support (optional)
JavaScript Functionality:
- Progressive enhancement
- Accessible interactions (keyboard support)
- Form validation
- Dynamic content loading
- Event handling
- Error handling
Accessibility Features:
- WCAG 2.1 Level AA compliance minimum
- Keyboard navigation support
- Focus indicators
- Screen reader friendly
- Color contrast compliance (4.5:1 minimum)
- Skip links
- ARIA attributes where needed
Example Output Structure:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Page Title</title>
<style>
/* Modern CSS with custom properties */
:root {
--primary-color: #0066cc;
--text-color: #1a1a1a;
--bg-color: #ffffff;
--spacing: 1rem;
}
/* Reset and base styles */
*, *::before, *::after {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
line-height: 1.6;
color: var(--text-color);
background: var(--bg-color);
}
/* Responsive layout */
@media (max-width: 768px) {
/* Mobile styles */
}
</style>
</head>
<body>
<!-- Accessible skip link -->
<a href="#main-content" class="skip-link">Skip to main content</a>
<!-- Semantic structure -->
<header role="banner">
<nav aria-label="Main navigation">
<!-- Navigation -->
</nav>
</header>
<main id="main-content" role="main">
<!-- Main content -->
</main>
<footer role="contentinfo">
<!-- Footer -->
</footer>
<script>
// Progressive enhancement JavaScript
(function() {
'use strict';
// Feature detection
if (!('querySelector' in document)) return;
// Your JavaScript here
})();
</script>
</body>
</html>Step 2: Save Design to File
Save the generated design to a file:
// Recommended file structure
project-name/
index.html // Main HTML file
styles.css // Separate CSS (if needed)
script.js // Separate JS (if needed)
assets/
images/ // Image assets
fonts/ // Custom fontsUse the Write tool to create the file:
- Save to user's current directory or ask for preferred location
- Use descriptive filename (e.g.,
landing-page.html,dashboard.html) - Create single-file HTML for mockups (CSS/JS inline)
- Create separate files for production builds
Phase 3: Design Verification (ONLY if Playwright MCP is available)
IMPORTANT: Only execute this phase if Playwright MCP was detected in Phase 1.
Step 1: Launch Browser and Load Design
Use Playwright MCP to open the design:
// Navigate to the local HTML file
await mcp__playwright__navigate({
url: 'file:///path/to/design.html'
});Step 2: Accessibility Testing
Run comprehensive accessibility checks:
- Automated Accessibility Scan
- Check for WCAG violations - Verify color contrast ratios - Check heading hierarchy - Verify ARIA attributes - Check form labels - Verify alt text on images
- Keyboard Navigation Test
- Tab through all interactive elements - Verify focus indicators are visible - Check tab order is logical - Test Escape key behavior (modals, dropdowns) - Verify no keyboard traps
- Screen Reader Compatibility
- Check ARIA landmarks - Verify semantic HTML usage - Check dynamic content announcements - Verify form error messages
Step 3: Visual Testing
Capture screenshots and verify layout:
// Take full-page screenshot
await mcp__playwright__screenshot({
fullPage: true,
path: 'design-screenshot.png'
});
// Test responsive breakpoints
const breakpoints = [
{ width: 375, height: 667, name: 'mobile' },
{ width: 768, height: 1024, name: 'tablet' },
{ width: 1440, height: 900, name: 'desktop' }
];
for (const bp of breakpoints) {
await mcp__playwright__setViewportSize({
width: bp.width,
height: bp.height
});
await mcp__playwright__screenshot({
path: `design-${bp.name}.png`
});
}Step 4: Functionality Testing
Test interactive elements:
- Form Validation
- Test required fields - Test input validation - Test error messages - Test success states
- Interactive Components
- Test buttons and links - Test modals and dialogs - Test dropdowns and menus - Test tabs and accordions - Test carousels and sliders
- JavaScript Functionality
- Verify event handlers work - Test dynamic content loading - Check console for errors - Verify progressive enhancement
Step 5: Performance Check
Evaluate performance metrics:
- Load Time
- Measure page load time - Check resource loading - Identify bottlenecks
- Resource Optimization
- Check CSS file size - Check JavaScript file size - Verify image optimization - Check for unused CSS/JS
Phase 4: Verification Report
Generate a comprehensive report:
# Design Verification Report
## Overview
- **Design Type**: [Landing Page / Dashboard / etc.]
- **Framework**: [Vanilla / Tailwind / React / etc.]
- **Verification Date**: [Date]
- **Playwright MCP**: [Available / Not Available]
## Accessibility Compliance
### WCAG 2.1 Level AA
✅ **PASSED**: Color contrast (4.5:1 minimum)
✅ **PASSED**: Keyboard navigation
✅ **PASSED**: Semantic HTML structure
⚠️ **WARNING**: Missing alt text on 2 images
❌ **FAILED**: Form missing associated labels
### Issues Found
1. **HIGH**: Form input #email missing label
- Location: Line 45
- Fix: Add `<label for="email">Email</label>`
2. **MEDIUM**: Image missing alt text
- Location: Line 78
- Fix: Add `alt="Description of image"`
## Visual Testing
### Responsive Breakpoints
✅ **Mobile (375px)**: Layout renders correctly
✅ **Tablet (768px)**: Layout renders correctly
✅ **Desktop (1440px)**: Layout renders correctly
### Screenshots
- [x] Full page screenshot saved
- [x] Mobile screenshot saved
- [x] Tablet screenshot saved
- [x] Desktop screenshot saved
## Functionality Testing
### Interactive Elements
✅ Navigation menu works
✅ Form submission works
✅ Modal opens and closes
⚠️ Focus not returned to trigger after modal close
### JavaScript
✅ No console errors
✅ Event handlers working
✅ Progressive enhancement implemented
## Performance
### Metrics
- **Page Load Time**: 1.2s
- **Total File Size**: 45KB
- **CSS Size**: 12KB
- **JavaScript Size**: 8KB
### Optimization Opportunities
- Consider minifying CSS (potential 30% reduction)
- Lazy load images below the fold
- Consider code splitting for JavaScript
## Recommendations
### High Priority
1. Fix form label associations
2. Add missing alt text to images
3. Implement focus management for modal
### Medium Priority
1. Minify CSS and JavaScript for production
2. Add loading states for dynamic content
3. Implement error boundaries for JavaScript
### Low Priority
1. Add dark mode support
2. Enhance animations with reduced motion support
3. Add print styles
## Next Steps
1. Review and fix high-priority issues
2. Re-run verification after fixes
3. Test with actual screen readers
4. Conduct user testing
5. Deploy to staging environmentPhase 5: Iteration and Refinement
Based on verification results:
- Fix Critical Issues
- Address all accessibility violations - Fix broken functionality - Resolve layout issues
- Apply Improvements
- Implement recommended optimizations - Enhance visual design based on feedback - Refine interactions and animations
- Re-verify
- Run verification again after fixes - Ensure all issues are resolved - Generate updated report
- Deliver Final Design
- Provide clean, production-ready code - Include documentation - Provide deployment instructions - Share verification report
Design Patterns & Best Practices
Responsive Design
Mobile-First Approach:
/* Base styles for mobile */
.container {
padding: 1rem;
}
/* Tablet and up */
@media (min-width: 768px) {
.container {
padding: 2rem;
max-width: 960px;
margin: 0 auto;
}
}
/* Desktop and up */
@media (min-width: 1024px) {
.container {
padding: 3rem;
max-width: 1200px;
}
}Accessible Forms
<form class="contact-form">
<div class="form-field">
<label for="name">
Name <span aria-label="required">*</span>
</label>
<input
type="text"
id="name"
name="name"
required
aria-required="true"
aria-describedby="name-error"
/>
<span id="name-error" class="error" role="alert" hidden>
Please enter your name
</span>
</div>
</form>Interactive Components
Accessible Modal:
function openModal(modalId) {
const modal = document.getElementById(modalId);
const lastFocused = document.activeElement;
modal.hidden = false;
modal.setAttribute('aria-modal', 'true');
// Focus first focusable element
const firstFocusable = modal.querySelector('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
firstFocusable?.focus();
// Store last focused for return
modal.dataset.lastFocused = lastFocused;
// Trap focus
trapFocus(modal);
}
function closeModal(modalId) {
const modal = document.getElementById(modalId);
modal.hidden = true;
// Return focus
const lastFocused = document.querySelector(`[data-last-focused="${modal.id}"]`);
lastFocused?.focus();
}Framework-Specific Guidelines
Tailwind CSS
Pros:
- Rapid development
- Consistent design system
- Built-in responsive utilities
- Excellent for prototyping
Setup:
<script src="https://cdn.tailwindcss.com"></script>
<script>
tailwind.config = {
theme: {
extend: {
colors: {
primary: '#0066cc',
}
}
}
}
</script>Example:
<div class="container mx-auto px-4">
<h1 class="text-4xl font-bold text-gray-900 mb-4">
Welcome
</h1>
<button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
Click Me
</button>
</div>React
Pros:
- Component reusability
- Virtual DOM performance
- Large ecosystem
- Great for SPAs
Example:
function DesignComponent() {
const [isOpen, setIsOpen] = React.useState(false);
return (
<div className="container">
<button
onClick={() => setIsOpen(!isOpen)}
aria-expanded={isOpen}
>
Toggle
</button>
{isOpen && (
<div className="content">
Content here
</div>
)}
</div>
);
}Alpine.js
Pros:
- Lightweight (15KB)
- Declarative syntax
- No build step needed
- Good for progressive enhancement
Example:
<div x-data="{ open: false }">
<button @click="open = !open" :aria-expanded="open">
Toggle
</button>
<div x-show="open" x-transition>
Content here
</div>
</div>MCP Setup Instructions
If Playwright MCP is not available, provide these instructions to the user:
Installing Playwright MCP
Option 1: Via NPM (Recommended)
# Install Playwright MCP server
npm install -g @playwright/mcp-server
# Configure in Claude Code
claude code mcp add playwrightOption 2: Manual Setup
- Create MCP configuration file:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp-server"],
"env": {}
}
}
}- Restart Claude Code
Verification: After installation, verify Playwright MCP is working:
# Check MCP servers
claude code mcp listYou should see playwright in the list of available MCP servers.
Communication Style
When working with users:
- Clarify Requirements First
- Ask about design goals and constraints - Understand technical requirements - Confirm framework preferences
- Provide Context
- Explain design decisions - Justify framework choices - Describe accessibility considerations
- Show Progress
- Inform when generating design - Update during verification (if MCP available) - Share findings incrementally
- Be Actionable
- Provide specific fixes for issues - Include code examples - Offer alternatives when appropriate
- Handle MCP Unavailability Gracefully
- Clearly state when verification is skipped - Provide manual testing guidance - Offer installation instructions
Deliverables
At the end of the design process, provide:
- Complete Design Files
- HTML, CSS, JavaScript files - Assets (if any) - README with setup instructions
- Verification Report (if MCP available)
- Accessibility compliance results - Visual testing screenshots - Functionality test results - Performance metrics - Prioritized recommendations
- Documentation
- Component usage guide - Customization instructions - Browser support information - Deployment guidelines
- Next Steps
- Suggested improvements - Testing recommendations - Production checklist
Example Workflow
User Request:
"Create a landing page for a SaaS product with a hero section, features, pricing, and contact form."
Your Response:
- Clarify Requirements:
- "I'll create a modern SaaS landing page. A few questions: - Do you have brand colors or should I use a professional default palette? - Framework preference? I recommend Tailwind CSS for rapid development. - Any specific features to highlight? - Contact form fields needed?"
- Check Playwright MCP:
- "Checking for Playwright MCP... Not detected. Design verification will be skipped. Would you like installation instructions?"
- Generate Design:
- Create complete HTML/CSS/JS file - Include hero, features, pricing, contact form - Make it responsive and accessible - Save to saas-landing-page.html
- Manual Verification Guide (since MCP not available):
- Provide checklist for manual testing - Share accessibility testing tools - Suggest browser testing approach
- Deliver:
- Share complete design file - Provide customization guide - Offer iteration if needed
Remember: The goal is to create beautiful, accessible, functional web designs that work for all users, with automatic verification when possible!