dashboard-design

设计 Vizro 仪表板

结构化的需求 → 布局 → 可视化工作流。

工作流执行

按顺序执行步骤 1–3；每一步都依赖上一步。跟踪进度：

Dashboard Development Progress:
- [ ] Step 1: Understand Requirements (define end user, dashboard goals, document decisions)
- [ ] Step 2: Design Layout & Interactions (wireframes, filter placement)
- [ ] Step 3: Select Visualizations (chart types, KPIs; colors only if user asked)

交互方式：收集需求或做出设计决策时，请提出有针对性的问题，并提供 2–5 个编号选项，方便用户快速选择。优先使用客户端内置的多选或提问界面，让交互更轻便、易于点击；如果没有此类功能，则在纯文本中使用相同的编号格式。

不要跳过步骤。 按以下方式处理不完整的上下文：

• 用户有数据但没有需求 → 从步骤 1 开始
• 用户有需求但没有数据 → 索要数据或建议使用示例数据
• 用户有线框图 → 验证步骤 1 的决策，然后继续步骤 2
• 用户有视觉设计/样稿 → 验证步骤 1–2 的决策，然后继续步骤 3
• 用户要求“直接构建” → 解释这些步骤的价值，提出简化流程但不跳过步骤，并索要数据或建议使用示例数据

对于简单的仪表板（单页、少于 5 个图表）：可以简化步骤 1–3，但不能完全跳过。

---

规格文件：记录决策

重要：每一步都会在 spec/ 目录中生成一个规格文件，用于记录推理、促进协作，并支持在未来的会话中继续工作。请在项目开始时创建 spec/ 目录。

---

步骤 1：了解需求

目标：明确展示哪些信息，以及这些信息为何重要。

要讨论的关键问题

1. 用户：谁是该仪表板的最终用户？针对每种用户类型：他们需要做出哪些决策？需要完成什么任务/工作？
2. 目标：当前需要解决什么问题？该仪表板的目标是什么？
3. 数据：有哪些可用的数据源？刷新频率如何？
4. 结构：有多少个页面或视图？如何进行逻辑分组？

设计原则

• 限制 KPI 数量：每页展示 5–9 个主要指标（7 ± 2 规则）
• 层次清晰：概览 → 详情 → 细节（最多 3 层）
• 基于用户角色：不同用户可能需要不同的视图
• 聚焦决策：每个指标都应为决策提供依据

必需输出：spec/1_information_architecture.md

将模板从 assets/1_information_architecture.md 复制到项目根目录下的 spec/1_information_architecture.md，填写占位符，并在继续步骤 2 之前保存。

验证清单

继续步骤 2 之前：

• 每个页面都有明确且独特的用途
• KPI 可衡量且可执行
• 数据源可访问
• 用户已确认结构

详细指南：参见 information_architecture.md；反模式：参见 common_mistakes.md 中的“步骤 1：需求方面的常见错误”

---

步骤 2：设计布局与交互

目标：明确用户如何浏览和探索数据。

Vizro 导航架构

Tier 1: Global Navigation
├── Multi-page sidebar (automatic in Vizro)
└── Page selection

Tier 2: Page-level Controls
└── Filters/Parameters in left collapsible sidebar

Tier 3: Component-level
├── Container-specific filters/parameters
├── Cross-filter, cross-highlight interactions
└── Export actions

布局策略

加载 designing-vizro-layouts 技能，了解网格系统、组件尺寸、筛选器位置和选择器规则。为用户审批制作 ASCII 线框图时，请使用线框图模板。

交互设计

除了标准侧边栏筛选器，Vizro 还支持高级交互：点击图表或表格会影响其他组件。加载 wiring-vizro-actions 技能，了解 6 种命名交互模式（层级下钻、单页下钻、对比聚焦、多维切片、选择与探索、数据导出），其中包含线框图、规范条目和代码。

所有高级交互都遵循 源 → 控制项 → 目标：源组件（Graph 或 Table——能够携带点击数据的组件）设置一个中间控制项（Filter 或 Parameter，始终要显式指定 id），由它更新承载数据的目标组件（Graph、Table、Figure）。

决策流程——根据数据形态和用户需求匹配交互模式：

Hierarchy where detail needs its own page?    → Pattern 1 (Hierarchical Drill-Down)
Hierarchy where detail fits in a container?   → Pattern 2 (Single-Page Drill-Down)
Compare one entity vs many, keep context?     → Pattern 3 (Comparison Spotlight)
2+ categorical dimensions, click one cell?    → Pattern 4 (Multi-Dimensional Slice)
Users need to download data?                  → Pattern 5 (Data Export)
Otherwise → standard filters/parameters are sufficient

不应使用高级交互的情况：仅用于查看的仪表板或高管仪表板、简单的筛选需求（侧边栏下拉菜单即可满足）、分组少于约 5 个，或在单个页面上使用超过 2 种交互模式（会令人困惑）。

对于每种交互，请记录：源组件、源值（列或 "x"/"y"）、控制项 ID 和类型（Filter/Parameter）、目标组件、可见性（高亮模式使用 visible=False），以及是否跨页面（show_in_url=True）。完整模板请参阅 wiring-vizro-actions 技能。

必需输出：spec/2_interaction_ux.md

将 assets/2_interaction_ux.md 中的模板复制到项目根目录下的 spec/2_interaction_ux.md，填写占位符（包括每页一个 ASCII 线框图），并在继续执行步骤 3 之前保存。如果标准筛选器/参数已满足需求，请删除整个 ## Interactions 部分。

验证清单

继续执行步骤 3 之前：

• 布局符合 Vizro 约束
• 筛选器的放置经过有意规划并已记录
• 已向用户展示每个页面的 ASCII 线框图，并获得用户批准
• interactions: 中的每个条目都对应 wiring-vizro-actions 中的命名模式（或明确确认有意不使用交互）
• 用户已确认交互流程

反模式：请参阅 common_mistakes.md 中的“步骤 2：布局与交互误区”部分

---

步骤 3：选择可视化

目标：选择合适的图表类型，并确保视觉风格一致。

图表类型、颜色与 KPI

加载 selecting-vizro-charts 技能，了解图表选择、配色策略、反模式和 KPI 卡片规则。关键设计决策：

• 根据数据问题匹配图表类型（比较用条形图，趋势用折线图，饼图仅用于 2–5 个扇区）
• 颜色：规范中不要包含 ## Colors 部分。Vizro 会自动分配调色板。仅当用户在消息中明确要求自定义颜色时才添加。
• 使用内置的 kpi_card / kpi_card_reference；切勿将其重新实现为自定义图表

必需输出：spec/3_visual_design.md

将 assets/3_visual_design.md 中的模板复制到项目根目录下的 spec/3_visual_design.md，填写占位符，并在开始实现（dashboard-build 技能）之前保存。除非用户明确要求自定义颜色，否则不要添加 ## Colors 部分——Vizro 会自动分配调色板。

验证清单

开始实现（dashboard-build 技能）之前：

• 图表类型与数据类型匹配（时间序列不使用饼图）
• 未使用任何反模式
• 已识别自定义图表需求
• 除非用户明确要求自定义颜色，否则不包含 ## Colors 部分

反模式：请参阅 common_mistakes.md 中的“步骤 3：可视化误区”部分

参考文件

参考资料	加载时机
information_architecture.md	步骤 1：深入了解需求
designing-vizro-layouts 技能	步骤 2：网格系统、组件尺寸、筛选器
wireframe_templates.md	步骤 2：线框模板和交互标签
wiring-vizro-actions 技能	步骤 2：交叉筛选 / 交叉高亮 / 下钻 / 导出模式
selecting-vizro-charts 技能	步骤 3：图表类型、反模式
common_mistakes.md	所有步骤：需要避免的反模式