Dashboard Craft

dashboard-craft

看板前端工程化开发规范。把"AI 辅助开发看板"从随机发挥，变成有约束、有门禁、可验证。

解决什么问题

AI 辅助开发看板时反复出现的三类事故：

1. 适配漂移 —— 开发时只看自己的显示器，交付到工厂电视、控制室大屏时 UI 变形、字号过小、图表模糊。
2. 风格断层 —— 第二期看板与第一期的配色、字号、图表样式不一致，因为设计决策靠每次现场发挥。
3. 拼凑实现 —— 功能能跑，但组件各写各的，越开发越乱。

根因不是"AI 不够强"，而是缺少约束层与门禁层。本规范用 8 个阶段解决，每个阶段都有明确的产出物与通过条件（Gate）。Gate 未通过，不进入下一阶段。

五条铁律

违背任一条，产出即视为不合格，必须回退。

1. 无约束不开发 —— 环境约束卡未填写完整，不得写第一行 UI 代码。
2. 无真源不写样式 —— 颜色、字号、间距、圆角、阴影、图表配色必须来自 design tokens，禁止页面内硬编码色值与魔法数字。硬编码包括：hex 色值（含 JSX 属性与内联样式里的字面量）、rgb()/hsl()、Tailwind 调色板原子类（bg-slate-900）、Tailwind 颜色关键字类（text-white）、任意值尺寸（text-[13px]）、内联样式数值。由 scripts/validate_tokens.py --fail-on-hardcode 机器判定，不接受口头声明。
3. 无矩阵不交付 —— 交付前必须跑完"分辨率 × 浏览器"验证矩阵，截图基线已存档。矩阵文件与基线路径由 scripts/check_gates.py 校验。
4. 一个概念一处实现 —— 同类组件与图表只有一个实现入口；禁止为赶进度另写一套。新增看板只允许新增配置与布局编排：图表与业务组件跨看板复用同一份实现，改一处应全部看板生效。（跨看板复用属人工确认项，见 references/05-components-charts.md）
5. 偏离必须登记 —— 任何对设计真源的偏离，都要写入页面级覆盖文件并说明理由，禁止静默偏离。

流程总览

阶段 1 与阶段 2 可并行；阶段 5 与阶段 6 每完成一个功能切片即可增量执行，不必等全部功能完成。

Gate 机器判定（不接受口头声明）

每个阶段的 Gate 必须由脚本判定，AI 不得自行声称"已通过"。检查对象是目标项目目录。

一键全查：python <skill>/scripts/check_gates.py --project .（<skill> 是本 skill 的安装目录）。

标准项目结构（Gate 检查据此定位文件，没按此结构组织时才需要 --tokens/--src 手动指定）：

design-system/
├── constraints-card.md      阶段 0 环境约束卡
├── MASTER.md                阶段 1 人读规范（必须含缩放策略、图表规范、目录结构）
├── design-tokens.json       阶段 1 机读真源
└── pages/<page>.md          页面级受限偏离
specs/*.md                   阶段 2 任务票（每票含验收标准）
acceptance-matrix.md         阶段 5 验收矩阵（含截图基线位置）
src/layouts|views|app        阶段 3 布局骨架入口
src/components + src/charts  阶段 4 组件与图表唯一入口
*report*.md                  阶段 6 性能/a11y/冒烟/视觉报告
README.md                    阶段 7 部署与回滚说明

参数与配置错误不算通过：--stage 只接受 0-7，传其他值直接报参数错误；显式 --src 指向的路径全部不存在时判失败——扫描没跑起来等于没检查，脚本不会拿"没有告警"冒充"通过"。

非标准目录约定也可行：若项目用 app/views、lib/ui、lib/charts 这类结构，在 MASTER 的「目录结构」小节登记真实路径即可通过阶段 3/4。登记必须按类别语义词对齐（骨架 / 组件 / 图表分别登记），登记一个不相关的目录不会放行整个结构 Gate。

汇报格式：每阶段结束时必须贴出脚本命令与其退出码。退出码非 0 即视为 Gate 未通过，不得进入下一阶段。

阶段执行要点

阶段 0 —— 约束锁定

先问清、再动手。必须落到纸面的是：

• 显示终端：工厂电视 / 控制室拼接屏 / 办公显示器 / 笔记本 / 移动端，各自型号与物理分辨率。
• 浏览器：目标浏览器及最低版本，是否包含国产内核浏览器（内核版本、是否缺 WebGL / 导出 / 字体特性）。
• 兼容目标与降级：Browserslist 查询串、是否需要 legacy 产物、DOM polyfill 清单。不因老设备就把源码退回 ES5，目标是声明兼容范围、由构建链按需降级（见 references/09-toolchain-landscape.md）。
• 缩放与 DPI：系统缩放（100% / 125% / 150%）、浏览器缩放、设备像素比。
• 观看距离与交互方式：是否只读展示、是否需要鼠标/触摸/遥控/键盘操作。
• 数据特性：刷新频率、单页数据点量级、是否 7×24 长时间运行。
• 网络环境：是否内网、带宽上限、是否允许外部 CDN（内网通常需本地化字体与依赖）。

模板见 assets/templates/constraints-card.md，方法见 references/01-constraints.md。

阶段 1 —— 设计单一真源

产出 design-system/MASTER.md 与 design-tokens.json：

• token 分层：基础值 → 语义值 → 组件值，上层只引用下层。
• 布局网格：栅格列数、间距刻度、断点定义（含 2560 / 3840 等大屏专用断点）。
• 图表规范：图表库唯一选型、色板顺序、坐标轴/图例/提示框统一样式、空数据与加载态。
• 主题：是否多主题、如何切换。
• 兼容目标：Browserslist 查询串与构建降级策略（若目标含老浏览器）。

大屏特有问题必须在此定死：字号随分辨率缩放策略（等比缩放 / 断点重排 / 混合）。这一条决定后期约 90% 的返工量。

「避免写死 px」与「整体 scale 缩放」是两条路线，不能同时主张：选 scale 就按固定设计稿写尺寸（px 必须来自 token 刻度），选重排就用 rem/clamp() 派生。不要把两句话混着说。

起点模板见 assets/templates/MASTER.md 与 assets/templates/design-tokens.example.json，方法见 references/02-design-system.md。

阶段 2 —— 规格与拆票

把设计真源转成可执行任务。每张票是纵向切片（贯穿数据 → 组件 → 验证），不是"先写完所有组件再写所有页面"。每张票必须写明交付的可验证行为、阻塞依赖、可勾选的验收标准。

方法见 references/03-spec-and-tickets.md。

阶段 3 —— 骨架先行

先搭不填肉的 Layout Shell：导航、内容区、栅格容器、卡片槽位、异常态占位。

关键动作：骨架必须在全部目标分辨率下先过一遍，确认不破版，再开始填充内容。这一步把适配问题从"交付前"提前到"第一天"。

方法见 references/04-shell-responsive.md。

阶段 4 —— 组件与图表

• 组件只从受限底座取用（统一组件库 + token），禁止页面内造样式。
• 图表只有一个封装入口：统一处理尺寸自适应、主题、空数据、加载、错误、销毁重建，以及 scale 方案下的 DPR 补偿。
• 看板即组合：第 N 个看板只新增配置与布局编排，复用既有图表与业务组件，禁止复制出第二份实现。
• 每个组件写完后，立即在最小与最大目标分辨率自检。

方法见 references/05-components-charts.md。

阶段 5 —— 适配验证

用固定视口矩阵截图并与基线比对：

• 视口矩阵覆盖阶段 0 列出的每个真实终端。
• 检查项：溢出、裁切、重叠、字体回退、意外滚动条、图表模糊。
• 基线入库，后续每次改动自动 diff。

模板见 assets/templates/acceptance-matrix.md，配置样例见 assets/templates/playwright.viewports.ts。

阶段 6 —— 质量门禁

• 性能预算：首屏时间、包体积、长时间运行内存曲线。
• 可访问性：对比度、焦点可见、键盘可达。
• 冒烟测试：核心数据链路可跑通。
• 视觉回归：无未登记差异。

四类结论都必须写进报告正文（文件名含 report/报告），check_gates.py --stage 6 会逐项检查；只写"性能"一项的报告不算通过。

方法见 references/06-verification-matrix.md。

阶段 7 —— 交付

交付包必须包含：源码、设计真源、截图基线、验证报告、部署与回滚说明、可复跑的回归资产。

方法见 references/07-delivery-handoff.md。

贯穿线：AI 协作规则

AI 是本流程的执行者，必须遵守输入规范与禁止项：

• 任务下达前的 prompt 模板（含必填约束字段）。
• 禁止项清单（禁止引入新图表库、禁止硬编码颜色、禁止跳过骨架直接开发页面等）。
• 变更影响面分析：改动共享组件或图表前，先列出受影响页面清单。
• 单一真源优先：样式冲突时以 token 为准，不以页面现状为准。

完整规则见 references/08-ai-collaboration.md。

工具链选型与更新

本规范绑定当前主流前端工具，不写死版本，通过 references/09-toolchain-landscape.md 维护"选型 + 更新机制"：

• 记录工具的角色、替代方案、更新频率。
• 用 scripts/refresh_toolchain.py 实时拉取最新版本，生成差异报告。
• 每季度复核一次，或在大版本发布时触发。

升级原则：小步升级、升级必回归、禁止在交付冲刺期做大版本跃迁。

参考文件索引