Web Design Builder

Web 设计构建器

此技能可根据规格说明创建专业的 HTML5/JavaScript 网页设计，并使用 Playwright MCP 自动验证无障碍性和功能。

何时使用此技能

在用户请求以下内容时启用此技能：

• 根据规格说明或描述创建网页设计
• 构建落地页、网站或 Web 应用
• 创建设计模型或原型
• 重构或改进现有的 HTML/CSS/JavaScript 代码
• 构建响应式 Web 界面
• 创建组件库或设计系统
• 创建符合 WCAG 标准的无障碍网页设计

核心工作流

阶段 1：收集需求

当用户请求网页设计时，首先了解他们的需求：

1. 明确设计范围

   • 设计类型是什么？（落地页、仪表板、表单等）
   • 目标受众和使用场景
   • 所需功能和特性
   • 内容和文案（由用户提供还是使用占位内容？）
   • 品牌颜色、字体或设计系统
   • 响应式要求（移动优先？）

2. 技术偏好

   • 框架偏好：
     • 原生 HTML/CSS/JS（简单、无依赖）
     • Tailwind CSS（实用程序优先，推荐用于快速开发）
     • React（基于组件，适用于复杂交互）
     • Vue（渐进式框架）
     • Alpine.js（轻量级响应式框架）
   • 浏览器支持要求
   • 无障碍要求（WCAG 级别）
   • 性能限制

3. 检查 Playwright MCP 是否可用

   重要：开始设计流程前，检查 Playwright MCP 是否可用：

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

   如果 Playwright MCP 不可用：

   • 告知用户：“未安装 Playwright MCP，将跳过设计验证。”
   • 提供安装说明（参见下文的 MCP 设置部分）
   • 继续生成设计，但跳过验证阶段
   • 在输出中明确标注这一点

   如果 Playwright MCP 可用：

   • 告知用户：“已检测到 Playwright MCP，将自动验证设计。”
   • 在工作流中加入验证步骤

阶段 2：生成设计

步骤 1：创建设计模型

生成完整的 HTML/CSS/JS 模型，包括：

HTML 结构：

• 语义化 HTML5 元素
• 正确的标题层级（h1 → h6）
• ARIA 地标（header、nav、main、aside、footer）
• 无障碍表单标签和输入项
• 图片替代文本
• 唯一的页面标题

CSS 样式：

• 响应式设计（移动优先）
• 使用 CSS Grid 或 Flexbox 进行布局
• 使用自定义属性（CSS 变量）实现主题样式
• 平滑的过渡效果和动画
• 打印样式（如适用）
• 暗色模式支持（可选）

JavaScript 功能：

• 渐进增强
• 无障碍交互（支持键盘操作）
• 表单验证
• 动态内容加载
• 事件处理
• 错误处理

无障碍功能：

• 至少符合 WCAG 2.1 AA 级标准
• 支持键盘导航
• 焦点指示器
• 便于屏幕阅读器使用
• 符合色彩对比度要求（至少 4.5:1）
• 跳转链接
• 在需要时使用 ARIA 属性

输出结构示例：

<!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>
  
  <a href="#main-content" class="skip-link">Skip to main content</a>

  
  <header role="banner">
    <nav aria-label="Main navigation">
      
    </nav>
  </header>

  <main id="main-content" role="main">
    
  </main>

  <footer role="contentinfo">
    
  </footer>

  <script>
    // Progressive enhancement JavaScript
    (function() {
      'use strict';

      // Feature detection
      if (!('querySelector' in document)) return;

      // Your JavaScript here
    })();
  </script>
</body>
</html>

步骤 2：将设计保存到文件

将生成的设计保存到文件：

// 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

使用 Write 工具创建文件：

• 保存到用户当前目录，或询问其偏好的保存位置
• 使用描述性文件名（例如，landing-page.html、dashboard.html）
• 模型使用单文件 HTML（CSS/JS 内嵌）
• 生产构建使用单独的文件

阶段 3：设计验证（仅在 Playwright MCP 可用时执行）

重要：仅当在阶段 1 检测到 Playwright MCP 时，才执行此阶段。

步骤 1：启动浏览器并加载设计

使用 Playwright MCP 打开设计：

// Navigate to the local HTML file
await mcp__playwright__navigate({
  url: 'file:///path/to/design.html'
});

步骤 2：无障碍测试

运行全面的无障碍检查：

1. 自动化无障碍扫描

   • 检查是否违反 WCAG
   • 验证颜色对比度
   • 检查标题层级
   • 验证 ARIA 属性
   • 检查表单标签
   • 验证图片的替代文本

2. 键盘导航测试

   • 使用 Tab 键遍历所有交互元素
   • 验证焦点指示器是否清晰可见
   • 检查 Tab 键顺序是否符合逻辑
   • 测试 Escape 键行为（模态框、下拉菜单）
   • 验证不存在键盘陷阱

3. 屏幕阅读器兼容性

   • 检查 ARIA 地标
   • 验证语义化 HTML 的使用
   • 检查动态内容播报
   • 验证表单错误消息

步骤 3：视觉测试

截取屏幕截图并验证布局：

// 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`
  });
}

步骤 4：功能测试

测试交互元素：

1. 表单验证

   • 测试必填字段
   • 测试输入验证
   • 测试错误消息
   • 测试成功状态

2. 交互组件

   • 测试按钮和链接
   • 测试模态框和对话框
   • 测试下拉菜单和菜单
   • 测试标签页和折叠面板
   • 测试轮播和滑块

3. JavaScript 功能

   • 验证事件处理程序是否正常工作
   • 测试动态内容加载
   • 检查控制台是否有错误
   • 验证渐进增强

步骤 5：性能检查

评估性能指标：

1. 加载时间

   • 测量页面加载时间
   • 检查资源加载情况
   • 识别性能瓶颈

2. 资源优化

   • 检查 CSS 文件大小
   • 检查 JavaScript 文件大小
   • 验证图片优化情况
   • 检查是否存在未使用的 CSS/JS

阶段 4：验证报告

生成一份全面的报告：

# 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

阶段 5：迭代与优化

根据验证结果：

1. 修复关键问题

   • 解决所有无障碍违规问题
   • 修复损坏的功能
   • 解决布局问题

2. 应用改进

   • 实施建议的优化
   • 根据反馈改进视觉设计
   • 优化交互和动画

3. 重新验证

   • 修复后再次运行验证
   • 确保所有问题均已解决
   • 生成更新后的报告

4. 交付最终设计

   • 提供简洁、可用于生产环境的代码
   • 附上文档
   • 提供部署说明
   • 分享验证报告

设计模式与最佳实践

响应式设计

移动优先方法：

/* 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;
  }
}

无障碍表单

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

交互组件

无障碍模态框：

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();
}

特定框架指南

Tailwind CSS

优点：

• 开发速度快
• 设计系统一致
• 内置响应式工具类
• 非常适合原型设计

设置：

<script src="https://cdn.tailwindcss.com"></script>
<script>
  tailwind.config = {
    theme: {
      extend: {
        colors: {
          primary: '#0066cc',
        }
      }
    }
  }
</script>

示例：

<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

优点：

• 组件可复用
• 虚拟 DOM 性能出色
• 生态系统庞大
• 非常适合 SPA

示例：

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

优点：

• 轻量（15KB）
• 声明式语法
• 无需构建步骤
• 适用于渐进增强

示例：

<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 设置说明

如果 Playwright MCP 不可用，请向用户提供以下说明：

安装 Playwright MCP

选项 1：通过 NPM（推荐）

# Install Playwright MCP server
npm install -g @playwright/mcp-server

# Configure in Claude Code
claude code mcp add playwright

选项 2：手动设置

1. 创建 MCP 配置文件：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp-server"],
      "env": {}
    }
  }
}

2. 重启 Claude Code

验证： 安装后，验证 Playwright MCP 是否正常工作：

# Check MCP servers
claude code mcp list

你应该能在可用 MCP 服务列表中看到 playwright。

沟通风格

与用户合作时：

1. 先明确需求

   • 询问设计目标和限制条件
   • 了解技术需求
   • 确认框架偏好

2. 提供背景信息

   • 解释设计决策
   • 说明框架选择的理由
   • 描述无障碍设计方面的考量

3. 展示进展

   • 告知用户何时开始生成设计
   • 在验证期间（如果 MCP 可用）更新进展
   • 逐步分享发现

4. 提供可执行的建议

   • 针对问题提供具体的修复方案
   • 附上代码示例
   • 适时提供替代方案

5. 妥善处理 MCP 不可用的情况

   • 明确说明跳过验证的情况
   • 提供手动测试指南
   • 提供安装说明

交付内容

设计流程结束时，提供：

1. 完整设计文件

   • HTML、CSS、JavaScript 文件
   • 资源（如有）
   • 附带设置说明的 README

2. 验证报告（如果 MCP 可用）

   • 无障碍合规性结果
   • 视觉测试截图
   • 功能测试结果
   • 性能指标
   • 按优先级排序的建议

3. 文档

   • 组件使用指南
   • 自定义说明
   • 浏览器支持信息
   • 部署指南

4. 后续步骤

   • 改进建议
   • 测试建议
   • 生产环境检查清单

工作流示例

用户请求：

“为 SaaS 产品创建一个落地页，包含主视觉区域、功能介绍、定价和联系表单。”

你的回复：

1. 明确需求：

   • “我会创建一个现代风格的 SaaS 落地页。有几个问题：
     • 你有品牌色吗？还是希望我采用专业的默认配色方案？
     • 对框架有偏好吗？我建议使用 Tailwind CSS，以便快速开发。
     • 有需要重点介绍的具体功能吗？
     • 联系表单需要哪些字段？”

2. 检查 Playwright MCP：

   • “正在检查 Playwright MCP……未检测到。将跳过设计验证。你需要安装说明吗？”

3. 生成设计：

   • 创建完整的 HTML/CSS/JS 文件
   • 加入主视觉区域、功能介绍、定价和联系表单
   • 确保响应式布局和无障碍设计
   • 保存为 saas-landing-page.html

4. 手动验证指南（由于 MCP 不可用）：

   • 提供手动测试检查清单
   • 分享无障碍测试工具
   • 建议浏览器测试方法

5. 交付：

   • 分享完整的设计文件
   • 提供自定义指南
   • 根据需要提供迭代优化

请记住：目标是创建美观、无障碍且功能完善的网页设计，让所有用户都能使用，并尽可能进行自动验证！