仪表盘布局系统

仪表盘布局系统 是做什么的？

目的

仪表盘布局系统为视口锁定、多面板的 Web 界面（通常称为应用外壳或工作区）提供了一套系统化的设计方法。与在单个滚动容器中无限向下滚动的标准文档式页面不同，仪表盘外壳将主视口高度锁定为精确的 100vh（或 100dvh），并将工作区分割为不同的功能区域。

系统化的方法可以解决常见的空间摩擦问题——例如“滚动中的滚动”锁定、视口橡皮筋效应、面板折叠过渡期间的布局偏移以及重叠的对话框焦点陷阱。它弥合了美学视觉设计与 CSS 容器技术之间的差距，从而形成一个连贯、高功能性且无障碍的工作区。

使用场景

• B2B SaaS 核心工作区： 需要同时查看侧边栏、筛选器、列表控件和内容详情面板的 Web 平台。
• 数据分析仪表盘： 高密度、多面板网格，在统一视图中呈现实时数据、指标、图表和控制侧边栏。
• 管理和运营面板： 需要固定操作标头和上下文详情抽屉以及大量数据网格的重型运营软件。
• 富内容编辑界面： 布局中包含可折叠的格式/属性侧边抽屉，位于中央画布或富文本工作区两侧（例如，CMS 编辑器、邮件生成器和设计画布工具）。

何时不使用

• 营销和落地页： 那些需要线性的、垂直滚动体验以优化故事讲述和行动号召的页面。请改用 hero-design-system 和 section-composition-system。
• 社论和博客文章： 读者期望标准的原生浏览器滚动和单一线性文本流。请改用 article-layout-system 和 table-of-contents-system。
• 电商产品列表页 (PLP)： 无限滚动或标准分页布局更适合持续的产品浏览。
• 简单的实用工具： 不需要多面板布局外壳的单一输入工具（例如简单的文件转换器或图像调整器）。

输入

1. 工作区面板清单： 应用所需的空间区域列表（例如，侧边栏导航、顶部操作栏、中央内容工作区、右侧属性抽屉）。
2. 交互控件布局： 可折叠面板、可调整大小的窗格和触发区域的技术规格。
3. 排版与间距令牌： 流体排版和相对间距系统（fluid-spacing-system 和 fluid-typography-system），以建立清晰的对齐网格。
4. 目标断点： 来自 responsive-grid-system 的设备布局定义，用于确定面板折叠、工具栏折叠和移动端抽屉过渡。

输出

1. 视口容器蓝图： HTML 和 CSS 网格/弹性盒子空间规范，将父容器尺寸锁定为 100dvh 并将滚动隔离到特定子容器。
2. 面板组合规范： 划分导航、实用标头和工作区的视觉定义、宽度约束和边框线。
3. 过渡与动效模型： 针对平滑、无偏移的可折叠面板过渡的硬件加速 CSS 动画指南（transform、opacity）。
4. 响应式折叠规则： 详述在桌面、平板和移动端视口范围内布局适配的技术规格。
5. 无障碍地标映射： 定义的 ARIA 角色区域和键盘导航流程参数。

工作流

1. 建立视口锁定和滚动容器

锁定主浏览器视口以防止整体页面滚动和橡皮筋效应。所有布局组件必须适合此刚性视口容器，并且滚动必须严格委托给隔离的内容面板：

• 将父容器（例如 .app-shell）设置为 width: 100vw 和 height: 100dvh（动态视口高度）及 overflow: hidden。
• 使用 2 层布局网格划分 .app-shell：
  • 第 1 层（外网格）： 将左侧边栏与右侧内容工作区分开。
  • 第 2 层（内网格）： 将工作区顶部栏/标头与滚动内容画布分开。
• 对于可滚动的面板，应用 overflow-y: auto 和 -webkit-overflow-scrolling: touch 以确保在移动端 Safari 上平滑的惯性滚动。

2. 定义面板视觉锚点和边框

使用清晰的视觉边界来组织高密度仪表盘，同时不增加视觉噪音：

• 边框分隔： 避免在相邻的持久面板之间使用重的阴影。相反，使用干净、低对比度的 1px 边框分隔线（例如 1px solid var(--border-neutral-muted)）来划分区域。
• 背景对比： 使用细微的背景色差来区分导航与活动内容。将导航侧边栏设置为稍暗或稍亮的色调（例如中性色调），而主内容工作区则使用干净的画布白色或深色表面。
• 滚动阴影： 对于滚动内容区域，在顶部和底部边缘边界处实现细微的线性渐变淡入叠加层，以向用户视觉提示还有更多内容在折叠区域之外。

3. 设计可折叠面板机制

可折叠面板（例如侧边栏或右侧详情抽屉）必须平滑地更改状态，而不会引入累积布局偏移 (CLS) 或视觉抖动：

• 避免宽度过渡： 动画化 CSS width 会迫使浏览器每帧重新计算所有子元素的布局，导致帧率低下。
• 优先使用变换： 将侧边抽屉绝对定位或移出画布边界，并使用 CSS transform: translateX() 结合硬件加速过渡来动画化其可见性。
• 内容遮罩： 在包含包装块上使用 overflow: hidden，以便滑动面板整齐地剪切在相邻视图后面。

4. 编写并移交无障碍地标

仪表盘布局模板必须为屏幕阅读器和键盘用户提供结构化的语义地标层级：

• 地标分配： 确保每个面板映射到适当的 HTML5 语义标签：
  • 全局导航侧边栏：<nav aria-label="主导航">
  • 工作区顶部栏/标头：<header>
  • 中央工作区：<main>
  • 属性/上下文抽屉：<aside aria-label="属性和元数据">
• 焦点管理： 当可折叠面板关闭时，以编程方式将焦点转移到关闭它的触发按钮。当移动端抽屉打开时，将键盘 Tab 焦点限制在该面板内。
• Inert 属性： 当模态面板或移动端侧边抽屉激活时，在中央主面板上切换 inert HTML 属性，防止键盘用户意外跳出可见的屏幕覆盖层。

5. 规划响应式适配（折叠规则）

优雅地跨不同设备缩放仪表盘工作区：

• 桌面范围 (>1200px)： 多面板布局完全展开。左侧导航侧边栏固定，工作区标头固定，中央画布自动滚动，右侧属性抽屉展开。
• 平板范围 (768px-1200px)： 将左侧导航侧边栏折叠为紧凑的“工具栏”（仅显示图标）。将右侧属性抽屉从持久的网格列转换，变为通过操作按钮触发的覆盖层。
• 移动端范围 (<768px)： 将侧边栏和属性抽屉都隐藏在覆盖层后面。主要布局简化为单列视图，由移动端顶部栏（包含汉堡菜单触发按钮和操作按钮）和独立的可滚动内容工作区组成。

决策规则

外壳结构使用网格 vs. 弹性盒子

方面	使用 CSS 网格	使用 CSS 弹性盒子
主轴	二维（行和列都是动态/固定的）。	一维（线性行堆栈或列堆栈）。
布局目的	外框结构（侧边栏列 + 主内容列）。	内部标头内容对齐（Logo 左 + 操作右）。
面板折叠	侧边栏列动态折叠到正好 0 宽度时。	子元素应该自然增长、收缩和换行时。

滚动管理：全局滚动 vs. 面板特定滚动

• 全局页面滚动（仪表盘中不要使用）： 导致整个标头、侧边栏和仪表盘框架从屏幕上滚走，迫使用户向上滚动以访问导航。
• 隔离的面板滚动（标准仪表盘模式）： 使外部框架（标头、工具栏、操作）完美锚定在屏幕边缘，而只有数据表格、图表馈送或文档编辑器在其视口单元格内独立滚动。

约束条件

• 动态视口高度： 外部父容器总是使用 dvh 单位 (100dvh) 而不是 vh (100vh)。在移动浏览器上，标准的 vh 单位不考虑浏览器 chrome（地址栏、导航控件）的展开/收缩，导致仪表盘底部被裁剪而无法触及。
• 焦点指示器： 确保交互式面板触发器上的焦点环高度可见。它们必须满足 WCAG 2.2 对比度规则，并且永远不会被 overflow: hidden 容器边缘裁剪。
• 无双重滚动条： 确保使用 CSS calc() 或 Flex/Grid 自动约束精确计算容器边距、内边距和高度边界，使滚动面板永远不会触发并排的嵌套双滚动条。
• 最小触摸目标： 可调整大小面板、侧边栏展开按钮和标签切换等处理程序必须提供至少 24x24px 的触摸目标（WCAG 2.2 SC 2.5.8），首选 44x44px。

常见失败模式

• 移动端地址栏裁剪： 在移动端使用 100vh，导致侧边栏底部的用户资料页脚或主要提交按钮隐藏在移动浏览器操作栏后面。
• 布局抖动： 在导航菜单上动画化 width 属性，导致主工作区内的卡片、图表和网格在折叠过渡期间快速跳动和重新渲染。
• 滚动陷阱 / 滚动泄漏： 未能在打开的覆盖层面板内隔离滚动事件，导致用户在移动导航抽屉上滑动时，主背景内容在其下方滚动。
• 未标记的滚动容器： 在页面容器上添加 overflow: auto 但没有附带角色或键盘焦点路径，这阻止了仅使用键盘的用户滚动该容器内的数据。
• 双重滚动条混乱： 创建没有严格高度限制的嵌套包装器，导致主浏览器窗口和内部容器都显示双重滚动条，造成导航混乱。

验证标准

• 外层布局容器高度锁定为 100dvh（或回退 100vh），主文档 overflow 设置为 hidden。
• 与滚动数据列表或工作区交互时，没有可见的双重滚动条。
• 在桌面、平板和移动端范围内定义了响应式状态，并具有适当的抽屉和工具栏变换。
• 滑动面板和侧边栏使用硬件加速 CSS 属性（transform: translateX()）进行动画。
• 工作区使用适当的语义 HTML5 地标（<nav>、<header>、<main>、<aside>）。
• 当覆盖层抽屉或面板在移动端打开时，背景元素设置为 inert 或从键盘焦点流程中隐藏。
• 面板触发器、切换按钮和手柄上的触摸目标满足最小尺寸要求 24x24px（首选 44px）。
• 在活动顶层覆盖层内滑动/滚动时，非活动背景面板元素不滚动（滚动泄漏预防）。