静态报告设计系统，不是网页组件库的翻版

很多团队一说“设计系统”，第一反应就是颜色、字号、按钮、卡片和组件库。

但如果目标是用 HTML 生成研究报告、白皮书、方案书、年度总结或数据快报，这样的理解是不够的。

静态报告面对的根本问题，不是界面交互，而是版式、阅读路径、分页稳定性，以及最终导出成 PDF 之后的成品质量。

所以，这类系统本质上不是普通的网页设计系统，而更接近一套：

报告排版系统 + HTML 组件库 + PDF 输出规范

如果只定义视觉变量和若干组件，做出来的内容大概率仍然像网页截图。只有把页面结构、内容语法、图表表格规则和分页约束一起纳入，报告才会真正呈现出专业感。

一、先把问题定义对

普通网站更关心响应式布局、交互反馈和页面跳转，静态报告则更关心另一组问题：

• 页面尺寸是否稳定
• 版心是否统一
• 章节是否有固定节奏
• 图表和表格是否清晰可信
• 长内容跨页后是否还能保持可读性
• 导出的 PDF 是否仍然符合设计意图

也就是说，报告设计系统最核心的目标，不是“把页面做漂亮”，而是把一份文档从头到尾组织得稳定、可控、可复用。

二、一套完整系统，至少要有六层

1. 文档级配置

在开始设计组件之前，应该先把整份报告的全局开关定下来。比如纸张是 A4 还是 Letter，横向还是纵向；输出是面向屏幕阅读还是面向打印；整体节奏是紧凑、标准还是舒展；使用中文、英文还是双语；目录展示到几级标题；页眉页脚显示什么；图表是彩色版还是打印友好版；是否需要保密水印，以及参考文献采用什么格式。

这些看起来不像传统意义上的设计变量，但它们决定了整份报告的气质、结构和边界。

2. 设计变量

报告系统当然需要一套设计变量，但不能只停留在颜色和字号。更合理的做法，是把变量分成三层维护：

• 基础值：色板、字体、字重、字号、行高、间距、圆角、边框、阴影
• 语义变量：正文主色、次级文字、页面底色、表头背景这类可迁移命名
• 组件级和页面级变量：页边距、页眉高度、章节间距、封面标题最大宽度、表格单元格留白等

如果再往下细分，这套变量至少还要覆盖几类常被忽略的信息：

• 品牌识别：主辅色、强调色、标志尺寸、安全留白、水印透明度
• 报告专用色：封面底色、章节分隔色、目录引导线、表头底色、图框底色、来源文字色
• 图表专用色和打印友好色
• 文字节奏：段前段后距、列表项间距、最大行宽、数字等宽对齐
• 页面版式：页面宽高、上下内外边距、不同版心宽度、栅格列数、侧栏宽度、安全区
• 组件专用变量：封面、目录、提示块、表格、指标卡、引文、图表

对静态报告来说，真正拉开品质差距的，往往不是颜色本身，而是版心、留白、密度和节奏。

3. 页面系统

报告不是无限滚动的网页，而是一页一页被阅读的文档。因此，页面系统是整个设计系统里最容易被忽视、但又最关键的一层。

这里至少要把这些规则说清楚：

• 页面尺寸、版心宽度、单栏或双栏规则
• 栅格、页边距、安全区、页眉页脚区域
• 章节是否另起一页
• 标题能否落在页尾
• 表格和图表能否跨页
• 附录长表如何分页

网页里常见的交互状态在这个场景里并不重要，真正重要的是页级排版是否稳定。对报告而言，分页规则的重要性通常高于响应式断点。

4. 组件系统

在报告场景里，组件的任务不只是“复用样式”，而是固定表达结构。

例如：

• 文档骨架组件：封面、目录、章节起始、页眉页脚
• 内容表达组件：摘要、结论提示、定义说明、脚注、来源说明
• 数据组件：指标卡、表格、图表容器、时间线、流程图
• 媒体组件：图片区、图注、标志墙

每个组件都应该说明：

• 用途和适用场景
• 组成结构和可插内容位
• 变体和长度限制
• 上下文间距
• 分页行为
• 明确禁止的用法

以表格为例，如果只定义边框和配色，那只是样式片段，不是报告组件。真正的表格组件还要规定表头是否重复、数字列如何对齐、超长文本如何换行、跨页时如何处理、表下注释和来源如何呈现。

图表也不要停留在“有个图表组件”这种泛化说法上。至少应明确支持的模板族，例如条形图、柱状图、堆叠图、折线图、面积图、组合图、散点图、气泡图、瀑布图、热力图、斜率图、漏斗图。环形图应限制使用，矩形树图和桑基图更适合放在可选层，而不是默认主力图型。

5. 页面模板和组合模式

很多团队组件并不少，但每做一份报告还是像重新拼版，原因往往不是组件不够，而是缺少更高层的页面模板和组合模式。

页面类型最好按四组管理：

• 前置页：封面、内封、出版信息、法务页、保密声明、版本信息、目录、图表目录、表格目录
• 正文页：标准正文、核心发现、指标快照、单图分析、多图对比、表格分析、对比推荐、方法论、案例、地图分析
• 后置页：附录起始、附录数据、术语表、缩写表、参考文献、尾注、致谢、联系方式
• 工具页：空白页、故意留白页、横版插页、索引页

在页面类型之外，还要定义稳定的组合模式。模块级至少可以有：

• cover.hero
• summary.strip
• insight.chart
• insight.table
• analysis.split
• compare.recommend
• kpi.snapshot
• quote.break
• figure.spotlight
• method.standard
• timeline.story
• process.explain
• case.study
• appendix.data
• references.standard

再往上，页面级和报告级还可以进一步形成白皮书、研究报告、数据包和方案书这类稳定骨架。

6. 内容规范、图表规则、工程规范与输出验收

报告的专业感，很大程度上来自表达纪律，而不是装饰技巧。

这一层内部至少应再拆成四套规则：

• 内容规范：标题层级、摘要写法、导语长度、数字日期单位格式、图题表题来源格式、参考文献口径
• 分页规范：哪些组件不可拆页、哪些允许跨页、标题是否要和下一段绑定、表格跨页是否重复表头、图表和图注是否必须同页、附录长表如何分页、孤行和寡行如何规避
• 图表规范：图型白名单、限制使用图型、强调数据的方式、基准线和目标线的呈现方式、小数位和单位规则，以及图例、注释、来源的位置
• 治理规范：这套系统由谁拥有、新组件如何申请和评审、变量如何变更、版本如何演进、废弃组件如何迁移、最佳实践怎么沉淀、常见错误如何记录

这一层还应包含视觉语言规范，例如色彩使用比例、留白原则、分割线粗细、卡片是否需要阴影、图标风格、插图和照片是否允许使用蒙版或渐变，以及哪些效果应被明确禁用。报告的高级感通常来自克制，而不是堆效果。

三、如果技术栈是 Astro + Tailwind v4，应该怎么落地

这类技术栈很适合做静态报告系统，但前提是分层要清楚。

真正会转成 Tailwind utility 的变量应进入 @theme，例如颜色、字体、字号、间距、圆角和阴影；而 A4 尺寸、页边距、页眉高度、版心宽度这类页面度量值，更适合放成普通 CSS 变量。

如果按工程目录来组织，更稳的方式通常是把 src/design-system 分成几层：

• tokens：基础、语义、组件和页面变量
• styles：全局基础样式、自定义工具类和打印样式
• primitives：页面框架、栈、簇、文本等低阶积木
• components：文档、内容和数据展示组件
• patterns：组合模块
• templates：整页或整份报告模板
• registry：预览站所需的注册表

内容说明文档可以放在 src/content/ds，布局放在 layouts，预览页和纯画布页放在 pages/preview，测试则拆成视觉回归和单元测试。

这里还有几个很关键的工程判断：

1. 如果预览页想把所有变量都稳定展示出来，构建时最好显式使用 @theme static。
2. 预览文档、MDX 示例和拆出去的组件包如果不在默认扫描范围内，要显式通过 @source 纳入扫描。
3. 不要在运行时拼动态类名，否则 Tailwind 根本不会生成对应样式。

关于仓库形态，也可以用一个简单标准判断：如果这套系统只在一个 Astro 项目里服务一类报告，单仓目录通常就足够；如果后续会给多个报告生成器、官网材料系统或自动化 PDF 服务复用，就应该更早把设计系统抽成独立包，把预览站作为单独应用维护。

四、预览系统不该只是一个总览页

如果这套系统是给静态报告服务的，那么预览环境也应该围绕报告生产来设计，而不是只做一个“组件大杂烩”页面。

更合理的做法，是建设一个独立的 /preview 工作台，并至少拆成四类页面：

• 变量预览页
• 组件预览页
• 组合模式预览页
• 模板预览页

与之配套，还要有一套 canvas 纯画布路由，用于无侧栏、固定尺寸的干净渲染，以方便视觉回归、截图和打印测试。

每个预览页也最好固定为四个区域：

1. 说明区：用途、适用场景、内容边界、分页行为
2. 控制区：主题、品牌、语言、密度、纸张、screen/print 模式
3. 画布区：真实渲染结果
4. 契约区：props、slots、变体、依赖变量、示例数据和代码片段

由于目标是 PDF，预览模式还必须专门覆盖报告场景，而不是只模拟普通网页。至少要能切换 A4 纵向和横向、screen 和 print、页眉页脚开关、版心和页边距辅助线，并能针对封面、目录、长表和附录做跨页检查。

模板层应该明确使用分页工具类，例如 break-before-page、break-after-page、break-inside-avoid-page，而不是把分页质量交给 PDF 引擎碰运气。

五、最稳妥的做法，是三层约束一起上

很多团队会纠结：规则到底应该写进组件库，还是留到最后组装 HTML 时再处理？

更稳妥的答案不是二选一，而是三层配合。

第一层：在组件库里前置硬约束

能在样式和结构层解决的问题，就不要拖到后面。

例如：

• 设计变量
• 组件属性
• 页面模板
• 数字和日期格式化函数
• 图表类型白名单
• “尽量不拆页”“标题跟随下一段”这一类分页意图

像图必须有标题、说明和来源，表格必须输出语义化表头，提示块默认尽量不拆页，这些都应属于第一层能解决的事情。

第二层：在文档组装层做结构约束

这里处理的是跨组件、跨页面的问题，例如标题层级关系是否合理，某类页面允许使用哪些模块，报告章节顺序是否完整，摘要和导语的数据结构是否符合要求，图表类型和页面意图是否匹配。

因此，第二层通常会自然长出这些东西：

• content schema
• composition rules
• chart rules
• validators

它们负责检查整份文档的结构合法性，而不是局部组件的样式是否正确。

第三层：在最终渲染后做版面验收

凡是依赖真实版面结果的问题，都不能只靠“规则已经写了”来判断是否成立。

比如：

• 页面正文是否过密
• 标题是否真的和下一段留在同页
• 图表和图注是否真的同页
• 长表跨页是否合理
• 表头是否在跨页后正确重复
• 附录长表是否拆分得当
• 孤行寡行是否被有效规避

这里还要强调一个现实边界：CSS 能表达很多分页意图，例如 @page、break-before-page、break-after-page、break-inside-avoid-page，也可以对段落设置 widows 和 orphans，但这些能力并不意味着最终版面一定完美可控。尤其是 widows 和 orphans 这类规则，本身就受实现兼容性影响，因此只能作为尽力而为的辅助，不能替代渲染后的真实验收。

六、第一版不用什么都做，但要先把底座搭起来

如果团队刚开始建设，不必一次把所有目录都做满，但有几块底座必须先有。

最直接的启动清单通常是七份：

1. 一份视觉原则与品牌语气说明
2. 一套三层变量体系
3. 一套页面与分页规则
4. 12 到 15 个核心组件规范
5. 4 到 6 个高频页模板
6. 一套图表与表格规范
7. 一套 HTML 转 PDF 的工程规范

再往实现层收口，P0 变量至少要包含：

• 色彩、字体、字号、行高、间距
• 页面尺寸与页边距
• 图表、封面、目录、提示块、表格和指标卡所需的专用变量

P0 组件可以先锁定：

• 页面框架
• 封面
• 目录
• 章节起始
• 节标题
• 正文排版
• 提示块
• 指标卡
• 表格
• 图表框架
• 方法说明
• 来源说明
• 参考文献
• 页脚与页码
• 封底

P0 页面类型则至少应覆盖：

• 封面
• 目录
• 章节起始
• 标准内容页
• 单图分析页
• 表格页
• 执行摘要页
• 方法论页
• 附录页
• 参考来源页
• 封底页

P0 组合模式也不应只停留在口头描述，最好至少明确：

• cover.hero
• summary.strip
• insight.chart
• analysis.split
• compare.recommend
• appendix.data
• references.standard

真正最容易被漏掉、但又最该先定住的，不是颜色和组件名，而是分页规则、版式系统、图表表格规范和组件内容边界。

反过来看，静态报告里有一批常见网页组件其实不该优先建设，比如表单输入、下拉框、抽屉、标签页、提示浮层、消息提示、复杂 hover 和 focus 状态、加载骨架、重交互响应式断点以及动画变量。对报告真正有决定作用的，仍然是版式、分页、标题层级、表格、图表、来源、脚注和章节节奏。

结论

静态报告设计系统的重点，从来都不是“做一套看起来漂亮的网页组件”，而是建立一条从文档级配置、设计变量、页面系统、组件系统、内容规范到 PDF 输出验收的完整链路。

所以，更准确的判断应该是：

这类系统不是网页设计系统的缩小版，而是一套围绕“报告生产”重新组织过的基础设施。

真正稳妥的落地顺序，也应该明确下来：

先在组件库里做硬约束，再在组装层做结构校验，最后在渲染结果上做自动化验收。