@topmindspace/tms-skills 2.0.1 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/CHANGELOG.md +139 -134
  2. package/bin/tms-skills.js +160 -160
  3. package/package.json +48 -48
  4. package/top-ppt-html/README.md +254 -254
  5. package/top-ppt-html/SKILL.md +111 -111
  6. package/top-ppt-html/assets/examples/2026-09-09-architecture-graphite-dark.html +3873 -3926
  7. package/top-ppt-html/assets/examples/2026-09-09-architecture-graphite-dark.model.json +167 -167
  8. package/top-ppt-html/assets/examples/2026-09-09-architecture-spectrum.html +3873 -3926
  9. package/top-ppt-html/assets/examples/2026-09-09-architecture-spectrum.model.json +167 -167
  10. package/top-ppt-html/assets/examples/2026-09-09-presentation-apple-mono.html +4272 -4325
  11. package/top-ppt-html/assets/examples/2026-09-09-presentation-apple-mono.model.json +320 -320
  12. package/top-ppt-html/assets/examples/2026-09-09-presentation-brand-red.html +4272 -4325
  13. package/top-ppt-html/assets/examples/2026-09-09-presentation-brand-red.model.json +320 -320
  14. package/top-ppt-html/assets/examples/2026-09-09-presentation-business-blue.html +4272 -4325
  15. package/top-ppt-html/assets/examples/2026-09-09-presentation-business-blue.model.json +320 -320
  16. package/top-ppt-html/assets/examples/2026-09-09-research-deep-teal.html +5474 -5527
  17. package/top-ppt-html/assets/examples/2026-09-09-research-deep-teal.model.json +913 -913
  18. package/top-ppt-html/assets/examples/2026-09-09-research-indigo-violet.html +5474 -5527
  19. package/top-ppt-html/assets/examples/2026-09-09-research-indigo-violet.model.json +913 -913
  20. package/top-ppt-html/assets/examples/2026-09-09-research-mckinsey.html +5474 -5527
  21. package/top-ppt-html/assets/examples/2026-09-09-research-mckinsey.model.json +913 -913
  22. package/top-ppt-html/assets/examples/2026-09-09-research-warm-sand.html +5474 -5527
  23. package/top-ppt-html/assets/examples/2026-09-09-research-warm-sand.model.json +913 -913
  24. package/top-ppt-html/assets/pptx-export.js +1944 -1944
  25. package/top-ppt-html/assets/style-gallery.html +559 -589
  26. package/top-ppt-html/assets/templates/architecture.html +3675 -3728
  27. package/top-ppt-html/assets/templates/engine.css +787 -840
  28. package/top-ppt-html/assets/templates/presentation.html +3685 -3738
  29. package/top-ppt-html/assets/templates/research.html +3964 -4017
  30. package/top-ppt-html/assets/templates/ui.js +520 -520
  31. package/top-ppt-html/assets/theme-overview-architecture.png +0 -0
  32. package/top-ppt-html/assets/theme-overview-presentation.png +0 -0
  33. package/top-ppt-html/assets/theme-overview-research.png +0 -0
  34. package/top-ppt-html/assets/theme-overview.png +0 -0
  35. package/top-ppt-html/evals/prompts.csv +15 -15
  36. package/top-ppt-html/evals/rubric.schema.json +25 -25
  37. package/top-ppt-html/evals/run_evals.py +220 -220
  38. package/top-ppt-html/evals/trace.example.json +16 -16
  39. package/top-ppt-html/package-lock.json +175 -0
  40. package/top-ppt-html/package.json +30 -35
  41. package/top-ppt-html/references/charts-basic.md +624 -624
  42. package/top-ppt-html/references/charts-discipline.md +108 -108
  43. package/top-ppt-html/references/charts-extended.md +482 -482
  44. package/top-ppt-html/references/charts.md +28 -28
  45. package/top-ppt-html/references/components-atoms.md +624 -624
  46. package/top-ppt-html/references/components.md +30 -30
  47. package/top-ppt-html/references/content-rules.md +490 -490
  48. package/top-ppt-html/references/design-system-engine.md +235 -235
  49. package/top-ppt-html/references/design-system.md +471 -478
  50. package/top-ppt-html/references/failure-modes.md +214 -214
  51. package/top-ppt-html/references/high-fidelity.md +127 -127
  52. package/top-ppt-html/references/icons.md +397 -397
  53. package/top-ppt-html/references/industry-benchmark.md +105 -105
  54. package/top-ppt-html/references/infographics-stats.md +308 -308
  55. package/top-ppt-html/references/infographics-structure.md +226 -226
  56. package/top-ppt-html/references/infographics.md +43 -43
  57. package/top-ppt-html/references/layout-grammar.md +315 -315
  58. package/top-ppt-html/references/layouts-architecture.md +108 -108
  59. package/top-ppt-html/references/layouts-combo.md +600 -600
  60. package/top-ppt-html/references/layouts-research.md +160 -160
  61. package/top-ppt-html/references/modes.md +254 -254
  62. package/top-ppt-html/references/outline-design.md +275 -275
  63. package/top-ppt-html/references/playbook.md +266 -266
  64. package/top-ppt-html/references/pptx-export.md +209 -209
  65. package/top-ppt-html/references/reform-plan.md +252 -252
  66. package/top-ppt-html/references/styles.md +336 -370
  67. package/top-ppt-html/references/tech-design.md +138 -138
  68. package/top-ppt-html/scripts/audit_css.py +109 -109
  69. package/top-ppt-html/scripts/audit_docs.py +176 -176
  70. package/top-ppt-html/scripts/audit_skill.py +220 -220
  71. package/top-ppt-html/scripts/audit_styles.py +293 -351
  72. package/top-ppt-html/scripts/build_examples.py +2276 -2276
  73. package/top-ppt-html/scripts/build_pptx.js +2380 -2380
  74. package/top-ppt-html/scripts/capture_theme_overview.js +78 -78
  75. package/top-ppt-html/scripts/checks_html.py +127 -127
  76. package/top-ppt-html/scripts/cross_verify.py +294 -294
  77. package/top-ppt-html/scripts/env_probe.py +158 -158
  78. package/top-ppt-html/scripts/extract_model.py +210 -210
  79. package/top-ppt-html/scripts/extract_snippet.py +374 -374
  80. package/top-ppt-html/scripts/gen_channel_a.js +214 -214
  81. package/top-ppt-html/scripts/layout-constants.json +3309 -3377
  82. package/top-ppt-html/scripts/layout_slots.json +830 -830
  83. package/top-ppt-html/scripts/lib_layout_regions.js +412 -412
  84. package/top-ppt-html/scripts/measure_height.py +178 -178
  85. package/top-ppt-html/scripts/model-schema.json +547 -547
  86. package/top-ppt-html/scripts/negative_tests.py +307 -307
  87. package/top-ppt-html/scripts/package_skill.py +291 -291
  88. package/top-ppt-html/scripts/prepare_images.py +341 -341
  89. package/top-ppt-html/scripts/probe_image_export.py +188 -188
  90. package/top-ppt-html/scripts/quality_gate.py +301 -301
  91. package/top-ppt-html/scripts/regression.py +307 -308
  92. package/top-ppt-html/scripts/render_compare.py +275 -275
  93. package/top-ppt-html/scripts/render_from_model.py +698 -698
  94. package/top-ppt-html/scripts/scaffold_report.py +1054 -1054
  95. package/top-ppt-html/scripts/section-file-map.json +104 -104
  96. package/top-ppt-html/scripts/sync_runtime.py +662 -662
  97. package/top-ppt-html/scripts/validate_pptx.py +1510 -1510
  98. package/top-ppt-html/scripts/validate_report.py +1456 -1456
@@ -1,315 +1,315 @@
1
- # 布局语法 · Layout Grammar(网格 · 元素 · 组合 · 留白)
2
-
3
- > **何时读**:任何页面动手排版之前;或觉得「不整齐 / 不优雅 / 空得别扭 / 挤」时。
4
- > **定位**:美观与空间秩序的**唯一排版契约**——先选骨架,再落元素,最后校准留白。与 `design-system.md`(token/字阶)互补:本文管**怎么摆**,那里管**用什么值**。
5
- > **单源**:预设骨架与元素规则 → `scripts/layout-constants.json` `layoutSystem`;几何英寸 → `pageTypes` / `grid`。
6
-
7
- ---
8
-
9
- ## 〇、排版总序(禁止跳步)
10
-
11
- ```
12
- ① 定内容角色(主张 / 证据 / 结构 / 情绪)
13
- ↓
14
- ② 选预设骨架 P1–P12(禁止临场发明栅格)
15
- ↓
16
- ③ 按元素规则落位(图标/列表/卡/图/表/图注)
17
- ↓
18
- ④ 套间距节奏(只用 --sp-* / 既有 gap token)
19
- ↓
20
- ⑤ 校准对齐与留白(顶边 / 左缘 / 光学中心 / 填充率)
21
- ↓
22
- ⑥ 跑布局门禁(LAYOUT_*)
23
- ```
24
-
25
- **一句话**:整齐优雅 = **同一左缘 + 同一节奏 + 单一视觉重心 + 有意留白**,不是「元素都放大」。
26
-
27
- ---
28
-
29
- ## 一、页面框架与网格
30
-
31
- ### 1.1 三层纵向区(每页固定)
32
-
33
- | 区 | 占位 | 内容 | 对齐 |
34
- |----|------|------|------|
35
- | **Chrome** | 顶 ~22% | eyebrow + 主标题 + 可选导语 + 标题线 | 左缘 = 版心左 `grid.x[0]` |
36
- | **Body** | 中 ~62% | 主件 + 从件(预设骨架决定列) | 落 12 列轨 |
37
- | **Annotation** | 底 ~16% | so-what / 口径 / 来源 / 页码 | 左缘同 Chrome;页码右缘 `x[12]` |
38
-
39
- - 绝对安全边距 `grid.safe`:任何元素不得越过。
40
- - 页码 / 来源永远压在 Annotation 带,**不进 Body**。
41
-
42
- ### 1.2 横向 12 列(与 PPTX `grid.x[]` 同源)
43
-
44
- | 常用跨列 | 用途 | 预设 |
45
- |----------|------|------|
46
- | 7 + 5 | 主视觉 + 注解(V1) | P1 |
47
- | 12 + 4/4/4 | 通栏主件 + 底带 | P2 |
48
- | 5 + 7 / 52:48 | 大数 + 佐证 | P3 |
49
- | 6 + 6 | 对称对照 | P4 |
50
- | 4 + 4 + 4 | 三栏并列 | P5 |
51
- | 6/6 × 2 行 | 四象限 | P6 |
52
- | 3 + 6 + 3 | 侧栏 + 主区 | P7 |
53
- | 8 + 4 | 主区 + 注解列 | P8 |
54
- | 12 | 全幅结构/素材 | P9 |
55
- | bento 4 列 | 不等大拼贴 | P10 |
56
- | 2 + 1 + 1 | 主 + 双辅 | P11 |
57
- | 1 + 1 + 2 | 双辅 + 主 | P12 |
58
-
59
- **纪律**:卡片/图/表的左缘必须落在列轨上;禁止目测居中(CRAP Alignment)。
60
-
61
- ### 1.3 间距节奏(只准用 token)
62
-
63
- | 层级 | Token | 用途 |
64
- |------|-------|------|
65
- | 微 | `--sp-1/2`(4/8) | 图标-文字、键-值、标签-数字 |
66
- | 组件内 | `--sp-3/4`(12/16) | 卡内标题-正文、列表项间 |
67
- | 组件间 | `--gap` / `--sp-5`(16–24) | 栅格 gap、卡片间距 |
68
- | 区块间 | `--sp-6/7`(32/48) | 主从件之间、图-注解 |
69
- | 页缘 | `--band-pad` | 上下呼吸 |
70
-
71
- **禁止**写死 `margin:13px` 之类游离值。同页同类间距必须同值。
72
-
73
- ---
74
-
75
- ## 二、预设骨架 P1–P12(先选骨架,再填内容)
76
-
77
- > 每个骨架绑定:**列比 · 视觉权重 · 允许元素 · 填充率目标 · PPTX 页型**。
78
- > 选型顺序:内容形态 → 下表「首选」→ 不够用再「次选」。**禁止临场发明表外栅格。**
79
-
80
- | ID | 名称 | 列结构 | 视觉权重 | 允许主件 | 填充率 | 适用 | PPTX |
81
- |----|------|--------|----------|----------|--------|------|------|
82
- | **P1** | 主从图文 | 7:5(`g-side`) | 主 60 / 从 40 | 图/图表/素材 \| 列表/卡 | 65–75% | V1 演讲图文 | `split` |
83
- | **P2** | 通栏+底带 | 12 + 4/4/4 | 主 55 / 带 45 | 大图/结构 \| 三卡/指标 | 70–80% | V2 总览→分解 | `bar`/`diagram`+cards |
84
- | **P3** | 大数佐证 | 5:7 或 52:48 | 数 45 / 证 55 | KPI \| 小图/迷你表/要点 | 60–70% | V3 极偏/单点 | `kpi` |
85
- | **P4** | 对称对照 | 6:6 | 左右各 50 | 双卡/双图/双表 | 70–80% | V4 前后/方案 | `comparison` |
86
- | **P5** | 三栏并列 | 4:4:4 | 均等(唯一允许) | 三卡/三栏文 | 70–80% | 并列论点 | `cards`/`threecol` |
87
- | **P6** | 四象限 | 6:6 × 2 | 对角平衡 | 卡×2 + 图×2 | 75–85% | 四观察 | `cards`+`split` |
88
- | **P7** | 侧栏主区 | 3:6:3 | 主 55 | 图/表 \| 导航/图例 | 65–75% | 密表+过滤 | `split` |
89
- | **P8** | 主区+注解列 | 8:4 | 主 70 / 注 30 | 图/表 \| 要点 3 条 | 70–80% | 证据页 | `exhibit`/`split` |
90
- | **P9** | 全幅结构 | 12 | 100% 主件 | 架构/全景/素材大图 | 75–90% | C 模式/情绪 | `diagram`/`image` |
91
- | **P10** | 拼贴 Bento | 4 列跨格 | 主卡 ≥2 格 | 不等大卡/指标/迷你图 | 75–85% | 经营快照 | `cards` |
92
- | **P11** | 主+双辅 | 2:1:1 | 主 50 | 主图/主文 + 双辅卡 | 70–80% | 一主两从 | `split` |
93
- | **P12** | 双辅+主 | 1:1:2 | 主 50 | 双辅 + 主图/主文 | 70–80% | 镜像 P11 | `split` |
94
-
95
- ### 2.1 权重铁律
96
-
97
- 1. **一屏一视觉重心**:主件面积/字重视觉重量 ≥ 从件 1.5×。
98
- 2. **禁止三等重大件**:三栏 P5 是唯一均分,且每栏必须是**同级**从件(都卡或都文),不得「图+卡+图」混均分。
99
- 3. **镜像成对**:左重用 P1/P11,右重用镜像(`--rev` / P12),同篇交替不超过 2 次连续同向。
100
- 4. **注释层不抢戏**:so-what 高度 ≤ Body 的 18%,字号 ≤ body。
101
-
102
- ### 2.2 填充率(留白纪律 · 可测)
103
-
104
- ```
105
- fill = Body 区被内容覆盖的估算面积 / Body 区面积
106
- ```
107
-
108
- | 模式 | 目标 | 过低(空) | 过高(爆) |
109
- |------|------|------------|------------|
110
- | presentation | 62–78% | <55% → 补从件/并页/改 P2/P3 | >85% → 拆页或升密表 |
111
- | research | 70–85% | <60% | >90% |
112
- | architecture | 75–90%(图) | <65% | 文字挤图 |
113
-
114
- **空的合法来源只有三种**:章节幕 / 金句 / 收尾 CTA。其余「半空页」= 不合格。
115
-
116
- ---
117
-
118
- ## 三、元素级排版规则(整齐优雅的最小单元)
119
-
120
- ### 3.1 图标 Icon
121
-
122
- | 项 | 规则 |
123
- |----|------|
124
- | 尺寸 | 仅 16 / 20 / 24 px(列表 16–18,卡头 20–24,指标角标 16) |
125
- | 描边 | 1.8,`currentColor`,无填充除非实心标记 |
126
- | 对齐 | **光学中心**对文字 x-height 中线(不是框几何中心) |
127
- | 图文距 | `--sp-2`(8px);图标左缘与文字块左缘差 = 图标宽 + 8 |
128
- | 位置 | 仅:卡头、列表行首、指标角标、提示条。**禁止**表格内/图表内/Agenda |
129
- | 密度 | 每屏 3–8 个;同屏同尺寸 |
130
-
131
- ### 3.2 列表 List
132
-
133
- | 项 | 规则 |
134
- |----|------|
135
- | 项长 | ≤2 行、≤45 字;超长拆项或转表 |
136
- | 项距 | `--sp-3`(12px);组间距 `--sp-5` |
137
- | 缩进 | 统一 `--sp-4`;嵌套仅 1 层 |
138
- | 引导 | 「**加粗结论。**解释」同一文本框(禁拆流) |
139
- | 对齐 | 多列列表顶边对齐;项符号光学对齐首字 |
140
- | 数量 | 卡内 ≤4(research ≤5);单页列表组 ≤3 |
141
-
142
- ### 3.3 卡片 Card
143
-
144
- | 项 | 规则 |
145
- |----|------|
146
- | 内边距 | `containers.pad.card`(≈18–24px),四边一致 |
147
- | 头 | 图标 + 标题同行,基线对齐;头-体 `--sp-3` |
148
- | 体 | 列表或 ≤3 行段落;禁止「标题+一行」占四行高度的空卡 |
149
- | 等高 | 同行卡片 `align-items:stretch`;矮卡**不拉伸内容**,只底对齐 |
150
- | 圆角/边 | 统一 `--r-md` + 1px `--border`;同页同风格 |
151
- | 网格 | P5=3 列 / P6=2×2 / P10=bento;禁止 5+ 等宽小卡挤一行 |
152
-
153
- ### 3.4 指标 Metric / KPI
154
-
155
- | 项 | 规则 |
156
- |----|------|
157
- | 数字 | `t-metric`,`tabular-nums`;单位字号约 45% 于数字 |
158
- | 标签 | 数字下 `--sp-2`;注解再 `--sp-1` |
159
- | 行 | 4–6 个一排(P2 底带);**数字基线对齐** |
160
- | KPI hero | 数字占 P3 左 45%,与右栏**垂直居中对齐**;Δ 变化色用 accent,不用红绿 |
161
-
162
- ### 3.5 图表 Chart
163
-
164
- | 项 | 规则 |
165
- |----|------|
166
- | 标题 | 图上方左对齐 `t-h3`/`fig__cap`;与图 `--sp-3` |
167
- | 图区 | 居中于所在列;容器 `pad.chart` |
168
- | 比例 | 柱/折线 ≈16:9~2:1;环/饼 1:1 且 **直径 ≤ 内容区高 45%**(简单占比更小,走 P3) |
169
- | 标签 | **禁止叠在弧/柱心**;环图数值进图例行;柱标条顶/条外 |
170
- | 标签盒 | 最小宽 ≥ 最长标签估算宽 + 8px,防换行叠字 |
171
- | 轴/图例 | `micro`;图例在图右或图下,**不与数据重叠** |
172
- | 图注 | 来源/口径一行在 Annotation,不塞进 SVG |
173
-
174
- ### 3.6 表格 Table
175
-
176
- | 项 | 规则 |
177
- |----|------|
178
- | 列 | 主标左对齐;数值右对齐 `tabular-nums` |
179
- | 行高 | 一致;密表 ≥0.32in / 常规 ≥0.5in |
180
- | 表头 | 高于正文行;底色 accent 或 surface-2 |
181
- | 空洞 | 空单元格 >40% → 合并列/换承载(`TABLE_DENSITY`) |
182
- | 宽度 | 占所在列 100%;与邻件顶边对齐 |
183
-
184
- ### 3.7 图文 / 插图 Media
185
-
186
- | 项 | 规则 |
187
- |----|------|
188
- | 比例锁 | 必须 `imageSpec.ratioCssClass`;禁止自由拉伸 |
189
- | 对齐 | 与邻栏**顶边对齐**(P1/P8)或整体居中(P3 hero) |
190
- | 图注 | 默认图下 `media__cap--below`;遮罩字仅 `half/full` 情绪图 |
191
- | 占位 | 虚线框 + `.media__ph` 标签居中;比例与正式图一致 |
192
- | 多图 | 等高、等 gap、角标 A/B 仅 compare |
193
-
194
- ### 3.8 列表化信息图 / 结构图 Infographic
195
-
196
- | 项 | 规则 |
197
- |----|------|
198
- | 节点 | 圆角矩形统一 `--r-sm/md`;内边距 8–12px;文字 2 行封顶 |
199
- | 连接 | **正交折线 + 箭头**(`.lane__arr` / `.arch__conn` / SVG `path+polygon`);层间间距恒定;**禁裸 `→` 文本** |
200
- | 标签 | 节点外优先;避让不压线;分支标在边中点上方 |
201
- | 图例 | 左下或右下一行 chips;与图 `--sp-4` |
202
- | 密度 | 节点 ≤24(C);同层等高、等宽(或等高不等宽按内容) |
203
-
204
- ### 3.9 结论条 / 标注
205
-
206
- | 项 | 规则 |
207
- |----|------|
208
- | so-what | 通栏或主区宽;左 3px accent 边;高 ≤0.7in |
209
- | flags | 列表式,不与 so-what 同高堆叠超过 2 条 |
210
- | 引用 `[n]` | 上标紧跟数字,不另起行 |
211
-
212
- ---
213
-
214
- ## 四、组合语法(多元素同页)
215
-
216
- ### 4.1 三层槽位模型(所有组合共用)
217
-
218
- ```
219
- ┌─────────────────────────────────────┐
220
- │ Chrome(标题区) │
221
- ├─────────────────────────────────────┤
222
- │ PRIMARY(主件,视觉重心) │
223
- │ ┌──────────┐ ┌─────────────────┐ │
224
- │ │ 主件 │ │ SECONDARY 从件 │ │
225
- │ └──────────┘ └─────────────────┘ │
226
- ├─────────────────────────────────────┤
227
- │ ANNOTATION(so-what / 来源 / 页码) │
228
- └─────────────────────────────────────┘
229
- ```
230
-
231
- | 槽位 | 面积(Body 内) | 可放 | 不可放 |
232
- |------|-----------------|------|--------|
233
- | PRIMARY | 50–70% | 图、表、结构、素材、KPI | 大段正文、装饰 |
234
- | SECONDARY | 20–40% | 列表、卡、小表、迷你图、图例 | 第二张同级大图 |
235
- | ANNOTATION | ≤18% | so-what、口径、flags | 论证正文 |
236
-
237
- ### 4.2 合法组合矩阵(摘要 · 完整选型见 playbook §四)
238
-
239
- | 组合 | 骨架 | 主 | 从 | 注 |
240
- |------|------|----|----|-----|
241
- | 图+解读 | P1/P8 | 图 | 要点 3–4 | so-what |
242
- | 表+图互证 | P4/P8 | 表或图 | 对侧 | 口径 |
243
- | 架构+图例 | P9 | 结构图 | legend chips | 图注 1–2 行 |
244
- | 大数+证据 | P3 | KPI | 小图/表/2 指标 | Δ/口径 |
245
- | 指标带+主图 | P2 | 图 | 指标 4–6 | 口径 |
246
- | 图文互证 | P1 | 素材 | 要点 3–4 | 图注+来源 |
247
- | 四观察 | P6 | 对角卡/图 | 对角 | — |
248
- | 拼贴经营快照 | P10 | 主卡跨 2 | 小卡 | 口径行 |
249
-
250
- ### 4.3 组合硬规则
251
-
252
- 1. **从件必须承载主件表达不了的信息**(趋势/对比/含义),禁止复述主件数字。
253
- 2. **高度匹配**:主从件顶边对齐(`a-start`);高度差 >25% 时矮侧补注解卡或减主件高,**禁止大块空白尾巴**。
254
- 3. **同型元素同构**:三卡同结构、双栏同维度对仗。
255
- 4. **最多两种表面色**(surface / accent-soft),层次靠明度+描边。
256
- 5. **跨页同类骨架连用 ≤2 页**(P5/P6 例外可 3),中间换 P3/P9 休止。
257
-
258
- ---
259
-
260
- ## 五、对齐与光学(优雅的可执行定义)
261
-
262
- | 规则 | 做法 | 反例 |
263
- |------|------|------|
264
- | 左缘 | Chrome / Body / Annotation 全部 `x[0]` | 标题缩进、卡片浮中 |
265
- | 顶边 | 混排栏 `align-items:start`;指标行数字基线对齐 | 图顶对卡中 |
266
- | 右缘 | 页码、数值列、次要按钮贴 `x[12]` | 右缘参差 |
267
- | 光学中心 | 图标/单行标签在色块内 optical 居中 | 几何居中导致视觉下沉 |
268
- | 等距 | 同行元素 gap 恒定;不等距用「组」拉开 | 12/15/12/20 混用 |
269
- | 对象对齐 | 多图/多卡等高;表与图顶对齐 | 底对齐导致标题错位 |
270
-
271
- **自检口诀**:瞇起眼——只剩色块时,是否仍有清晰的「一条左线、一条顶线、一块重心」?
272
-
273
- ---
274
-
275
- ## 六、布局门禁(`LAYOUT_*` · 单源 `layoutSystem`)
276
-
277
- | 码 | 判据 | 级别 |
278
- |----|------|------|
279
- | `LAYOUT_NO_SKELETON` | 内容页未使用 P1–P12 对应类(`g-side/g-2/g-3/g-bento/...`)且手写 inline grid | FAIL |
280
- | `LAYOUT_MULTI_FOCUS` | 同页 ≥2 个「大件」(图宽>55% 或 metric 字号>40px)且无主从比 | FAIL |
281
- | `LAYOUT_ALIGN_DRIFT` | 混排缺 `a-start/a-c` 或主从件无顶边/居中声明 | FAIL |
282
- | `LAYOUT_SPACING_OFF_TOKEN` | 正文 margin/padding/gap 出现非 token 像素值(白名单 clamp 与 --sp) | WARN→FAIL |
283
- | `LAYOUT_FILL_LOW` / `HIGH` | 填充率超出模式目标带 | FAIL |
284
- | `LAYOUT_ICON_SIZE` | 图标宽高 ∉ {16,18,20,24} | WARN |
285
- | `LAYOUT_LABEL_COLLIDE` | 图表标签强制换行迹象(短 width + 长 text) | FAIL |
286
-
287
- ---
288
-
289
- ## 七、与 V1–V4 / 模式的关系
290
-
291
- | 演讲图文 | 骨架 |
292
- |----------|------|
293
- | V1 主视觉+右注解 | **P1** |
294
- | V2 上图下带 | **P2** |
295
- | V3 大数+佐证 | **P3** |
296
- | V4 双图对照 | **P4** |
297
-
298
- - A presentation:默认 P1–P4、P6、P10。
299
- - B research:P5、P7、P8 + 密表;仍禁双大件。
300
- - C architecture:P9 为主;结构必须真边(见 infographics-structure)。
301
-
302
- ---
303
-
304
- ## 八、落地检查清单(交付前)
305
-
306
- - [ ] 每内容页标注了骨架 ID(P__)
307
- - [ ] 左缘/顶边眯眼自检通过
308
- - [ ] 填充率在模式目标带
309
- - [ ] 图标仅 3–8 且尺寸合规
310
- - [ ] 图表标签不叠不换行
311
- - [ ] 卡内无「标题+一行」空卡
312
- - [ ] Annotation 只有 so-what/口径/页码
313
- - [ ] `LAYOUT_*` 全 PASS
314
-
315
- > 整改与实现细节见 `reform-plan.md` §四-b。间距与色 token 见 `design-system.md`。
1
+ # 布局语法 · Layout Grammar(网格 · 元素 · 组合 · 留白)
2
+
3
+ > **何时读**:任何页面动手排版之前;或觉得「不整齐 / 不优雅 / 空得别扭 / 挤」时。
4
+ > **定位**:美观与空间秩序的**唯一排版契约**——先选骨架,再落元素,最后校准留白。与 `design-system.md`(token/字阶)互补:本文管**怎么摆**,那里管**用什么值**。
5
+ > **单源**:预设骨架与元素规则 → `scripts/layout-constants.json` `layoutSystem`;几何英寸 → `pageTypes` / `grid`。
6
+
7
+ ---
8
+
9
+ ## 〇、排版总序(禁止跳步)
10
+
11
+ ```
12
+ ① 定内容角色(主张 / 证据 / 结构 / 情绪)
13
+ ↓
14
+ ② 选预设骨架 P1–P12(禁止临场发明栅格)
15
+ ↓
16
+ ③ 按元素规则落位(图标/列表/卡/图/表/图注)
17
+ ↓
18
+ ④ 套间距节奏(只用 --sp-* / 既有 gap token)
19
+ ↓
20
+ ⑤ 校准对齐与留白(顶边 / 左缘 / 光学中心 / 填充率)
21
+ ↓
22
+ ⑥ 跑布局门禁(LAYOUT_*)
23
+ ```
24
+
25
+ **一句话**:整齐优雅 = **同一左缘 + 同一节奏 + 单一视觉重心 + 有意留白**,不是「元素都放大」。
26
+
27
+ ---
28
+
29
+ ## 一、页面框架与网格
30
+
31
+ ### 1.1 三层纵向区(每页固定)
32
+
33
+ | 区 | 占位 | 内容 | 对齐 |
34
+ |----|------|------|------|
35
+ | **Chrome** | 顶 ~22% | eyebrow + 主标题 + 可选导语 + 标题线 | 左缘 = 版心左 `grid.x[0]` |
36
+ | **Body** | 中 ~62% | 主件 + 从件(预设骨架决定列) | 落 12 列轨 |
37
+ | **Annotation** | 底 ~16% | so-what / 口径 / 来源 / 页码 | 左缘同 Chrome;页码右缘 `x[12]` |
38
+
39
+ - 绝对安全边距 `grid.safe`:任何元素不得越过。
40
+ - 页码 / 来源永远压在 Annotation 带,**不进 Body**。
41
+
42
+ ### 1.2 横向 12 列(与 PPTX `grid.x[]` 同源)
43
+
44
+ | 常用跨列 | 用途 | 预设 |
45
+ |----------|------|------|
46
+ | 7 + 5 | 主视觉 + 注解(V1) | P1 |
47
+ | 12 + 4/4/4 | 通栏主件 + 底带 | P2 |
48
+ | 5 + 7 / 52:48 | 大数 + 佐证 | P3 |
49
+ | 6 + 6 | 对称对照 | P4 |
50
+ | 4 + 4 + 4 | 三栏并列 | P5 |
51
+ | 6/6 × 2 行 | 四象限 | P6 |
52
+ | 3 + 6 + 3 | 侧栏 + 主区 | P7 |
53
+ | 8 + 4 | 主区 + 注解列 | P8 |
54
+ | 12 | 全幅结构/素材 | P9 |
55
+ | bento 4 列 | 不等大拼贴 | P10 |
56
+ | 2 + 1 + 1 | 主 + 双辅 | P11 |
57
+ | 1 + 1 + 2 | 双辅 + 主 | P12 |
58
+
59
+ **纪律**:卡片/图/表的左缘必须落在列轨上;禁止目测居中(CRAP Alignment)。
60
+
61
+ ### 1.3 间距节奏(只准用 token)
62
+
63
+ | 层级 | Token | 用途 |
64
+ |------|-------|------|
65
+ | 微 | `--sp-1/2`(4/8) | 图标-文字、键-值、标签-数字 |
66
+ | 组件内 | `--sp-3/4`(12/16) | 卡内标题-正文、列表项间 |
67
+ | 组件间 | `--gap` / `--sp-5`(16–24) | 栅格 gap、卡片间距 |
68
+ | 区块间 | `--sp-6/7`(32/48) | 主从件之间、图-注解 |
69
+ | 页缘 | `--band-pad` | 上下呼吸 |
70
+
71
+ **禁止**写死 `margin:13px` 之类游离值。同页同类间距必须同值。
72
+
73
+ ---
74
+
75
+ ## 二、预设骨架 P1–P12(先选骨架,再填内容)
76
+
77
+ > 每个骨架绑定:**列比 · 视觉权重 · 允许元素 · 填充率目标 · PPTX 页型**。
78
+ > 选型顺序:内容形态 → 下表「首选」→ 不够用再「次选」。**禁止临场发明表外栅格。**
79
+
80
+ | ID | 名称 | 列结构 | 视觉权重 | 允许主件 | 填充率 | 适用 | PPTX |
81
+ |----|------|--------|----------|----------|--------|------|------|
82
+ | **P1** | 主从图文 | 7:5(`g-side`) | 主 60 / 从 40 | 图/图表/素材 \| 列表/卡 | 65–75% | V1 演讲图文 | `split` |
83
+ | **P2** | 通栏+底带 | 12 + 4/4/4 | 主 55 / 带 45 | 大图/结构 \| 三卡/指标 | 70–80% | V2 总览→分解 | `bar`/`diagram`+cards |
84
+ | **P3** | 大数佐证 | 5:7 或 52:48 | 数 45 / 证 55 | KPI \| 小图/迷你表/要点 | 60–70% | V3 极偏/单点 | `kpi` |
85
+ | **P4** | 对称对照 | 6:6 | 左右各 50 | 双卡/双图/双表 | 70–80% | V4 前后/方案 | `comparison` |
86
+ | **P5** | 三栏并列 | 4:4:4 | 均等(唯一允许) | 三卡/三栏文 | 70–80% | 并列论点 | `cards`/`threecol` |
87
+ | **P6** | 四象限 | 6:6 × 2 | 对角平衡 | 卡×2 + 图×2 | 75–85% | 四观察 | `cards`+`split` |
88
+ | **P7** | 侧栏主区 | 3:6:3 | 主 55 | 图/表 \| 导航/图例 | 65–75% | 密表+过滤 | `split` |
89
+ | **P8** | 主区+注解列 | 8:4 | 主 70 / 注 30 | 图/表 \| 要点 3 条 | 70–80% | 证据页 | `exhibit`/`split` |
90
+ | **P9** | 全幅结构 | 12 | 100% 主件 | 架构/全景/素材大图 | 75–90% | C 模式/情绪 | `diagram`/`image` |
91
+ | **P10** | 拼贴 Bento | 4 列跨格 | 主卡 ≥2 格 | 不等大卡/指标/迷你图 | 75–85% | 经营快照 | `cards` |
92
+ | **P11** | 主+双辅 | 2:1:1 | 主 50 | 主图/主文 + 双辅卡 | 70–80% | 一主两从 | `split` |
93
+ | **P12** | 双辅+主 | 1:1:2 | 主 50 | 双辅 + 主图/主文 | 70–80% | 镜像 P11 | `split` |
94
+
95
+ ### 2.1 权重铁律
96
+
97
+ 1. **一屏一视觉重心**:主件面积/字重视觉重量 ≥ 从件 1.5×。
98
+ 2. **禁止三等重大件**:三栏 P5 是唯一均分,且每栏必须是**同级**从件(都卡或都文),不得「图+卡+图」混均分。
99
+ 3. **镜像成对**:左重用 P1/P11,右重用镜像(`--rev` / P12),同篇交替不超过 2 次连续同向。
100
+ 4. **注释层不抢戏**:so-what 高度 ≤ Body 的 18%,字号 ≤ body。
101
+
102
+ ### 2.2 填充率(留白纪律 · 可测)
103
+
104
+ ```
105
+ fill = Body 区被内容覆盖的估算面积 / Body 区面积
106
+ ```
107
+
108
+ | 模式 | 目标 | 过低(空) | 过高(爆) |
109
+ |------|------|------------|------------|
110
+ | presentation | 62–78% | <55% → 补从件/并页/改 P2/P3 | >85% → 拆页或升密表 |
111
+ | research | 70–85% | <60% | >90% |
112
+ | architecture | 75–90%(图) | <65% | 文字挤图 |
113
+
114
+ **空的合法来源只有三种**:章节幕 / 金句 / 收尾 CTA。其余「半空页」= 不合格。
115
+
116
+ ---
117
+
118
+ ## 三、元素级排版规则(整齐优雅的最小单元)
119
+
120
+ ### 3.1 图标 Icon
121
+
122
+ | 项 | 规则 |
123
+ |----|------|
124
+ | 尺寸 | 仅 16 / 20 / 24 px(列表 16–18,卡头 20–24,指标角标 16) |
125
+ | 描边 | 1.8,`currentColor`,无填充除非实心标记 |
126
+ | 对齐 | **光学中心**对文字 x-height 中线(不是框几何中心) |
127
+ | 图文距 | `--sp-2`(8px);图标左缘与文字块左缘差 = 图标宽 + 8 |
128
+ | 位置 | 仅:卡头、列表行首、指标角标、提示条。**禁止**表格内/图表内/Agenda |
129
+ | 密度 | 每屏 3–8 个;同屏同尺寸 |
130
+
131
+ ### 3.2 列表 List
132
+
133
+ | 项 | 规则 |
134
+ |----|------|
135
+ | 项长 | ≤2 行、≤45 字;超长拆项或转表 |
136
+ | 项距 | `--sp-3`(12px);组间距 `--sp-5` |
137
+ | 缩进 | 统一 `--sp-4`;嵌套仅 1 层 |
138
+ | 引导 | 「**加粗结论。**解释」同一文本框(禁拆流) |
139
+ | 对齐 | 多列列表顶边对齐;项符号光学对齐首字 |
140
+ | 数量 | 卡内 ≤4(research ≤5);单页列表组 ≤3 |
141
+
142
+ ### 3.3 卡片 Card
143
+
144
+ | 项 | 规则 |
145
+ |----|------|
146
+ | 内边距 | `containers.pad.card`(≈18–24px),四边一致 |
147
+ | 头 | 图标 + 标题同行,基线对齐;头-体 `--sp-3` |
148
+ | 体 | 列表或 ≤3 行段落;禁止「标题+一行」占四行高度的空卡 |
149
+ | 等高 | 同行卡片 `align-items:stretch`;矮卡**不拉伸内容**,只底对齐 |
150
+ | 圆角/边 | 统一 `--r-md` + 1px `--border`;同页同风格 |
151
+ | 网格 | P5=3 列 / P6=2×2 / P10=bento;禁止 5+ 等宽小卡挤一行 |
152
+
153
+ ### 3.4 指标 Metric / KPI
154
+
155
+ | 项 | 规则 |
156
+ |----|------|
157
+ | 数字 | `t-metric`,`tabular-nums`;单位字号约 45% 于数字 |
158
+ | 标签 | 数字下 `--sp-2`;注解再 `--sp-1` |
159
+ | 行 | 4–6 个一排(P2 底带);**数字基线对齐** |
160
+ | KPI hero | 数字占 P3 左 45%,与右栏**垂直居中对齐**;Δ 变化色用 accent,不用红绿 |
161
+
162
+ ### 3.5 图表 Chart
163
+
164
+ | 项 | 规则 |
165
+ |----|------|
166
+ | 标题 | 图上方左对齐 `t-h3`/`fig__cap`;与图 `--sp-3` |
167
+ | 图区 | 居中于所在列;容器 `pad.chart` |
168
+ | 比例 | 柱/折线 ≈16:9~2:1;环/饼 1:1 且 **直径 ≤ 内容区高 45%**(简单占比更小,走 P3) |
169
+ | 标签 | **禁止叠在弧/柱心**;环图数值进图例行;柱标条顶/条外 |
170
+ | 标签盒 | 最小宽 ≥ 最长标签估算宽 + 8px,防换行叠字 |
171
+ | 轴/图例 | `micro`;图例在图右或图下,**不与数据重叠** |
172
+ | 图注 | 来源/口径一行在 Annotation,不塞进 SVG |
173
+
174
+ ### 3.6 表格 Table
175
+
176
+ | 项 | 规则 |
177
+ |----|------|
178
+ | 列 | 主标左对齐;数值右对齐 `tabular-nums` |
179
+ | 行高 | 一致;密表 ≥0.32in / 常规 ≥0.5in |
180
+ | 表头 | 高于正文行;底色 accent 或 surface-2 |
181
+ | 空洞 | 空单元格 >40% → 合并列/换承载(`TABLE_DENSITY`) |
182
+ | 宽度 | 占所在列 100%;与邻件顶边对齐 |
183
+
184
+ ### 3.7 图文 / 插图 Media
185
+
186
+ | 项 | 规则 |
187
+ |----|------|
188
+ | 比例锁 | 必须 `imageSpec.ratioCssClass`;禁止自由拉伸 |
189
+ | 对齐 | 与邻栏**顶边对齐**(P1/P8)或整体居中(P3 hero) |
190
+ | 图注 | 默认图下 `media__cap--below`;遮罩字仅 `half/full` 情绪图 |
191
+ | 占位 | 虚线框 + `.media__ph` 标签居中;比例与正式图一致 |
192
+ | 多图 | 等高、等 gap、角标 A/B 仅 compare |
193
+
194
+ ### 3.8 列表化信息图 / 结构图 Infographic
195
+
196
+ | 项 | 规则 |
197
+ |----|------|
198
+ | 节点 | 圆角矩形统一 `--r-sm/md`;内边距 8–12px;文字 2 行封顶 |
199
+ | 连接 | **正交折线 + 箭头**(`.lane__arr` / `.arch__conn` / SVG `path+polygon`);层间间距恒定;**禁裸 `→` 文本** |
200
+ | 标签 | 节点外优先;避让不压线;分支标在边中点上方 |
201
+ | 图例 | 左下或右下一行 chips;与图 `--sp-4` |
202
+ | 密度 | 节点 ≤24(C);同层等高、等宽(或等高不等宽按内容) |
203
+
204
+ ### 3.9 结论条 / 标注
205
+
206
+ | 项 | 规则 |
207
+ |----|------|
208
+ | so-what | 通栏或主区宽;左 3px accent 边;高 ≤0.7in |
209
+ | flags | 列表式,不与 so-what 同高堆叠超过 2 条 |
210
+ | 引用 `[n]` | 上标紧跟数字,不另起行 |
211
+
212
+ ---
213
+
214
+ ## 四、组合语法(多元素同页)
215
+
216
+ ### 4.1 三层槽位模型(所有组合共用)
217
+
218
+ ```
219
+ ┌─────────────────────────────────────┐
220
+ │ Chrome(标题区) │
221
+ ├─────────────────────────────────────┤
222
+ │ PRIMARY(主件,视觉重心) │
223
+ │ ┌──────────┐ ┌─────────────────┐ │
224
+ │ │ 主件 │ │ SECONDARY 从件 │ │
225
+ │ └──────────┘ └─────────────────┘ │
226
+ ├─────────────────────────────────────┤
227
+ │ ANNOTATION(so-what / 来源 / 页码) │
228
+ └─────────────────────────────────────┘
229
+ ```
230
+
231
+ | 槽位 | 面积(Body 内) | 可放 | 不可放 |
232
+ |------|-----------------|------|--------|
233
+ | PRIMARY | 50–70% | 图、表、结构、素材、KPI | 大段正文、装饰 |
234
+ | SECONDARY | 20–40% | 列表、卡、小表、迷你图、图例 | 第二张同级大图 |
235
+ | ANNOTATION | ≤18% | so-what、口径、flags | 论证正文 |
236
+
237
+ ### 4.2 合法组合矩阵(摘要 · 完整选型见 playbook §四)
238
+
239
+ | 组合 | 骨架 | 主 | 从 | 注 |
240
+ |------|------|----|----|-----|
241
+ | 图+解读 | P1/P8 | 图 | 要点 3–4 | so-what |
242
+ | 表+图互证 | P4/P8 | 表或图 | 对侧 | 口径 |
243
+ | 架构+图例 | P9 | 结构图 | legend chips | 图注 1–2 行 |
244
+ | 大数+证据 | P3 | KPI | 小图/表/2 指标 | Δ/口径 |
245
+ | 指标带+主图 | P2 | 图 | 指标 4–6 | 口径 |
246
+ | 图文互证 | P1 | 素材 | 要点 3–4 | 图注+来源 |
247
+ | 四观察 | P6 | 对角卡/图 | 对角 | — |
248
+ | 拼贴经营快照 | P10 | 主卡跨 2 | 小卡 | 口径行 |
249
+
250
+ ### 4.3 组合硬规则
251
+
252
+ 1. **从件必须承载主件表达不了的信息**(趋势/对比/含义),禁止复述主件数字。
253
+ 2. **高度匹配**:主从件顶边对齐(`a-start`);高度差 >25% 时矮侧补注解卡或减主件高,**禁止大块空白尾巴**。
254
+ 3. **同型元素同构**:三卡同结构、双栏同维度对仗。
255
+ 4. **最多两种表面色**(surface / accent-soft),层次靠明度+描边。
256
+ 5. **跨页同类骨架连用 ≤2 页**(P5/P6 例外可 3),中间换 P3/P9 休止。
257
+
258
+ ---
259
+
260
+ ## 五、对齐与光学(优雅的可执行定义)
261
+
262
+ | 规则 | 做法 | 反例 |
263
+ |------|------|------|
264
+ | 左缘 | Chrome / Body / Annotation 全部 `x[0]` | 标题缩进、卡片浮中 |
265
+ | 顶边 | 混排栏 `align-items:start`;指标行数字基线对齐 | 图顶对卡中 |
266
+ | 右缘 | 页码、数值列、次要按钮贴 `x[12]` | 右缘参差 |
267
+ | 光学中心 | 图标/单行标签在色块内 optical 居中 | 几何居中导致视觉下沉 |
268
+ | 等距 | 同行元素 gap 恒定;不等距用「组」拉开 | 12/15/12/20 混用 |
269
+ | 对象对齐 | 多图/多卡等高;表与图顶对齐 | 底对齐导致标题错位 |
270
+
271
+ **自检口诀**:瞇起眼——只剩色块时,是否仍有清晰的「一条左线、一条顶线、一块重心」?
272
+
273
+ ---
274
+
275
+ ## 六、布局门禁(`LAYOUT_*` · 单源 `layoutSystem`)
276
+
277
+ | 码 | 判据 | 级别 |
278
+ |----|------|------|
279
+ | `LAYOUT_NO_SKELETON` | 内容页未使用 P1–P12 对应类(`g-side/g-2/g-3/g-bento/...`)且手写 inline grid | FAIL |
280
+ | `LAYOUT_MULTI_FOCUS` | 同页 ≥2 个「大件」(图宽>55% 或 metric 字号>40px)且无主从比 | FAIL |
281
+ | `LAYOUT_ALIGN_DRIFT` | 混排缺 `a-start/a-c` 或主从件无顶边/居中声明 | FAIL |
282
+ | `LAYOUT_SPACING_OFF_TOKEN` | 正文 margin/padding/gap 出现非 token 像素值(白名单 clamp 与 --sp) | WARN→FAIL |
283
+ | `LAYOUT_FILL_LOW` / `HIGH` | 填充率超出模式目标带 | FAIL |
284
+ | `LAYOUT_ICON_SIZE` | 图标宽高 ∉ {16,18,20,24} | WARN |
285
+ | `LAYOUT_LABEL_COLLIDE` | 图表标签强制换行迹象(短 width + 长 text) | FAIL |
286
+
287
+ ---
288
+
289
+ ## 七、与 V1–V4 / 模式的关系
290
+
291
+ | 演讲图文 | 骨架 |
292
+ |----------|------|
293
+ | V1 主视觉+右注解 | **P1** |
294
+ | V2 上图下带 | **P2** |
295
+ | V3 大数+佐证 | **P3** |
296
+ | V4 双图对照 | **P4** |
297
+
298
+ - A presentation:默认 P1–P4、P6、P10。
299
+ - B research:P5、P7、P8 + 密表;仍禁双大件。
300
+ - C architecture:P9 为主;结构必须真边(见 infographics-structure)。
301
+
302
+ ---
303
+
304
+ ## 八、落地检查清单(交付前)
305
+
306
+ - [ ] 每内容页标注了骨架 ID(P__)
307
+ - [ ] 左缘/顶边眯眼自检通过
308
+ - [ ] 填充率在模式目标带
309
+ - [ ] 图标仅 3–8 且尺寸合规
310
+ - [ ] 图表标签不叠不换行
311
+ - [ ] 卡内无「标题+一行」空卡
312
+ - [ ] Annotation 只有 so-what/口径/页码
313
+ - [ ] `LAYOUT_*` 全 PASS
314
+
315
+ > 整改与实现细节见 `reform-plan.md` §四-b。间距与色 token 见 `design-system.md`。