企业官网建设流程全解析

• 开发工具
• CLI
• 数据可视化
• LLMOps

本文以仓库根目录下 DESIGN.md 为主体，系统讲解 Tokscale 前端在公共用户档案（/u/[username]）、全球排行榜（/leaderboard）、群组排名（/groups/[slug]）与 README Embed 组件（/api/embed/[username]/svg）上的信息架构、视觉语言、可访问性契约与实现约束，并结合 packages/frontend 下的实际源码逐条印证。读完本文，你将掌握这套"以数据为先、轻量实用、跨 320px 到桌面端一致"的设计系统的完整规则，以及如何用仓库内的真实实现落地每一个设计决策。

一、文档定位与证据基线（Source of truth）

DESIGN.md 是一份面向产品/设计/前端工程师的设计实施规范（design spec），而非用户手册。它明确声明自己的证据基线（Status: Active，最近刷新于 2026-07-12），并列出需要遵守的产品表面：

规范同时给出了它审阅的证据来源：ProfilePageClient.tsx、components/profile/、lib/embed/、embed SVG 路由、leaderboard 与 groups 目录、lib/leaderboard/、lib/groups/、Navigation.tsx 与 globals.css。这意味着本文以下所有结论都能在仓库中直接找到对应实现，具备可验证性。

二、品牌与产品目标：精确、冷静、安静地竞争

品牌定位可以概括为四个关键词：精确（Precise）、技术（Technical）、冷静（Calm）、安静地竞争（Quietly competitive）。

信任信号（Trust signals）要求全部围绕真实数据展开：

• 精确的用量数值（exact usage values）；
• 透明的时间范围（transparent time ranges）；
• 可访问的数据标签（accessible data labels）；
• 可见的新鲜度（visible freshness，如 "Updated … (UTC)" 页脚）；
• 熟悉的 GitHub 身份（GitHub 头像与用户名）。

被明确禁止的视觉装饰包括：应用界面内的宇宙装饰（cosmic decoration）、超大药丸形控件（oversized pill controls）、重复指标（repeated metrics）、无意义的 3D 处理、过度渐变、密集卡片堆叠，以及抄袭其他产品的品牌。

**产品目标（Goals）**可归纳为五条：

1. 档案在一个视口内即可读懂；
2. 全球与群组排名一眼可扫（immediately scannable）；
3. 在每个视口都保留 tokens、cost、time、rank、role 五项决策指标；
4. 群组发现与成员流程要像一个统一服务；
5. 每个 Embed 模板讲一个独立、清晰的用量故事，并保证从 320px 到桌面端都干净可用。

**非目标（Non-goals）**同样重要：本轮不做数据库 schema、认证、设置、全局落地页/页脚资产与/local图表重设计；排行榜响应可裁剪到其排名表面真正消费的字段；不引入新依赖；不做参考站点的像素级克隆。

成功信号（Success signals）：访客无需越过营销 hero 即可触达排名数据；前三名与活跃范围在数秒内可扫；公共群组足够紧凑可互相比较；群组详情不与导航冲突；移动端排名行无需横向滚动即可保留关键指标；profile、leaderboard、groups、embeds 共享同一套视觉语法。

三、用户画像与核心任务（Personas and jobs）

规范定义五类主要用户画像：

1. 自查者：查看自己活动的开发者；
2. 比较者：对比公共用户的访客；
3. 团队所有者：管理受限排名范围的团队负责人；
4. 成员：查看自身排名的群组成员；
5. 维护者：调试已提交用量的仓库维护者。

对应九类用户任务：识别某个人或群组、理解排名范围、对比关键用量指标、找到某个成员、查看个人排名、创建或加入群组、配置真实可信的 embed、分享结果。

**关键使用上下文（Key contexts of use）**包括：宽屏桌面对比、窄屏移动端排名检查、纯键盘导航、登录/匿名两种群组发现、GitHub README 渲染环境，以及"长名称、稀疏活动、多页数据、缺失可选指标"等边缘数据集。这些上下文直接决定了后文响应式与可访问性规则的取舍。

四、信息架构：核心路由与导航

4.1 路由总览

规范把核心路由分成四类，并指明各自职责：

**内容层级（Content hierarchy）**也逐路由明确：档案保持"身份 → 指标 → 分析"；全球排行榜使用"标题/范围 → 聚合事实 → 范围/搜索/排序 → 排名 → 加入指引"；群组目录使用"目的/动作 → 公开/拥有过滤 → 紧凑群组列表"；群组详情使用"身份/成员关系 → 受限事实 → 周期/搜索/排序 → 排名 →（授权时）邀请管理"。

4.2 导航实现：纯链接而非客户端状态

规范要求：现有 Tokscale 应用导航保持不变，/leaderboard使用基于链接的 Users/Groups 导航，以保证 URL、历史记录与服务器渲染保持权威。这一点在 ViewSelector.tsx/leaderboard/ViewSelector.tsx) 中有直接体现：

• 它是"use client"组件，但两个页签都用Link渲染（as={Link}），注释明确写着 "Pure-link nav (no client state)"；
• 使用aria-current="page"而非role="tablist"，因为这是整页导航而非页内 tab 面板，箭头键行为保持浏览器原生；
• buildLeaderboardViewHref()负责过滤参数保留：跳过page与view参数本身，且仅当当前周期为custom时才携带from/to，避免在目标视图上留下过期日期输入。

在 leaderboard/page.tsx/leaderboard/page.tsx) 中可以看到服务的双层组织：页面外壳由service-page-shell+Navigation+ServiceFooter组成，LeaderboardWithPreferences按searchParams.view分流到LeaderboardClient（用户榜）或GroupsView（群组目录）；generateMetadata把不同筛选参数坍缩到两个 canonical URL 上，只有view=groups是真正不同的页面，因此 canonical 到自身，避免近重复页面被爬取。

4.3 旧路由的收敛

旧/groups顶层列表页已被合并进/leaderboard?view=groups，从而使 groups 不再占用顶层导航页签。packages/frontend/src/app/(main)/groups/page.tsx/groups/page.tsx) 现在只是一个redirect("/leaderboard?view=groups")的占位页；而/groups/[slug]、/groups/new、/groups/join/[token]保持独立路由不受影响。群组目录的分页"Load more"数据来自 packages/frontend/src/app/api/groups/route.ts 对应的/api/groups接口（page/limit/my=true参数，见 GroupsBrowser.tsx/leaderboard/GroupsBrowser.tsx) 中的请求构造）。

五、设计原则：数据先于装饰

规范给出了八条可操作的设计原则，全部指向同一目标——信息层级由数据承载，而不是装饰：

1. Data before decoration：标签、数值、趋势与范围上下文承载层级；
2. One fact, one home：tokens、cost、active time、sessions 不在多张卡片间重复；
3. Lightest useful surface：优先用留白与分隔线；有边框的面板只保留给身份概览、图表、Usage details、Token mix 和独立分组数据集；
4. Compact, not cramped：桌面控件高度 28–36px；移动端保持 44–48px 粗指针目标而不放大视觉镀铬；
5. Ranking before promotion：应用内排名以标题和数据开场，黑洞营销 hero不出现在 leaderboard 或 groups 路由；
6. Preserve comparison context：响应式排名重排为紧凑行，而不是隐藏 cost、tokens、rank、role 或有用的 all-time 事实；
7. Honest group identity：群组缺少头像时使用确定性的文字 monogram（首字母徽标），绝不用无关的装饰性渐变；
8. Reference, not replica：借鉴参考站点的窄内容度量、克制边框、图表优先组合与低噪声控件，但保留 Tokscale 自己的字体、数据与蓝色强调。

第 7 条的落地可看 RankingUI.tsx 的GroupMark组件：有avatarUrl时渲染图片，否则调用 presentation.ts 的getGroupMonogram()——取名称前两个词的首字母（单字则取前两个字母）大写，如群组名空时回退为 "TG"。同时 utils.ts 的slugifyGroupName()会把空 slug 或保留字（new、join、settings、members）追加 8 位随机串，从路径层保证群组身份的确定性。

权衡取舍（Tradeoffs）记录在案：公共档案保留专用的响应式用量趋势，并新增一个可选的内联等距（isometric）贡献视图，且与 2D 使用同一个受限日历；不复用更重的/local图容器或装饰性 3D embed 卡片；原始总量保持权威；用量趋势默认使用 trailing average；2D 仍是默认贡献视图。

六、视觉语言（Visual language）

6.1 色彩

• 深色锌中性画布（dark zinc-neutral canvas），抬升表面只略微更亮；
• 半透明白色边框；
• white/default/muted 三档文本，均满足 WCAG AA 对比度；
• Tokscale 蓝只用于单一主操作与选中数据强调；
• provider 颜色只出现在图表/图例语境。

对应的 token 化实现可在 embedShared.ts 的THEMES常量中看到：深色主题surface: #131822、border: rgba(255,255,255,0.16)、brand: #2F8FFF；浅色主题surface: #FFFFFF、brand: #0969DA。服务页的语义变量则来自 globals.css（--service-surface、--service-border、--service-accent、--service-focus等，见各组件的 styled 定义）。

6.2 排版

• 仅使用现有FigtreeUI 字体与JetBrains Mono（仅代码）；
• 字号阶梯：页面标题 20–24px medium/semibold，章节标题 16–18px medium，正文 14–16px，元数据 12–13px；
• 数值一律使用 tabular figures（表格数字），保证排名数字对齐——MetricValue、MobileRank、RankBadge等组件均设置了font-variant-numeric: tabular-nums；
• Embed 侧对应FIGTREE_FONT_STACK与MONO_FONT_STACK两套字体栈，以及cardTextStyle()注入的text{font-variant-numeric:tabular-nums}样式。

6.3 间距、圆角、动效与图标

• 4px 基准网格，常用间距 8/12/16/20/24px；
• 应用画布最大 1500px，响应式 16–32px 排水沟（gutters）；ServiceFooter的Inner正是max-width: 1500px+padding: 20px 32px；
• 排名行目标高度：桌面 56–64px，移动端 76–92px 且信息完整；
• 圆角：控件 8px、面板 12px，仅徽章/头像使用全圆角；深色应用表面用边框而非阴影；
• 动效：状态变化即时生效；仅按压控件允许 120–160ms transform；遵循prefers-reduced-motion（GroupsBrowser的骨架屏 shimmer 即用@media (prefers-reduced-motion: reduce)关闭）；
• 头像规范：GitHub 头像 + 微弱的深色描边，移动端 72px、桌面 80px；排名强调色紧邻身份元数据；复用现有 16px 应用图标，禁止装饰性图标容器。

七、组件体系（Components）

7.1 复用与新增

复用清单：Navigation、档案组件、lib/utils的格式化器、共享图表面板色/设置、TabBar、现有 16px 图标与既有 server-fetching 模式。

新增/变更清单：

变体与状态：primary/secondary/ghost 动作；active/inactive 导航与周期；当前用户行与前三名行；public/private/member/owner/admin 群组状态；loading、empty、search-empty、error、pagination、copied-invite、submitting 状态；桌面表格与移动排名列表两种构图。LeaderboardClient中当前用户行通过data-current-user="true"使用--service-accent-soft背景 + 2px 左侧强调线标识。

7.2 图表契约（Chart contract）

每个 provider/model 对渲染一个稳定的堆叠面积图。Provider 组及其模型按原始受限用量升序排列，使主导带保持在顶部；仅活动 tooltip 行按降序排序。使用 provider 级图例色、确定性模型色调、40% 填充、1px 单色边界，且无图表动画。

该契约是"参考而非复制"原则在图表上的落地，目的是让排名主导的数据带稳定、不闪烁。

7.3 贡献图契约（Contribution contract）

• 渲染完整的请求 UTC 日期范围，包括零值的外部天数（outer days）；
• 2D 强度与 3D 高度派生自同一个 token 受限日历；
• 提供紧凑视图与调色板选择器；
• hover/focus 时显示视口钳制的每日 tooltip；
• 点击、触摸、Enter 或 Space 更新一个持久的 tokens/cost/client/model 明细，默认显示可视范围末端，跨视图与调色板切换保持不变，两视图均保留漫游式键盘导航，并输出简洁的屏幕阅读器摘要。

该契约的几何核心在 embedShared.ts：getContributionWindow()把贡献事实限定在档案同款"trailing year"内，网格可从前一个周日开始但对齐填充不影响强度、活跃天数与一年总量；layoutContributions()输出 GitHub 风格网格（列=周、行=星期几，首列周日对齐，未来天数省略，activeDays计有产出的天数）；getContributionIntensity()用tokens/maxTokens分档 0–4。3D 侧见 renderIsometric3DSvg.ts：用<rect>+ CSS transform 渲染等距立方体（顶面skewY(-30) skewX(40.89) scale(1 1.15)，左右面按 0.8367/0.7 系数压暗），MAX_HEIGHT/MIN_HEIGHT限制柱高。

7.4 Embed 契约（Embed contract）

• 实时预览视觉优先；密集设置放在视口受限的滚动区内；只暴露当前渲染器消费的选项；对话框打开期间捕获/还原焦点；
• 八个 2D 模板共享同一实心表面、身份头、分隔线、页脚、字号阶梯与克制的语义色，但各自使用不同的数据层级；禁止装饰性渐变、发光、图案、伪 chrome 与隐喻化装饰；
• 3D 贡献视图仍是受支持的一等渲染器，有自己兼容的控件；
• 桌面端用 preview/settings 双面板，移动端单 body 滚动。

八模板的职责分工（Embed hierarchy）：

并明确：SVG 内不得出现模板名 overline、杜撰的系统标签或解释性标语。

路由级实现见 packages/frontend/src/app/api/embed/[username]/svg/route.ts：

• 查询参数解析：theme（默认 dark）、compact（1/true）、sort（tokens/cost）、period（all/month/week，非法回退 all）、graph、view（2d/3d）、template（非法回退 classic）、color、tokens/cost（compact/full）、rank（plain/percent/total）；
• 用户名先经isValidGitHubUsername校验，非法返回 400 错误卡；用户不存在返回错误卡；大小写别名用 308 重定向到 canonical 用户名路径；
• 缓存策略：revalidate = 60，响应头Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300，并带X-Content-Type-Options: nosniff与严格 CSP（default-src 'none'; img-src data:; style-src 'unsafe-inline'），保证独立 SVG 输出与 CSP 兼容；
• requiresContributions()决定哪些模板/组合必须取贡献数据（graph、vitals、blueprint，或showGraph且非 compact classic），缺失时返回 503 错误卡；
• 各模板分发到独立的渲染器：renderProfileEmbedSvg（classic）、renderMinimalEmbedSvg、renderTerminalEmbedSvg、renderGraphEmbedSvg、renderOrbitEmbedSvg、renderVitalsEmbedSvg、renderBlueprintEmbedSvg、renderReceiptEmbedSvg，3D 走renderIsometric3DEmbedSvg。

数据层见 getUserEmbedStats.ts：getUserEmbedStats用unstable_cache+ tag 缓存（embed-user:{username}:{sortBy}:{period}）；有限周期从daily_breakdown聚合 tokens/cost；排名计算区分有限窗口（ROW_NUMBER，与排行榜周期页签相同 tie-breaker）与 lifetime 窗口（RANK，与 all-time 页签一致），leaderboard_hidden用户不占位也不膨胀分母；贡献数据按 dateRange 取daily_breakdown并按 UTC 锚定一年窗口（含 7 天缓冲）。

7.5 Token 与组件所有权

• 新增 service tokens 放在 src/app/globals.css，且不得改动 landing、leaderboard、settings、groups、/local正在使用的既有全局别名；
• 档案组合与变体放在src/components/profile/；
• 共享的/local图组件不在本范围。

八、可访问性（Accessibility）：WCAG 2.2 AA

目标标准为WCAG 2.2 AA，规则分为四组：

键盘/焦点：可见焦点环；排名目的地使用链接语义；使用原生 button/input/select/checkbox；view、period、sort、pagination、copy、membership 全部可键盘完成；既有图表与 embed 焦点契约保持不变。

对比/可读：muted 文本对正常文本至少 4.5:1；provider 颜色永远不是唯一的数据标签；移动端正文字体 ≥16px。

屏幕阅读器语义：结构化标题；事实用<dl>；宽排名视图用真实 table 语义，窄视图用等价的标记列表；导航上用aria-current；搜索与日期控件有标签；异步结果用 status/alert 区域。实现证据：MetricStrip是<dl>，MobileRankingList是<ol>，GroupsBrowser的分页状态用role="status" aria-live="polite"、错误用role="alert"、骨架屏aria-busy="true"。

减少动效与感官：reduced motion 下禁用非必要 transform/动画；标签与数值独立于色相呈现。

九、响应式行为（Responsive behavior）

断点：覆盖 320px 到宽桌面；主检查点为 390、768、1024+ CSS px；用量图表移动端 224px、桌面 256px 高。

布局适配：

• 排行榜与群组页使用 1500px 应用外壳、16–32px 排水沟、无营销 hero；
• 聚合事实在桌面用分隔线分隔的紧凑轨道（MetricStrip720px+ 横向），移动端两列网格；
• 全球与群组排名在空间允许时渲染语义表格，窄屏渲染信息完整的链接行（MobileRankingRow），无页面级或嵌套横向滚动条；
• 群组目录卡片在窄屏变成紧凑的类列表 tile，描述限高（-webkit-line-clamp: 2）而非固定空高度；
• 身份/动作与控件栏换行成单列，不与固定导航重叠；创建/加入表单保持受限同时占满移动宽度。

触摸/悬停差异：粗指针至少 44px 有效目标（SegmentButton、PrimaryActionLink在 ≤640px 时min-height: 40–44px即为证据）；图表选择支持点按与键盘，图表下方为紧凑明细面板；细指针获得钳制、可内部滚动的浮动 tooltip；贡献格在 hover 与 focus 暴露相同数值。

十、交互状态（Interaction states）

十一、内容语气（Content voice）

• 语气：简洁、事实化、面向开发者；
• 术语统一使用 "tokens"、"cost"、"active days"、"submissions"、"providers"、"models"、"devices"；
• 微文案规则：控件/表头用 sentence case；完整解释句加标点；不用 emoji；不得使用含糊图表标签，例如只有最近一年每日行时不能写 "all-time history"。

十二、实现约束（Implementation constraints）

12.1 框架与样式

Next.js 16 + React 19 + styled-components；不引入 Sass、Tailwind 或图表库。仓库中 package.json 与 next.config.ts 可确认技术栈；所有上述组件均为 styled-components 的 styled 定义。

12.2 设计 token 与性能

• 新增 token 不得破坏既有全局别名（landing/leaderboard/settings/groups//local共用）；
• 图表与贡献图几何推导保持 memoized（useMemo见 LeaderboardClient）；正常档案保留模型带；高病理序列设上限并显式标注余量；同一时刻只渲染一个贡献视图；保留服务端数据获取与 ISR（embed 路由revalidate = 60即 ISR 的证据）；
• 排名查询与 API 载荷只包含展示所需的 identity、rank、token、cost、time、role、scope、pagination 事实；submission counts 与新鲜度元数据留在档案专属表面。这对应 lib/leaderboard/types.ts 中LeaderboardUser与LeaderboardData的字段设计——没有多余的 submit 计数字段。

12.3 分析约束

• 缺失日历日期按零值处理；
• lifetime 默认 trailing 30-day average，有限范围默认 trailing 7-day average，日值作为显式展示模式可用；
• 移动平均绝不改变原始范围总量或稳定序列排名。Embed 侧同款逻辑见getEmbedPeriodDateRange()（以最新提交日与 UTC 今天中较晚者锚定窗口，兼顾 UTC 以东时区）与getEmbedPeriodLabel()（all→lifetime、month→30d、week→7d）。

12.4 兼容性约束

• 认证、数据库 schema、档案 API 与 canonical 档案重定向全部保持不变；
• 公共排行榜 API 有意省略未使用的 submission-count 与 freshness 字段；
• 不得改变共享GraphContainer的行为；
• 保留所有公共 embed 模板 ID 与查询参数、XML 转义、CSP 兼容的独立 SVG 输出、模板固有宽度，以及无效/缺省模板时的 classic 回退（parseEmbedTemplate已实现）。

12.5 测试与截图预期

• 保留既有 profile/embed 覆盖；
• 新增聚焦测试：view 链接过滤参数保留、响应式排名/群组展示辅助函数（仓库 packages/frontend/tests/lib/leaderboardViewSelector.test.ts 等对应测试可查）；
• 跑前端 tests、lint、typecheck、build；
• 截图基线：/leaderboard、/leaderboard?view=groups、有数据的公共/groups/[slug]，尺寸 1440×1100 与 390×844；演练 search、period、sort、view 与主要群组导航；视觉结论持久化到.omx/state/groups-leaderboard/ralph-progress.json，通过目标 90。

十三、未决问题（Open questions）

规范中唯一悬而未决的问题：紧凑服务语言（compact service language）是否应扩展到设置、导航与装饰性全局页脚，owner 为 product/design，影响范围是站点级外壳一致性——本轮刻意排除，留给未来迭代决定。这一点与"非目标"中"不做全局 landing/footer 资产"的声明相互呼应。

小结

DESIGN.md 是一份高度可执行的"实现前规范"：它先定品牌与目标，再定信息架构与内容层级，然后落到组件、图表、贡献图、Embed 八模板的具体契约，最后用实现约束、兼容性红线与截图验收标准收口。而 Tokscale 仓库的 packages/frontend/src 几乎逐条兑现了这份规范——从纯链接的ViewSelector、<dl>事实条、确定性的GroupMarkmonogram，到带 CSP 与 ISR 的 embed SVG 路由与ROW_NUMBER/RANK排名 SQL。对希望在 Tokscale 上做二次开发、贡献前端代码或复用其设计语言的工程师而言，将本文的规则与上述源码文件对照阅读，即可得到一套完整、可验证的落地路径。

• 开发工具
• CLI
• 数据可视化
• LLMOps