组件规范

把基础规范落到具体控件上：每个组件长什么样、有哪些状态、多大。这里是 packages/ui 的设计输入。清单里的控件已经全部实现，各期清单里逐项写了做到哪一步；最后一期是后来补的、最初的清单里没有的控件。

怎么读#

每篇的结构：用途 → 图解 → 规格表 → 状态 → 行为与无障碍 → 宜 / 忌 → 来源。

规格表里的数值分两种：

• 颜色与状态变化多数是实测（官网）或社区（游戏界面）；
• 尺寸是把官网的流式 rem 换算到 16px 基准后的建议值，实现时可以微调。

通用约定#

尺寸#

三档，全库统一：

官网通用按钮是 4.5rem 高，在 1920 稿上是 54px、在 1440 视口上约 40px，所以 md 取 40、lg 取 56。

触屏上任何可点击元素的点击区域不小于 40 × 40px。

状态#

每个交互组件按需实现：

命名#

• 变体用语义名：action、control、light、danger。不用颜色名。
• 尺寸用 sm / md / lg。
• 形状是变体的一部分，不单独暴露成属性：不提供 rounded、cut 这类让使用者随意组合的开关。
• 色调用 tone：neutral、info、success、warning、danger。

主题#

所有组件只使用 theme.css 里的语义令牌（surface、ink、line、action、control…），因此自动适配亮 / 暗主题与主题色接管。组件内不出现十六进制色值。

几条实现时定下的细则：

• 随主题翻转的颜色一律用语义令牌。 只有"本来就是为某一种底色设计"的填充才直接用 neutral-*、在两个主题下保持不变，清单见 色彩 的"哪些颜色有意不随主题变"。
• 压在反转块上的强调记号用 accent-ink-inverse，不直接用 action。 surface-inverse 在暗色主题下是近白，黄色压在上面看不见。已选的复选与单选、开启的开关、反转图标钮的图标都是这一条。
• 反转块里还要放别的控件时，把它做成反转主题（data-theme="inverse"），里面照常用 surface、ink、accent-ink。面板的标题带、表格的表头带、完成横幅都是。见 色彩。
• 压在页面表面上的强调记号用 accent-ink。 行动色在亮色表面上同样看不见（必填标记）。
• 悬停底用 bg-ink/5，不用 surface-sunken。 后者在暗色主题下是纯黑，悬停会变暗而选中变亮，方向相反（页签、列表行）。

链接与路由#

能当链接用的控件（按钮、列表行、媒体卡、物品格、面包屑项、菜单项、展开条的项，以及侧轨项、全屏菜单项、主行动块）有两种写法：

<Button render={<Link to="/archive" />}>查看档案</Button>

• 控件算好的类名、状态属性（aria-current、data-variant…）和事件会合并到那个元素上：类名拼在一起，事件两边都触发，其余属性以那个元素自己写的为准。
• 传了 render 就按链接处理，哪怕没有 href——地址在那个元素自己手里。
• 这个写法和浮层的触发元素是同一个（都是 Base UI 的 render），所以库里没有 asChild。
• 禁用时有一处差别。 href 形态下，禁用的链接被去掉地址，焦点也到不了它。render 形态下地址去不掉，所以它仍然能被聚焦；控件给它标上 aria-disabled 并拦下点击（路由库的链接组件看到点击被拦下就不会跳转）。

无障碍#

• 用原生元素（button、a、input）；浮层这类原生元素做不好的，用无障碍基元 Base UI。
• 纯图标控件必须有可访问名称。
• 状态不只靠颜色表达。
• 装饰元素（竖条、括号、纹理、巨字）对辅助技术隐藏。
• 动效遵守"减少动态效果"。
• clip-path 切角不能裁掉焦点环，做法见 切角与斜楔。

组件清单与建议顺序#

按"先把语言立住，再铺开"的顺序。每一期做完都应该能搭出一类完整的页面。

第一期：立住语言（已实现）#

能搭出一个官网气质的内容页。源码在 packages/ui/src/components，在仓库根目录 pnpm dev 可以在 Storybook 里并排看亮暗两套。

这一期当时没做、后来补上的：按钮组、列表行、媒体卡、物品格、胶囊族的筛选 / 资源 / 倒计时徽章、增益签、日期块的小红角、页签的 wedge 变体。

第二期：表单与反馈#

能搭出设置页、表单页、列表页。在 Storybook 的"示例 / 设置页"和"示例 / 列表页"里可以看到用它们搭出来的页面。

Select 的面板和 Toast 的容器都是浮层，需要定位与焦点管理，和第三期的浮层共用同一套无障碍基元（Base UI）。

第三期：浮层与导航#

能搭出完整的应用外壳。在 Storybook 的"示例 / 调度台"里可以看到：宽屏是侧轨，窄屏换成顶栏和全屏菜单。

第四期：数据与游戏风格#

能搭出工具站、数据面板、游戏风格的界面。

第五期：母题组件（已实现）#

把 母题 做成可复用的装饰组件：

切角、斜楔、角括号、镂空字、斜纹、警示条纹、三种底纹同时是 utilities.css 里的工具类；切角与斜楔只有工具类，没有组件——"形状是变体的一部分"，谁能切角由控件自己决定（目前是楔形页签和物品格的 NEW 签）。

这些放在最后，是因为它们最容易被滥用。先有扎实的基础组件，再提供装饰。

第六期：清单之外补的（已实现）#

前五期做完之后补的。它们在最初的清单里没有——有的是官网上看得到、当时没列进来的（头像切换、媒体轮播、排期、播放钮），有的是搭真实页面时发现缺的。每一个都是先在对应的文档里写了规格、标了来源等级，再做的。表里从播放钮往下的五行是第二批；从行展开往下的五行是第三批——官网上没有它们的原型，是从库里已有的画法延伸出来的，每一行写了借的是哪一处；最后五行是第四批，同样是延伸出来的。

不做什么#

• 不做"万能卡片"。 这套语言里的层次靠底色和线，不靠卡片嵌套。
• 不提供发光、玻璃拟态、霓虹描边的变体。
• 不内置官方素材：图标、Logo、立绘、字体都不进库。唯一的例外是单独成一类的 Game 实机风格：它走独立入口，带着官方图片，这一页的约定不适用于它。
• 不做滚动劫持和整页缩放。 那是展示站的手法，由使用方在页面层决定。
• 不把游戏术语写进组件名。 叫 ItemSlot 不叫 OperatorCard；业务组件由使用方组合。

参照#

社区组件库 ReEnd-Components 已经实现了 75 个以上的组件，它的清单是很好的查漏依据。和它的主要差异：