Communitygithub.com

21 Grams UI

对已有 UI 进行去 AI 痕迹 并提升用户体验的轻量级规则集,通过项目自身的组件和设计 Token 施加经过验证的 UX 与动效原则。当用户要求美化、精炼、去 AI 化、改进或“让界面不再像 AI 生成”,或提及“21 grams UI”、“21 grams”(或“twenty-one grams”),或希望对照内部风格、20 条 UX 与动画原则、10 条设计技巧或 20 条动画工艺对 UI 进行审计时使用。

21 Grams UI 是什么?

21 Grams UI 是一个 AI 助手技能,用于对现有 UI 进行美化与去 AI 痕迹 处理,不引入新 UI 组件库,而是通过项目已有的组件和设计 Token 施加一套固定规则,使界面看起来更精致、响应更快且始终符合产品风格。它适用于 Claude Code、Cursor、Codex 等 AI 编程助手,当用户请求提升 UI 质量、去除 AI 生成感、或引用“21 grams 原则”时被激活。该技能涵盖六大领域:内部风格指南(包括圆角、按钮、动效、排版、间距、色彩、层级和文案规则)、20 条 UX 与动画原则、10 条高级 CSS 技巧、20 条动画工艺、10 条排版技巧以及 20 条“去 AI 劣化”规则。工作流程从盘点项目组件与 Token 开始,审计并列出问题,优先使用项目现有组件修复,最后验证并报告变更。核心原则包括:所有修改必须通过项目自身的组件和 Token 实现;动效时长控制在 120–300ms,使用正确的缓动曲线;确保无障碍对比度;遵循嵌套圆角、OKLCH 色彩空间、合理弹性和触感反馈等高级实践。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ilbognov/21grams/tree/HEAD/skills/ui

在你喜欢的 AI 中提问

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

文档

21 Grams UI 是做什么的?

对已有 UI 进行二次美化。21 Grams UI(21 Grams 家族中的 UI 包)不会重新设计产品,也不引入自己的 UI 组件库。它会移除 AI 生成 UI 的特征,并通过项目已有的组件和 Token 应用一套固定规则,使界面看起来经过深思熟虑、响应快速,且仍属于该产品。

第零条规则:使用项目自身的组件

每一项修改都通过项目已经使用的资源完成。21 Grams UI 从不构建一套平行的组件。

  1. 触碰任何代码前,先进行盘点。 记录设计 Token 或主题(CSS 变量、Tailwind 配置、主题文件)、组件库(shadcn/ui、Radix、MUI、Chakra、内部组件库、客户设计系统)、图标集、图表库和动画库。记下每个共享组件的名称和所在位置。
  2. 在原地修复问题。 按钮规则应应用到项目的 Button 组件(Token、变体、属性或其样式),绝不会在单个屏幕上创建一次性副本。颜色或圆角规则应应用到 Token,而非硬编码值。
  3. 有现成组件就绝不新增组件,也绝不为了达到 21 Grams UI 效果而新增依赖(UI 组件库、图标集、图表或动画库)。使用已安装的资源。没有动画库时,使用 CSS 过渡。
  4. 当确实缺少某个组件时(如没有分段控件、开关),用项目已有的基础元素和 Token 构建,遵循其文件布局和命名规范,并在报告中说明。
  5. 内部样式值仅作为空白处的默认值。 rules/ 和 tokens/tokens.css 提供项目尚未决定时的默认值。将这些值映射到项目的 Token 上。切勿将 tokens.css 粘贴到已有系统旁。
  6. 品牌特征保持不变。 品牌色、字体、Logo、图标样式和语气绝不替换。21 Grams UI 改变的是它们的使用方式(对比度、层级、间距、动效),而非它们本身。

优先级: 用户的要求优先,其次是项目的设计系统和品牌,最后是 21 Grams UI 内部样式。原则、技巧和动画工艺在任何地方都适用,但必须用项目自身的组件来表达。

包含内容

  1. 内部样式。 rules/ 中的八大领域:radius.md(12/8/4 嵌套圆角)、buttons.md(36px 高度,0.97 按压缩放)、motion.md(平滑、从触发元素开始、无弹跳)、type.md(紧凑、少量字号)、spacing.md(4pt 分组间距)、colour.md(单一强调色、AA 对比度)、elevation.md(色调填充)、copy.md(简洁、有帮助)。另外三个组件文件:icons.md(单一风格、线型、实心或双色,绝不混用)、charts.md(折线图、柱状图和横向条形图)和 toggles.md(开关和分段控件)。默认值在 tokens/tokens.css 中。
  2. 20 条原则。 UX 和动画原则,详见 references/principles.md。
  3. 10 条设计技巧。 CSS 层面的工艺细节,详见 references/design-hacks.md。
  4. 20 条动画工艺。 实现层面的动效规则(原点、持续时间、交错延迟、按压、拖拽、共享布局),详见 references/animation-craft.md。
  5. 10 条排版技巧。 保留粗体宽度、文本框修剪、下划线偏移、上标间距、流体显示字体、小型大写缩写、弯引号、中间截断、自动连字符和限定行数的标题,详见 references/typography.md。
  6. 20 条去 AI 劣化规则。 组成和内容的劣化特征(填充性徽章、冗余标签、随机斜体、装饰性等宽字体、抽象英雄图、权重均等的功能模块、模糊标题、发光效果、光学对齐、加载状态),详见 references/unslop.md。

如果安装了数据可视化相关技能,在涉及图表时一并加载。

工作流程

  1. 进行盘点(第零条规则)。如果项目完全没有设计系统,需说明并直接使用内部样式默认值。
  2. 在修改前进行审计。 逐项检查屏幕或组件,按领域(圆角…文案)、原则编号、技巧编号和工艺编号列出问题。使用 references/principles.md、references/design-hacks.md、references/animation-craft.md、references/typography.md、references/unslop.md 和 rules/icons.md 末尾的检查清单。每个问题需记录文件及行号、问题描述、修复方法,以及修复应写入哪个现有组件或 Token。标记所有 21 Grams UI 规则与项目设计系统冲突的地方,由用户决定优先级。
  3. 向用户展示审计结果(简要清单),并在进行大规模修改前征得同意。在请求范围内简单且明显的问题可以直接修复。
  4. 按以下顺序应用修复: Token → 共享组件 → 屏幕。确保差异只涉及被审计的范围,并遵循项目自身的约定(格式化、语法检查、命名)。
  5. 在浏览器中验证。 每个修改后屏幕的“修改前/修改后”截图。检查悬停、按压、聚焦、加载、错误状态、明暗两种主题和还原动效偏好。测量按钮和文本对比度,而非目测。对于动效,尽可能录制修改前/修改后对比。使用带可拖动分割线且两侧交互正常的前后对比页面是审查改进的最佳方式。
  6. 报告每个领域、原则、技巧和工艺的变更内容,涉及哪些组件和 Token,以及任何未完成的工作。

内部样式概览(空白处默认值)

  • 圆角:容器 12 / 控件 8 / 小部件 4,嵌套时内圆角 = 外圆角 − 内边距。除标签和开关外不使用药丸形。
  • 按钮 36px(紧凑 32,突出 40),圆角 8,字号 14 / 字重 500,一个实色主按钮,每个视图一个主按钮,悬停仅改变颜色阶数,按压 = 颜色阶数 + scale(.97) 持续 150ms,加载时保持宽度。
  • 动效:日常 UI 无弹跳。菜单 220ms 进入 / 175ms 退出,从触发元素 scale(.95) 开始,面板 240 / 190,入场 ease-out,出场 ease-in(约入场时长的 80%),列表行交错 30ms,频繁交互即时响应。
  • 排版:使用项目自有字体(无指定时使用 Geist)。等宽字体仅用于代码,绝不用于标签、眉毛区、徽章、时间戳或数字(在无衬线字体中通过 tabular-nums 对齐数字)。字号 12/14/16/22/28,字重 400/500/600,标题 -0.022em 字间距,每个屏幕最多四种字号。在移动端,标题提升一级:区域标题 18,卡片标题 16。
  • 移动端聊天发送按钮为仅图标 44×44 的纸飞机按钮,带有 aria-label="Send"。
  • 间距:4pt 比例。组内比组间更紧密(4 / 6 / 16 / 24–32 / 48)。选择器的下拉箭头距右侧 12px,右内边距 36px。
  • 颜色:一个强调色(操作、聚焦、选中),状态色独立,按钮文本在两个主题下 ≥ 4.5:1,每个主题配有 --on-accent。
  • 层级:静态表面用填充层级变化,无边框或阴影。仅浮动层使用边框环和阴影。暗色模式下层级越高越亮。
  • 图标:每个产品统一一种风格,线型、实心或双色,绝不在菜单、导航、工具栏、列表或卡片中混用。选中状态仅改变颜色,不改变图标风格。只用一个图标库、一种线条宽度、每组统一尺寸。
  • 文案:动词 + 对象按钮,错误信息包含原因和修复方法,句子式大小写,无 emoji,无夸张词汇。

不可协商原则(来自 20 条原则)

  • 用户触发的 UI 动效时长 120–300ms,退出时长约为进入的 80%。移动效果绝不使用 linear。
  • 缓动曲线需匹配方向:入场 ease-out,退出 ease-in,屏幕上 A→B 使用 ease-in-out。日常 UI 无过冲。
  • 高频交互(键盘导航、列表高亮、工具选项卡)即时响应。
  • 每个输入在 100ms 内得到反馈。保存操作使用乐观 UI。超过 400ms 显示进度。
  • 触摸区域至少 44×44,密集桌面至少 32×32,即使图标较小。
  • 每个视图一个聚焦焦点和一个主操作。聚焦时调暗背景。
  • 长数字分段显示。输入接受凌乱格式并回显整理后的值。
  • 除非有特殊理由,否则使用标准位置和图标。
  • 设计每个组件状态:空闲、悬停、按压、加载、成功、错误、禁用。
  • prefers-reduced-motion:移除移动、缩放和过冲,仅保留短暂的透明度变化。

不可协商原则(来自 10 条技巧)

  • 嵌套圆角:内圆角 = 外圆角 − 内边距。
  • 边框使用 alpha 通道(rgb(0 0 0 / .12)),绝不在不同表面上使用纯灰十六进制色。
  • 调色板和渐变使用 OKLCH(渐变色中标注 in oklch)。
  • 图标线条粗细与相邻文字粗细匹配。
  • 水平滚动条边缘通过遮罩淡出。
  • 图标切换时通过 filter: blur(4px) 进行交叉淡入。
  • 暗色模式:层级越高越亮(页面 < 卡片 < 菜单)。
  • 移动端全屏高度用 dvh/svh,绝不使用裸 100vh。
  • 在着色卡片上的白底产品图使用 mix-blend-mode: multiply。

不可协商原则(来自 10 条排版技巧)

  • 悬停加粗或选中加粗绝不引起布局变化(预先保留粗体宽度)。
  • 按钮和徽章中的单行标签需光学居中(text-box-trim)。
  • 链接下划线避开下行部分(text-underline-offset: 0.2em)。上标不破坏行高节奏。
  • 文案中使用真正标点:弯引号、撇号、短破折号、省略号。
  • 末尾不同的名字进行中间截断。网格中卡片标题限定为相同行数。

不可协商原则(来自 20 条动画工艺)

  • 弹出面板和菜单从其触发元素向外扩展(transform-origin 位于触发元素),从 scale(.95) 开始,绝不从 scale(0) 开始,并退出回到触发元素。
  • 新旧状态重叠。在“保存”和“已保存”之间绝不出现空白帧。
  • 拖拽时指针与元素 1:1 跟随,按下时无过渡,超出边界时产生橡皮筋效果。
  • 卡片 → 详情页展开同一元素(共享 layoutId / 视图过渡),绝不使用不相关的替换。
  • 分段控件和选项卡用跟随指示器移动的遮罩揭示活动标签。
  • 移动的旋钮约拉伸 12%(面积保持)。成功操作有一次脉冲效果。

需要移除的 AI 劣化特征

混合图标风格(实心房子配上轮廓文件夹、轮廓图标选择后变为实心)、单个屏幕上出现两个图标库、emoji 作为图标、标题上方“NEW”填充式徽章、重复标题的眉毛区、标题中随机出现一个斜体或等宽单词、等宽字体用于标签、眉毛区、徽章、时间戳或数字(如“// 01 STATUS”等大写等宽)、用光泽 3D 球体代替真实产品、权重均等的特征卡片行、“X, meet Y.”式标题、发光渐变边框、靛蓝到紫色渐变、渐变文字、彩色发光阴影、所有元素统一使用 16px 圆角(内外一致)、药丸形按钮配圆角输入框、卡片和按钮悬停时整体放大、所有动画统一 300ms ease-in-out、页面加载时统一淡入、统一的 p-6 gap-6、卡片套卡片、每个块同时使用阴影+边框+圆角、所有次要文本使用 grey-500、标题中出现 emoji,以及“Unlock”、“Supercharge”、“Seamless”、“Oops!”等文案。

鸣谢

原则、技巧和动画工艺源自五部短篇设计视频的释义和扩展:《20 Principles of UX & Animation》、《10 Niche Design Hacks》、《20 Ways to Make Beautiful AI Animations》、《10 Niche Typography Hacks》和《20 Ways to Unslop AI Designs》。鸣谢详见 README。

相关技能