etaf-playground/DESIGN.zh-CN.md

设计规范

事实来源

• 状态：生效中
• 最近更新：2026-08-05
• 主要产品界面：etaf-playground-open、etaf-playground-open-ui 与交互式应用 etaf-playground-open-showcase。
• 已审阅证据：etaf-playground.el、tests/etaf-playground-tests.el、中英文 README、当前 Showcase 的真实 GUI 渲染，以及 ../emacs-box/examples/playground/flex-reference.ebox 的全屏 GUI 渲染。

品牌

• 气质：精确、克制、现代、技术感强，并且明显经过设计，而不是通用框架默认外观。
• 可信信号：精确对齐、清晰对比度、更新时稳定的几何结构、一致的语义颜色，以及能够真实演示 ETAF 公共模型的例子。
• 避免：未加样式的默认 Emacs 文本、过度饱和的仪表盘颜色、浅色背景上的低对比文字、装饰噪音、无意义的大面积留白，以及与普通正文无法区分的控件。

产品目标

• 目标：通过精致、可运行的应用体现 ETAF 的能力；用可见结构讲清 View、Component、Context、Data、Grid、保留状态与事件；所有例子只使用公共 API。
• 非目标：模仿浏览器、使用位图装饰、另建样式框架、加入仅供示例使用的隐藏渲染路径，或假装当前较小的 etaf-ui 目录已经功能完整。
• 成功信号：首屏具有明确的应用结构；导航、数据和主题更新保持层级与几何稳定；截图中没有裁切、续行标记、意外换行或低对比文字。

用户与任务

• 主要用户：ETAF 应用作者、Ebox/ETAF 维护者，以及评估新架构是否可用的人。
• 用户任务：快速理解框架、复制公共 API 模式、检查真实交互流程，并确认更新后视觉结构稳定。
• 主要环境：GUI Emacs 单应用缓冲区、全屏演示，以及批处理/ERT 验证。

信息架构

• 主导航：固定的横向命令条，包含 Overview、Work items 与 Theme。
• 核心界面：Overview 仪表盘、交互式 Work items 表格、Theme and semantics 色彩页、紧凑的核心计数器例子，以及可选的 etaf-ui 组件目录例子。
• 内容层级：品牌应用标题、固定导航、页面标题与说明、主要卡片或表格、上下文操作区，以及安静的状态栏。

设计原则

• 原则一：通过可见分组教学；每项能力都放在有标题、有边界的区域中，而不是混成一串文本。
• 原则二：沿用 Flex 参考示例的暖色、克制配色与一像素边框，不依赖阴影或浏览器专有视觉效果。
• 原则三：几何正确性就是功能正确性；viewport owner 必须包含自身边框，子区域必须适配 owner 的内容盒，更新不得引入换行或截断标记。
• 取舍：优先采用适合桌面 Emacs 的紧凑构图，而不是过量留白；内部响应式容器省略宽度，让 Ebox Flex 分配和换行，避免脆弱的多层 viewport 算术。

视觉语言

• 颜色：暖白画布 #F8F5EE；纸张 #FFFDF8；正文 #252A2E；弱化文字 #66706A；激活陶土色 #B84F35；淡陶土色 #F1D4C9；鼠尾草绿 #DCEBDD；蓝色 #D9EAF2；紫色 #E7E2F1；暗色模式使用深中性色表面和同一组语义色的亮色版本。
• 字体：沿用 Emacs 配置的等宽字体；粗体只用于标题、标签、关键数值和激活控件。
• 间距：纵向以一行作为节奏；横向间距 12–16px；区块内边距 16–24px；卡片与表格边缘对齐。
• 形状与层级：方正的文本原生表面、一像素边框，不模拟圆角或阴影。
• 动效：状态直接发布，并在 redisplay 后保持稳定；不使用装饰动画。
• 图像与图标：只使用文字与克制的语义符号，不使用 logo、emoji 装饰或位图外框。

组件

• 复用能力：ETAF 核心 Hosts、保留式 Components、Grid、Context 主题值、Data Controller 与公共事件分发。
• 新增或调整：Showcase 区块标题、指标卡、导航项、任务行、操作按钮、色板、紧凑状态栏，以及核心/UI 例子的精致外壳。
• 状态：激活导航、选中任务、启用/禁用操作、亮色/暗色主题、success/review/open、loading、empty 与 error。
• 所有权：色彩 token 位于 etaf-playground--showcase-palette；各 helper 拥有自己的展示表面；ETAF/Ebox 继续拥有布局与渲染。

可访问性

• 目标：高对比、可用键盘操作的 Emacs UI，并保留明确的语义 role 与 ref。
• 键盘与焦点：所有可操作表面保留 :role 'button、:tab-index 0、稳定 ref，以及可见的激活/选中样式。
• 对比度：所有着色表面都有明确前景色；弱化文字在画布与纸张上都可读；激活控件同时使用颜色、边框或背景变化。
• 语义：框架支持时保留 label、role、ref 与 aria-label。
• 动效：不依赖动画，普通 redisplay 即可使用。

响应式行为

• 支持范围：约 900px 宽的 GUI Emacs 窗口到全屏桌面宽度；验证时还使用 777px 可用宽度作为更严格下限。
• 布局适配：宿主测量窗口正文，并在右侧预留一个字符单元；最外层 shell 拥有 viewport 宽度；直接的 header/main/status 区域在其中 stretch；嵌套响应式容器省略宽度，由 Ebox Flex 分配或换行。
• 触摸/悬停：不适用；键盘与鼠标 press 共用公共事件模型。

交互状态

• Loading：有标签、有边界，并显示明确状态。
• Empty：安静的解释区域；可用时给出下一步操作。
• Error：高对比 danger 区域；错误保持可见，不静默回退。
• Success：鼠尾草绿强调色与明确反馈文本。
• Disabled：弱化前景色，并移除回调与 tab stop。
• 离线/慢网络：当前不适用，因为示例使用同步内存数据源。

内容语气

• 风格：直接、技术化、简洁、自解释。
• 术语：统一使用 ETAF 词汇：View、Component、Host、Context、Data Controller、Runtime、event 与 public API。
• 文案规则：说清正在演示的能力和操作后的可见结果，避免宣传式填充文字。

实现约束

• 技术边界：Emacs 29.1+、ETAF 公共 View/Component API，以及 Ebox 公共布局/样式属性。
• Token：复用 palette helper 与语义 token key；不新建平行主题或 CSS 层。
• 性能：交互保持同步且有界；视觉改进不得增加隐藏的全树工作或除现有 viewport sync 外的新 timer。
• 兼容性：etaf-playground 必须独立于 ebox-playground，不得调用 ebox--* 私有 API。
• 验证：make check 通过；GUI 截图只显示一个目标缓冲区窗口；动态检查覆盖导航、选择、新增、主题切换与返回 Overview；不接受可见截断/续行标记或意外换行。

待解决问题

• 扩展官方 etaf-ui 目录后，才能把目录示例表述为完成迁移的组件画廊；维护者；阻止错误的功能对等声明。