Communitygithub.com

ui-craft

设计和构建适用于任何软件的高级、专业、易用的界面——涵盖网页应用、仪表盘、桌面应用、移动应用、营销网站等。包含艺术指导、色彩理论、心理学、无障碍设计等。

ui-craft 是什么?

ui-craft 是一个面向 AI 智能体(如 Claude Code、Cursor、Codex)的通用界面设计技能,旨在帮助构建外观高级且易于使用的界面。它提供了从零开始的工作流,包括:先检查现有设计系统、理解用户心理、选择合适的视觉方向(包含16种预设方向)、编写设计简报、按结构-系统-细节的顺序构建、设计所有交互状态,最后通过内置的 `ui-audit.mjs` 脚本进行自动审核,确保对比度、触控目标、溢出等指标达标。该技能适用于各种平台(Web、Mac、Windows、iOS、Android、Flutter、React Native)和产品类型(数据工具、SaaS、营销网站、移动应用等)。其核心方法论强调“高级”由四要素构成:合适(appropriate)、果断(decided)、精雕细琢(crafted)、诚实(honest),并通过详细的参考文件(如布局间距、色彩理论、排版规范、组件状态、情感与信任)提供具体的设计规则和最佳实践。智能体应遵循该技能提供的标准化令牌(tokens)和脚本,确保设计的一致性和质量,并能够生成可直接使用的 HTML 原型或设计评估报告。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/najeebafridi/ui-craft/tree/HEAD/skills/ui-craft

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

ui-craft 是做什么的?

如何构建在各种平台上看起来高级且易于使用的界面。 数字的单位为 CSS px;对于原生应用,请将 px 视为 pt(iOS、macOS)、dp(Android)或 epx(Windows)。

高级意味着四件事。 合适:适合受众、他们的心态和平台。果断:在整个应用中应用一个小型系统(有限的尺寸、统一的圆角族、一个强调色)。精雕细琢:细节处理到位。诚实:赢得信任,绝不欺骗。一个仅“正确”的屏幕看起来平庸;一个仅“装饰”的屏幕看起来廉价。

1. 工作流(每次都要执行)

  1. 构建前先观察。 检查现有的设计系统:令牌、主题文件、Tailwind 配置、组件库、品牌色、字体,或者 DESIGN.md 设计简报和从 ui-craft Studio 导出的 theme.css。如果存在,就使用它;不要重新发明一套。 仅填补空白。
  2. 理解用户。 谁在使用这个,处于什么心态(匆忙、焦虑、怀疑、高效心流状态的专家),他们应该感受到什么?一句话概括。详见 references/psychology-emotion.md。
  3. 选择一个方向。 如果没有确定的品牌身份,从 references/directions.md 中选择一个视觉方向以适应用户(而不是为了追求新奇),阅读 assets/directions/ 中对应文件的头部,并记下其“签名”(signature)。如果有品牌色,保持方向并重建颜色:node <skill-dir>/scripts/palette.mjs --accent "#HEX"。更喜欢凭视觉选择的人可以使用 ui-craft Studio (https://najeebafridi.github.io/ui-craft/):选择一个方向,在实时屏幕上调整,然后导出 theme.css 和 DESIGN.md 设计简报供你遵循。
  4. 在写代码之前编写设计简报(在你的回复或注释中):
    产品:面向小企业的薪资管理(Web 应用,桌面优先)
    用户和感受:老板在晚上处理薪资,担心出错 -> 安全、有引导、精确
    方向:Trusted ledger;强调色深青色(他们的品牌色),冷中性色,浅色主题
    字体:IBM Plex Sans + Mono,14px 正文,表格数字     形状与深度:6px 圆角,柔和阴影
    密度与动效:紧凑,干净利落(120-200ms)             平台:响应式 Web
    签名:数字排列像账本;确认信息明确显示具体金额和时间
    此屏幕的主要任务:查看本月的运行情况并批准
    
  5. 先构建结构,再应用样式。 首先用真实内容构建布局和层次结构,然后是系统(令牌),最后是细节。不要用 Lorem Ipsum:要写真实的人名、数字和文案。尽早构建“签名”,并让其他所有东西都比它更安静。 展示其工作状态。 第一个视图应该是屏幕在使用中的状态:包含真实数据、已选中的合理默认值、可见的主要交互。不要在空白或锁定状态、显示“$0”的死亡总计或关键步骤被隐藏时打开。
  6. 设计所有状态:加载、空状态、错误、成功、长文本、多项目、单项目、无权限(references/feedback-states.md)。
  7. 完成并检查。 执行 references/premium-craft.md 中的收尾步骤。然后查看结果:如果有 Node 和 Chrome,运行 node <skill-dir>/scripts/ui-audit.mjs page.html。它会在 1440px 和 390px 下评分对比度、尺寸、触控目标和溢出问题,记录工艺问题,并保存截图。打开两个截图,并像对待桌面版一样严格地评判手机版:没有内容被裁剪、覆盖或挤压,关键内容在首屏内。检查屏幕是否讲述一个故事:摘要与选择匹配,总计加起来正确,计数与列表一致,日期相符。修复你看到的问题,然后删除任何无助于主要任务的内容。清单:references/review-checklist.md。

为客户快速制作原型:references/mockups.md。审阅或评分现有产品:references/review-mode.md。

同一主题的不同层次。 对于 3D 场景、着色器、滚动叙事或电影级动效,请使用 immersive-web 技能(同一插件):它读取相同的令牌,并且主题的 --immersive 级别(0 静止到 3 叙事)指示了应该走多远。要借鉴其他类型或媒介(游戏、科幻、电影)的外观,请阅读 references/mixing.md。

2. 按产品类型划分的密度

产品正文字号密度导航
数据工具、管理后台、开发工具、金融14px紧凑:行高 36px,控件 32-36px左侧边栏 220-280px
SaaS Web 应用14-16px标准:控件 36-40px侧边栏或顶部栏
仪表盘、分析工具14px紧凑侧边栏 + 筛选栏
营销、着陆页16-18px宽敞:区块间距 64-96px顶部栏,4-6 个链接 + 1 个操作
移动应用16-17px触控:目标至少 44px底部标签栏,3-5 项
桌面应用13-14px(平台默认)紧凑侧边栏 + 工具栏;遵循操作系统
消费类、趣味性16px标准按平台

正文字号默认为 16px;仅在密集的桌面工具中使用 14px。绝不能低于 12px。紧凑密度仅适用于鼠标和键盘:在触摸屏上,每个控件都要增长到 44px(§13)。

3. 层次结构(最重要的胜利)

  • 每个屏幕一个主角和一个主要操作。 主要操作是唯一的实心强调色按钮;其他按钮应为轮廓、柔和或文本按钮。
  • 通过尺寸、字重和颜色共同构建层次结构。为了让标题突出,应使标签和元文本更安静,而不是放大标题。
  • 标签比数值更安静。在“收入 $48,210”中,标签应为 12-14px 的柔和色,数值应为 24px 半粗体。
  • 按 间距优先 进行分组,其次是背景色调,然后是线条,最后是阴影。组之间的间隙至少是组内间隙的两倍。更少的框和线条看起来更昂贵。
  • 阅读顺序应与重要性匹配:主要任务位于左上角(在从左到右的语言中)或中心。

4. 布局和间距

  • 间距刻度(4px 基数):4, 8, 12, 16, 24, 32, 48, 64, 96。 仅使用这些值。
  • 组件内部:4-12;组件之间:16-24;区块之间:32-48(应用),64-96(营销)。
  • 页面侧边距:移动端 16px,平板 24px,桌面端 32px 或更多。内容最大宽度 1200-1440px(应用),1120-1280px(营销);阅读文本 65-75 个字符。
  • 使用 grid 或 flex 配合 gap 进行布局。在两个轴向上对齐:相邻元素共享左边框和基线。轻微的不对齐会显得业余。
  • 外部边距至少等于内部间隙。不确定时,增加空白并移除边框。
  • 没有死空间。 不要拉伸卡片以匹配更高的邻居(使用 align-items: start),也不要让面板大部分为空:赋予其实质内容、缩小它或移除它。
  • 密度是一个决定:宽敞或紧凑,始终精确。断点:640, 1024, 1440;至少检查 375 和 1440。

详情:references/layout-spacing.md。

5. 排版

  • 字号比例:12, 14, 16, 18, 20, 24, 30, 36, 48, 60(更大仅用于展示性文字)。应用屏幕使用 4-6 种字号,营销页面最多 7 种。
  • 字体来自方向或品牌:应用使用一种字体族,最多两种(一个展示性字体用于标题,一个中性正文字体)。绝不要仅仅因为它是默认字体而使用。所有建议的字体都是免费的(SIL OFL)。
  • 根据字号调整排版。 正文行高 1.5,标题 1.2-1.3,展示文字 1.05-1.15。字间距:14-16px 为 0,20-24px 约为 -0.015em,30-36px 为 -0.025em,48px 及以上为 -0.03 到 -0.04em;小号全大写标签为 +0.06em。
  • 字重:正文 400,标签和按钮 500,标题 600;700+ 仅用于大号展示文字。每个屏幕最多 3 种字重。悬停时字重不变。
  • 标题使用 text-wrap: balance,段落使用 pretty。在每个变化或对齐的数字上使用 font-variant-numeric: tabular-nums;表格中的数字右对齐。
  • 标题、按钮和标签使用句首大写。使用真实引用、破折号和省略号。

详情:references/typography.md。

6. 色彩

  • 先选择感受。 亮度(Lightness)和饱和度(Saturation)对屏幕感受的影响大于色相(Hue):更亮更愉悦,更饱和更刺激,低饱和度强对比则平静且严肃。然后选择色相以传达含义、符合类别并与竞争对手区别开来。references/color-theory.md。
  • 调色板是带色调的中性色 + 一个强调色 + 状态色(成功、警告、危险、信息)。中性色应带有颜色痕迹(暖、冷或品牌色相),绝不是死灰色;大区域不使用纯黑或纯白。
  • 大部分是中性色。 强调色覆盖约 5-10%:主要按钮、链接、选中状态、焦点、关键数据。高饱和度仅用于小而重要的位置。
  • 使用 scripts/palette.mjs(OKLCH 颜色空间,浅色 + 深色,所有文本和边框颜色都经过对比度测试)或从某个方向获取。绝不要凭肉眼发明十六进制值。
  • 组件中仅使用语义令牌:--bg、--surface、--surface-2、--border、--border-strong、--text、--text-muted、--text-subtle、--accent、--accent-fg、--accent-soft、--accent-text、--focus、--danger... 每个表面都有对应的前景色。
  • 对比度下限(WCAG 2.2 AA):文本 4.5:1,大号文本(24px+,或 18.66px+ 粗体)和 UI 组件(输入框边框、图标、焦点环、图表标记)为 3:1。分隔线可以微弱;输入框边框使用 --border-strong。
  • 绝不仅仅依赖颜色传达含义:添加图标、文本或形状。状态色与品牌色保持分开;红色品牌色绝不能兼作错误色。
  • 深色模式有独立的调色板:近乎黑色的带色调表面,凸起表面更亮,近白文本,更柔和的强调色。提供两种主题并遵循操作系统设置。

详情:references/color-theory.md、references/color-dark-mode.md。令牌:assets/tokens.css、assets/directions/。

7. 光影、深度和形状

  • 单一光源,来自上方,应用于所有地方。仅三个层级:平面、凸起(--shadow-raised)、覆盖(--shadow-overlay)。
  • 阴影是分层的并带有色调:多个薄层,而非单层灰色模糊。层级越高,阴影越大、越柔和、越淡。
  • 卡片和菜单使用阴影中的 1px 边圈 代替边框;实心按钮获得微弱的顶部内高光(--shadow-button)。
  • 统一的圆角族。 圆角半径随高度增加(控件、卡片、表单)。嵌套角是同心圆的:内角半径 = 外角半径减去之间的内边距。
  • 在深色主题中,深度通过更亮的表面和边圈实现,而不是阴影。
  • 每个产品使用一种深度技术(发丝线、柔和、清晰、漫射、平面或唇形,由方向决定)。不要使用发光,不要在每个卡片上都加阴影。
  • 模糊和半透明仅属于界面镀铬元素(如粘性页眉、表单、系统材料),绝不应用于内容卡片。

详情:references/premium-craft.md。

8. 组件

  • 每个交互元素都有状态: 默认、悬停、焦点可见、按下、禁用;按钮有加载状态;行和切换开关有选中状态。悬停绝不能是唯一的提示。
  • 按钮和输入框:默认 40px,紧凑 32-36px,触控 44-48px。水平内边距约为垂直的两倍。标签 = 动词 + 宾语(如“创建发票”)。纯图标按钮需要 aria-label 和工具提示。
  • 焦点环始终对键盘用户可见:2px --focus,2px 偏移。绝不要在没有替代方案的情况下使用 outline: none。
  • 输入框:上方有可见标签(占位符不是标签),使用 --border-strong 边框,下方有帮助文本,下方有带图标和文字的报错。长表单在顶部添加错误摘要。
  • 表单的主要操作(保存、继续)从一开始就可见。它可以在某些内容变化前看起来更安静;但绝不要仅在编辑后才出现。
  • 切换开关立即生效;复选框在保存时应用。
  • 卡片仅用于分隔的、可比较的内容。不要在每个区块周围都使用卡片;永远不要在卡片内套卡片。
  • 图标:使用统一的一套,统一的描边宽度,尺寸与旁边的文本匹配。绝不要使用 emoji 作为图标。
  • 图片:真实内容,固定 aspect-ratio,有意义的 alt 文本,1px 内部轮廓。不要使用占位符服务。如果没有真实照片,在最终裁切中使用安静的色调块,并配以小字标注(如“摄影:花园间”);绝不要使用粗糙的主体绘画,这会拉低周围所有内容。
  • 模态框(Modal)仅用于短小、专注的任务;优先使用内联编辑或侧面板。
  • 破坏性操作:使用危险色,具名(如“删除项目”),确认后可撤消或提供撤消功能。对于频繁操作,撤消优于确认。

references/forms.md、references/tables-lists.md、references/navigation.md、references/dashboards-charts.md。

9. 反馈状态

  • 在 100ms 内响应每一次按压。在约 300ms 后显示加载旋转图标或骨架屏,然后保持约 500ms。
  • 骨架屏用于已知布局的页面或部分加载;旋转图标用于按钮和小部件内部;进度条(带百分比)用于持续时间超过约 10s 的操作。
  • 空状态 = 这是什么 + 为什么为空 + 一个操作。错误 = 发生了什么 + 如何修复,用通俗的语言,在发生的地方提示;不要清除用户的输入。
  • 成功 是安静且具体的(如“发票 1042 已发送给 Anna,14:02”)。Toast 提示持续 4-6s,但绝不能成为重要信息的唯一副本。
  • 在安全的情况下乐观地更新,失败时提供撤消功能。速度被视为质量。

详情:references/feedback-states.md。

10. 情感与信任

  • 人们在大约 50ms 内判断一个屏幕的外观,而这个外观是他们可信度测试的第一步。结构简单熟悉,细节独特才能胜出。
  • 根据用户状态匹配设计:焦虑的(说明下一步会怎样,提交前提供摘要,提供简单的回退路径),匆忙的(最少的步骤,预先填写,提供快捷方式),怀疑的(在声明旁边提供证据,早期显示完整价格),专家(提供高密度、快捷方式,撤消优于确认),尴尬或悲伤的(使用中性语气,不要庆祝)。
  • 强力收尾:最后一步和确认是用户记忆最深刻的部分。
  • 愉悦感存在于低风险时刻(首次运行、空状态、成功),绝不要出现在错误或敏感任务中。事件发生得越频繁,其表现形式就应该越平淡。
  • 拒绝黑暗模式:虚假的紧迫感或稀缺性、虚假评论、预先勾选的附加项、隐藏成本、难以取消、确认羞辱、一个巨大的“接受”按钮旁边藏着一个“拒绝”按钮。提供诚实的版本。

详情:references/emotion-trust.md。

11. 平台惯例与无障碍

  • 触摸目标至少为 44px(交互元素的宽度和高度,或矩形最小尺寸),包括移动设备和触摸屏桌面设备。控件之间的间距至少为 8px。所有可聚焦元素必须可通过键盘访问,并且具有可见的焦点指示器。
  • 遵循平台标准。 macOS 使用标题栏中的标准窗口控件并支持手势;Windows 和 Linux 使用左上角控件。移动端使用底部标签栏而不是侧边栏。不要重新发明标准的系统控件(如滚动条、选择框)。所有交互元素必须响应 hover、focus、active 和 disabled 状态。
  • Web 特定:表单使用原生 <form> 提交,适当时使用 autocomplete 属性,并使用语义化 HTML(<nav>、<main>、<aside>、<article>)。所有按钮都有 aria-label。图片有 alt 文本。颜色对比度符合 WCAG 2.2 AA 标准。
  • 移动端特定:输入使用正确的 inputmode(如数字输入使用 type="number" 或 inputmode="numeric")。支持触控手势(滑动、长按),并尽快显示合适的键盘(如数字键盘用于数字)。
  • 响应式:桌面端和移动端都具有完整功能。在移动端,导航栏折叠或转换为标签栏。表格在移动端转换为列表或可水平滚动。

详情:references/platform-conventions.md、references/accessibility.md。

12. 混合设计与系统一致性

  • 当多个技能或设计语言共存时,ui-craft 的令牌优先。所有基于它的技能必须使用相同的 --accent、--text、--surface 等令牌。没有基于 ui-craft 的组件可以定义自己的颜色或字体,除非是极少数、有记录注明的例外情况。
  • 3D 或沉浸式场景(使用 immersive-web)读取相同的 --*-level 令牌并应用匹配的光照和颜色。沉浸式组件从 ui-craft 主题继承其调色板。
  • 当生成多层设计时(如营销页面带有 3D 元素、仪表盘和电子邮件),所有内容都源自共同的令牌。没有独立的主题。--immersive 级别(0-3)决定了 3D 替换的程度:
    • 0:无沉浸式元素(无 3D,无动态)。标准 Web 或应用界面。
    • 1:微妙元素(柔和的视差、微妙的景深、小装饰)。
    • 2:显式元素(全页式 3D 场景、拖拽、前后对比滑块、滚动故事章节)。
    • 3:电影式(实时 3D 场景、屏幕空间效果、相机动画、环境光照匹配主题色调——适合游戏、着陆页、展示)。
  • 对于打印或 PDF 输出,令牌转换为 CMYK 近似值。链接和图标被移除或转换为文本。

13. 动画与过渡

  • 动效服务于目的:引导注意力、提供反馈、传达层级。绝不要仅仅为了动效而动效。
  • 持续时间:微交互(悬停、焦点、按钮按下)100-150ms;UI 过渡(面板、模式框)150-300ms;场景变化(页面过渡、入场)300-500ms。更远距离的变化使用更长的持续时间。
  • 缓动:标准 UI 使用 ease-out;自然运动使用 ease-in-out;强调元素使用自定义贝塞尔曲线。绝不要使用 linear 进行 UI 动画。使用 transform 和 opacity 以获得 GPU 加速性能。
  • 进入动画:元素应按层级顺序从顶部/左部进入。不要过分华丽,胜在克制。
  • 退出动画:元素应更快地淡出(通常是进入时间的 2/3)。
  • 减少动效:尊重用户的 prefers-reduced-motion 设置并禁用所有非必要动画。

详情:references/animation.md。

有用的链接

  • ui-craft Studio(方向选择器和主题导出器):https://najeebafridi.github.io/ui-craft/
  • 脚本:node <skill-dir>/scripts/palette.mjs --accent "#HEX" 构建调色板
  • 自动审核:node <skill-dir>/scripts/ui-audit.mjs page.html 评分界面

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能