如何读懂 Kubai Icons 徽章组合体系:从近 900 个物体到 2800+ 图标全解析
如何读懂 Kubai Icons 徽章组合体系:从近 900 个物体到 2800+ 图标全解析
Kubai Icons 是一个为 Claude Code、Codex 等编码智能体服务的图标技能项目:它用同一套风格绘制会动的小图标,并附带 2,800+ 个面向 React、Vue 与 SVG 的开源图标。很多人好奇——为什么只有近 900 个"物体",却能撑起 2,800+ 个图标?秘密就在于它的徽章组合体系:用 18 种小徽章和 1 种斜杠,把基础图标"乘"出成倍的状态变体。本文带你用 5 分钟完全读懂这套机制。
先搞清楚"近 900 个物体"是什么
打开 icons/ 目录,里面每一个 .js 文件就是一个基础图标(base icon),例如 folder.js 是文件夹、calendar.js 是日历。排除下划线开头的共享几何模块(如 _arrows.js)后,仓库里当前共有 921 个基础图标——这就是"近 900 个物体"的出处。
而徽章全部住在 badges/ 目录,一共 18 个语义徽章:
plus, minus, check, x, alert, info, up, down, right,
clock, sync, star, heart, lock, search, cog, sparkle, bolt
加上一个特殊的斜杠文件 _slash.js(负责 -off 变体),组合的"原料"就齐了。
组合机制拆解:一行声明,生成一个新图标
整套组合逻辑只有两个函数,都在 packages/core/src/compose.js:
withBadge(base, badge)—— 把徽章贴到基础图标右下角,生成<名字>-<徽章>复合图标withSlash(base, slash)—— 斜着画一道杠,生成<名字>-off图标
具体触发规则在注册器 tools/registry.mjs 里,完全由每个基础图标自己声明决定:
| 声明字段 | 效果 | 例子 |
|---|---|---|
variants: ['plus', 'check', ...] |
每个徽章生成一个复合图标 | folder + plus → folder-plus |
off: true |
生成斜杠版 | bell → bell-off |
换句话说:文件夹想要哪些徽章,就在自己的文件里点哪些名。folder.js 声明了几乎全部 18 种徽章,所以它一个人就贡献了 18 个复合图标;而箭头这类图标一个都不声明,因为"加号箭头"在产品里很少用得上。
这种"按需点菜"是整个体系保持干净的关键:不是 921 × 18 = 一万多的乱炖,而是 440 个基础图标精选了真正需要的组合。
徽章为什么"贴上去就好看":圆盘 + 挖槽的细节
如果直接把徽章画在图标身上,颜色会糊在一起。Kubai Icons 的解法写得很直白(见 badges/_disc.js 的注释):
- 徽章 = 实心圆盘 + 白色符号,永远和主体区分开,不需要描边或阴影;
withBadge会用一个 SVGmask在基础图标的徽章位置周围挖出 1.4 单位的环形缺口,让圆盘"浮"在主体上,视觉上自成一体;- 徽章的悬停动画和基础图标的动画各自独立、同步播放,而且挖出的缺口会随徽章悬停时的放大部分一起长大,保持缝隙均匀。
圆盘默认是中性墨色;如果页面需要语义色(加号=绿、叉=红),会改用徽章自带的 tone,比如 badges/alert.js 的琥珀色 #D97706。
18 种徽章的语义速查表
官方在 docs/authoring.md 中给出了这张对照表,是理解命名规则的核心:
| 徽章 | 含义 |
|---|---|
plus、minus、check、x |
新增、移除、完成、取消/错误 |
alert、info |
警告、详情 |
up、down、right |
上传/导出、下载/导入、移动/发送 |
clock、sync |
定时/最近、同步中 |
star、heart |
收藏、点赞 |
lock、search、cog |
私有、查找、设置 |
sparkle、bolt |
AI/智能、快速/强劲 |
而 off: true 则专门给"能开关"的东西:铃铛、麦克风、相机、信号、灯光。斜杠在悬停时还会做一个短促的阻尼抖动,像是在说"开不了机"(见 _slash.js)。
每个徽章自身也有小动画:lock 的锁钩会弹开、check 的勾会重新描一遍、sparkle 的四角星会旋转闪光(见 badges/sparkle.js)。
数字对账:921 → 2945 是怎么算出来的
用项目自带的注册器实际统计一下,账目非常清楚:
| 项目 | 数量 |
|---|---|
| 基础图标("物体") | 921 |
徽章组合出的复合图标(-plus、-check…) |
1,955 |
斜杠 -off 图标 |
69 |
| 合计 | 2,945(即官方口径的 2,800+) |
也就是说,69% 的图标量来自组合,而不是多画了 69% 的图。每个复合图标还会自动合并双方的中文名与标签(例如"归档·新增",tags 合并 archive + plus 的关键词),在 tools/registry.mjs 中自动完成——搜索、网站展示、包发布全都复用这份数据。
想上手验证或扩展?两个入口
- 本地看一眼:克隆仓库后运行
npm install,再执行node tools/check.mjs --only 'archive*',check-out/lib/下会生成variants.png,把所有复合图标并排画成对照表,肉眼即可核对组合效果。 - 自己加图标:格式规范都在 docs/authoring.md——一个图标一个模块、
variants只挑产品真用得到的徽章、off只给能开关的物体。
小结
Kubai Icons 的徽章组合体系,本质是把"图标状态"抽象成了可声明的组件:基础图标负责"物体",徽章负责"语义",withBadge / withSlash 负责"拼装"。921 个物体因此以极低的维护成本生长为 2,945 个开箱即用的图标——这正是它能被 AI 智能体稳定复用、也能被开发者手动扩展的底层原因。