Tokscale 前端设计系统与信息架构指南：公共档案、排行榜与 Embed 的实现规范

开发工具CLI数据可视化LLMOps【免费下载链接】tokscale️ Track token usage across AI coding agents from your terminal. Global leaderboard with trillions of tokens tracked.项目地址https://gitcode.com/gh_mirrors/to/tokscale点击查看免费下载本文以仓库根目录下 DESIGN.md 为主体系统讲解 Tokscale 前端在公共用户档案/u/[username]、全球排行榜/leaderboard、群组排名/groups/[slug]与 README Embed 组件/api/embed/[username]/svg上的信息架构、视觉语言、可访问性契约与实现约束并结合 packages/frontend 下的实际源码逐条印证。读完本文你将掌握这套以数据为先、轻量实用、跨 320px 到桌面端一致的设计系统的完整规则以及如何用仓库内的真实实现落地每一个设计决策。一、文档定位与证据基线Source of truthDESIGN.md 是一份面向产品/设计/前端工程师的设计实施规范design spec而非用户手册。它明确声明自己的证据基线Status: Active最近刷新于 2026-07-12并列出需要遵守的产品表面产品表面路由 / 端点对应实现公共用户档案/u/[username]packages/frontend/src/app/u/[username]/ProfilePageClient.tsx 及 packages/frontend/src/components/profile/档案 Embed 对话框 / README 挂件/api/embed/[username]/svgpackages/frontend/src/app/api/embed/[username]/svg/route.ts 与 packages/frontend/src/lib/embed/全球排行榜/leaderboardpackages/frontend/src/app/(main)/leaderboard//leaderboard/)群组目录/leaderboard?viewgroups同目录下的 GroupsBrowser.tsx/leaderboard/GroupsBrowser.tsx)群组详情/groups/[slug]packages/frontend/src/app/(main)/groups/[slug]/page.tsx建组 / 加入流程/groups/new、/groups/join/[token]CreateGroupClient.tsx/groups/new/CreateGroupClient.tsx)规范同时给出了它审阅的证据来源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**可归纳为五条档案在一个视口内即可读懂全球与群组排名一眼可扫immediately scannable在每个视口都保留 tokens、cost、time、rank、role 五项决策指标群组发现与成员流程要像一个统一服务每个 Embed 模板讲一个独立、清晰的用量故事并保证从 320px 到桌面端都干净可用。**非目标Non-goals**同样重要本轮不做数据库 schema、认证、设置、全局落地页/页脚资产与/local图表重设计排行榜响应可裁剪到其排名表面真正消费的字段不引入新依赖不做参考站点的像素级克隆。成功信号Success signals访客无需越过营销 hero 即可触达排名数据前三名与活跃范围在数秒内可扫公共群组足够紧凑可互相比较群组详情不与导航冲突移动端排名行无需横向滚动即可保留关键指标profile、leaderboard、groups、embeds 共享同一套视觉语法。三、用户画像与核心任务Personas and jobs规范定义五类主要用户画像自查者查看自己活动的开发者比较者对比公共用户的访客团队所有者管理受限排名范围的团队负责人成员查看自身排名的群组成员维护者调试已提交用量的仓库维护者。对应九类用户任务识别某个人或群组、理解排名范围、对比关键用量指标、找到某个成员、查看个人排名、创建或加入群组、配置真实可信的 embed、分享结果。**关键使用上下文Key contexts of use**包括宽屏桌面对比、窄屏移动端排名检查、纯键盘导航、登录/匿名两种群组发现、GitHub README 渲染环境以及长名称、稀疏活动、多页数据、缺失可选指标等边缘数据集。这些上下文直接决定了后文响应式与可访问性规则的取舍。四、信息架构核心路由与导航4.1 路由总览规范把核心路由分成四类并指明各自职责路由职责/u/[username]公共档案的唯一权威入口canonical/leaderboard紧凑的全球排名/leaderboard?viewgroups群组目录与成员关系入口/groups/[slug]受限排名与邀请管理视图/groups/new、/groups/join/[token]聚焦单一任务的表单**内容层级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-currentpage而非roletablist因为这是整页导航而非页内 tab 面板箭头键行为保持浏览器原生buildLeaderboardViewHref()负责过滤参数保留跳过page与view参数本身且仅当当前周期为custom时才携带from/to避免在目标视图上留下过期日期输入。在 leaderboard/page.tsx/leaderboard/page.tsx) 中可以看到服务的双层组织页面外壳由service-page-shellNavigationServiceFooter组成LeaderboardWithPreferences按searchParams.view分流到LeaderboardClient用户榜或GroupsView群组目录generateMetadata把不同筛选参数坍缩到两个 canonical URL 上只有viewgroups是真正不同的页面因此 canonical 到自身避免近重复页面被爬取。4.3 旧路由的收敛旧/groups顶层列表页已被合并进/leaderboard?viewgroups从而使 groups 不再占用顶层导航页签。packages/frontend/src/app/(main)/groups/page.tsx/groups/page.tsx) 现在只是一个redirect(/leaderboard?viewgroups)的占位页而/groups/[slug]、/groups/new、/groups/join/[token]保持独立路由不受影响。群组目录的分页Load more数据来自 packages/frontend/src/app/api/groups/route.ts 对应的/api/groups接口page/limit/mytrue参数见 GroupsBrowser.tsx/leaderboard/GroupsBrowser.tsx) 中的请求构造。五、设计原则数据先于装饰规范给出了八条可操作的设计原则全部指向同一目标——信息层级由数据承载而不是装饰Data before decoration标签、数值、趋势与范围上下文承载层级One fact, one hometokens、cost、active time、sessions 不在多张卡片间重复Lightest useful surface优先用留白与分隔线有边框的面板只保留给身份概览、图表、Usage details、Token mix 和独立分组数据集Compact, not cramped桌面控件高度 28–36px移动端保持 44–48px 粗指针目标而不放大视觉镀铬Ranking before promotion应用内排名以标题和数据开场黑洞营销 hero不出现在 leaderboard 或 groups 路由Preserve comparison context响应式排名重排为紧凑行而不是隐藏 cost、tokens、rank、role 或有用的 all-time 事实Honest group identity群组缺少头像时使用确定性的文字 monogram首字母徽标绝不用无关的装饰性渐变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 average2D 仍是默认贡献视图。六、视觉语言Visual language6.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-numsEmbed 侧对应FIGTREE_FONT_STACK与MONO_FONT_STACK两套字体栈以及cardTextStyle()注入的text{font-variant-numeric:tabular-nums}样式。6.3 间距、圆角、动效与图标4px 基准网格常用间距 8/12/16/20/24px应用画布最大 1500px响应式 16–32px 排水沟guttersServiceFooter的Inner正是max-width: 1500pxpadding: 20px 32px排名行目标高度桌面 56–64px移动端 76–92px 且信息完整圆角控件 8px、面板 12px仅徽章/头像使用全圆角深色应用表面用边框而非阴影动效状态变化即时生效仅按压控件允许 120–160ms transform遵循prefers-reduced-motionGroupsBrowser的骨架屏 shimmer 即用media (prefers-reduced-motion: reduce)关闭头像规范GitHub 头像 微弱的深色描边移动端 72px、桌面 80px排名强调色紧邻身份元数据复用现有 16px 应用图标禁止装饰性图标容器。七、组件体系Components7.1 复用与新增复用清单Navigation、档案组件、lib/utils的格式化器、共享图表面板色/设置、TabBar、现有 16px 图标与既有 server-fetching 模式。新增/变更清单组件实现共享紧凑应用外壳 ServiceFooterServiceFooter.tsx含 Leaderboard / Groups / Privacy / Terms / Contact 链接紧凑LeaderboardViewSelectorViewSelector.tsx/leaderboard/ViewSelector.tsx)聚合事实条aggregate fact stripMetricStrip/MetricItemRankingUI.tsxdl语义桌面 720px 横向、窄屏两列网格响应式全球排名行TableMobileRankingList/MobileRankingRowGroupDirectoryGroupsBrowser.tsx/leaderboard/GroupsBrowser.tsx)确定性群组标记GroupMarkgetGroupMonogram受限群组概览GroupDetailClientpackages/frontend/src/app/(main)/groups/[slug]/GroupDetailClient.tsx响应式群组排名行复用同一MobileRankingRow契约聚焦的创建/加入表单CreateGroupClient.tsx/groups/new/CreateGroupClient.tsx)变体与状态primary/secondary/ghost 动作active/inactive 导航与周期当前用户行与前三名行public/private/member/owner/admin 群组状态loading、empty、search-empty、error、pagination、copied-invite、submitting 状态桌面表格与移动排名列表两种构图。LeaderboardClient中当前用户行通过data-current-usertrue使用--service-accent-soft背景 2px 左侧强调线标识。7.2 图表契约Chart contract每个 provider/model 对渲染一个稳定的堆叠面积图。Provider 组及其模型按原始受限用量升序排列使主导带保持在顶部仅活动 tooltip 行按降序排序。使用 provider 级图例色、确定性模型色调、40% 填充、1px 单色边界且无图表动画。该契约是参考而非复制原则在图表上的落地目的是让排名主导的数据带稳定、不闪烁。7.3 贡献图契约Contribution contract渲染完整的请求 UTC 日期范围包括零值的外部天数outer days2D 强度与 3D 高度派生自同一个 token 受限日历提供紧凑视图与调色板选择器hover/focus 时显示视口钳制的每日 tooltip点击、触摸、Enter 或 Space 更新一个持久的 tokens/cost/client/model 明细默认显示可视范围末端跨视图与调色板切换保持不变两视图均保留漫游式键盘导航并输出简洁的屏幕阅读器摘要。该契约的几何核心在 embedShared.tsgetContributionWindow()把贡献事实限定在档案同款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模板信息层级定位Overview身份与三项 canonical 事实的平衡Token focustokens 占据主导字号Readout真正精简的等宽 key/value 视图Contributions日历成为主角Rank focus排名与百分位上下文居中Activity summary对比可测的一年活动信号Detailed stats最密集的两列事实表Compact list最窄的先扫列表账本并明确SVG 内不得出现模板名 overline、杜撰的系统标签或解释性标语。路由级实现见 packages/frontend/src/app/api/embed/[username]/svg/route.ts查询参数解析theme默认 dark、compact1/true、sorttokens/cost、periodall/month/week非法回退 all、graph、view2d/3d、template非法回退 classic、color、tokens/costcompact/full、rankplain/percent/total用户名先经isValidGitHubUsername校验非法返回 400 错误卡用户不存在返回错误卡大小写别名用 308 重定向到 canonical 用户名路径缓存策略revalidate 60响应头Cache-Control: public, max-age0, s-maxage60, stale-while-revalidate300并带X-Content-Type-Options: nosniff与严格 CSPdefault-src none; img-src data:; style-src unsafe-inline保证独立 SVG 输出与 CSP 兼容requiresContributions()决定哪些模板/组合必须取贡献数据graph、vitals、blueprint或showGraph且非 compact classic缺失时返回 503 错误卡各模板分发到独立的渲染器renderProfileEmbedSvgclassic、renderMinimalEmbedSvg、renderTerminalEmbedSvg、renderGraphEmbedSvg、renderOrbitEmbedSvg、renderVitalsEmbedSvg、renderBlueprintEmbedSvg、renderReceiptEmbedSvg3D 走renderIsometric3DEmbedSvg。数据层见 getUserEmbedStats.tsgetUserEmbedStats用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图组件不在本范围。八、可访问性AccessibilityWCAG 2.2 AA目标标准为WCAG 2.2 AA规则分为四组键盘/焦点可见焦点环排名目的地使用链接语义使用原生 button/input/select/checkboxview、period、sort、pagination、copy、membership 全部可键盘完成既有图表与 embed 焦点契约保持不变。对比/可读muted 文本对正常文本至少 4.5:1provider 颜色永远不是唯一的数据标签移动端正文字体 ≥16px。屏幕阅读器语义结构化标题事实用dl宽排名视图用真实 table 语义窄视图用等价的标记列表导航上用aria-current搜索与日期控件有标签异步结果用 status/alert 区域。实现证据MetricStrip是dlMobileRankingList是olGroupsBrowser的分页状态用rolestatus aria-livepolite、错误用rolealert、骨架屏aria-busytrue。减少动效与感官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状态规则Loading保留服务器渲染仅当引入加载行为时添加档案形状的路由骨架LeaderboardSkeleton已用于排行榜Empty保留身份与指标可见再说明尚未提交用量数据并在合适时引导档案主人执行 submit 命令Error保留既有路由级 not-found 行为交互式复制/分享失败走现有 toast 通道Success分享确认复制embed 动作保持现有确认行为Disabled原生控件暴露 disabled 语义并降低对比度但不至于不可读离线/慢网服务器渲染的档案内容保持可用导航会话富化可稍后到达而不移动主布局十一、内容语气Content voice语气简洁、事实化、面向开发者术语统一使用 tokens、cost、active days、submissions、providers、models、devices微文案规则控件/表头用 sentence case完整解释句加标点不用 emoji不得使用含糊图表标签例如只有最近一年每日行时不能写 all-time history。十二、实现约束Implementation constraints12.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共用图表与贡献图几何推导保持 memoizeduseMemo见 LeaderboardClient正常档案保留模型带高病理序列设上限并显式标注余量同一时刻只渲染一个贡献视图保留服务端数据获取与 ISRembed 路由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?viewgroups、有数据的公共/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【免费下载链接】tokscale️ Track token usage across AI coding agents from your terminal. Global leaderboard with trillions of tokens tracked.项目地址https://gitcode.com/gh_mirrors/to/tokscale点击查看免费下载相关推荐Skynet排行榜系统高效实时排名的设计与实现Skynet排行榜系统高效实时排名的设计与实现 1. 排行榜系统的技术痛点与解决方案 在大型多人在线游戏MMOG中排行榜Ranking System后端游戏开发OpenXR-SDK-Source核心组件解析Loader、Validation Layers与hello_xr示例OpenXR SDK Source核心组件解析Loader、Validation Layers与hello_xr示例 OpenXR SDK Source是KhTeleport 前端设计系统解析Gravitational Design System 的排版Typography规范与实践Teleport 前端设计系统解析Gravitational Design System 的排版Typography规范与实践 导读 本文以 Telepo网络安全认证鉴权运维后端上一篇Mongoose 自定义 Schema Type 开发指南从 Int8 示例到 cast 机制源码解析下一篇FastMCP 与 fastmcp-slim用 Pythonic 方式构建 MCP 服务器与客户端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考