# 设计 ## 真相来源 - 状态：有效 - 最近更新：2026-09-11 - 主要产品界面：`examples/` 下的 `.ebox` 文件、`ebox-playground-open` 打开的缓冲区，以及通用文件模式。 - 已审阅证据：`ebox-playground.el`、`examples/` 下的 `.ebox` fixture、`tests/ebox-playground-tests.el`、`README.md`、`README.zh-CN.md` 以及画廊/参考文件的实际渲染。 ## Parallax 桌面示例 `examples/desktop-reference.ebox` 与同名 companion 单独演示直接操作，保留原有图层参考页。 深蓝工作台中有五个窗口：紫色 Studio、纸色 Notes、青色 Signal、薄荷色 Terminal、玫瑰色 Palette。各窗口有独立内容和局部层叠，全部使用当前字体大小；标题栏与底部窗口栏标出 活动窗口，不添加假的关闭按钮或自动动画。 亮色主题使用暖白外框、浅蓝灰工作区和五种浅色卡片，搭配深色正文。标题栏、窗口入口、 辅助文字、波形、嵌套图案与色板都单独适配，不能只把工作台背景换亮。配色表保留在 DSL 中，以语义 class 连接 companion 的公开 selector/region 更新，不使用全局样式表。 点击露出的标题、正文或底部窗口入口时整窗置顶；按住标题栏拖拽时即时发布位置，保留 鼠标抓取偏移，并应用松手的最终位置。横向按像素，纵向遵循文本行网格。中断保留最后 成功的位置，手势退出不留下 timer、advice 或全局键位。RET/SPC 激活，标题或窗口栏的 Alt+方向键移动窗口，RESET 恢复原始位置与次序。业务状态只在 Ebox 发布成功后提交， 每个预览独立。 LIGHT/DARK 在一次发布中切换完整配色，保留位置、层次和活动窗口；RESET 不改变主题。 新预览默认深色。Desktop 局部 minor mode 拦截背景、按钮间隙、换行和缓冲区末尾的原生 鼠标选区命令，保留按钮与标题栏自身的行为。卸载或切换成其他示例后移除该策略， 不修改 Emacs 的全局鼠标绑定。 结构为紧凑页头与工具栏、裁剪的主工作区、固定窗口栏和坐标状态；推荐至少 40 列、 20 行。较小尺寸保留窗口入口，RESET 可找回拖出边界的窗口。测试覆盖真实 keymap 命令、中间运动帧、松手、遮挡归属、失败回滚及独立渲染一致性。遵守不操作用户 GUI Emacs 的现有限制，批处理验证不等同于原生重绘延迟或截图验收。 ## 品牌 - 个性：精确、现代、克制、适合教学。 - 信任信号：像素对齐的分区、准确的 Grid 放置、明确的文字对比度、只使用公开 API，以及不依赖主题 face 也清晰的布局。 - 避免：没有样式的裸 fixture 文本、低对比度的浅色文字、随意的彩虹配色、过大的空白画布，以及私有诊断接口。 ## 产品目标 - 目标：用一个精致的独立示例演示 Ebox Grid 与组合能力，让底层包达到 Flex 参考示例的视觉质量标准。 - 非目标：ETAF Component、通用应用框架，或第二套 Playground 运行器。交互示例通过同名 companion 维护自己的小型状态。 - 成功信号：第一屏能清楚表达层级和 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/组件归属：配色值和示例组合放在 `.ebox` fixture 中；运行器读取唯一一个普通 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 膨胀。