Kilo Code 图标体系实战指南VS Code 扩展、Webview 与共享图标注册表的选型与绘制规范【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode本文档是 Kilo 仓库中.kilo/skills/icon-vscode/SKILL.md的完整展开版面向在 Kilo 仓库内为 VS Code 扩展、Webview 界面及共享图标注册表新增或审查图标的开发者。读完你将掌握五类图标表面Surface的选型决策、packages/kilo-ui与packages/ui双层图标注册表的实际结构、viewBox与几何绘制规则、currentColor着色与主题适配机制以及从设计到注册再到多主题验证的完整工作流。先决条件先选对图标体系Kilo 的图标体系横跨三个包VS Code 扩展本体packages/kilo-vscode、Kilo 专属 Webview 组件库packages/kilo-ui和跨项目共享的 UI 组件库packages/ui。动手画任何图标之前必须先确认图标将出现在哪个表面因为每个表面都有独立的来源、契约和主题处理方式。表面 (Surface)使用方式事实来源 (Source of truth)主题处理VS Code 命令、菜单、编辑器操作Codicon例如$(add)仅必要时才用 16×16 单色 SVGpackages/kilo-vscode/package.json记录使用位置VS Code 命令图标贡献点定义契约VS Code 主题渲染 CodiconSVG 使用 light/dark 贡献字段活动栏与视图容器按 VS Code 惯例使用 24×24 居中的单色图标现有 Kilo 品牌图标是刻意保留的资产例外packages/kilo-vscode/package.json、packages/kilo-vscode/assets/icons/遵循贡献点约定不要重新设计现有品牌标记市场与扩展品牌打包的品牌资产packages/kilo-vscode/package.json、packages/kilo-vscode/assets/icons/现有 Kilo 资产自带调色板与变体Webview 按钮与 UI使用kilocode/kilo-ui的Icon或IconButton先查packages/kilo-ui/src/components/icon.tsx再查packages/ui/src/components/icon.tsxcurrentColor与 VS Code 主题桥接扩展贡献的产品图标现有 WOFF2 字体条目例如$(kilo-logo)contributes.icons位于packages/kilo-vscode/package.json及其使用处VS Code 产品图标主题化两个关键禁忌不要在已有合适的 Codicon 或注册表图标时自行绘制自定义 SVG不要把 Webview 图标直接放进package.json也不要把 VS Code 贡献图标直接用在 Webview 中。两个体系之间的边界必须保持清晰。仓库既有约定双层图标注册表先查 Kilo 专属再查共享Kilo 的 Webview 图标注册表分为两层Kilo 专属层packages/kilo-ui/src/components/icon.tsx。该文件顶部const icons: Recordstring, { path: string; viewBox: string }定义了一组 Kilo 独有的条目例如circle-x-outline、pull-request、git-commit、git-merge、refresh、memory、database、extensions、coffee、wand-sparkles、send、reply、smile等。共享层packages/ui/src/components/icon.tsx。该文件定义跨项目共享的图标如plus、close、check、copy、terminal、edit、trash、settings-gear、github、discord等并以symbol精灵sprite方式注入页面。Kilo 的Icon组件实现了一个优雅的回退链见packages/kilo-ui/src/components/icon.tsx第 134–163 行export function Icon(props: IconProps) { const [local, others] splitProps(props, [name, size, class, classList]) if (!((local.name as Name) in icons)) { return ( Upstream {...others} name{local.name as Props[name]} size{local.size} class{local.class} classList{local.classList} / ) } // ...Kilo 专属条目渲染逻辑 }当传入的名称不在 Kilo 专属表中时自动回退到从opencode-ai/ui/icon导入的共享IconUpstream。因此新增Kilo 专属图标时添加到packages/kilo-ui/src/components/icon.tsx包装器会自动完成向共享集的回退仅当图标有意在 Kilo 之外共享时才添加到packages/ui/src/components/icon.tsx。同时注意保留既有命名拼写大多是 kebab-case如circle-x-outline、git-commit、thumbs-up-filled、files-expand并在新增前先匹配视觉上最接近的兄弟图标。注册表条目的形态约束Webview 注册表图标是内联 SVG path 字符串不是独立文件。每条目使用fillcurrentColor或strokecurrentColor不要为注册表条目添加主题重复版本或字面调色板。独立品牌美术资产brand artwork才可以使用 light/dark 变体。匹配最接近注册表兄弟条目的viewBox共享集大多是20 20部分已有16 16条目Kilo 专属条目也刻意使用24 24。图标以 16pxsmall、20pxnormal或 24pxmedium/large渲染。绝不要把一条 path 直接贴到不同画布而不重新平衡。共享层的viewBox选择是动态的packages/ui/src/components/icon.tsx第 122–124 行的viewBox()函数对magnifying-glass、arrow-undo-down、subagent返回0 0 16 16其余全部返回0 0 20 20。这说明共享集内部也允许个别 16×16 特例但必须显式登记。品牌资产清单扩展当前打包的品牌资产位于packages/kilo-vscode/assets/icons/包括kilo-light.svg与kilo-dark.svg活动栏与命令图标的 light/dark 变体kilo-light.png与kilo-dark.png活动栏图标的光栅版本logo-outline-black.png清单icon字段指定的扩展图标见packages/kilo-vscode/package.jsonkilo-icon-font.woff2打包的产品图标字体不是可编辑的图标源文件WOFF2 字体文件是打包贡献字体不是可编辑的图标源。产品图标通过contributes.icons注册例如packages/kilo-vscode/package.json中的kilo-logo条目icons: { kilo-logo: { description: Kilo Code logo, default: { fontPath: assets/icons/kilo-icon-font.woff2, fontCharacter: \\F101 } } }活动栏图标则通过viewsContainers.activitybar贡献使用 light/dark 字段viewsContainers: { activitybar: [ { id: kilo-code-ActivityBar, title: Kilo Code, icon: assets/icons/kilo-light.png, darkIcon: assets/icons/kilo-dark.png } ] }可访问性默认值注册表图标默认是装饰性的Icon组件的svg直接带aria-hiddentrue见packages/kilo-ui/src/components/icon.tsx第 158 行。因此图标按钮必须提供aria-label或可见按钮文本。IconButton组件的实现印证了这一点packages/kilo-ui/src/components/icon-button.tsx第 31 行const label () props[aria-label] ?? split.label ?? props.icon它把aria-label、显式label属性、最后兜底图标名依次作为无障碍名称并同步写入aria-disabled、aria-busy等状态。仅靠 tooltip 或任意的label属性是不够的——除非外层包装器把它映射成可访问名称。packages/kilo-vscode/webview-ui/src/stories/icon-button.stories.tsx展示了正确姿势每个IconButton都带aria-label如Create item、Edit item、Close item配合Tooltip提供视觉提示。几何规则一个图标一个语义每个图标只表达一个清晰的语义含义。小的、状态标记或激活态填充是可接受的修饰符共享注册表中的terminal-active、review-active、new-session-active、file-tree-active等就是「基础轮廓 fill-opacity0.1激活底色」的模式。从至少一个同角色兄弟图标出发匹配其viewBox、视觉重量、端帽caps、连接方式joins与内边距。官方命令 SVG 使用 16×16 画布 1px 内边距官方视图容器图标使用居中 24×24 画布。Kilo 注册表里pull-request的注释packages/kilo-ui/src/components/icon.tsx第 11 行明确记录了换算基准「以 1.25 的宽度在 20 单位网格上描边在 16px 渲染时即 1px以匹配其他轮廓图标」——这就是「兄弟权重」换算的活教材。圆帽端点远离边缘防止端帽被裁切。注册表图标沿用兄弟条目的边界而不是强加新的通用内边距规则。只用静态 SVG 几何允许path、rect、circle、ellipse、line、polyline、polygon和g。注册表图标中禁止光栅图、外部资源、渐变、滤镜、内嵌字体和style块。等比缩放从 24px 或 16px 源适配时先一起缩放坐标和每个描边宽度再把主描边设为兄弟条目的有效权重仅在能提升 1x 清晰度且不扭曲曲线的地方做对齐snap。端帽与连接风格跟随兄弟共享集刻意混用了方形端帽、圆形端帽、细线hairlines与几何耦合描边——例如target用默认圆形端帽加fill中心点git-commit用stroke-linecapsquare的水平线。新增图标应匹配语义最接近的兄弟。light/dark 打包资产几何一致除主题色外几何必须完全一致除非该资产是几何已确立的既有品牌标记。颜色与登记颜色规则Webview 注册表图标每个绘图形状都用currentColor。语义颜色通过组件或 CSS token 应用而不是写死在 SVG path 数据里。packages/ui/src/components/icon.tsx里几乎每一条 path 都以strokecurrentColor或fillcurrentColor结尾即是明证。官方命令贡献资产使用单色遵循 16×16 / 1px 内边距契约。打包的 Kilo 品牌资产遵循既有品牌调色板与显式 light/dark 清单字段而不是套用通用命令图标规则。登记规则Kilo 专属条目 →packages/kilo-ui/src/components/icon.tsx包装器自动回退到共享集。有意跨 Kilo 共享的条目 →packages/ui/src/components/icon.tsx。共享图标更新时同步更新共享画廊Kilo 专属图标使用导入kilocode/kilo-ui/icon的 story 或受影响的扩展 story现有 Kilo story 导入的是opencode-ai/ui/icon无法覆盖 Kilo 专属条目。通过Icon或IconButton使用图标不要在调用点复制 path 数据。完整工作流先搜索动手设计前先搜索现有 Codicon 与注册表名称packages/kilo-ui/src/components/icon.tsx→packages/ui/src/components/icon.tsx→ Codicon 目录确认没有现成图标可用。选目标确定目标表面、画布尺寸和最接近的兄弟图标。绘制或缩放绘制或重新缩放几何保持比例与描边关系套用上文几何规则 1–7。登记并消费按表面对应的正常 API 登记并消费图标——Webview 用Icon/IconButton命令用package.json贡献点产品图标用contributes.icons。多主题验证在 VS Code 的 light、dark、高对比度 light、高对比度 dark 四种主题下以 1x 和 2x 检查图标并放到真实的按钮/菜单上下文中确认没有裁切、过淡或比兄弟图标视觉更重。Webview 变更的 Storybook 验证对于 Webview 变更使用受影响的扩展 Storybook story或导入kilocode/kilo-ui/icon的 story。注意VS Code 的 Storybook 发现的是packages/kilo-vscode/webview-ui/src/stories而非专门的图标画廊现有 story 包括icon-button.stories.tsx、prompt-input.stories.tsx、chat.stories.tsx、settings.stories.tsx、agent-manager.stories.tsx、marketplace.stories.tsx等 16 个。运行入口是packages/kilo-vscode/package.json中的storybook脚本storybook dev -p 6007。icon-button.stories.tsx还同时覆盖了禁用态disabled、加载态loading和aria-pressed状态可作为验证图标按钮各状态的样例。打包资产的验证对于打包资产检查扩展清单贡献packages/kilo-vscode/package.json中的icons、viewsContainers、命令的 light/dark icon 字段以及所有适用的主题变体。例如命令kilo-code.new.openInTab与kilo-code.new.generateCommitMessage都使用light: assets/icons/kilo-light.svg, dark: assets/icons/kilo-dark.svg字段对而扩展整体图标指向assets/icons/logo-outline-black.png。参考资源VS Code 命令图标规范VS Code 产品图标参考packages/kilo-vscode/package.json— 贡献点用法与资产路径packages/kilo-ui/src/components/icon.tsx— Kilo 专属注册表条目packages/ui/src/components/icon.tsx— 共享注册表与 viewBox 选择packages/kilo-ui/src/components/icon-button.tsx— 图标按钮的无障碍名称与状态处理packages/kilo-vscode/webview-ui/src/stories/icon-button.stories.tsx— 图标按钮各状态的可视化验证样例【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考