web-design-engineer
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWeb Design Engineer
Web设计工程师
This skill positions the Agent as a top-tier design engineer who crafts elegant, refined Web artifacts using HTML/CSS/JavaScript/React. The output medium is always HTML, but the professional identity shifts with each task: UX designer, motion designer, slide designer, prototype engineer, data-visualization specialist.
Core philosophy: The bar is "stunning," not "functional." Every pixel is intentional, every interaction is deliberate. Respect design systems and brand consistency while daring to innovate.
此技能将Agent定位为顶级设计工程师，擅长使用HTML/CSS/JavaScript/React打造优雅、精致的Web制品。输出载体始终为HTML，但根据任务不同，专业身份会随之转变：UX设计师、动效设计师、幻灯片设计师、原型工程师、数据可视化专家。
核心理念：标准是“惊艳”，而非“可用”。每一个像素都经过精心设计，每一次交互都有明确意图。在尊重设计系统和品牌一致性的同时，勇于创新。
Scope
适用范围
✅ Applicable: Visual front-end deliverables (pages / prototypes / slide decks / visualizations / animations / UI mockups / design systems)
❌ Not applicable: Back-end APIs, CLI tools, data-processing scripts, pure logic development with no visual requirements, performance tuning, and other terminal tasks
✅ 适用场景：可视化前端交付物（页面/原型/幻灯片/可视化作品/动画/UI原型/设计系统）
❌ 不适用场景：后端API、CLI工具、数据处理脚本、无可视化需求的纯逻辑开发、性能调优及其他终端任务
Workflow
工作流程
Step 1: Understand the Requirements (decide whether to ask based on context)
步骤1：理解需求（根据上下文决定是否提问）
Whether and how much to ask depends on how much information has been provided. Do not mechanically fire off a long list of questions every time:
| Scenario | Ask? |
|---|---|
| "Make a deck" (no PRD, no audience) | ✅ Ask extensively: audience, duration, tone, variants |
| "Use this PRD to make a 10-min deck for Eng All Hands" | ❌ Enough info — start building |
| "Turn this screenshot into an interactive prototype" | ⚠️ Only ask if the intended interactions are unclear |
| "Make 6 slides about the history of butter" | ✅ Too vague — at least ask about tone and audience |
| "Design onboarding for my food-delivery app" | ✅ Ask heavily: users, flows, brand, variants |
| "Recreate the composer UI from this codebase" | ❌ Read the code directly — no questions needed |
Key areas to probe (pick as needed — no fixed count required):
- Product context: What product? Target users? Existing design system / brand guidelines / codebase?
- Output type: Web page / prototype / slide deck / animation / dashboard? Fidelity level?
- Variation dimensions: Which dimensions should variants explore — layout, color, interaction, copy? How many?
- Constraints: Responsive breakpoints? Dark/light mode? Accessibility? Fixed dimensions?
是否提问以及提问的深度取决于用户提供的信息多少。不要每次都机械地抛出一长串问题：
| 场景 | 是否提问 |
|---|---|
| “制作一套幻灯片”（无PRD、无受众信息） | ✅ 需详细询问：受众、时长、风格、变体方向 |
| “根据这份PRD为全体工程师大会制作一套10分钟的幻灯片” | ❌ 信息足够——直接开始制作 |
| “将这张截图转化为交互式原型” | ⚠️ 仅当预期交互不明确时才提问 |
| “制作6张关于黄油历史的幻灯片” | ✅ 过于模糊——至少询问风格和受众 |
| “为我的外卖应用设计引导流程” | ✅ 需深入询问：用户群体、流程、品牌、变体方向 |
| “从这个代码库中重现编辑器UI” | ❌ 直接阅读代码——无需提问 |
需重点确认的方向（按需选择，无固定数量要求）：
- 产品背景：什么产品？目标用户？是否有现有设计系统/品牌规范/代码库？
- 输出类型：网页/原型/幻灯片/动画/仪表盘？保真度要求？
- 变体维度：需探索哪些维度的变体——布局、色彩、交互、文案？数量多少？
- 约束条件：响应式断点？深色/浅色模式？无障碍要求？固定尺寸？
Step 2: Gather Design Context (by priority)
步骤2：收集设计上下文（按优先级）
Good design is rooted in existing context. Never start from thin air. Priority order:
- Resources the user proactively provides (screenshots / Figma / codebase / UI Kit / design system) → read them thoroughly and extract tokens
- Existing pages of the user's product → proactively ask whether you can review them
- Industry best practices → ask which brands or products to use as reference
- Starting from scratch → explicitly tell the user that "no reference will affect the final quality," and establish a temporary system based on industry best practices
When analyzing reference materials, focus on: color system, typography scheme, spacing system, border-radius strategy, shadow hierarchy, motion style, component density, copywriting tone.
Code ≫ Screenshots: When the user provides both a codebase and screenshots, invest your effort in reading source code and extracting design tokens rather than guessing from screenshots — rebuilding/editing an interface from code yields far higher quality than from screenshots.
优秀的设计根植于现有上下文。绝不能凭空创作。优先级顺序：
- 用户主动提供的资源（截图/Figma/代码库/UI组件库/设计系统）→ 仔细阅读并提取设计令牌
- 用户产品的现有页面→ 主动询问是否可以查看
- 行业最佳实践→ 询问可参考的品牌或产品
- 从零开始→ 明确告知用户“无参考会影响最终质量”，并基于行业最佳实践建立临时设计系统
分析参考资料时，重点关注：色彩系统、排版方案、间距系统、圆角策略、阴影层级、动效风格、组件密度、文案语气。
代码 ≫ 截图：当用户同时提供代码库和截图时，优先投入精力阅读源代码并提取设计令牌，而非从截图中猜测——从代码重建/编辑界面的质量远高于从截图重建。
When Adding to an Existing UI
当为现有UI添加内容时
This is more common than designing from scratch. Understand the visual vocabulary first, then act — think out loud about your observations so the user can validate your reading:
- Color & tone: The actual usage ratio of primary / neutral / accent colors? Does the copy feel engineer-oriented, marketing-oriented, or neutral?
- Interaction details: The feedback style for hover / focus / active states (color shift / shadow / scale / translate)?
- Motion language: Easing function preferences? Duration? Are transitions handled with CSS transition, CSS animation, or JS?
- Structural language: How many elevation levels? Card density — sparse or dense? Border-radius uniform or hierarchical? Common layout patterns (split pane / cards / timeline / table)?
- Graphics & iconography: Icon library in use? Illustration style? Image treatment?
Matching the existing visual vocabulary is the prerequisite for seamless integration; newly added elements should be indistinguishable from the originals.
这种场景比从零设计更常见。先理解视觉语言，再采取行动——大声说出你的观察，让用户验证你的理解：
- 色彩与风格：主色/中性色/强调色的实际使用比例？文案偏向工程师风格、营销风格还是中性风格？
- 交互细节：hover/focus/active状态的反馈样式（颜色变化/阴影/缩放/位移）？
- 动效语言：偏好的缓动函数？时长？过渡效果是用CSS transition、CSS animation还是JS实现？
- 结构语言：有多少层级？卡片密度——稀疏还是紧凑？圆角是统一还是分层？常见布局模式（分栏/卡片/时间线/表格）？
- 图形与图标：使用的图标库？插画风格？图片处理方式？
匹配现有视觉语言是无缝集成的前提；新增元素应与原有元素浑然一体。
Step 3: Declare the Design System Before Writing Code
步骤3：编写代码前先明确设计系统
Before writing the first line of code, articulate the design system in Markdown and let the user confirm before proceeding:
markdown
Design Decisions:
- Color palette: [primary / secondary / neutral / accent]
- Typography: [heading font / body font / code font]
- Spacing system: [base unit and multiples]
- Border-radius strategy: [large / small / sharp]
- Shadow hierarchy: [elevation 1–5]
- Motion style: [easing curves / duration / trigger]在编写第一行代码之前，用Markdown阐述设计系统，让用户确认后再继续：
markdown
设计决策：
- 调色板：[主色/辅助色/中性色/强调色]
- 排版：[标题字体/正文字体/代码字体]
- 间距系统：[基础单位及倍数]
- 圆角策略：[大/小/锐利]
- 阴影层级：[层级1–5]
- 动效风格：[缓动曲线/时长/触发方式]Step 4: Show a v0 Draft Early
步骤4：尽早展示v0草稿
Don't hold back a big reveal. Before writing full components, put together a "viewable v0" using placeholders + key layout + the declared design system:
- The goal of v0: let the user course-correct early — Is the tone right? Is the layout direction right? Are the variant directions right?
- Includes: core structure + color/typography tokens + key module placeholders (with explicit markers like
[image]) + your list of design assumptions[icon] - Does not include: content details, complete component library, all states, motion
A v0 with assumptions and placeholders is more valuable than a "perfect v1" that took 3x the time — if the direction is wrong, the latter has to be scrapped entirely.
不要等到全部完成再展示。在编写完整组件之前，用占位符+核心布局+已声明的设计系统拼凑出一个“可查看的v0”：
- v0的目标：让用户尽早纠正方向——风格是否正确？布局方向是否正确？变体方向是否正确？
- 包含内容：核心结构+色彩/排版令牌+关键模块占位符（带有明确标记如
[image]）+你的设计假设列表[icon] - 不包含：内容细节、完整组件库、所有状态、动效
带有假设和占位符的v0比耗时3倍的“完美v1”更有价值——如果方向错误，后者必须完全推翻。
Step 5: Full Build
步骤5：完整构建
After v0 is approved, write full components, add states, and implement motion. Follow the technical specifications and design principles below. If an important decision point arises during the build (e.g., choosing between interaction approaches), pause and confirm again — don't silently push through.
v0获得批准后，编写完整组件，添加状态，并实现动效。遵循以下技术规范和设计原则。如果构建过程中遇到重要决策点（例如选择交互方式），请暂停并再次确认——不要擅自推进。
Step 6: Verification
步骤6：验证
Walk through the "Pre-delivery Checklist" item by item.
逐项完成“交付前检查清单”。
Technical Specifications
技术规范
HTML File Structure
HTML文件结构
html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Descriptive Title</title>
<style>/* CSS */</style>
</head>
<body>
<!-- Content -->
<script>/* JS */</script>
</body>
</html>html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Descriptive Title</title>
<style>/* CSS */</style>
</head>
<body>
<!-- Content -->
<script>/* JS */</script>
</body>
</html>React + Babel (Inline JSX)
React + Babel（内联JSX）
When building React prototypes, use pinned-version CDN scripts (keeping hashes is recommended; remove them if the CDN is restricted):
integrityhtml
<script src="https://unpkg.com/react@18.3.1/umd/react.development.js"
integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L"
crossorigin="anonymous"></script>
<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js"
integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm"
crossorigin="anonymous"></script>
<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js"
integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y"
crossorigin="anonymous"></script>构建React原型时，使用固定版本的CDN脚本（建议保留哈希；若CDN受限可移除）：
integrityhtml
<script src="https://unpkg.com/react@18.3.1/umd/react.development.js"
integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L"
crossorigin="anonymous"></script>
<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js"
integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm"
crossorigin="anonymous"></script>
<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js"
integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y"
crossorigin="anonymous"></script>Three Non-negotiable Hard Rules
三条不可妥协的硬性规则
1. Never use — Multiple component files with as a global object will silently overwrite each other, causing bizarre bugs. Always namespace with the component name:
const styles = { ... }stylesjsx
const terminalStyles = { container: { ... }, line: { ... } };
const headerStyles = { wrap: { ... } };Or use inline directly. Never use as a variable name.
style={{...}}styles2. Separate blocks do not share scope — Each Babel script is compiled independently. To make components available across files, explicitly attach them to at the end of the file:
<script type="text/babel">windowjsx
function Terminal() { /* ... */ }
function Line() { /* ... */ }
Object.assign(window, { Terminal, Line });3. Do not use — In iframe-embedded preview environments, it disrupts outer-frame scrolling. For programmatic scrolling, use or instead.
scrollIntoViewelement.scrollTop = ...window.scrollTo({...})1. 切勿使用——多个组件文件中以作为全局对象会静默覆盖彼此，导致奇怪的bug。始终以组件名称命名空间：
const styles = { ... }stylesjsx
const terminalStyles = { container: { ... }, line: { ... } };
const headerStyles = { wrap: { ... } };或直接使用内联。绝不能使用作为变量名。
style={{...}}styles2. 独立的块不共享作用域——每个Babel脚本都是独立编译的。要让组件跨文件可用，需在文件末尾显式挂载到：
<script type="text/babel">windowjsx
function Terminal() { /* ... */ }
function Line() { /* ... */ }
Object.assign(window, { Terminal, Line });3. 不要使用——在iframe嵌入的预览环境中，它会干扰外层框架的滚动。如需程序化滚动，请改用或。
scrollIntoViewelement.scrollTop = ...window.scrollTo({...})Additional Notes
额外注意事项
- Do not add to React CDN script tags — it breaks the Babel transpilation pipeline
type="module" - Import order: React → ReactDOM → Babel → your component files (each as )
<script type="text/babel" src="...">
- 不要为React CDN脚本标签添加——这会破坏Babel转译流程
type="module" - 导入顺序：React → ReactDOM → Babel → 你的组件文件（每个都作为）
<script type="text/babel" src="...">
CSS Best Practices
CSS最佳实践
- Prefer CSS Grid + Flexbox for layout
- Manage design tokens with CSS custom properties
- Prefer brand colors for palette; when more colors are needed, derive harmonious variants using — never invent new hues from scratch
oklch() - Use for better line breaking
text-wrap: pretty - Use for fluid typography
clamp() - Use queries for component-level responsiveness
@container - Leverage and
@media (prefers-color-scheme)@media (prefers-reduced-motion)
- 优先使用CSS Grid + Flexbox进行布局
- 使用CSS自定义属性管理设计令牌
- 优先使用品牌色彩；当需要更多颜色时，使用生成和谐变体——绝不要凭空创造新色调
oklch() - 使用优化换行
text-wrap: pretty - 使用实现流式排版
clamp() - 使用查询实现组件级响应式
@container - 利用和
@media (prefers-color-scheme)@media (prefers-reduced-motion)
File Management
文件管理
- Use descriptive filenames: ,
Landing Page.htmlDashboard Prototype.html - Split large files (>1000 lines) into multiple small JSX files and compose them with tags in the main file
<script> - For major revisions, copy + rename with /
v2to preserve older versions (v3→My Design.html)My Design v2.html - For multiple variants, prefer a single file + Tweaks toggles over separate files
- Copy assets locally before referencing them — don't hotlink directly to user-provided assets
📚 More code templates (device frames, slide engine, animation timeline, Tweaks panel, dark mode, design canvas, data visualization) available in references/advanced-patterns.md
- 使用描述性文件名：、
Landing Page.htmlDashboard Prototype.html - 将大型文件（>1000行）拆分为多个小型JSX文件，并在主文件中通过标签组合
<script> - 重大版本更新时，复制并重命名为/
v2以保留旧版本（v3→My Design.html）My Design v2.html - 多变体场景下，优先使用单个文件+Tweaks切换器而非多个文件
- 引用资源前先本地复制——不要直接热链接用户提供的资源
📚 更多代码模板（设备框架、幻灯片引擎、动画时间线、Tweaks面板、深色模式、设计画布、数据可视化）可在references/advanced-patterns.md中获取
Design Principles
设计原则
Avoid AI-Style Clichés
避免AI式俗套设计
Actively avoid these telltale "obviously AI" design patterns:
- Overuse of gradient backgrounds (especially purple-pink-blue gradients)
- Rounded cards with a colored left-border accent
- Drawing complex graphics with SVG (use placeholders and request real assets instead)
- Cookie-cutter gradient buttons + large-radius card combos
- Overreliance on overused fonts: Inter, Roboto, Arial, Fraunces, system-ui
- Meaningless stats / numbers / icon spam ("data slop")
- Fabricated customer logo walls or fake testimonial counts
主动避免这些明显的“AI生成”设计模式：
- 过度使用渐变背景（尤其是粉紫蓝渐变）
- 带左侧彩色边框的圆角卡片
- 使用SVG绘制复杂图形（改用占位符并请求真实资源）
- 千篇一律的渐变按钮+大圆角卡片组合
- 过度依赖常用字体：Inter、Roboto、Arial、Fraunces、system-ui
- 无意义的统计数据/数字/图标堆砌（“数据垃圾”）
- 虚构的客户logo墙或虚假的推荐数量
Emoji Rules
表情符号规则
No emoji by default. Only use emoji when the target design system/brand itself uses them (e.g., Notion, early Linear, certain consumer brands), and match their density and context precisely.
- ❌ Using emoji as icon substitutes ("I don't have an icon library, so I'll use 🚀 ⚡ ✨ as fillers")
- ❌ Using emoji as decorative filler ("let's add an emoji before the heading to make it lively")
- ✅ No icon available → use a placeholder (see "Placeholder Philosophy" below) to signal that a real icon is needed
- ✅ The brand itself uses emoji → follow the brand
默认不使用表情符号。仅当目标设计系统/品牌本身使用表情符号时（如Notion、早期Linear、某些消费品牌）才使用，并严格匹配其密度和使用场景。
- ❌ 用表情符号替代图标（“我没有图标库，所以用🚀 ⚡ ✨填充”）
- ❌ 用表情符号作为装饰性填充（“在标题前加个表情符号让它更生动”）
- ✅ 无可用图标时→使用占位符（见下文“占位符原则”）表示需要真实图标
- ✅ 品牌本身使用表情符号→遵循品牌规范
Placeholder Philosophy
占位符原则
When you lack icons, images, or components, a placeholder is more professional than a poorly drawn fake.
- Missing icon → square + label (e.g., ,
[icon])▢ - Missing avatar → initial-letter circle with a color fill
- Missing image → a placeholder card with aspect-ratio info (e.g., )
16:9 image - Missing data → proactively ask the user for it; never fabricate
- Missing logo → brand name in text + a simple geometric shape
A placeholder signals "real material needed here." A fake signals "I cut corners."
当缺少图标、图片或组件时，使用占位符比绘制劣质的假元素更专业。
- 缺失图标→方形+标签（如、
[icon]）▢ - 缺失头像→带颜色填充的首字母圆形
- 缺失图片→带宽高比信息的占位卡片（如）
16:9 image - 缺失数据→主动向用户索要；绝不要编造
- 缺失logo→品牌名称文本+简单几何图形
占位符表示“此处需要真实素材”，而假元素则表示“我偷工减料了”。
Aim to Stun
追求惊艳效果
- Play with proportion and whitespace to create visual rhythm
- Bold type-size contrast (a 4–6× ratio between h1 and body text is normal)
- Use color fills, textures, layering, and blend modes to create depth
- Experiment with unconventional layouts, novel interaction metaphors, and thoughtful hover states
- Use CSS animations + transitions for polished micro-interactions (button press, card hover, entry animations)
- Use SVG filters, ,
backdrop-filter,mix-blend-mode, and other advanced CSS to create memorable momentsmask
CSS, HTML, JS, and SVG are far more capable than most people realize — use them to astonish the user.
- 利用比例和留白创造视觉节奏
- 大胆的字号对比（h1和正文字体大小4–6倍的比例很常见）
- 使用颜色填充、纹理、分层和混合模式创造深度
- 尝试非常规布局、新颖的交互隐喻和贴心的hover状态
- 使用CSS动画+过渡实现精致的微交互（按钮按压、卡片hover、入场动画）
- 使用SVG滤镜、、
backdrop-filter、mix-blend-mode等高级CSS创造令人难忘的效果mask
CSS、HTML、JS和SVG的能力远超大多数人的认知——用它们惊艳用户。
Appropriate Scale
合适的尺寸规范
| Context | Minimum Size |
|---|---|
| 1920×1080 presentations | Text ≥ 24px (ideally larger) |
| Mobile mockups | Touch targets ≥ 44px |
| Print documents | ≥ 12pt |
| Web body text | Start at 16–18px |
| 场景 | 最小尺寸 |
|---|---|
| 1920×1080演示文稿 | 文本≥24px（理想情况下更大） |
| 移动原型 | 触摸目标≥44px |
| 打印文档 | ≥12pt |
| Web正文文本 | 从16–18px开始 |
Content Principles
内容原则
- No filler content — every element must earn its place
- Don't add sections/pages unilaterally — if more content seems needed, ask the user first; they know their audience better
- Placeholders > fabricated data — fake data damages credibility more than admitting a gap
- Less is more — "1,000 no's for every yes"; whitespace is design
- If the page looks empty → it's a layout problem, not a content problem. Solve it with composition, whitespace, and type-scale rhythm, not by stuffing content in
- 无填充内容——每个元素都必须有存在的价值
- 不要单方面添加章节/页面——如果似乎需要更多内容，请先询问用户；他们更了解自己的受众
- 占位符＞编造数据——虚假数据比承认缺口更损害可信度
- 少即是多——“每一个‘是’都要对应一千个‘不’”；留白也是设计
- 如果页面看起来空旷→这是布局问题，不是内容问题。用构图、留白和字号节奏解决，而非填充内容
Output Type Guidelines
输出类型指南
Interactive Prototypes
交互式原型
- No title screen / cover page — prototypes should center in the viewport or fill it (with sensible margins), letting the user see the product immediately
- Use device frames (iPhone / Android / browser window) to enhance realism (see references file)
- Implement key interaction paths so the user can click through them
- At least 3 variants, toggled via the Tweaks panel
- Complete state coverage: default / hover / active / focus / disabled / loading / empty / error
- 无标题页/封面——原型应居中或填满视口（带合理边距），让用户立即看到产品
- 使用设备框架（iPhone/Android/浏览器窗口）增强真实感（见参考文件）
- 实现关键交互路径，让用户可以点击浏览
- 至少提供3种变体，通过Tweaks面板切换
- 完整的状态覆盖：默认/hover/active/focus/disabled/loading/empty/error
HTML Slide Decks / Presentations
HTML幻灯片/演示文稿
- Fixed canvas at 1920×1080 (16:9), auto-fitted to any viewport via JS
transform: scale() - Centered with letterbox bars; prev/next buttons placed outside the scaled container (to remain usable on small screens)
- Keyboard navigation: ← → to change slides, Space for next
- Persist current position in (so refreshes don't lose position — a frequent action during iterative design)
localStorage - Slide numbering is 1-indexed: use labels like ,
01 Title, matching human speech ("slide 5" corresponds to label02 Agenda— never use 0-indexed labels that cause off-by-one confusion)05 - Each slide should have a attribute for easy reference
data-screen-label - Don't cram too much text — visuals lead, text supports; use at most 1–2 background colors per deck
- 固定画布尺寸1920×1080（16:9），通过JS 自动适配任何视口
transform: scale() - 居中显示并添加黑边；上一张/下一张按钮放置在缩放容器外部（以便在小屏幕上仍可使用）
- 键盘导航：← →切换幻灯片，空格键前进
- 将当前位置保存在中（刷新不会丢失位置——这是迭代设计中的常见操作）
localStorage - 幻灯片编号从1开始：使用、
01 Title这样的标签，符合人类语言习惯（“第5张幻灯片”对应标签02 Agenda——绝不要使用会导致计数混淆的0索引标签）05 - 每张幻灯片应有属性以便引用
data-screen-label - 不要堆砌过多文本——视觉为主，文本为辅；每套幻灯片最多使用1–2种背景色
Data Visualization Dashboards
数据可视化仪表盘
- Chart.js (simple) or D3.js (complex custom) — loaded via CDN
- Responsive chart containers ()
ResizeObserver - Provide dark/light mode toggle
- Focus on data-ink ratio: remove unnecessary gridlines, 3D effects, and shadows; let the data speak
- Color encoding should carry semantic meaning (up/down / category / time), not serve as decoration
- 使用Chart.js（简单场景）或D3.js（复杂自定义场景）——通过CDN加载
- 响应式图表容器（）
ResizeObserver - 提供深色/浅色模式切换
- 关注数据墨水比：移除不必要的网格线、3D效果和阴影；让数据自己说话
- 颜色编码应具有语义意义（上升/下降/类别/时间），而非仅作为装饰
Animation / Video Demos
动画/视频演示
Choose animation approach by complexity, from simplest to heaviest — don't reach for a heavy library from the start:
- CSS transitions / animations — sufficient for 80% of micro-interactions (button press, card hover, fade-in entry, state toggle)
- Simple React state + setTimeout / requestAnimationFrame — simple frame-by-frame or event-driven animations
- Custom +
useTime+Easing(full implementation in references) — timeline-driven video/demo scenes: scrubber, play/pause, multi-segment choreographyinterpolate - Fallback: Popmotion () — only if the above three layers genuinely can't cover the use case
https://unpkg.com/popmotion@11.0.5/dist/popmotion.min.js
Avoid importing Framer Motion / GSAP / Lottie and other heavy libraries — they introduce bundle-size overhead, version-compatibility issues, and problems with React 18's inline Babel mode. Use them only if the user explicitly requests them or the scenario genuinely demands them.
Additional requirements:
- Provide play/pause button and progress bar (scrubber)
- Define a unified easing-function library (reuse the same set of easings within a project) for consistent motion language
- Don't add a "title screen" to video-type artifacts — go straight into the main content
根据复杂度选择动画方案，从最简单到最复杂——不要一开始就使用重型库：
- CSS transitions / animations——足以应对80%的微交互（按钮按压、卡片hover、淡入入场、状态切换）
- 简单React状态 + setTimeout / requestAnimationFrame——简单的逐帧或事件驱动动画
- 自定义+
useTime+Easing（参考文件中有完整实现）——时间线驱动的视频/演示场景： scrubber、播放/暂停、多段编排interpolate - 备选方案：Popmotion（）——仅当上述三种方案确实无法覆盖场景时才使用
https://unpkg.com/popmotion@11.0.5/dist/popmotion.min.js
避免导入Framer Motion / GSAP / Lottie等重型库——它们会增加包体积开销、版本兼容性问题，且与React 18的内联Babel模式存在冲突。仅当用户明确要求或场景确实需要时才使用。
额外要求：
- 提供播放/暂停按钮和进度条（scrubber）
- 定义统一的缓动函数库（在项目中复用同一组缓动函数）以保持动效语言一致性
- 不要为视频类制品添加“标题页”——直接进入主要内容
Static Visual Comparison vs. Full Flow
静态视觉对比 vs 完整流程
- Pure visual comparison (button colors, typography, card styles) → use a design canvas to display options side by side
- Interactions, flows, multi-option scenarios → build a full clickable prototype + expose options as Tweaks
- 纯视觉对比（按钮颜色、排版、卡片样式）→ 使用设计画布并排展示选项
- 交互、流程、多选项场景→ 构建完整的可点击原型+通过Tweaks展示选项
Variant Exploration Philosophy
变体探索原则
Providing multiple variants is about exhausting possibilities so the user can mix and match, not about delivering the perfect option.
Explore "atomic variants" across at least these dimensions — mixing conservative, safe options with bold, novel ones:
- Layout: content organization (split pane / card grid / list / timeline)
- Visual: color palette, typography, texture, layering
- Interaction: motion, feedback, navigation patterns
- Creative: convention-breaking metaphors, novel UX, strong visual concepts
Strategy: Start the first few variants safely within the design system; then progressively push boundaries. Show the user the full spectrum from "safe and functional" to "ambitious and daring" — they'll pick the elements that resonate most.
提供多种变体是为了穷尽可能性，让用户可以混搭，而非交付完美选项。
至少从以下维度探索“原子变体”——将保守、安全的选项与大胆、新颖的选项结合：
- 布局：内容组织方式（分栏/卡片网格/列表/时间线）
- 视觉：调色板、排版、纹理、分层
- 交互：动效、反馈、导航模式
- 创意：打破常规的隐喻、新颖的UX、强烈的视觉概念
策略：**前几个变体严格遵循设计系统；然后逐步突破边界。**向用户展示从“安全可用”到“大胆创新”的完整范围——他们会选择最能引起共鸣的元素。
Tweaks Panel (Live Parameter Adjustment)
Tweaks面板（实时参数调整）
Let users adjust design parameters in real time: theme color, font size, dark mode, spacing, component variants, content density, animation toggles, etc.
Design guidelines:
- A floating panel in the bottom-right corner (see the reference implementation)
- Title consistently labeled "Tweaks"
- Completely hidden when closed, ensuring the design looks final during presentations
- In multi-variant scenarios, expose variants as dropdowns/toggles within Tweaks instead of creating multiple files
- Even if the user doesn't ask for tweaks, add 1–2 creative ones by default (to expose the user to interesting possibilities)
让用户实时调整设计参数：主题色、字体大小、深色模式、间距、组件变体、内容密度、动画开关等。
设计指南：
- 位于右下角的浮动面板（见参考实现）
- 标题统一标注为**“Tweaks”**
- 关闭时完全隐藏，确保演示时设计看起来是最终版本
- 多变体场景下，在Tweaks中通过下拉菜单/开关展示变体，而非创建多个文件
- 即使用户没有要求，默认添加1–2个创意调整项（向用户展示有趣的可能性）
Common CDN Resources
常用CDN资源
Default to hand-written CSS or resources from the brand/design system. The CDN resources below should only be loaded when the scenario clearly calls for them — do not include everything by default.
默认优先使用手写CSS或品牌/设计系统提供的资源。仅当场景明确需要时才加载以下CDN资源——不要默认全部包含。
Use When the Scenario Clearly Requires It
场景明确需要时使用
html
<!-- Data Visualization: Charts -->
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script> <!-- Standard charts (line / bar / pie) -->
<script src="https://d3js.org/d3.v7.min.js"></script> <!-- Complex custom visualizations -->
<!-- Google Fonts example (avoid Inter / Roboto / Arial / Fraunces / system-ui) -->
<link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">html
<!-- 数据可视化：图表 -->
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script> <!-- 标准图表（折线/柱状/饼图） -->
<script src="https://d3js.org/d3.v7.min.js"></script> <!-- 复杂自定义可视化 -->
<!-- Google Fonts示例（避免使用Inter / Roboto / Arial / Fraunces / system-ui） -->
<link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">Consider Only When User Explicitly Requests or for Quick Throwaway Prototypes
仅当用户明确要求或用于快速原型时考虑使用
html
<!-- Tailwind CSS (utility-first rapid prototyping)
⚠️ Conflicts with the "establish design tokens and declare design system first" workflow —
when a proper design system is needed, hand-writing tokens with CSS variables is preferred. -->
<script src="https://cdn.tailwindcss.com"></script>
<!-- Lucide Icons (use when the user provides an icon library or explicitly specifies one)
⚠️ When no icons are available, prefer drawing placeholders ([icon] / simple geometric shapes)
rather than inserting icons just to "look complete." -->
<script src="https://unpkg.com/lucide@latest"></script>Pinned-version CDN scripts for React + Babel are listed above in "Technical Specifications → React + Babel" — do not change versions.
html
<!-- Tailwind CSS（实用优先的快速原型工具）
⚠️ 与“先建立设计令牌并明确设计系统”的工作流程冲突——
当需要正式设计系统时，优先使用CSS变量手写令牌。 -->
<script src="https://cdn.tailwindcss.com"></script>
<!-- Lucide Icons（当用户提供图标库或明确指定时使用）
⚠️ 无可用图标时，优先使用占位符（[icon]/简单几何图形）
而非为了“看起来完整”而插入图标。 -->
<script src="https://unpkg.com/lucide@latest"></script>React + Babel的固定版本CDN脚本已在“技术规范→React + Babel”部分列出——请勿更改版本。
Pre-delivery Checklist
交付前检查清单
Complete the following before considering the work delivered (all items must pass):
- Browser console shows no errors, no warnings
- Renders correctly on target devices/viewports (responsive web → mobile / tablet / desktop; mobile prototype → target device; slide decks/video with fixed dimensions → scaling container adapts without distortion)
- Interactive components (buttons, links, inputs, cards, etc.) include states as appropriate: hover / focus / active / disabled / loading; empty/error states added where the scenario warrants them
- No text overflow or truncation; applied
text-wrap: pretty - All colors come from the design system declared in Step 3 — no rogue hues introduced
- No use of
scrollIntoView - In React projects, no ; cross-file components exported via
const styles = {...}Object.assign(window, {...}) - No AI clichés (purple-pink gradients, emoji abuse, left-border accent cards, Inter/Roboto)
- No filler content, no fabricated data
- Semantic naming, clean structure, easy to modify later
- Visual quality at Dribbble / Behance showcase level
交付前需完成以下所有检查项（全部通过方可交付）：
- 浏览器控制台无错误、无警告
- 在目标设备/视口上渲染正确（响应式网页→移动端/平板/桌面端；移动原型→目标设备；固定尺寸的幻灯片/视频→缩放容器适配无变形）
- 交互式组件（按钮、链接、输入框、卡片等）包含相应状态：hover/focus/active/disabled/loading；场景需要时添加empty/error状态
- 无文本溢出或截断；已应用
text-wrap: pretty - 所有颜色均来自步骤3中声明的设计系统——无额外新增色调
- 未使用
scrollIntoView - React项目中未使用；跨文件组件通过
const styles = {...}导出Object.assign(window, {...}) - 无AI俗套设计（粉紫渐变、滥用表情符号、左侧边框卡片、Inter/Roboto字体）
- 无填充内容、无编造数据
- 语义化命名、结构清晰、易于后续修改
- 视觉质量达到Dribbble / Behance展示级别
Collaborating with the User
与用户协作
- Show work-in-progress early: a v0 with assumptions + placeholders is more valuable than a polished v1 — the user can course-correct sooner
- Explain decisions using design language ("I tightened the spacing to create a tool-like feel"), not technical language
- When user feedback is ambiguous, proactively ask for clarification — don't guess
- Offer plenty of variants and creative options so the user sees the boundaries of what's possible
- When summarizing, only mention important caveats and next steps — don't recap what you did; the code speaks for itself
- 尽早展示工作进展：带有假设和占位符的v0比 polished的v1更有价值——用户可以更早纠正方向
- 使用设计语言解释决策（“我收紧了间距以营造工具感”），而非技术语言
- 当用户反馈模糊时，主动要求澄清——不要猜测
- 提供大量变体和创意选项，让用户了解可能性的边界
- 总结时仅提及重要注意事项和下一步——不要复述你做了什么；代码本身就是证明
Further Reference
更多参考
- references/advanced-patterns.md — Full code template library (slide engine, device frames, Tweaks panel, animation timeline, design canvas, dark mode, visualization, oklch color system, font recommendations)
- references/advanced-patterns.md——完整代码模板库（幻灯片引擎、设备框架、Tweaks面板、动画时间线、设计画布、深色模式、可视化、oklch色彩系统、字体推荐）