公共包与界面设计

Common

让共享界面保留清楚的任务、原生的交互。

Common 提供 EggyByte 产品共用的排版、品牌资产、原生控件与页面组合。偏好纯值、浏览器绑定、Svelte 适配和样式分别作为公开入口，调用方按需引入。共享呈现保持一致，产品继续决定内容、业务状态、权限与实际操作。

让同一项任务在不同页面保持一致 资源列表、表单和结果正文共用稳定的内容轴、原生控件与语言偏好。项目仍明确每一项事实和操作，用户切换语言或调整窗口后能够继续当前任务。

共享呈现，保留产品自己的决定

Common 的公共身份是 @eggybyte/common。它提供排版与间距、固定品牌资产、原生控件、页面框架和常见内容组合。项目提供有意义的文字、当前业务状态、可执行的操作以及实际导航目的地。

例如，资源行负责把名称、事实与操作放在一起；它不根据一个状态词推断权限，也不自行生成删除或重试。结果页先呈现结论与必要事实，再容纳产品真正提供的下一步。这样，视觉的一致性不会改变业务行为。

只需要计算语言或外观偏好时，使用 preferences 即可：输入输出是纯值，不操作浏览器。需要让页面跟随偏好变化时，再显式建立 browser 绑定；Svelte 组件适配同一个绑定，不另建偏好所有者。

应用根节点持有绑定，决定初始化时机并在离开时清理。styles.css 单独引入公共样式和本地字体，产品继续决定页面由哪些内容和操作组成。四个入口可以按需要选择，无需为了纯值解析引入浏览器或 Svelte。

共享呈现不接管路由、业务状态、权限与实际操作。

一个使用 Common 的页面先显式引入公共样式，再选择需要的程序入口。只计算偏好时保持纯值调用；需要同步文档时，由应用根部建立唯一 browser 绑定；Svelte 适配读取同一份绑定，不在各页面重复创建。

初始化应先于受语言影响的可见内容，文档语言与首屏文字保持一致。离开应用时由原持有者清理监听。业务页面提供自己的标题、导航位置、数据和操作；公共包不从展示文案推导路由，也不因为换语言而重新发起业务请求。

页面框架管理导航、主内容与跳转到正文的入口。内容区域保持稳定，文章的行长和短任务的控件宽度在局部决定。页面不会因为加载、提交或显示结果，就突然切换到另一种外层宽度。

资源集合在宽屏上并排展示事实，窄屏按同一个对象依次展开。名称、状态和操作保持关联，控件身份不因换行而替换。阅读内容采用连续标题、段落、列表和表格；只有真正共同执行的设置或选择，才需要一个明确的分组边界。

语言优先读取受支持的显式存储选择，再按浏览器语言次序寻找中文或英文，最终回退到中文。格式化语言只负责显示习惯，不能替产品选择金额精度或业务日期所用的时区。

偏好绑定同步应用当前文档的语言与外观，再向使用者公布状态。存储失败时保留内存中的选择；界面切换不重设业务状态、路由或尚未提交的输入。同一来源的应用可在初始化时读取相同键，不承诺跨来源共享或实时同步。

一个列表至少要区分正在读取、读取成功但为空和读取失败；提交操作还可能处于等待、明确拒绝或结果未知。Common 提供呈现这些区别的构件，具体状态与允许的下一步由业务返回，不把失败页面自动变成“重试”按钮。

已知事实与最新观察也要分开。刷新失败时可以保留上一次读到的有用内容，并明确它的观察范围；未知修改结果不能因重新打开页面就改成未发生。金额、数量、时区和精度遵循业务定义，语言切换只改变表达方式。

导航用链接，命令用按钮，互斥选项用原生单选。选择一个选项本身不触发业务提交；每个操作保留自己的说明、等待状态和真实目标。表单标签、帮助与错误信息关联到实际输入，图标在已有名称的控件内保持装饰性。

验证围绕完整任务展开：查找并操作资源、设置并提交、选择登录方式、理解结果与恢复。设计要求同时检查中英文宽窄布局、字体与品牌资产、键盘焦点，以及切换偏好后仍保留的输入和调用次数。图像评审与行为验证分别提供证据，不把几何检查当作完整视觉验收。

视觉检查使用真实长度的标题、正文、对象事实与反馈，让中文和英文分别经历宽屏与窄屏布局。应核对同一对象的名称、状态和操作是否仍在一起，正文是否保留连续阅读关系，完整值是否能换行且不迫使整页横向滚动。

行为检查则观察键盘焦点、原生控件关系、尚未提交的输入和实际调用次数。切换语言后内容可以重新排版，但草稿、目标与业务状态不能丢失。尺寸检查能发现越界，最终视觉判断仍需要实际查看完成页面。