96 lines
5.4 KiB
Markdown
96 lines
5.4 KiB
Markdown
# 设计
|
||
|
||
## 来源与状态
|
||
|
||
- 状态：唯一 reviewed pair 的 active draft
|
||
- 更新日期：2026-08-20
|
||
- 主产品面：`examples/operations-console.etaf` + `examples/operations-console.el`
|
||
- 视觉参考：`design/operations-console.html`
|
||
- 已审查证据：pair loader/manifest、`etaf-ui.el`、Ebox viewport 合同及当前 GUI/性能证据。
|
||
|
||
## 品牌
|
||
|
||
- 气质：安静的操作控制台；准确、温暖、克制地体现技术感。
|
||
- 信任信号：状态 chip、更新时间、明确计数、清晰的成功/错误反馈。
|
||
- 避免：普通玩具 dashboard、彩虹渐变、无语义状态的装饰控件和杂乱控制区。
|
||
|
||
## 产品目标
|
||
|
||
- 用一个好看的 app 同时展示 Component、组合、响应式、Context/Theme、Behavior、事件/Action、Data、Resource、错误边界、焦点和生命周期。
|
||
- 不扩展第二个 Playground 场景，不伪装成完整生产分析产品，不用假动画掩盖框架问题。
|
||
- HTML 原型和 ETAF 实现保持同一层级、状态文字、交互结果和 compact/fullscreen 几何。
|
||
|
||
## 信息架构
|
||
|
||
- Shell：品牌/header → 导航 tabs → page surface → 持久 status footer。
|
||
- Overview：hero/status、KPI 卡片、活动/控制 workspace、能力卡片和事件时间线。
|
||
- Data：选择摘要、可交互 DataGrid、selection detail。
|
||
- Resource：资源状态、reload/fail-next、boundary 结果和 cleanup 计数。
|
||
- 层级：先显示页面标题和状态，再显示主操作，最后显示诊断/细节。
|
||
|
||
## 设计原则
|
||
|
||
1. 一个视觉层级：每个控件属于有名字的 surface，每个 surface 都有可见状态。
|
||
2. 状态优先于装饰：theme、loading、error、selected、disabled、success 都有文字表达。
|
||
3. 几何稳定：compact 下控件保持单行，页面只替换 page surface。
|
||
4. API 真实：HTML 可以用普通 HTML/JS，但 ETAF 只用公开 ETAF/ETAF-UI API。
|
||
|
||
## 视觉语言
|
||
|
||
- 色彩：墨蓝 `#142235`、纸张 `#F6F1E8`、灰蓝 `#526174`、青绿 `#2E8B83`、珊瑚 `#E26D5A`、琥珀 `#D99A3D`、成功绿 `#3E9B72`。
|
||
- 字体：易读 sans body，紧凑 monospace 指标/标签，粗体页面标题。
|
||
- 节奏：一行外部节奏、双列 workspace、固定 gap、shell 全宽，卡片有明确内边距。
|
||
- 形状：细深色边框、克制 elevation；ETAF 不依赖浮层。
|
||
- 动效：不以动画为正确性前提，状态变化即时且支持 reduced motion。
|
||
- 图形：只用文字标记和 Unicode 状态符号，不依赖外部资源。
|
||
|
||
## 组件
|
||
|
||
- 复用公开 `button`、`checkbox`、`label`、`panel`、`data-grid`。
|
||
- companion 组件：`operations-console-shell`、`hero-status`、`metric-strip`、`activity-card`、`capability-card`、`timeline`、`data-page`、`resource-page`。
|
||
- 状态：active/inactive nav、light/dark theme、selected/unselected row、Behavior on/off、resource ready/loading/error、boundary handled、compact/fullscreen。
|
||
- 所有权：`.etaf` 只放静态 composition 和 section 名称；`.el` 持有 token、props、refs、资源、handlers 和 state。
|
||
|
||
## 无障碍
|
||
|
||
- 目标：键盘完整、高对比文字，使用公开组件提供语义 role。
|
||
- Tab/Shift-Tab 遍历 nav/action/data rows；RET 派发 focused ref；移除目标时清焦点。
|
||
- 每个状态都有文字反馈，颜色不是唯一信号；不依赖 hover-only 行为。
|
||
- Ebox Theme 承载继承的 Ebox 默认属性；应用 palette 仍由 companion 查询，
|
||
Renderer 会在进入 Ebox 几何层前过滤未知 token 名。
|
||
|
||
## 响应式
|
||
|
||
- 支持 compact 900–940px body 和 fullscreen desktop GUI。
|
||
- metric 尽量一行展示，workspace 从双列退化为上下堆叠，控件保持 intrinsic 单行宽度。
|
||
- 需要分配剩余宽度的行使用 `flex`，固定 intrinsic 控件组才使用 `row`；导航
|
||
控件组使用 max-content，确保每个 hover/active 区域都是独立控件。
|
||
- mouse-1 和键盘激活使用同一组公开 refs。
|
||
|
||
## 交互状态
|
||
|
||
- Loading：Resource 显示 `Loading…`，shell 几何不移动。
|
||
- Empty：DataGrid 明确显示 empty，选择控件仍可用。
|
||
- Error：reload 可故意失败一次，Boundary 显示 handled error 且仍可恢复。
|
||
- Success：action/status 和 timestamp 可见更新。
|
||
- Disabled：不可用操作暴露 disabled 语义，不静默吞输入。
|
||
|
||
## 内容语气
|
||
|
||
- 简洁、操作化、解释性；标签明确指出正在展示的框架能力。
|
||
- 统一使用 `Component`、`Context`、`Theme`、`Behavior`、`Action`、`Data`、`Resource`、`Boundary`。
|
||
- 优先“动词 + 结果”（如 `Reload resource`、`Handled: …`、`Selected Beacon`）。
|
||
|
||
## 实现约束
|
||
|
||
- 使用 `.etaf`/`.el` 的公开 ETAF View DSL，由 Ebox 渲染，不引入 HTML/CSS runtime dependency。
|
||
- palette/spacing token 在 companion 单处定义并复用，禁止散落临时色值。
|
||
- 性能：普通 warm p50 <=100ms，counter/resource p50 <=150ms，每个 warm max <=250ms；每个逻辑动作一次 publication。
|
||
- 保留唯一同名 `operations-console` pair、静态安全读取、公开 API boundary、双 mount/unmount cleanup 和 manifest 语义。
|
||
- 导航：稳定的 page ref 由 retained router Component 读取；页面 Host 是唯一 semantic Range 锚点，页面切换只替换一个 Range payload，不重建 shell root。
|
||
- HTML 是视觉参考；ETAF 需要 compact/fullscreen 截图和动态键鼠 checkpoint 证明布局、宽度、焦点和状态。
|
||
|
||
## 待 review
|
||
|
||
- [ ] 用户可在第一版 HTML/ETAF 对照后调整 palette 或页面命名；行为和公开 ref 覆盖保持不变。
|