@bytechain.cn/colamd-themes 0.5.9 → 0.6.0

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.
@@ -1,217 +1,224 @@
1
- #!/usr/bin/env bash
2
- #
3
- # Build agent-specific skill files from the canonical source.
4
- #
5
- # Usage:
6
- # bash skills/build-skills.sh # generate all
7
- # bash skills/build-skills.sh claude # generate for one agent
8
- #
9
- # Source: skills/colamd-themes/SKILL.md
10
- # Output: .{agent}/skills/colamd-themes/SKILL.md (or equivalent)
11
-
12
- set -euo pipefail
13
- cd "$(dirname "$0")/.."
14
-
15
- SOURCE="skills/colamd-themes/SKILL.md"
16
- if [[ ! -f "$SOURCE" ]]; then
17
- echo "Error: Source skill not found: $SOURCE" >&2
18
- exit 1
19
- fi
20
-
21
- # Read the body (everything after the first blank line following the heading).
22
- # Strip CR first: on Windows checkouts the source may use CRLF, and sed's
23
- # `/^$/` cannot match a "\r" line — silently producing an empty BODY and
24
- # truncated skill files (regression shipped in 0.5.2).
25
- BODY=$(sed 's/\r$//' "$SOURCE" | sed -n '/^$/,$ { /^# ColaMD/!p; }' | sed '1{/^$/d;}')
26
- if [[ -z "$BODY" ]]; then
27
- echo "Error: extracted body from $SOURCE is empty (line-ending issue?)" >&2
28
- exit 1
29
- fi
30
-
31
- # ── Frontmatter templates ──
32
-
33
- FRONT_CLAUDE='---
34
- name: colamd-themes
35
- description: >
36
- Generate, validate, export, and manage ColaMD 2.7.8-rc.2 contract CSS themes.
37
- Extract formatting from URLs, DOCX, or PDF sources; export Markdown to
38
- standalone HTML/PDF with themes applied; batch export; manage theme
39
- configuration.
40
- ---'
41
-
42
- FRONT_OPENCODE='---
43
- name: colamd-themes
44
- version: "1.0.0"
45
- description: >
46
- Generate, validate, export, and manage ColaMD 2.7.8-rc.2 contract CSS themes.
47
- Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
48
- user-invocable: true
49
- allowed-tools:
50
- - Read
51
- - Write
52
- - Edit
53
- - Bash
54
- - Glob
55
- - Grep
56
- ---'
57
-
58
- FRONT_OPENCLAW='---
59
- id: colamd-themes
60
- name: ColaMD Themes
61
- description: >
62
- Generate, validate, export, and manage ColaMD 2.7.8-rc.2 contract CSS themes.
63
- Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
64
- version: "1.0.0"
65
- icon: "\U0001F3A8"
66
- author: bytechain
67
- homepage: https://github.com/byteuser1977/ColaMD-themes
68
- user-invocable: true
69
- metadata:
70
- openclaw:
71
- os: [darwin, linux, win32]
72
- clawdbot:
73
- emoji: "\U0001F3A8"
74
- requires:
75
- bins: [node, npm]
76
- ---'
77
-
78
- FRONT_HERMES='---
79
- name: colamd-themes
80
- description: "Generate, validate, export, and manage ColaMD 2.7.8-rc.2 contract CSS themes."
81
- version: 1.0.0
82
- author: bytechain
83
- license: MIT
84
- metadata:
85
- hermes:
86
- tags: [colamd, themes, css, markdown, export, pdf, html]
87
- prerequisites:
88
- commands: [node, npm]
89
- ---'
90
-
91
- FRONT_DSH='---
92
- name: colamd-themes
93
- version: "1.0.0"
94
- description: >
95
- Generate, validate, export, and manage ColaMD 2.7.8-rc.2 contract CSS themes.
96
- Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
97
- metadata:
98
- dsh:
99
- tags: [colamd, themes, css, markdown, export, pdf, html]
100
- prerequisites:
101
- commands: [node, npm]
102
- ---'
103
-
104
- # Trae project skill constraints: description is a single-line plain scalar,
105
- # unquoted, with no ": ", "<", or ">" (router-visible trigger text).
106
- FRONT_TRAE_SKILL='---
107
- name: colamd-themes
108
- description: Generate, validate, and export ColaMD contract CSS themes — extract from URLs, DOCX or PDF, export Markdown to HTML or PDF. Use when the user asks to create, validate, export, or manage ColaMD themes.
109
- ---'
110
-
111
- # ── Generator functions ──
112
-
113
- generate_claude() {
114
- local dir=".claude/skills"
115
- mkdir -p "$dir"
116
- local file="$dir/colamd-themes.skill.md"
117
- echo "$FRONT_CLAUDE" > "$file"
118
- echo "" >> "$file"
119
- echo "$BODY" >> "$file"
120
- echo " → $file"
121
- }
122
-
123
- generate_opencode() {
124
- local dir=".opencode/skills/colamd-themes"
125
- mkdir -p "$dir"
126
- local file="$dir/SKILL.md"
127
- echo "$FRONT_OPENCODE" > "$file"
128
- echo "" >> "$file"
129
- echo "$BODY" >> "$file"
130
- echo " → $file"
131
- }
132
-
133
- generate_openclaw() {
134
- local dir=".openclaw/skills/colamd-themes"
135
- mkdir -p "$dir"
136
- local file="$dir/SKILL.md"
137
- echo "$FRONT_OPENCLAW" > "$file"
138
- echo "" >> "$file"
139
- echo "$BODY" >> "$file"
140
- echo " → $file"
141
- }
142
-
143
- generate_hermes() {
144
- local dir=".hermes/skills/tools/colamd-themes"
145
- mkdir -p "$dir"
146
- local file="$dir/SKILL.md"
147
- echo "$FRONT_HERMES" > "$file"
148
- echo "" >> "$file"
149
- echo "$BODY" >> "$file"
150
- echo " → $file"
151
- }
152
-
153
- generate_dsh() {
154
- local dir=".dsh/skills/colamd-themes"
155
- mkdir -p "$dir"
156
- local file="$dir/SKILL.md"
157
- echo "$FRONT_DSH" > "$file"
158
- echo "" >> "$file"
159
- echo "$BODY" >> "$file"
160
- echo " → $file"
161
- }
162
-
163
- generate_trae() {
164
- local dir=".trae/rules"
165
- mkdir -p "$dir"
166
- local file="$dir/colamd-themes.md"
167
- # Trae uses plain Markdown, no YAML frontmatter
168
- echo "# ColaMD Themes Skill Instructions" > "$file"
169
- echo "" >> "$file"
170
- echo "When the user asks to create, validate, export, or manage ColaMD themes, use the following CLI tool:" >> "$file"
171
- echo "" >> "$file"
172
- echo "$BODY" >> "$file"
173
- echo " → $file"
174
- }
175
-
176
- generate_trae_skill() {
177
- local dir=".trae/skills/colamd-themes"
178
- mkdir -p "$dir"
179
- local file="$dir/SKILL.md"
180
- echo "$FRONT_TRAE_SKILL" > "$file"
181
- echo "" >> "$file"
182
- echo "$BODY" >> "$file"
183
- echo " → $file"
184
- }
185
-
186
- # ── Main ──
187
-
188
- TARGET="${1:-all}"
189
- echo "Building skill files from: $SOURCE"
190
- echo ""
191
-
192
- case "$TARGET" in
193
- claude) generate_claude ;;
194
- opencode) generate_opencode ;;
195
- openclaw) generate_openclaw ;;
196
- hermes) generate_hermes ;;
197
- trae) generate_trae ;;
198
- trae-skill) generate_trae_skill ;;
199
- dsh) generate_dsh ;;
200
- all)
201
- generate_claude
202
- generate_opencode
203
- generate_openclaw
204
- generate_hermes
205
- generate_trae
206
- generate_trae_skill
207
- generate_dsh
208
- ;;
209
- *)
210
- echo "Unknown agent: $TARGET" >&2
211
- echo "Usage: $0 [claude|opencode|openclaw|hermes|trae|trae-skill|dsh|all]" >&2
212
- exit 1
213
- ;;
214
- esac
215
-
216
- echo ""
217
- echo "Done. Skill files generated."
1
+ #!/usr/bin/env bash
2
+ #
3
+ # Build agent-specific skill files from the canonical source.
4
+ #
5
+ # Usage:
6
+ # bash skills/build-skills.sh # generate all
7
+ # bash skills/build-skills.sh claude # generate for one agent
8
+ #
9
+ # Source: skills/colamd-themes/SKILL.md
10
+ # Output: .{agent}/skills/colamd-themes/SKILL.md (or equivalent)
11
+
12
+ set -euo pipefail
13
+ cd "$(dirname "$0")/.."
14
+
15
+ SOURCE="skills/colamd-themes/SKILL.md"
16
+ if [[ ! -f "$SOURCE" ]]; then
17
+ echo "Error: Source skill not found: $SOURCE" >&2
18
+ exit 1
19
+ fi
20
+
21
+ # Read the body (everything after the first blank line following the heading).
22
+ # Strip CR first: on Windows checkouts the source may use CRLF, and sed's
23
+ # `/^$/` cannot match a "\r" line — silently producing an empty BODY and
24
+ # truncated skill files (regression shipped in 0.5.2).
25
+ BODY=$(sed 's/\r$//' "$SOURCE" | sed -n '/^$/,$ { /^# ColaMD/!p; }' | sed '1{/^$/d;}')
26
+ if [[ -z "$BODY" ]]; then
27
+ echo "Error: extracted body from $SOURCE is empty (line-ending issue?)" >&2
28
+ exit 1
29
+ fi
30
+
31
+ # ── Frontmatter templates ──
32
+
33
+ FRONT_CLAUDE='---
34
+ name: colamd-themes
35
+ description: >
36
+ Generate, validate, export, and manage ColaMD 2.7 contract CSS themes
37
+ (2.7.13 anchor, slide layouts stable). Extract formatting from URLs,
38
+ DOCX, or PDF sources (optionally with PPT --slide-* styling); convert
39
+ Markdown into slide-deck Markdown; export Markdown to standalone HTML/PDF
40
+ with themes applied; batch export; manage theme configuration.
41
+ ---'
42
+
43
+ FRONT_OPENCODE='---
44
+ name: colamd-themes
45
+ version: "1.0.0"
46
+ description: >
47
+ Generate, validate, export, and manage ColaMD 2.7 contract CSS themes
48
+ (2.7.13 anchor, slide layouts stable). Extract from URLs/DOCX/PDF
49
+ with optional PPT styling; convert Markdown to slide decks; export
50
+ Markdown to HTML/PDF; batch export.
51
+ user-invocable: true
52
+ allowed-tools:
53
+ - Read
54
+ - Write
55
+ - Edit
56
+ - Bash
57
+ - Glob
58
+ - Grep
59
+ ---'
60
+
61
+ FRONT_OPENCLAW='---
62
+ id: colamd-themes
63
+ name: ColaMD Themes
64
+ description: >
65
+ Generate, validate, export, and manage ColaMD 2.7 contract CSS themes
66
+ (2.7.13 anchor, slide layouts stable). Extract from URLs/DOCX/PDF
67
+ with optional PPT styling; convert Markdown to slide decks; export
68
+ Markdown to HTML/PDF; batch export.
69
+ version: "1.0.0"
70
+ icon: "\U0001F3A8"
71
+ author: bytechain
72
+ homepage: https://github.com/byteuser1977/ColaMD-themes
73
+ user-invocable: true
74
+ metadata:
75
+ openclaw:
76
+ os: [darwin, linux, win32]
77
+ clawdbot:
78
+ emoji: "\U0001F3A8"
79
+ requires:
80
+ bins: [node, npm]
81
+ ---'
82
+
83
+ FRONT_HERMES='---
84
+ name: colamd-themes
85
+ description: "Generate, validate, export, and manage ColaMD 2.7 contract CSS themes with PPT slide layouts; convert Markdown to slide decks; export HTML/PDF."
86
+ version: 1.0.0
87
+ author: bytechain
88
+ license: MIT
89
+ metadata:
90
+ hermes:
91
+ tags: [colamd, themes, css, markdown, export, pdf, html]
92
+ prerequisites:
93
+ commands: [node, npm]
94
+ ---'
95
+
96
+ FRONT_DSH='---
97
+ name: colamd-themes
98
+ version: "1.0.0"
99
+ description: >
100
+ Generate, validate, export, and manage ColaMD 2.7 contract CSS themes
101
+ (2.7.13 anchor, slide layouts stable). Extract from URLs/DOCX/PDF
102
+ with optional PPT styling; convert Markdown to slide decks; export
103
+ Markdown to HTML/PDF; batch export.
104
+ metadata:
105
+ dsh:
106
+ tags: [colamd, themes, css, markdown, export, pdf, html]
107
+ prerequisites:
108
+ commands: [node, npm]
109
+ ---'
110
+
111
+ # Trae project skill constraints: description is a single-line plain scalar,
112
+ # unquoted, with no ": ", "<", or ">" (router-visible trigger text).
113
+ FRONT_TRAE_SKILL='---
114
+ name: colamd-themes
115
+ description: Generate, validate, and export ColaMD contract CSS themes with PPT slide layout support — extract from URLs, DOCX or PDF (optionally with PPT --slide-* styling), convert Markdown to slide-deck Markdown, export Markdown to HTML or PDF. Use when the user asks to create, validate, export, or manage ColaMD themes, or to generate PPT slides from Markdown.
116
+ ---'
117
+
118
+ # ── Generator functions ──
119
+
120
+ generate_claude() {
121
+ local dir=".claude/skills"
122
+ mkdir -p "$dir"
123
+ local file="$dir/colamd-themes.skill.md"
124
+ echo "$FRONT_CLAUDE" > "$file"
125
+ echo "" >> "$file"
126
+ echo "$BODY" >> "$file"
127
+ echo " → $file"
128
+ }
129
+
130
+ generate_opencode() {
131
+ local dir=".opencode/skills/colamd-themes"
132
+ mkdir -p "$dir"
133
+ local file="$dir/SKILL.md"
134
+ echo "$FRONT_OPENCODE" > "$file"
135
+ echo "" >> "$file"
136
+ echo "$BODY" >> "$file"
137
+ echo " → $file"
138
+ }
139
+
140
+ generate_openclaw() {
141
+ local dir=".openclaw/skills/colamd-themes"
142
+ mkdir -p "$dir"
143
+ local file="$dir/SKILL.md"
144
+ echo "$FRONT_OPENCLAW" > "$file"
145
+ echo "" >> "$file"
146
+ echo "$BODY" >> "$file"
147
+ echo " → $file"
148
+ }
149
+
150
+ generate_hermes() {
151
+ local dir=".hermes/skills/tools/colamd-themes"
152
+ mkdir -p "$dir"
153
+ local file="$dir/SKILL.md"
154
+ echo "$FRONT_HERMES" > "$file"
155
+ echo "" >> "$file"
156
+ echo "$BODY" >> "$file"
157
+ echo " → $file"
158
+ }
159
+
160
+ generate_dsh() {
161
+ local dir=".dsh/skills/colamd-themes"
162
+ mkdir -p "$dir"
163
+ local file="$dir/SKILL.md"
164
+ echo "$FRONT_DSH" > "$file"
165
+ echo "" >> "$file"
166
+ echo "$BODY" >> "$file"
167
+ echo " → $file"
168
+ }
169
+
170
+ generate_trae() {
171
+ local dir=".trae/rules"
172
+ mkdir -p "$dir"
173
+ local file="$dir/colamd-themes.md"
174
+ # Trae uses plain Markdown, no YAML frontmatter
175
+ echo "# ColaMD Themes Skill Instructions" > "$file"
176
+ echo "" >> "$file"
177
+ echo "When the user asks to create, validate, export, or manage ColaMD themes, use the following CLI tool:" >> "$file"
178
+ echo "" >> "$file"
179
+ echo "$BODY" >> "$file"
180
+ echo " → $file"
181
+ }
182
+
183
+ generate_trae_skill() {
184
+ local dir=".trae/skills/colamd-themes"
185
+ mkdir -p "$dir"
186
+ local file="$dir/SKILL.md"
187
+ echo "$FRONT_TRAE_SKILL" > "$file"
188
+ echo "" >> "$file"
189
+ echo "$BODY" >> "$file"
190
+ echo " → $file"
191
+ }
192
+
193
+ # ── Main ──
194
+
195
+ TARGET="${1:-all}"
196
+ echo "Building skill files from: $SOURCE"
197
+ echo ""
198
+
199
+ case "$TARGET" in
200
+ claude) generate_claude ;;
201
+ opencode) generate_opencode ;;
202
+ openclaw) generate_openclaw ;;
203
+ hermes) generate_hermes ;;
204
+ trae) generate_trae ;;
205
+ trae-skill) generate_trae_skill ;;
206
+ dsh) generate_dsh ;;
207
+ all)
208
+ generate_claude
209
+ generate_opencode
210
+ generate_openclaw
211
+ generate_hermes
212
+ generate_trae
213
+ generate_trae_skill
214
+ generate_dsh
215
+ ;;
216
+ *)
217
+ echo "Unknown agent: $TARGET" >&2
218
+ echo "Usage: $0 [claude|opencode|openclaw|hermes|trae|trae-skill|dsh|all]" >&2
219
+ exit 1
220
+ ;;
221
+ esac
222
+
223
+ echo ""
224
+ echo "Done. Skill files generated."
@@ -1,6 +1,6 @@
1
1
  # ColaMD Themes — Universal AI Agent Skill
2
2
 
3
- Generate, validate, export, and manage ColaMD **2.7.12 contract** CSS themes. Extract formatting from URLs, DOCX, or PDF sources; export Markdown to standalone HTML/PDF with themes applied; batch export; manage theme configuration.
3
+ Generate, validate, export, and manage ColaMD **2.7 contract** CSS themes (2.7.13 anchor, slide layouts stable). Extract formatting from URLs, DOCX, or PDF sources (optionally with PPT `--slide-*` styling); convert Markdown into slide-deck Markdown; export Markdown to standalone HTML/PDF with themes applied; batch export; manage theme configuration.
4
4
 
5
5
  ## Prerequisites
6
6
 
@@ -48,10 +48,10 @@ colamd-themes set-theme <name> --remove
48
48
  ```bash
49
49
  colamd-themes color-systems [-j]
50
50
  colamd-themes list [-d <dir>]
51
- colamd-themes validate <file.css>
51
+ colamd-themes validate <file.css | file.md>
52
52
  ```
53
53
 
54
- `validate` prints a **platform compat line** ("平台兼容") — it reports the installed `@bytechain.cn/colamd` version and whether its `themes/contract.json` matches the 2.7.12 theme contract. On drift it lists missing live variables; treat that as a signal to check the platform changelog or pin `@bytechain.cn/colamd@^2.7.12`.
54
+ `validate` accepts theme CSS **and** slides markdown (`.md` → directive contract checks). It prints a **platform compat line** ("平台兼容") — it reports the installed `@bytechain.cn/colamd` version, whether its `themes/contract.json` matches the theme contract (2.7.13 and 2.7.13 are both accepted), and whether the **slide layout system** is available (幻灯片版式: 支持/不支持). On drift it lists missing live variables; treat that as a signal to check the platform changelog or pin `@bytechain.cn/colamd@^2.7.13`.
55
55
 
56
56
  ## Options
57
57
 
@@ -64,6 +64,7 @@ colamd-themes validate <file.css>
64
64
  | `-d, --themes-dir` | Themes directory (default: `themes/`) |
65
65
  | `-c, --color-system` | Force a color system |
66
66
  | `-A, --auto-match` | Auto-match a color system from the extracted palette |
67
+ | `--ppt [style]` | Also emit PPT `--slide-*` tokens (2.7.13 slides); optional preset `serif` (default) / `sans` / `mono`. Off by default |
67
68
 
68
69
  ### Export options
69
70
 
@@ -139,7 +140,93 @@ Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
139
140
  8. `buildExportHTML()` → standalone HTML with embedded CSS
140
141
  9. For PDF: load the export HTML in a fresh page + `page.pdf()` — do NOT `emulateMediaType('screen')`, the theme's `@media print` rules (with `print-color-adjust: exact`) must apply
141
142
 
142
- ## 2.7.12 Contract Constraints
143
+ ## Slide Layouts (ColaMD 2.7.13 幻灯片版式)
144
+
145
+ Upstream 2.7.13 adds a slide deck system. A deck is plain markdown: pages split on `---`, each page may open with a header comment block.
146
+
147
+ ### Directive syntax
148
+
149
+ ```markdown
150
+ <!-- deck
151
+ logo: ./assets/logo.png
152
+ brand: 你的品牌
153
+ title: 报告标题
154
+ meta: 2026.11 · 汇报版
155
+ -->
156
+
157
+ ---
158
+
159
+ <!-- slide: kpi
160
+ kicker: Executive Summary
161
+ label: 核心数据速览
162
+ chapter: Act I · 数据
163
+ -->
164
+
165
+ ## 页标题
166
+
167
+ 标题后的第一段自动成为导语。
168
+
169
+ - **数字** 说明
170
+ ```
171
+
172
+ - `<!-- slide: 名字 … -->` 页头块:**仅页首生效**(该页第一个真实内容之前);第一行是版式名 `[a-z][a-z0-9-]*`,后续行是字段 `kicker / label / chapter`。单行 `<!-- slide: cover -->` 与 `<!-- slide-kicker: … -->` 旧写法兼容。
173
+ - 页角色由 Markdown 结构决定:一页第一个标题(h1/h2 同权)是页标题,标题后第一段是导语,标题前紧邻段落兜底当 kicker。
174
+ - `<!-- slide-css h1 { … } -->` 页内 CSS 微调(白名单清洗,拒 `position: absolute/fixed`、`z-index`、伪协议);`<!-- slide-js … -->` 页内脚本(放映沙箱执行,导出不执行)。
175
+ - deck 块配置每页 chrome:logo / brand / title / meta,文档顶部写一次。
176
+
177
+ ### 11 built-in layouts
178
+
179
+ | 版式 | 内容约定 |
180
+ |---|---|
181
+ | `cover` | 首页 h1 主标题 + h2 副标题 + 首段导语 |
182
+ | `section` | 一个短标题 + 一句说明,大留白 |
183
+ | `agenda` | 有序列表 3-6 项 `**章名** 说明` |
184
+ | `kpi` | 无序列表 2-6 项 `**数字+单位** 说明` |
185
+ | `timeline` | 列表项带年份/日期 `**2019 年** 事件` |
186
+ | `steps` | 有序列表 3-5 项 `**步骤名** 说明` |
187
+ | `matrix` | 无序列表 3-8 项 `**名称** 说明` |
188
+ | `two-col` | 两个 h2 对半(左论点/右证据) |
189
+ | `figure` | 图片 / Mermaid / 表格为主体的页 |
190
+ | `quote` | 引用块为主体的页,引用后一行可作署名 |
191
+ | `closing` | 末页行动清单 |
192
+
193
+ 未声明版式的页自动走默认文章版式;未知版式名无害降级。
194
+
195
+ ### Markdown → PPT Markdown
196
+
197
+ ```bash
198
+ colamd-themes to-slides <input.md> -o <output.md>
199
+ colamd-themes to-slides report.md --deck-brand "品牌" --deck-title "报告" --deck-meta "2026.11"
200
+ ```
201
+
202
+ 按内容结构自动分页并推断上述 11 种版式,生成 deck 块与页头块(kicker/chapter 随章节推进)。生成后自动跑指令契约校验。
203
+
204
+ ### Slide rule validation
205
+
206
+ ```bash
207
+ colamd-themes validate deck.md
208
+ ```
209
+
210
+ - **SLIDES-01** (MUST_NOT):slide 页头块出现在页首内容之后(上游会降级为普通注释)
211
+ - **SLIDES-02** (MUST_NOT):版式名不符合 `[a-z][a-z0-9-]*`
212
+ - **SLIDES-03** (SHOULD):未知版式名(无害降级)
213
+ - **SLIDES-04/05** (MUST_NOT):页头块字段键 ∉ kicker/label/chapter、deck 键 ∉ logo/brand/title/meta
214
+ - **SLIDES-06** (MUST_NOT):slide-css 含 `position: absolute/fixed`、`z-index`、伪协议 URL
215
+
216
+ ### PPT style tokens (--slide-*)
217
+
218
+ Upstream `slides.css` defines ~26 `--slide-*` tokens on `:root` (title font/size/weight/tracking, kicker, chrome, page padding, KPI/quote sizes). Themes can override them — **`--ppt [style]`** emits a token section into the generated theme:
219
+
220
+ ```bash
221
+ colamd-themes from-url <URL> -n my-brand --ppt sans # presets: serif | sans | mono
222
+ ```
223
+
224
+ - serif = 上游杂志衬线默认;sans = Notion 气质(无衬线、居中封面);mono = Writer 气质(等宽标题)。品牌层只派生 `--slide-title-font` / `--slide-mono` / `--slide-title-weight`,版式字号阶梯保持上游默认。
225
+ - 自定义主题 CSS 在 slides.css 之后加载,`:root` 同权重后到先赢;不要写 `body.theme-custom`(文档契约死选择器)。
226
+ - 手写主题里的幻灯片规则须遵守:**SLIDE-01** (SHOULD) 只用已知令牌;**SLIDE-02** (MUST_NOT) `.cm-md-page-*` / `.cm-md-slide-*` / `.slide-chrome|foot|ghost` 必须包裹在 `body.presenting` 或 `body.slides-printing` 作用域下(裸写污染编辑视图);**SLIDE-03** (SHOULD) 标题字体栈含中文字族并以 generic family 结尾。
227
+ - 平台需 ≥ 2.7.13 才消费这些令牌(compat 行「幻灯片版式」);旧平台下令牌惰性。导出的 HTML/PDF 仍为文档式排版,放映版式在 ColaMD 应用内查看。
228
+
229
+ ## 2.7 Contract Constraints
143
230
 
144
231
  - Variables live in `:root`; anything in `body.theme-*` is ignored
145
232
  - Live variables only: `--bg-color --text-color --text-secondary --text-muted --border-color --link-color --code-bg --code-block-bg --code-block-text --blockquote-border --blockquote-bg --table-header-bg --selection-bg --highlight-bg --font-body --font-mono --editor-font-size --editor-column-width` + `--pele-*`
@@ -183,9 +270,9 @@ Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
183
270
  ## Architecture
184
271
 
185
272
  ```
186
- Source → Extractor → ThemeStyle → Color System + Pele + Validators → CSS (2.7.12 contract)
273
+ Source → Extractor → ThemeStyle → Color System + Pele + Validators → CSS (2.7.13 contract)
187
274
 
188
275
  Markdown → Puppeteer + ColaMD renderer → HTML / PDF
189
276
  ```
190
277
 
191
- > Export runs the ColaMD 2.x library renderer (`@bytechain.cn/colamd@^2.7.12` ships `dist/lib/colamd-renderer.js` + `colamd.css`); the same CM6 editor as the app runs headless via Puppeteer. Theme CSS is consumed directly as `:root` declarations and `buildExportHTML({ title })` serializes only contract live variables. Generated CSS targets the 2.7.12 contract (unchanged since 2.7.7, machine-readable as `themes/contract.json` in the npm package), so it carries over unchanged. Platform upgrades are handled by a compat layer (`src/compat.ts`): contract drift is reported by `validate` and non-fatally at export, and the renderer API surface is probed at init — upgrades produce actionable diagnostics, not crashes.
278
+ > Export runs the ColaMD 2.x library renderer (`@bytechain.cn/colamd@^2.7.13` ships `dist/lib/colamd-renderer.js` + `colamd.css`); the same CM6 editor as the app runs headless via Puppeteer. Theme CSS is consumed directly as `:root` declarations and `buildExportHTML({ title })` serializes only contract live variables. Generated CSS targets the 2.7.13 contract (unchanged since 2.7.7, machine-readable as `themes/contract.json` in the npm package), so it carries over unchanged. Platform upgrades are handled by a compat layer (`src/compat.ts`): contract drift is reported by `validate` and non-fatally at export, and the renderer API surface is probed at init — upgrades produce actionable diagnostics, not crashes.