design-engineering

design-engineering

这项技能是一张图谱，而不是一个文件。以下正文是内容地图。仅在需要时沿着 [[wikilinks]] 查看——这正是渐进式披露的意义。

如何使用这项技能

0. /design-engineering 首先是一个路由器，其次才是资料库：[[skill-router]] 会解析设计契约，判定所处阶段（未决定 → 构建 → 优化 → 检查 → 命名），并将任务交给一个负责人——这里的一个节点、一个子 Agent，或一个已安装的伴随技能（AgentsORG design、impeccable、HyperFrames、ElevenLabs、transitions-dev、shadcn CLI、diagram-design、tldraw、GSAP、better-icons、Jakub Krehel 的 interfaces 技能、fun-isometric）。负责人最多一两个，绝不选五个。
1. 先进行路由：对于大多数单一问题，[[routing-table]] 会将意图映射到入口节点。如果两种意图难以区分，[[disambiguation]] 会指出判定依据。多集群任务遵循 [[stacking-chains]]。
2. 否则，浏览下方的 MOC，选中对应集群，并打开其 MOC-*.md，查看该集群下的原子节点。
3. 只阅读匹配的原子节点。每个节点都可以独立使用——无需查看同级节点。
4. 审查 UI 代码前，也要加载 [[gotchas]] 和 [[pov]]。

如果用户要求审查 UI 代码，请使用 [[review-format]] 中定义的格式，并依据 [[review-checklist]] 进行检查。

理念——何时、何处以及为何精致度很重要

如何理解品味、愉悦感，以及营销 UI 与产品 UI 的区别。

• [[MOC-philosophy]] → [[taste-is-trained]], [[unseen-details-compound]], [[beauty-is-leverage]], [[delight-impact-curve]], [[feeling-right]], [[marketing-vs-product-ui]], [[states-are-the-work]], [[data-is-content]], [[dependency-discipline]], [[pointing-beats-describing]], [[articulate-precisely]]

动效——何时应该动起来，以及如何实现

最大的集群。动画是现代 UI 中最常被滥用的工具；这个集群会告诉你何时不该使用动画，也会告诉你何时该用。

• [[MOC-motion]] → [[animation-decision-framework]], [[easing-curves]], [[duration-table]], [[spring-animations]], [[transform-opacity-only]], [[performance-discipline]], [[transform-mastery]], [[clip-path-tricks]], [[never-scale-from-zero]], [[gesture-momentum]], [[stagger-choreography]], [[prefers-reduced-motion]], [[fly-not-teleport]], [[responsive-feedback]], [[sonner-principles]], [[debugging-animations]], [[lerp-breathing]], [[morphing-icons]], [[shared-letter-morph]], [[hover-default-imperative]], [[tray-rules]], [[css-conventions]], [[frame-rate-independence]], [[animated-hit-testing]]

转场技巧——Jakub Antalik 的目录

聚焦于常见 UI 原型的经典转场的动效子集。Motion MOC 讲解原则，这些节点讲解实现方式。来源：transitions.dev。

• [[cross-blur-transitions]] — 将透明度 0↔1 与 filter: blur(2px) ↔ 0 配合，用于掩盖不完美的交叉淡化。
• [[compose-subtract-asymmetry]] — 进入时使用比退出时更多的属性。消失效果会显得柔和，而不是反向播放。
• [[distance-falloff-propagation]] — 分组悬停时，通过 lift * pow(falloff, distance) 为每个元素施加抬升效果。
• [[multi-segment-shake]] — 表单错误抖动：在 280ms 内经过 0%、28.57%、57.14%、78.57%、100% 这些关键帧。

声音——何时以及如何让界面发出声音

这是网络所遗忘的感官。产品 UI 默认静音；发布视频则恰恰相反。这个集群会判断何时使用声音、设计一组统一的音色、将声音与动效同步，并生成文件——可按需使用 ElevenLabs，也可使用开源权重模型、程序化生成或 CC0 资源，无需密钥。

• [[MOC-sound]] → [[sound-decision-framework]], [[sound-motion-sync]], [[sound-palette]], [[sound-spec]], [[sound-playback-web]], [[sound-generation-elevenlabs]], [[sound-generation-open-source]], [[launch-video-sound]], [[launch-video-music]], [[sound-from-motion]], [[designed-sfx-anatomy]], [[earshot-reconciliation]], [[sound-licensing]]

发布视频 — 规划、剪辑、配乐和审阅发布影片

渲染完成的影片本身就是一个呈现界面：确定风格基调、安排节拍、编排文案和 UI 演示、处理衔接与剪辑、放置音效，再对照风格基调进行审阅。HyperFrames 负责构建；此主题集负责确定风格基调、节拍、文案和音效，而 [[hyperframes-reconciliation]] 则负责处理 HyperFrames 项目内部的衔接。

• [[MOC-launch-video]] → [[launch-video-registers]], [[launch-video-structure]], [[launch-video-type]], [[launch-video-ui-demo]], [[launch-video-motion]], [[launch-video-seams]], [[launch-video-cuts]], [[launch-video-review]], [[hyperframes-reconciliation]], [[launch-video-formats]], [[cinetic-reconciliation]]

SVG — 创建、动画、变形和矢量化

唯一同时也是一种界面的图像格式。基于令牌系统创作，使用其原生环境支持的引擎来驱动动画，按照命令数量规则进行变形，并将扁平视频片段转化为可编辑的吉祥物。

• [[MOC-svg]] → [[svg-creation]], [[svg-animation]], [[svg-path-morphing]], [[video-to-vector-pipeline]], [[isometric-stickers]], [[fun-isometric-reconciliation]]

图表 — 图形、画布，以及是否应该绘制

图表是表达某事物最昂贵的方式。先判断图示是否值得占据一席之地，以及接下来由谁处理。然后绘制完整图形（Cathryn Lavery 的图表设计），或编辑实时画布（tldraw 的桌面技能或 MCP 应用）。将项目的约定映射到图形上，并依据连接线规则进行审阅。

• [[MOC-diagram]] → [[diagram-decision]], [[diagram-craft]], [[diagram-design-reconciliation]], [[tldraw-canvas]]

字体排印 — 让文字更有人情味

AI 时代的默认字体一眼就能看出来。更好的选择，以及与之相关的规则。

• [[MOC-typography]] → [[typography-humanity]], [[line-length-tracking]], [[type-scale-and-rhythm]], [[line-behavior]]

表面 — 色彩、阴影、圆角、深色模式、不完美感

多数设计指南都会跳过的“背景”选择，却是营造质感的基础。

• [[MOC-surface]] → [[color-monochromatic]], [[color-scales-oklch]], [[dark-mode]], [[shadows-whisper]], [[depth-and-nesting]], [[border-radius]], [[visual-imperfection]], [[contrast-and-color-scheme]], [[z-index-strategy]], [[color-token-tiers]], [[palette-step-roles]], [[gradient-interpolation]]

布局 — 页面级网格、视口、固定导航、以 URL 表示状态、营销页面

关注容器，而非组件。营销页面尤其适合针对不同视口进行定制；产品应用则能从 URL 驱动的状态中受益。

• [[MOC-layout]] → [[viewport-custom-design]], [[sticky-and-scroll-tells]], [[url-as-state]], [[marketing-surface-rules]], [[page-frame]], [[scroll-anchoring]], [[grouping-by-space]], [[growth-and-overflow]], [[logical-properties-rtl]]

组件 — 按钮、悬停、状态、卡片、表单、头像、图标、无障碍、文案、API

用户实际接触的基本元素。精细打磨体现在它们的行为上。

• [[MOC-components]] → [[hover-states-subtle]], [[empty-loading-states]], [[icon-systems]], [[cards-design]], [[forms-validation]], [[forms-behavior]], [[touch-and-focus]], [[ui-polish-pass]], [[component-api-design]], [[avatar-systems]], [[interaction-personality]], [[accessibility-baseline]], [[optimistic-updates]], [[copy-voice]], [[dashboard-tells]], [[screen-reader-announcements]], [[keyboard-patterns]], [[wcag-thresholds]], [[strings-and-locale]], [[destructive-actions]]

反模式 — AI 生成的 UI 暴露了什么

哪些东西看起来像“AI 默认风格”，以及如何避免。它的价值很高，因为它关注的是删减，而非添加。

• [[MOC-anti-patterns]] → [[ai-default-tells]], [[unslop-pass]], [[content-authenticity]], [[copy-tells]], [[code-tells]], [[screenshot-critique]]

Meta — 评审格式、design.md、Agentation、评测、各安装器文件

流程规则与持续增长的文件。进行 UI 代码评审时，必须使用 [[review-format]]。

• [[skill-router]] — /design-engineering 首先要做什么：明确约定、判定阶段，并交接给一个负责人——节点、子 Agent 或已安装的配套工具（AgentsORG design、impeccable、HyperFrames、ElevenLabs、transitions-dev、shadcn CLI、diagram-design、tldraw、GSAP、better-icons、fun-isometric）。
• [[routing-table]] — 意图 → 入口节点路由器，包含四种处理方式（构建／评判／决策／命名）。遇到单一问题时，先于其他内容打开此文件。
• [[prototype-picker]] — 尚未决定？通过实时选择器展示三到五个真正不同的版本，在控件上标注数字，然后记录决策并删除测试框架。
• [[build-a-tool]] — 两次得到的结果都“更接近了，但还是不对”？停止重新编写提示词；诊断差距，并构建能生成所需产物的小工具。
• [[vibe-to-generator]] — 只有氛围感，没有规格？研究其视觉语言并整理成规则，然后构建带旋钮和保存按钮、可设定随机种子的生成器。
• [[design-system-docs]] — 编写 Agent 能遵循的 DESIGN.md 或文档目录：盘点代码，说明何时使用／替代方案，列出封闭的变体集合，提供正确／错误示例，并通过提示词验证。
• [[skill-writing-rules]] — 编码流程、写清原因、严格要求、让每一行都发挥作用、每个技能只涵盖一个方面，并通过实际运行来测试。此规则适用于此处的所有节点及 [[pov]]。
• [[design-benchmarks]] — DesignBench 的生成／编辑／修复任务、Design Arena 的成对投票，以及本技能借鉴两者构建的评测套件。
• [[disambiguation]] — 容易混淆的问题（四种动画问题、三个深色模式负责人、两个布局偏移负责人）以及各自所属的节点。
• [[stacking-chains]] — 多步骤任务的有序节点链（新屏幕、改善观感、设计系统、营销网站、无障碍审查）。
• [[review-format]] — UI 评审必需的输出格式（Before | After | Why Markdown 表格）。
• [[review-checklist]] — UI 评审签字确认前，用于检查的 26 行审计清单。
• [[change-scoped-review]] — 评审差异，而不是整个屏幕：检查范围、影响半径、每个差异块中被删除的内容，并将每条发现标记为 Introduced、Regression 或 Pre-existing。
• [[stress-scenarios]] — 在临时测试框架中，针对所有可能作用于某组件的场景（长度、形状、数量、容器、状态）进行测试，并通过切换器展示该组件的产品状态。
• [[reading-others-interfaces]] — 分析他人的网站或效果是如何构建的：证据而非指令，区分实测／推导／推测，按绘制顺序排列图层，并用文字写出实现方案。
• [[interfaces-reconciliation]] — 将 Jakub Krehel 的 interfaces 技能作为配套工具：安装后各自负责什么工作，以及如何解决 12 项价值观冲突。
• [[design-vocabulary]] — 每种设计现象的准确术语，以及技能会在哪些方面深入探讨。这是 [[articulate-precisely]] 背后的词汇表；由 Index（Emil Kowalski 和 Glenn Carstens-Peters）提供初始内容。
• [[using-design-file]] — 如何使用项目的 .design 约定（架构 design.v1）。机器可读的令牌、已提交的设计意图、可执行策略；其优先级高于本技能的默认设置。
• [[using-design-md]] — 如何使用项目的 DESIGN.md（Google Labs 规范）。令牌具有规范效力；说明文字提供上下文。
• [[agentation-workflow]] — 安装并使用 Agentation 进行点击标注式设计评审。先评审再修复的双会话工作流。
• [[cross-model-testing]] — 如何针对 GPT、Claude Opus 和 Claude Sonnet 测试描述／路由变更。
• [[gotchas]] — Agent 遇到问题时追加记录的实际失败案例。
• [[pov]] — 作者／安装者的个人观点和审美判断，可覆盖默认设置。分叉时请编辑此文件。
• [[animations-dev-curriculum]] — 指向 Emil 课程的外部链接；不要重复收录。

工作流子 Agent — 同级 agents/ 目录

此文件旁边的 agents/ 中有 10 个用途单一的子 Agent。当用户的请求符合其特定工作流时，启动相应的子 Agent。每个子 Agent 都会加载图谱中的一部分，并将结构化结果返回给主 Agent。

• [[ui-reviewer]] — 使用 [[review-format]] 表格和 [[review-checklist]] 审查清单审核 UI 片段。
• [[motion-auditor]] — 根据动效集群和 transitions.dev 节点评审动画与过渡效果。
• [[anti-pattern-scanner]] — 扫描 AI 默认风格的特征和内容真实性方面的疏漏。
• [[agentation-fix-loop]] — 负责 [[agentation-workflow]] 中第二轮会话的修复工作。读取 MCP 注释并应用修复。
• [[design-md-consumer]] — 读取项目的 DESIGN.md，并按照 [[using-design-md]] 将其中的设计令牌融入生成的 UI。
• [[pov-curator]] — 协助安装者派生 [[pov]]，并在实际失败后向 [[gotchas]] 添加内容。
• [[sound-designer]] — 端到端执行声音集群流程：确定方案、选择音色、生成（产品系列使用 scripts/sound-family.mjs，根据动效生成视频音轨使用 scripts/sound-sheet.mjs）、编写规格、接入。返回声音映射。
• [[svg-creator]] — 创建或重构 SVG 资源：网格、命名分组、令牌颜色、使用正确标志运行 SVGO，以及无障碍名称。
• [[svg-animator]] — 为 SVG 添加动画，或根据帧构建矢量翻页动画（scripts/svg-flipbook.mjs）；根据文件所在位置选择引擎。
• [[launch-film-analyst]] — 按原生帧率分析参考发布影片或你自己的渲染内容，并返回 [[launch-video-review]] 评估标准和每部影片对应的 JSON。

完整目录和选择指南见 agents/README.md。

身份 — SOUL.md

此代码库的根目录还附带 SOUL.md，其中定义了在此技能中运行的所有 Agent 的语气、立场和品味传承。AGENTS.md 说明“做什么／怎么做”；SOUL.md 说明“是谁／为什么”。如果你的运行环境不会自动注入该文件，请在每个会话中阅读一次。

Token 成本检查

上面的每句话在每个会话中都会消耗 token。如果你想添加一句话，请先问自己：没有这句话，Agent 会做错吗？ 如果不会，就删掉。如果会，就应将其放入原子节点，而不是这里。

— HKTITAN，2026。