Web Design Builder

by @rknall in Development

# Install this skill:

npx skills add rknall/claude-skills --skill "Web Design Builder"

Install specific skill from multi-skill repository

# Description

Create and refactor HTML5/JavaScript web designs from specifications or descriptions. Generates complete, accessible, responsive web designs with modern frameworks. Automatically verifies designs using Playwright MCP for accessibility and functionality testing. Use this skill when users ask to create web designs, mockups, landing pages, web applications, or refactor existing HTML/CSS/JS designs.

# SKILL.md

name: "Web Design Builder"
description: "Create and refactor HTML5/JavaScript web designs from specifications or descriptions. Generates complete, accessible, responsive web designs with modern frameworks. Automatically verifies designs using Playwright MCP for accessibility and functionality testing. Use this skill when users ask to create web designs, mockups, landing pages, web applications, or refactor existing HTML/CSS/JS designs."

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:

javascript // Check if mcp__playwright tools are available // Look for tools like: mcp__playwright__navigate, mcp__playwright__screenshot, etc.

If Playwright MCP is NOT 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

If Playwright MCP IS available:
- 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 fonts

Use 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 environment

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 playwright

Option 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 list

You 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!

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.

Web Design Builder

# Description

# SKILL.md

Web Design Builder

When to Use This Skill

Core Workflow

Phase 1: Requirements Gathering

Phase 2: Design Generation

Step 1: Create Design Mockup

Step 2: Save Design to File

Phase 3: Design Verification (ONLY if Playwright MCP is available)

Step 1: Launch Browser and Load Design

Step 2: Accessibility Testing

Step 3: Visual Testing

Step 4: Functionality Testing

Step 5: Performance Check

Phase 4: Verification Report

Phase 5: Iteration and Refinement

Design Patterns & Best Practices

Responsive Design

Accessible Forms

Interactive Components

Framework-Specific Guidelines

Tailwind CSS

React

Alpine.js

MCP Setup Instructions

Installing Playwright MCP

Communication Style

Deliverables

Example Workflow

# Related Skills

# Supported AI Coding Agents

Confirm

Submit a Skill