diff --git a/docs/specs/2026-09-20-sidebar-spacing-design.md b/docs/specs/2026-09-20-sidebar-spacing-design.md new file mode 100644 index 00000000..0b301651 --- /dev/null +++ b/docs/specs/2026-09-20-sidebar-spacing-design.md @@ -0,0 +1,584 @@ +# ACECode 左侧侧边栏间距调整设计方案 + +## 1. 背景与目标 + +ACECode 左侧侧边栏当前的问题不是单纯“整体太松”或“整体太紧”,而是纵向间距缺少稳定语义: + +- 分组标题上方留白较大,标题下方却因负 margin 显得拥挤; +- 同类任务行连续贴合,缺少稳定的扫描节奏; +- 工作区父行、子任务和下一工作区使用不同的间距规则; +- 局部负 margin 会让标题、工作区行和子任务行的布局范围发生重叠。 + +本次调整只重新定义侧边栏的纵向节奏,并允许轻微调整分组标题字号。必须保留现有信息结构、交互行为、左侧基线、右侧基线和列宽关系。 + +核心原则: + +> 只重新定义纵向关系,不重新设计横向网格。 + +## 2. 范围 + +### 2.1 包含 + +- 统一普通列表行之间的纵向间距; +- 统一分组之间的纵向间距; +- 移除侧边栏列表中的负 margin 重叠; +- 将分组标题调整为更紧凑的高度; +- 将分组标题字号从 11px token 调整为 12px token; +- 固化现有横向对齐规则,防止后续修改造成回归; +- 补充相应的结构测试和视觉验收。 + +### 2.2 不包含 + +- 不修改侧边栏宽度; +- 不修改 TopBar 与侧边栏的水平对应关系; +- 不改变任务、工作区、置顶任务或扩展的信息结构; +- 不删除会话左侧状态槽; +- 不隐藏会话时间; +- 不改变右侧时间列宽度; +- 不修改图标大小、操作按钮位置或折叠按钮显示逻辑; +- 不修改会话拖拽、工作区展开或数据加载行为; +- 不重构 Sidebar 数据流; +- 不编辑导出的 `ACECode.html` 或构建产物。 + +## 3. 不可破坏的横向对齐契约 + +以下数值是现有布局契约,不是本次可自由调整的参数。 + +### 3.1 树形行三列结构 + +会话行、工作区行、空状态行和“展开显示”行继续使用: + +```text +24px 图标/状态列 +7px 列间距 +minmax(0, 1fr) 标题列 +7px 列间距 +76px 右侧信息/操作列 +``` + +对应 class 必须继续保持: + +```jsx +grid-cols-[24px_minmax(0,1fr)_76px] +gap-x-[7px] +mx-1.5 +pl-[13px] +pr-2 +``` + +主要位置: + +- `SessionRow`; +- `WorkspaceGroup`; +- 工作区和无工作区空状态; +- 工作区和无工作区“展开显示”行。 + +禁止: + +- 将 `76px` 改为 `auto`; +- 修改 `gap-x-[7px]`; +- 删除 `mx-1.5`; +- 修改 `pl-[13px] pr-2`; +- 让标题跨列; +- 根据内容动态改变右侧列宽。 + +该契约保证: + +- 所有会话标题左对齐; +- 工作区名称与会话标题左对齐; +- “展开显示”与标题列左对齐; +- 时间、计数和操作按钮右对齐; +- 时间、状态、悬浮操作切换时标题不会水平跳动。 + +### 3.2 一级导航左侧基线 + +一级导航继续保持: + +```jsx +pl-[19px] +pr-3 +w-6 +gap-[7px] +justify-start +``` + +其文字起点保持为: + +```text +19px 左边距 + 24px 图标槽 + 7px gap = 50px +``` + +适用于: + +- `SidebarNavItem`; +- `CustomSidebarItem`; +- 扩展入口。 + +### 3.3 分组标题左侧基线 + +分组标题中的折叠图标槽继续保留: + +```jsx +pl-[19px] +w-6 +gap-[7px] +``` + +即使折叠图标默认透明,也不得删除这个槽位。它负责让“任务”“工作区”等分组标题与标题列共享既有基线。 + +### 3.4 右侧基线 + +以下元素继续使用固定的 76px 右侧列: + +- 会话时间; +- 权限请求状态; +- 等待回复状态; +- 工作区菜单和新建任务按钮区域; +- 扩展数量; +- 空状态对应的第三列。 + +右侧容器继续保持: + +```jsx +w-full +justify-end +``` + +不得为了缩小空白移除固定右侧列。 + +## 4. 目标纵向节奏 + +采用两档间距系统: + +| 关系 | 目标值 | +|---|---:| +| 普通行高度 | 32px | +| 同类行之间 | 2px | +| 分组标题高度 | 24px | +| 分组标题到首行 | 2px | +| 前一组到下一分组标题 | 8px | +| 展开工作区结束到下一工作区 | 8px | +| 品牌区 | 保持现状 | + +统一规则: + +```text +组内:2px +组间:8px +普通行:32px +标题行:24px +``` + +不再使用负 margin 表达层级关系。 + +## 5. 详细设计 + +### 5.1 品牌区 + +品牌区保持现状: + +```jsx +gap-[11px] +pl-[19px] +pr-[18px] +py-3 +``` + +Logo、品牌名称、版本号和品牌区总高度都不调整。 + +### 5.2 一级导航 + +以下项目继续使用 `h-8`: + +- 新建任务; +- 定时任务; +- 扩展; +- 扩展展开后的子项。 + +由列表父容器统一提供 2px 间隔: + +```jsx +