Skip to content

webkubor/ui-craft / skills/ui-design

ui-design

Verified

帮助 AI coding agent 做出更好的 UI:从读取项目设计规范、确定页面层级与风格,到实现组件、检查真实截图、修复视觉问题。遵循已有品牌和 tokens;无契约时在授权范围内记录假设、建立 DESIGN.md 并继续实现;完成后按项目规范验证响应式、可访问性与交互。适用于新页面、存量改版、组件设计、UI 评审与视觉修复。

UI Design

总纲

这是 UI skill:帮助 Agent 按项目设计契约做出更好的组件和页面,并检查真实浏览器效果。细节由本 skill 按用户授权范围处理。

  • 跨项目风格自由:不同项目应该长得不一样,本 skill 不带默认皮肤。
  • 项目内风格一致:风格真源是项目自己的 DESIGN.md + tokens,不是 Agent 当下的审美。改 UI 前先找它,没有就先定方向,不准自己编风格。
  • 质量底线统一:层级、间距、对比度、交互状态、响应式、GEO、工程接线,所有项目同一条线。

触发优先级:做 UI 时先加载本 skill(ui-design 是唯一入口)。impeccable 是本 skill 按需调度的执行器(访谈、反模式扫描、专项改造),不作为并行入口——两个 skill 不各自抢入口。impeccable 的命令对照、4 种 mode、调用纪律见 references/impeccable.md。

阶段总纲见 docs/ui-design.md,判定真源见 评审标准,工程方法见 通用方法。加载其它 skill 时使用当前 coding agent 提供的 skill 加载机制;相关文件位于本仓 skills/。

交付定义(DoD)

块必须做到细则
工程化复用项目脚手架与组件;tokens 单一真源(CSS 变量 / OKLCH,按项目支持明暗主题);组件分层;运行项目提供的 lint、类型检查与构建engineering.md
可观测按项目接入浏览器日志、截图或性能观测;需要时检查版本更新与错误反馈observability.md
可维护维护 DESIGN.md + tokens 决策记录;为 Agent 标明 UI 改动前先读设计契约;更新运行与交付说明;避免硬编码设计值maintainability.md

Step 0 · 硬性前置:找项目设计真源

ls DESIGN.md docs/DESIGN.md design/DESIGN.md 2>/dev/null
rg -l -g '!node_modules' 'design-tokens|--color-|@theme' . | head
  • 先读项目 AGENTS.md / CLAUDE.md 指定的设计文件、组件库或主题包,并遵循项目的品牌与协作规则。
  • 先查 logo / brand-mark:有已确认的品牌色时沿用;需要从 logo 推导色彩时遵循 differentiation.md,并兼顾可读性和设计契约。
  • 有 DESIGN.md / tokens → 通读并服从;不重选风格或顺手改配色字体。与需求冲突时,若冲突会改变品牌或产品体验则澄清;否则按用户目标作最小一致调整并记录。
  • 只有 tokens → 从 tokens + 现有页面反推 DESIGN.md,标注为推断并继续任务;如用户要求方案评审,再提交确认。
  • 都没有 → Step 1 确定方向。用户授权实现时可由 Agent 根据需求与证据选择并记录方向,再开始 UI 实现。

存量项目补齐缺口:先体检与任务相关的设计契约、tokens、组件状态、可访问性与浏览器复查;按 engineering.md 只补确实缺失的能力,不推翻已有风格与工具链。

Step 0b · 存量反推(已有代码、缺 DESIGN.md)

项目已有可运行的 UI 代码但没有 DESIGN.md 时,方向不是从零拍脑袋,而是从代码反推:

  1. 抽 → 调 impeccable extract:从现有代码抽 tokens(颜色、字阶、间距、圆角、阴影)与重复组件模式。命令、产出与调用方式见 references/impeccable.md。
  2. 成稿 → 用抽出的结果拼出 DESIGN.md 初稿:产品语气和方向可从页面与用户需求推断;无法推断的部分标注假设或待定。
  3. 核对 → 用真实页面与用户目标对照反推结果,识别明显冲突。用户已授权实现时,除非发现无法逆转的重大品牌或产品决策,否则继续落实;需要用户参与评审时提供预览和取舍。
  4. 落盘 → 按 templates/DESIGN.md 结构落盘 DESIGN.md + tokens,决策记录区分「用户明确给定」与「根据存量代码/需求推断」。impeccable document 的结果也须校核后再采纳。

只有 tokens 没有 DESIGN.md 时同样走这条路(extract 的输入可以是 tokens + 页面)。

新项目不适用本步:没有代码可反推,直接 Step 1 定方向(差异化 + GEO)。

Step 1 · 定方向(新项目 / 无 DESIGN.md / 明确改版)

  1. 受众、目的、语气:从用户目标、产品现状和页面内容确认或推导,并明确关键假设。仅当缺失信息会改变核心产品/品牌方向且不能从现有材料判断时才请求补充。impeccable shape / init 可辅助访谈和整理 brief。
  2. 竞品扫描:3–5 个同类产品,写「它们长什么样 → 我们刻意不同在哪」(已有 logo 时色彩从 logo 推导,无 logo 才从竞品/方向推导)。见 differentiation.md。
  3. GEO 与内容结构:此时就定信息架构、一句话定位、标题层级、FAQ、渲染方式、结构化数据。见 geo.md。后台/内部工具可声明不适用,须写理由。
  4. 形成方向并执行:在内部比较 2–3 个有明显取舍的候选,用差异化与换名测试排除模板化方案;用户要求参与选型时,给出候选和预览。用户已授权实现时,选择最适合目标的一案,记录取舍后继续。

素材库(不是强制皮肤,按需从本仓 skills/ 加载):apple-design(交互与动效原理)、award-creative-ui(创意类项目)、landing-page-design(营销页结构与风格菜单)、logo-brand-designer(标识与品牌色)。

Step 2 · 落盘:DESIGN.md + tokens

  • 项目根写 DESIGN.md,用 templates/DESIGN.md:定位、语气、定位与差异化、视觉系统、Do/Don't、参考、GEO/内容结构、决策记录(日期、证据、假设或取舍)。
  • 写 tokens:颜色(light/dark 语义层)、字阶、间距、圆角、阴影、动效。示例 templates/tokens.css;已有 Tailwind/主题包就落进它的配置,不另起一套。
  • 项目 AGENTS.md 加入 UI 改动片段(见 maintainability.md)。
  • impeccable document 生成的 DESIGN.md 需按本模板结构与项目事实核对后再写入;无法确认的决定标注为假设。

Step 2.5 · 工程接线

适用项目先读 engineering.md 并检查现有脚手架、CI 与观测工具;只补项目确实缺少的能力。Vite 项目可使用 npx ui-craft setup --dry-run 检查 CLI 接线方案(已有仓库仍可使用 ui-craft 命令别名),再按项目需要接入检查脚本。其它框架按 engineering.md 使用对应等价方式。

Step 3 · 实现:只用 tokens

  • 颜色、字号、间距、圆角、阴影、动效只引用 tokens;tokens 之外不出现裸 hex / rgb / px 魔数(1px 边线、栅格结构尺寸按项目约定)。
  • 新 token:先改 tokens + DESIGN.md 决策记录补一行,再用。不在组件里就地造。
  • 复用项目组件;hover / focus-visible / active / disabled / loading / empty / error 与视觉同时实现。
  • 不加 DESIGN.md 未声明的风格元素(新渐变、新字体、新插画风)。

Step 4 · 验收:项目规范 + 质量底线

先对照本项目 DESIGN.md(Do/Don't、可记忆点、语气),再过底线:

底线证明方式
层级 / 间距与本项目用户任务、信息量和视觉契约相符;避免默认堆卡片,间距优先复用项目 scale
对比度遵循项目已有目标;色彩 CLI 是可选辅助项,不代表整页已通过
反模式在可用时用 impeccable detect 辅助发现模板化结构;必须结合真实截图和产品上下文判断
交互状态相关交互可用键盘操作、focus 清晰,必要状态有设计
响应式 / 主题声明的临界宽度无关键溢出遮挡;项目支持主题切换时检查相应主题
GEOgeo.md:对外公开页面检查内容是否便于搜索与 AI 摘要理解;后台或内部工具可注明不适用
工程 / 可观测遵守项目规范;真实页面可检查,新增运行错误和未测范围如实记录

阶段路由:

阶段按需 skill退出证据
1 定义任务项目规范、评审标准设计契约;区分新设计/还原/缺陷修复
2 设计或还原本 skill Step 1–2;有稿 ui-restore;整站参考 clone-websiteDESIGN.md + tokens 或还原方案
3 实现apple-design、design-to-motion、award-creative-ui可运行实现、影响面
4 比对修复ui-restore、ui-review观察→原因→改法→前后证据
5 验收frontend-e2e、browser-verifyPASS/HOLD/未验证 + 截图
6 交付项目交付规则测试、部署版本、复测、残余项

工具不可用或换名测试未通过时如实标缺口并写清代价,不得用必然通过的假断言、HTTP 200 或本地通过冒充目标环境验收。

汇报(必填)

最终回复必须包含:

UI 依据:已加载 skills = ui-design, <其它>;DESIGN.md = <路径@commit / 本次基于证据新建 / 不适用及原因>;真实截图/交互验证 = <证据或缺口>;残留问题 = <无 / 列表>

没有 DESIGN.md 却改了 UI = 违反本 skill;说明原因并补 Step 1/2。

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall