企业官网建设流程全解析

本文聚焦 CCBaga 仓库中vendor/cromma-ui/src/pika/这一层 Pika 图标模块，说明它如何以 15 个原版 SVG 图标、一个统一导出入口和一份 props 类型契约，为 CCBaga 桌面端提供自包含、零图标库依赖的图标能力。读完后你将掌握该模块的目录职责、PikaIconProps的每个字段如何生效、图标在侧栏与按钮中的真实调用方式，以及按仓库既有约定新增或替换图标时应遵循的完整流程与自检清单。

模块定位：一个只在本地消费的图标子集

pika/目录的职责在它的层级文档中写得非常克制：

icons/: 应用使用的 15 个原版 SVG 图标；新增房屋、浏览器窗口与连通节点用于侧栏语义导航，Server 用于 VPS 按钮。 index.ts: 应用组件导出入口；从原版库提取实际使用控件与其依赖闭包。 types.ts: Pika SVG 图标的尺寸与原版属性契约。

来源见 pika/CLAUDE.md。三点信息值得展开：

1. 这是"子集"而非完整图标库。上游 Pika 有上千个图标，但 CCBaga 只搬运了实际被界面引用的 15 个，遵循父级文档"复制使用组件及依赖，不建立跨工程链接"的原则（vendor/cromma-ui/CLAUDE.md），以及src/层"从原版库提取实际使用控件与其依赖闭包"的表述（vendor/cromma-ui/src/CLAUDE.md）。
2. 图标承载语义，而非装饰。文档特别点名HomeDefault（房屋）、WindowBrowser（浏览器窗口）、Share01（连通节点）三个"新增"图标用于侧栏语义导航，Server用于 VPS 按钮——这说明图标选择与界面信息架构是绑定关系，见下文映射表。
3. [PROTOCOL]是强制约束。目录头部最后一行写着"变更时更新此头部，然后检查 CLAUDE.md"，从仓库根 CLAUDE.md 到vendor/、src/、pika/、icons/形成了一条逐级 L2 的文档链，任何增删图标都必须同步维护。

三层结构：文件、入口、契约

pika/只有三样东西，边界清晰：

index.ts的头部注释把这条链路说得很明确："[INPUT]: Pika 图标的本地副本。[OUTPUT]: 本应用具名使用的 Pika 图标。[POS]: 同源图标的唯一消费入口。" 全部 15 行导出一一对应磁盘文件：

export { default as EraserDefault } from "./icons/EraserDefault"; export { default as Translate } from "./icons/Translate"; export { default as ShieldCheck } from "./icons/ShieldCheck"; export { default as Settings01 } from "./icons/Settings01"; export { default as Globe } from "./icons/Globe"; export { default as Refresh } from "./icons/Refresh"; export { default as FolderDefault } from "./icons/FolderDefault"; export { default as SearchDefault } from "./icons/SearchDefault"; export { default as CheckTickCircle } from "./icons/CheckTickCircle"; export { default as ClockDefault } from "./icons/ClockDefault"; export { default as MapPin } from "./icons/MapPin"; export { default as HomeDefault } from "./icons/HomeDefault"; export { default as WindowBrowser } from "./icons/WindowBrowser"; export { default as Share01 } from "./icons/Share01"; export { default as Server } from "./icons/Server";

注意"唯一消费入口"是靠包导出表强化的：package.json只暴露三个子路径，图标走./pika，业务代码必须写import ... from 'cromma-ui/pika'：

"exports": { ".": "./src/index.ts", "./theme.css": "./src/theme.css", "./pika": "./src/pika/index.ts" }

见 vendor/cromma-ui/package.json。这也解释了为什么业务侧从不出现cromma-ui/src/pika/icons/xxx这类深路径导入——一旦绕过index.ts，icons/的内部命名就不再是稳定接口。

PikaIconProps：一份写在类型根上的契约

types.ts的注释直接说明了设计意图："PikaIconProps 是全部 Pika 图标的 props 契约（size、color、className、ariaLabel）。… 一千多个形状一致的图标只在这里写一次类型。" 完整定义如下：

import type { SVGProps } from 'react'; export interface PikaIconProps extends Omit<SVGProps<SVGSVGElement>, 'color'> { size?: number | string; color?: string; ariaLabel?: string; }

四个字段的实际行为，需要结合图标实现一起看：

• size：默认24，同时写入width与height。类型是number | string，因此18、"1.1em"都合法——业务侧大量使用 15/16/17/18/19 等小尺寸覆盖。
• color：先被Omit<SVGProps<SVGSVGElement>, 'color'>从 React 的 SVG 属性中摘除，避免与 React 的color属性类型冲突，再以字符串形式重新声明。实现里落到style={{ color: color || 'currentColor' }}，配合stroke="currentColor"生效。
• className：原样透传给<svg>，因此外部可以用 Tailwind 类控制尺寸、旋转、颜色继承（如spin旋转类）。
• ariaLabel：作为aria-label的可覆盖默认值来源；同时所有图标都带role="img"。

而{...props}的透传意味着aria-hidden、data-*、事件等 SVG 属性仍然可用——这正是 CCBaga 业务层"装饰性图标"的写法基础。

单文件形态：生成产物的统一模板

除Server.tsx外，其余图标文件结构高度一致，以HomeDefault.tsx为例：

// 由 cromma-ui/scripts/gen-icons.ts 生成，不手改（源：icons/pika） import type { PikaIconProps } from '../types'; export default function HomeDefault({ size = 24, color, className, ariaLabel, ...props }: PikaIconProps) { const iconStyle = { color: color || 'currentColor' }; return <svg width={size} height={size} viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" className={className} role="img" aria-label={ariaLabel ?? 'home-default icon'} style={iconStyle} {...props}> <path stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M3 12.759c0-1.017 ..." fill="none" /> </svg>; }

可提炼出五条稳定约定（见 icons/HomeDefault.tsx）：

1. 视口固定0 0 24 24、fill="none"，线条靠stroke绘制，属线性图标风格。
2. strokeWidth硬编码为2，与 Pika 原版轮廓保持一致，不做按尺寸缩放。
3. 路径完全保留。icons/CLAUDE.md逐条强调"保持源项目路径与轮廓""路径不改"，说明移植时只做 JSX 属性名转换（如stroke-linecap→strokeLinecap），不改几何数据。
4. 默认无障碍名是小写 kebab 形式，如home-default icon、window-browser icon、share01 icon。它是兜底值，不是最终面向用户的文案。
5. // 由 cromma-ui/scripts/gen-icons.ts 生成，不手改是一条重要事实约束：图标文件是生成产物。但本仓库的 vendor 副本只保留了src/，并未包含scripts/gen-icons.ts，因此当前仓库内并没有可运行的图标生成器；从源码结构看，这份注释与统一模板是升级时对齐上游的唯一线索。实际维护时应以"模板复制 + 路径原样保留"的方式新增图标，而不是期待脚本存在。

Server.tsx是一个有意义的例外，它把{...props}放在width/height之前，并把className、role、aria-label、style写在展开之前：

export default function Server({size=24,color,className,ariaLabel,...props}:PikaIconProps){ return <svg className={className} role="img" aria-label={ariaLabel ?? "server icon"} style={{color:color||"currentColor"}} {...props} width={size} height={size} viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"> <path stroke="currentColor" ... strokeWidth="2" d="M7 12h10..." fill="none"/> </svg>; }

差异带来两个后果：一是外部传入的width/height无法覆盖size；二是外部传入的className会被{...props}中的className（如果有）覆盖。正常调用不会触发，但如果你在扩展时给图标加自定义width，需要知道这个顺序差异。文档对它的定位也很明确："Pika 原版 server.svg 转 JSX，表达 VPS；路径不改。"

15 个图标与界面的语义映射

icons/CLAUDE.md为每个文件都写了语义说明，结合业务侧的import语句可以还原真实映射（业务侧使用别名导入，见 src/main.tsx）：

其中Refresh是最"通用"的一个：仅src/目录就有 7 个文件从cromma-ui/pika导入它，常用于按钮的leftIcon、加载中旋转（className="spin"）等场景。这也解释了为什么它必须是"唯一消费入口"——单一来源才能保证所有刷新按钮的线条粗细与视角完全一致。

在界面中的三种典型用法

1. 侧栏导航：图标由数据映射驱动

src/main.tsx用一张icons表把页面 key 映射到图标组件，再交给NavButton渲染：

const icons: Record<Page, typeof HomeIcon> = { quick: HomeIcon, cleaner: IdentityIcon, browser: BrowserIcon, system: SettingsIcon, vps: NetworkIcon, help: HelpIcon }; // ... <NavButton className="workspace-nav" active={page === p} aria-current={page === p ? "page" : undefined} disabled={locked} icon={<Icon size={18} aria-hidden="true"/>} ...>{t(titles[p])}</NavButton>

这里有两个值得注意的工程细节：size={18}让图标适配 32px 高的导航行；aria-hidden="true"抑制图标的role="img"语义，避免读屏器把"home-default icon"这样的兜底文案念出来——导航项的可访问名来自文字children，图标是纯视觉元素。

2. 按钮左图标：尺寸随按钮档位

快捷操作区把四种动作映射为四个图标，并统一用 19px：

const icons = { cache: WindowBrowser, fingerprint: Refresh, system: ClockDefault, claude: ShieldCheck }; <Button leftIcon={<Icon size={19}/>} variant="secondary" size="small" loading={busy === kind} ...>

见 src/quick-actions.tsx。系统页与网络页则普遍使用 15–18px，例如<ClockIcon size={18}/>、<ServerIcon size={15} aria-hidden="true"/>。这套"由调用方决定尺寸"的做法，正是size默认值 24 存在的意义：图标本身不绑定任何界面密度。

3. 动效编舞：图标作为状态载体

NavButton把icon包在一个relative flex size-6的容器里，悬停时原图标向左位移、旋转、缩到 0.56 并淡出，同时一条内联 SVG 箭头沿路径"描绘"出来：

<span className={cn('absolute inset-0 flex items-center justify-center transition-[opacity,transform] group-hover:-translate-x-[5px] group-hover:-rotate-[8deg] group-hover:scale-[0.56] group-hover:opacity-0', active ? 'text-foreground' : 'text-muted-foreground')}>{icon}</span> <svg aria-hidden="true" ... className="... [stroke-dasharray:1] [stroke-dashoffset:1] ..."> <path d="M9 18a30.6 30.6 0 0 0 5.817-5.49..." pathLength={1} stroke="currentColor" strokeWidth="2" .../> </svg>

见 vendor/cromma-ui/src/ui/nav-button.tsx。注释写明这条曲线来自"Pika ChevronBigRight 的原始曲线"，但它没有进入pika/index.ts的导出清单——它属于 UI 原语的内部零件，与ui/glyphs.tsx中"不进包入口"的内部字形属于同一类设计决策。

颜色链路：currentColor 与主题令牌

图标本身不含任何颜色常量，全部通过stroke="currentColor"继承文本色，style.color = color || 'currentColor'只是让"显式传色"这条路径可行。真正的颜色来自 Tailwind 语义类：未选中text-muted-foreground，选中/悬停text-foreground，而这两个类最终绑定到 tokens.css 中的--muted-foreground、--foreground（浅色主题oklch(0.5103 0 0)/oklch(0.3211 0 0)，深色主题另有对应值，并有--sidebar-accent系列）。于是同一套图标在浅色/深色主题下零改动工作。

这条链路也解释了一个常见疑问：为什么给图标传className="text-blue-500"能生效，但传fill或color属性却不起作用？因为图形靠stroke而非fill绘制（fill="none"），且stroke="currentColor"绑定的是 CSScolor，而非 SVG 的fill。

新增或替换一个图标：可执行的完整流程

仍以新增一个图标为例，按仓库现有约定应这样操作（仓库为只读，以下描述的是在你自己的分支上进行的维护流程）：

1. 放置文件：在 vendor/cromma-ui/src/pika/icons/ 下新建XxxName.tsx，文件名与导出名保持一致（Pika 原版命名，如HomeDefault、Share01的后缀风格）。
2. 套用模板并保留路径：复制任一现有文件的函数签名与svg外壳，只替换d属性与默认aria-label（小写 kebab 形式，如'my-icon icon'），保留viewBox="0 0 24 24"、fill="none"、strokeWidth={2}。
3. 登记导出：在 index.ts 增加一行export { default as XxxName } from "./icons/XxxName";，保持现有按使用优先级排列的风格。
4. 更新文档头：修改 pika/CLAUDE.md 的"成员清单"（数量与语义说明）和 icons/CLAUDE.md（逐文件一行说明），并遵守两处的[PROTOCOL]要求。
5. 业务侧改用别名并声明无障碍：在调用处import { XxxName as XxxIcon } from 'cromma-ui/pika'；纯装饰场景加aria-hidden="true"，需要读屏表达时传ariaLabel。
6. 验证：bun run build会先执行tsc --noEmit再vite build（见 package.json），类型错误与未使用导入会在此暴露；bun run dev起 Vite 开发服务（固定1420端口，strictPort）可做视觉核对，见 vite.config.ts。
7. 审计旧图标：新增后回头检查index.ts中是否出现"仅导出、零引用"的条目。表格中EraserDefault、Globe、SearchDefault、CheckTickCircle目前处于备用状态——若遵循"只保留实际使用控件"的原则，这类条目应明确标注语义用途或删除。

若要做"替换"而非"新增"，注意不要改动文件名与导出名：index.ts、CLAUDE.md与业务侧别名都按名字耦合，改名会造成跨文件的连锁修改；同时确认新路径的笔画方向与strokeWidth与原集合一致，否则侧栏会出现线条粗细不齐。

变更自检清单与授权边界

围绕这个模块，仓库把检查项写成了制度，而不是口头约定：

• 层级文档必须同步：pika/CLAUDE.md、icons/CLAUDE.md都要求"变更时更新此头部，然后检查 CLAUDE.md"，父级 vendor/CLAUDE.md 记录了组件库来源与"升级时同步来源而非另造控件"的原则。
• 不要另造控件：如果上游 Pika 已有合适图标，就不应自行绘制；这条原则与本模块"只做移植、不改路径"的定位互相印证。
• 授权提示不可忽略：NOTICE.md 明确写到vendor/cromma-ui是 Cromma UI 的本地副本（含 Pika 图标子集），"The copied tree does not currently contain an independent upstream license notice. Confirm its redistribution terms and restore any required notices before publishing these components." 也就是说，仓库内的 MIT 声明不能自动视为上游权利人的授权，对外分发前需自行确认再分发条款。这一点在新增图标时同样适用。
• 图标不等于 AI 工具图标：assets/ai-icons/是从 LobeHub lobe-icons 引入的第三方品牌 SVG（Codex、Cursor、OpenCode、Copilot 等），有独立许可证与归属说明，与本模块的 Pika 图标是两条互不相干的来源，不要混用或互相搬移。

常见问题速查

• 图标尺寸设了没变化？确认是否在Server图标上传了width/height：由于{...props}位于width/height之前，width会被size覆盖。
• 图标颜色不跟随主题？检查是否用style或color覆盖了currentColor；主题跟随依赖父级文本色类（text-foreground/text-muted-foreground）。
• 读屏器念出 "home-default icon"？说明该处未传ariaLabel也未加aria-hidden="true"；导航与按钮内的装饰性图标应显式隐藏。
• 深路径导入为何不行？cromma-ui的exports只开放.、./theme.css、./pika，icons/内部文件不是公共接口。
• 想跑图标生成脚本？本地副本不含scripts/gen-icons.ts，该注释仅记录生成来源；维护时按模板手工同步并保持路径不变。

相关路径速览

• 模块文档：vendor/cromma-ui/src/pika/CLAUDE.md
• 导出入口：vendor/cromma-ui/src/pika/index.ts
• 类型契约：vendor/cromma-ui/src/pika/types.ts
• 图标清单：vendor/cromma-ui/src/pika/icons/CLAUDE.md
• 代表图标：HomeDefault、Server、Refresh
• 消费方：src/main.tsx、src/quick-actions.tsx、src/vps.tsx、src/system.tsx
• 导航原语与动效：vendor/cromma-ui/src/ui/nav-button.tsx
• 主题令牌：vendor/cromma-ui/src/tokens.css
• 授权说明：NOTICE.md