6cd5a67a35
Load same-basename Elisp companions through the generic preview runner. Demonstrate size semantics and native help, pointer, hover and keymap behavior with isolated example state. Update Flex and Grid examples and extend reusable comparison and interaction evaluators with publication, allocation and fresh-render parity checks. Validation: make check passed, including all 72 Playground tests.
5.3 KiB
5.3 KiB
设计
真相来源
- 状态：有效
- 最近更新：2026-09-08
- 主要产品界面：
examples/下的.ebox文件、ebox-playground-open打开的缓冲区，以及通用文件模式。 - 已审阅证据：
ebox-playground.el、examples/下的.eboxfixture、tests/ebox-playground-tests.el、README.md、README.zh-CN.md以及画廊/参考文件的实际渲染。
品牌
- 个性：精确、现代、克制、适合教学。
- 信任信号：像素对齐的分区、准确的 Grid 放置、明确的文字对比度、只使用公开 API，以及不依赖主题 face 也清晰的布局。
- 避免：没有样式的裸 fixture 文本、低对比度的浅色文字、随意的彩虹配色、过大的空白画布，以及私有诊断接口。
产品目标
- 目标：用一个精致的独立示例演示 Ebox Grid 与组合能力，让底层包达到 Flex 参考示例的视觉质量标准。
- 非目标：ETAF Component、应用状态、浏览器仿制品，或第二套 Playground 框架。
- 成功信号：第一屏能清楚表达层级和 Grid 行为；每个带色区块的文字都清晰可读；没有内容越过可见视口。
用户与任务
- 主要用户：Ebox 作者和维护者。
- 用户任务：打开一个缓冲区，理解公开节点契约，并直观看到固定/分数轨道、显式放置和组合渲染。
- 主要使用场景：GUI Emacs、全屏演示和 ERT 渲染检查。
信息架构
- 主导航：无；这是一个自包含的参考界面。
- 核心界面：一个标题区和三个能力分区。
- 内容层级：标题与说明、带编号的能力标题带、随后是小型对比示例。
设计原则
- 原则 1：延续 Flex 参考示例的“标题—解释—示例”节奏。
- 原则 2：每个能力分区只使用一组克制的语义强调色。
- 原则 3：运行器保持通用；每个具体布局都放在易读的
.ebox源文件中。 - 取舍：优先紧凑且有代表性的画廊，而不是穷举所有属性。
视觉语言
- 颜色：暖纸色画布，搭配陶土色、鼠尾草绿、灰蓝色和紫色分区；按对比度明确设置深色或白色文字。
- 字体：使用当前等宽字体，只在标题和短标签中加粗。
- 间距与布局节奏：一行垂直间隔、12 px 水平间隔、16–24 px 分区内边距。
- 形状/圆角/层级：方形一像素边框；不使用阴影或伪圆角。
- 动效：无。
- 图像与图标：纯文本。
组件
- 复用的作者 form：String、
text、box、row、column、flex和grid。空box直接表达间距，不再引入另一个公共 form。 - 新增/调整的组件：标题带、能力分区标题带、固定/分数轨道卡片、放置卡片和公开契约页脚。
- 变体与状态：仅使用静态语义色组。
- Token/组件归属：配色值和示例组合放在
.eboxfixture 中；运行器读取唯一一个普通 Elisp 表达式，以词法绑定求值，将结果作为 DSL 数据传给公开ebox-build并渲染。新增布局不需要在运行器中增加针对 fixture 的分支。 - 源文件契约：静态布局对整个列表加 quote；动态布局使用普通 Elisp 的
let、反引号、逗号和逗号展开。该表达式与.el中ebox-build的参数一致。运行器不再单独求值属性，也不自动识别旧的裸结构格式。 - 尺寸契约：使用 Ebox 的显式
(单位 数值)（px、%、vw、vh、ch、lh）和calc/min/max/clamp数据。裸fit-content是关键词，不是函数。尺寸解析和纵向行量化由 Ebox 负责，Playground 不增加单位解析器或另一套语义。
无障碍
- 目标标准：在常见 GUI Emacs 主题下保持高对比度和标签可读性。
- 键盘/焦点行为：该静态示例没有交互控件。
- 对比度/可读性：每个带色表面都显式设置前景色。
- 屏幕阅读语义：描述性纯文本保留在缓冲区中。
- 减少动态与感官刺激：无动态效果。
响应式行为
- 支持的断点/设备：正文宽度至少为 760 px 的 GUI Emacs 窗口，从紧凑窗口到全屏桌面。
- 布局适配：独立画廊默认使用 720 px 内容画布；分屏
.ebox预览将(vw 100)解析为预览窗格的显示安全宽度，将(vh 100)解析为正文区域高度，让视口相对区块适应预览窗格。 - 触控/悬停差异：无。
交互状态
- 加载：不适用。
- 空状态：不适用。
- 错误：公开 Ebox 错误正常向外暴露。
- 成功：完整渲染画廊本身就是成功状态。
- 禁用：不适用。
- 离线/慢网络：不适用。
内容语气
- 语气：简洁、事实明确、自解释。
- 术语：Ebox、节点、Grid、固定轨道、分数轨道、放置、公开 API。
- 微文案规则：用一句话说明每个可见分区证明了什么。
实现约束
- 框架/样式系统：Emacs 29.1+，只使用公开 Ebox 构造函数和属性。
- 设计 Token 约束：复用 Flex 参考示例的克制色系，不引入主题包。
- 性能约束：单次同步渲染，不使用定时器或后台任务。
- 兼容性约束：不依赖 ETAF，不调用
ebox--*。 - 测试/截图要求：
make check通过；单窗口 GUI 截图显示完整且未裁剪的标签分区。
开放问题
- 只有当每个新增
.ebox示例都能讲清一种独立的公开 Ebox 责任时才继续扩展，避免 fixture 膨胀。