ui-craft 是做什么的?
如何构建在各种平台上看起来高级且易于使用的界面。 数字的单位为 CSS px;对于原生应用,请将 px 视为 pt(iOS、macOS)、dp(Android)或 epx(Windows)。
高级意味着四件事。 合适:适合受众、他们的心态和平台。果断:在整个应用中应用一个小型系统(有限的尺寸、统一的圆角族、一个强调色)。精雕细琢:细节处理到位。诚实:赢得信任,绝不欺骗。一个仅“正确”的屏幕看起来平庸;一个仅“装饰”的屏幕看起来廉价。
1. 工作流(每次都要执行)
- 构建前先观察。 检查现有的设计系统:令牌、主题文件、Tailwind 配置、组件库、品牌色、字体,或者
DESIGN.md设计简报和从 ui-craft Studio 导出的theme.css。如果存在,就使用它;不要重新发明一套。 仅填补空白。 - 理解用户。 谁在使用这个,处于什么心态(匆忙、焦虑、怀疑、高效心流状态的专家),他们应该感受到什么?一句话概括。详见
references/psychology-emotion.md。 - 选择一个方向。 如果没有确定的品牌身份,从
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设计简报供你遵循。 - 在写代码之前编写设计简报(在你的回复或注释中):
产品:面向小企业的薪资管理(Web 应用,桌面优先) 用户和感受:老板在晚上处理薪资,担心出错 -> 安全、有引导、精确 方向:Trusted ledger;强调色深青色(他们的品牌色),冷中性色,浅色主题 字体:IBM Plex Sans + Mono,14px 正文,表格数字 形状与深度:6px 圆角,柔和阴影 密度与动效:紧凑,干净利落(120-200ms) 平台:响应式 Web 签名:数字排列像账本;确认信息明确显示具体金额和时间 此屏幕的主要任务:查看本月的运行情况并批准 - 先构建结构,再应用样式。 首先用真实内容构建布局和层次结构,然后是系统(令牌),最后是细节。不要用 Lorem Ipsum:要写真实的人名、数字和文案。尽早构建“签名”,并让其他所有东西都比它更安静。 展示其工作状态。 第一个视图应该是屏幕在使用中的状态:包含真实数据、已选中的合理默认值、可见的主要交互。不要在空白或锁定状态、显示“$0”的死亡总计或关键步骤被隐藏时打开。
- 设计所有状态:加载、空状态、错误、成功、长文本、多项目、单项目、无权限(
references/feedback-states.md)。 - 完成并检查。 执行
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评分界面