etaf/DESIGN.zh-CN.md

设计规范

事实来源

• 状态：生效中
• 最近更新：2026-08-05
• 主要产品界面：examples/ 下的可执行应用，尤其是三个 etaf-*-example-open 命令打开的缓冲区。
• 已审阅证据：ETAF 公开源码与用户指南、core/Data/Resource 测试、../etaf-playground/DESIGN.md、精修后的 ETAF Showcase，以及原始 Ebox Flex 参考示例。

品牌

• 气质：精确、克制、现代、技术化，并且经过明确构图。
• 可信信号：稳定的几何结构、清晰的对比度、明确的状态所有权、只使用公开 API，以及可见的成功/错误/选择状态。
• 避免：裸 fixture 文本、低对比度浅色文字、装饰性 emoji、假浏览器外壳、无意义的大面积留白，以及与正文无法区分的控件。

产品目标

• 目标：通过小型可执行文件提供可复制的 ETAF core 最佳实践；证明已安装 Runtime 的真实交互路径；让视觉质量与 Flex 参考和 ETAF Showcase 保持一致。
• 非目标：替代 etaf-playground、假装缺失的 etaf-ui 目录已经存在、引入第二套主题系统，或在一个应用里展示全部公开符号。
• 成功信号：每个示例只讲清一个所有权边界；加载文件时不产生应用副作用；通过公开事件响应；正确清理资源；在紧凑 GUI 窗口中不裁切。

用户与任务

• 主要用户：ETAF 应用作者和框架维护者。
• 用户任务：复制正确的状态/Data/Resource 模式、检查真实挂载应用，并验证事件产生的可见结果。
• 主要环境：源码阅读、GUI Emacs 探索、自动化 ERT 和框架回归审查。

信息架构

• 主导航：不增加共享 launcher；每个文件拥有一个明确的 open 与 close 命令。
• 核心界面：保留式计数器、任务 Data Controller、Resource 健康状态。
• 内容层级：能力 eyebrow、应用标题与说明、主要状态区域、操作区、所有权规则页脚。

设计原则

• 原则一：一个示例只讲一个 lifecycle owner；避免用 mega-demo 隐藏状态与清理的归属。
• 原则二：写操作发生在 Event、Action、lifecycle、Data 或 Resource 边界；render 函数保持只读。
• 原则三：使用暖色、克制的语义色和一像素边框呈现结构，不增加设计系统依赖。
• 取舍：独立示例采用固定的紧凑教学画布；完整 viewport 响应式应用继续由 etaf-playground 展示。

视觉语言

• 颜色：暖色画布 #F8F5EE、纸张 #FFFDF8、正文 #252A2E、弱化正文 #66706A、陶土色 #F1D4C9、鼠尾草绿 #DCEBDD、蓝色 #D9EAF2 与紫色 #E7E2F1，始终搭配明确的深色文字。
• 字体：沿用 Emacs 当前等宽字体；粗体只用于标题、操作、状态和关键数值。
• 间距：一行纵向间隔、10–12 px 水平间隔、12–18 px 表面内边距。
• 形状与层级：方正的文本原生区块和一像素边框；不使用阴影或伪圆角。
• 动效：无；同步 commit 后几何结构必须稳定。
• 图像与图标：只使用文本和选择圆点等克制语义标记。

组件

• 复用能力：core Host、保留式 Component、ref、computed、Action、focusable Behavior、Data Controller、Resource 与 Runtime lifecycle callback。
• 新增或调整：示例专用 shell、metric、action、row、status 与 footer Component/Host。
• 状态：ready/active 计数器、selected/unselected 任务、open/done 筛选、idle/loading/success/error Resource。
• 所有权：每个示例拥有自己的小型静态配色和组合；ETAF/Ebox 拥有语义、布局和渲染。

可访问性

• 目标：高对比、可通过键盘寻址的文本 UI。
• 键盘与焦点：每个操作都具有稳定 ref、button role 和 etaf-focusable Behavior。
• 对比度：着色表面始终显式设置前景色；状态同时使用文字和颜色表达。
• 语义：保留文字标签和语义 role，不只用装饰表达含义。
• 动效：不使用动画或闪烁状态。

响应式行为

• 支持范围：正文宽度约 760 px 及以上的 GUI Emacs。
• 布局适配：示例使用 680–720 px 教学画布；操作组使用可换行 Flex；完整 viewport 响应式模式留在 etaf-playground。
• 触控/悬停：无；交互使用 Runtime event 边界。

交互状态

• Loading：明确显示 Resource/Data 状态，不伪造 fallback。
• Empty：有边界的解释行，不填充隐藏的占位数据。
• Error：高对比、持续可见的错误文案，直到下一次操作。
• Success：鼠尾草绿表面和明确状态文字。
• Disabled：移除 event/tab stop，不展示误导性的可用控件。
• 离线/慢网络：同步 core 示例不适用。

内容语气

• 风格：直接、技术化、简洁、适合教学。
• 术语：统一使用 View、Component、Host、Runtime、Data Controller、Resource、Event、Action、Scope 与 public API。
• 文案规则：点明展示的所有权边界与可见操作效果，避免宣传式填充文字。

实现约束

• 技术边界：Emacs 29.1+、公开 etaf facade，以及通过 ETAF Host 下沉的公开 Ebox 属性。
• Token：直接复用既有暖色配色；不为三个示例增加 token 框架。
• 性能：只使用同步、有界数据；不使用 timer、后台工作或隐藏的重复 mount。
• 兼容性：core 示例不得依赖 etaf-ui、etaf-sqlite、etaf-playground，也不得调用私有 etaf--* / ebox--* API。
• 验证：make check 会编译示例并驱动已挂载的公开事件路径；GUI 验证只使用一个目标缓冲区窗口，并拒绝裁切或续行标记。

待解决问题

• 只有 ETAF 定义公开异步完成契约后才增加异步 Resource 示例；维护者；避免教授臆造 API。