35f8eb80ef
Replace the bare fixture with a 720 px three-section Grid and Flex reference, add paired design documentation, and lock the compact-window width contract.\n\nVerified with make check and a single-window GUI capture at a 784 px body width; rendered content stayed at 720 px.
83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
# 设计
|
||
|
||
## 真相来源
|
||
- 状态：有效
|
||
- 最近更新：2026-08-05
|
||
- 主要产品界面：`ebox-playground-open` 打开的缓冲区及其公开布局示例树。
|
||
- 已审阅证据：`ebox-playground.el`、`tests/ebox-playground-tests.el`、`README.md`、`README.zh-CN.md`、当前示例的实际渲染，以及在 GUI Emacs 中全屏渲染的 `../emacs-box/examples/playground/flex-reference.ebox`。
|
||
|
||
## 品牌
|
||
- 个性：精确、现代、克制、适合教学。
|
||
- 信任信号：像素对齐的分区、准确的 Grid 放置、明确的文字对比度、只使用公开 API，以及不依赖主题 face 也清晰的布局。
|
||
- 避免：没有样式的裸 fixture 文本、低对比度的浅色文字、随意的彩虹配色、过大的空白画布，以及私有诊断接口。
|
||
|
||
## 产品目标
|
||
- 目标：用一个精致的独立示例演示 Ebox Grid 与组合能力，让底层包达到 Flex 参考示例的视觉质量标准。
|
||
- 非目标：ETAF Component、应用状态、浏览器仿制品，或第二套 Playground 框架。
|
||
- 成功信号：第一屏能清楚表达层级和 Grid 行为；每个带色区块的文字都清晰可读；没有内容越过可见视口。
|
||
|
||
## 用户与任务
|
||
- 主要用户：Ebox 作者和维护者。
|
||
- 用户任务：打开一个缓冲区，理解公开节点契约，并直观看到固定/分数轨道、显式放置和组合渲染。
|
||
- 主要使用场景：GUI Emacs、全屏演示和 ERT 渲染检查。
|
||
|
||
## 信息架构
|
||
- 主导航：无；这是一个自包含的参考界面。
|
||
- 核心界面：一个标题区和三个能力分区。
|
||
- 内容层级：标题与说明、带编号的能力标题带、随后是小型对比示例。
|
||
|
||
## 设计原则
|
||
- 原则 1：延续 Flex 参考示例的“标题—解释—示例”节奏。
|
||
- 原则 2：每个能力分区只使用一组克制的语义强调色。
|
||
- 原则 3：示例只使用公开 API，并保持在一个源文件内即可理解的规模。
|
||
- 取舍：优先紧凑且有代表性的画廊，而不是穷举所有属性。
|
||
|
||
## 视觉语言
|
||
- 颜色：暖纸色画布，搭配陶土色、鼠尾草绿、灰蓝色和紫色分区；按对比度明确设置深色或白色文字。
|
||
- 字体：使用当前等宽字体，只在标题和短标签中加粗。
|
||
- 间距与布局节奏：一行垂直间隔、12 px 水平间隔、16–24 px 分区内边距。
|
||
- 形状/圆角/层级：方形一像素边框；不使用阴影或伪圆角。
|
||
- 动效：无。
|
||
- 图像与图标：纯文本。
|
||
|
||
## 组件
|
||
- 复用的现有组件：`ebox-create`、`ebox-column`、`ebox-row`、`ebox-flex`、`ebox-grid` 和 `ebox-spacer`。
|
||
- 新增/调整的组件：标题带、能力分区标题带、固定/分数轨道卡片、放置卡片和公开契约页脚。
|
||
- 变体与状态：仅使用静态语义色组。
|
||
- Token/组件归属：配色常量和示例组合保留在 `ebox-playground.el`；Ebox 负责渲染。
|
||
|
||
## 无障碍
|
||
- 目标标准：在常见 GUI Emacs 主题下保持高对比度和标签可读性。
|
||
- 键盘/焦点行为：该静态示例没有交互控件。
|
||
- 对比度/可读性：每个带色表面都显式设置前景色。
|
||
- 屏幕阅读语义：描述性纯文本保留在缓冲区中。
|
||
- 减少动态与感官刺激：无动态效果。
|
||
|
||
## 响应式行为
|
||
- 支持的断点/设备：正文宽度至少为 760 px 的 GUI Emacs 窗口，从紧凑窗口到全屏桌面。
|
||
- 布局适配：画廊统一拥有一个固定的 720 px 内容画布；嵌套 Grid 和 Flex 通过公开 Ebox 布局行为划分该宽度，而不是各自读取视口。
|
||
- 触控/悬停差异：无。
|
||
|
||
## 交互状态
|
||
- 加载：不适用。
|
||
- 空状态：不适用。
|
||
- 错误：公开 Ebox 错误正常向外暴露。
|
||
- 成功：完整渲染画廊本身就是成功状态。
|
||
- 禁用：不适用。
|
||
- 离线/慢网络：不适用。
|
||
|
||
## 内容语气
|
||
- 语气：简洁、事实明确、自解释。
|
||
- 术语：Ebox、节点、Grid、固定轨道、分数轨道、放置、公开 API。
|
||
- 微文案规则：用一句话说明每个可见分区证明了什么。
|
||
|
||
## 实现约束
|
||
- 框架/样式系统：Emacs 29.1+，只使用公开 Ebox 构造函数和属性。
|
||
- 设计 Token 约束：复用 Flex 参考示例的克制色系，不引入主题包。
|
||
- 性能约束：单次同步渲染，不使用定时器或后台任务。
|
||
- 兼容性约束：不依赖 ETAF，不调用 `ebox--*`。
|
||
- 测试/截图要求：`make check` 通过；单窗口 GUI 截图显示完整且未裁剪的标签分区。
|
||
|
||
## 开放问题
|
||
- [ ] 只有当每个新增示例都能讲清一种独立的公开 Ebox 责任时才继续扩展示例，避免 fixture 膨胀。
|