如何读懂 Kubai Icons 徽章组合体系:从近 900 个物体到 2800+ 图标全解析

原创2026-11-13 15:13:16909 阅读

如何读懂 Kubai Icons 徽章组合体系:从近 900 个物体到 2800+ 图标全解析

Kubai Icons 是一个为 Claude Code、Codex 等编码智能体服务的图标技能项目:它用同一套风格绘制会动的小图标,并附带 2,800+ 个面向 React、Vue 与 SVG 的开源图标。很多人好奇——为什么只有近 900 个"物体",却能撑起 2,800+ 个图标?秘密就在于它的徽章组合体系:用 18 种小徽章和 1 种斜杠,把基础图标"乘"出成倍的状态变体。本文带你用 5 分钟完全读懂这套机制。

Kubai Icons 图标画廊:多排彩色小图标展示一致的徽章组合风格

先搞清楚"近 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 的注释):

  1. 徽章 = 实心圆盘 + 白色符号,永远和主体区分开,不需要描边或阴影;
  2. withBadge 会用一个 SVG mask 在基础图标的徽章位置周围挖出 1.4 单位的环形缺口,让圆盘"浮"在主体上,视觉上自成一体;
  3. 徽章的悬停动画和基础图标的动画各自独立、同步播放,而且挖出的缺口会随徽章悬停时的放大部分一起长大,保持缝隙均匀。

圆盘默认是中性墨色;如果页面需要语义色(加号=绿、叉=红),会改用徽章自带的 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)。

Kubai Icons 官方横幅:彩色动效图标阵列展示统一风格

数字对账: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 项目主页图:16 个图标在悬停时依次展开动画

小结

Kubai Icons 的徽章组合体系,本质是把"图标状态"抽象成了可声明的组件:基础图标负责"物体",徽章负责"语义",withBadge / withSlash 负责"拼装"。921 个物体因此以极低的维护成本生长为 2,945 个开箱即用的图标——这正是它能被 AI 智能体稳定复用、也能被开发者手动扩展的底层原因。

登录后查看全文
kubai-icons