@bytechain.cn/colamd-themes 0.5.9 → 0.6.1
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.
- package/README.md +85 -19
- package/dist/cli.js +70 -6
- package/dist/cli.js.map +1 -1
- package/dist/compat.d.ts +23 -3
- package/dist/compat.js +71 -12
- package/dist/compat.js.map +1 -1
- package/dist/dsh-plugin.js +1 -1
- package/dist/generator.d.ts +1 -1
- package/dist/generator.js +5 -2
- package/dist/generator.js.map +1 -1
- package/dist/models.d.ts +7 -1
- package/dist/models.js +1 -1
- package/dist/models.js.map +1 -1
- package/dist/renderer.d.ts +1 -1
- package/dist/renderer.js +21 -3
- package/dist/renderer.js.map +1 -1
- package/dist/slides-markdown.d.ts +45 -0
- package/dist/slides-markdown.js +515 -0
- package/dist/slides-markdown.js.map +1 -0
- package/dist/slides.d.ts +36 -0
- package/dist/slides.js +149 -0
- package/dist/slides.js.map +1 -0
- package/dist/templates/theme-template.hbs +11 -0
- package/dist/validators.d.ts +2 -2
- package/dist/validators.js +71 -4
- package/dist/validators.js.map +1 -1
- package/package.json +3 -2
- package/skills/build-skills.sh +224 -217
- package/skills/colamd-themes/SKILL.md +178 -6
- package/themes/8-bit-orbit.css +817 -0
- package/themes/README.md +69 -0
- package/themes/biennale-yellow.css +577 -0
- package/themes/block-frame.css +774 -0
- package/themes/blue-professional.css +741 -0
- package/themes/bold-poster.css +794 -0
- package/themes/broadside.css +837 -0
- package/themes/capsule.css +767 -0
- package/themes/cartesian.css +584 -0
- package/themes/cobalt-grid.css +632 -0
- package/themes/coral.css +699 -0
- package/themes/creative-mode.css +642 -0
- package/themes/daisy-days.css +1052 -0
- package/themes/editorial-forest.css +796 -0
- package/themes/editorial-tri-tone.css +811 -0
- package/themes/emerald-editorial.css +683 -0
- package/themes/grove.css +623 -0
- package/themes/indigo-deck.css +336 -0
- package/themes/indigo-porcelain-light.css +335 -0
- package/themes/long-table.css +782 -0
- package/themes/mat.css +848 -0
- package/themes/monochrome.css +782 -0
- package/themes/neo-grid-bold.css +838 -0
- package/themes/peoples-platform.css +843 -0
- package/themes/pin-and-paper.css +700 -0
- package/themes/pink-script-dark.css +648 -0
- package/themes/pink-script.css +290 -0
- package/themes/playful.css +774 -0
- package/themes/raw-grid.css +814 -0
- package/themes/retro-windows.css +767 -0
- package/themes/retro-zine.css +814 -0
- package/themes/sakura-chroma.css +775 -0
- package/themes/scatterbrain.css +726 -0
- package/themes/signal.css +872 -0
- package/themes/soft-editorial.css +788 -0
- package/themes/stencil-tablet.css +922 -0
- package/themes/studio.css +767 -0
- package/themes/swiss-lemon-dark.css +529 -0
- package/themes/swiss-lemon-light.css +375 -0
- package/themes/vellum.css +723 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# ColaMD Themes — Universal AI Agent Skill
|
|
2
2
|
|
|
3
|
-
Generate, validate, export, and manage ColaMD **2.7
|
|
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
|
|
|
@@ -14,11 +14,21 @@ Generate, validate, export, and manage ColaMD **2.7.12 contract** CSS themes. Ex
|
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
16
|
colamd-themes from-url <URL> [options]
|
|
17
|
+
colamd-themes from-html <file> [options]
|
|
17
18
|
colamd-themes from-docx <file> [options]
|
|
18
19
|
colamd-themes from-pdf <file> [options]
|
|
19
20
|
colamd-themes extract <source> [options]
|
|
20
21
|
```
|
|
21
22
|
|
|
23
|
+
`from-html` extracts from a **local HTML file** (v0.6.1+). A sibling
|
|
24
|
+
`template.json` — when present — supplies authoritative metadata: slug/tagline
|
|
25
|
+
as theme name/description, `typography.display/body/mono` (+ `serif_cn` /
|
|
26
|
+
`sans_cn`) as CJK-safe font stacks, `scheme`/`density`/`formality`/`mood` as
|
|
27
|
+
slide design hints. Colors come from the template's `:root` custom properties
|
|
28
|
+
(semantic-name matching first, luminance/saturation heuristics as fallback);
|
|
29
|
+
the palette is sanitized to satisfy the paradigm's luminance ordering (SL-04)
|
|
30
|
+
and contrast rules (CR-02). `extract` auto-detects local `.html/.htm` too.
|
|
31
|
+
|
|
22
32
|
### Export to HTML / PDF
|
|
23
33
|
|
|
24
34
|
```bash
|
|
@@ -48,10 +58,10 @@ colamd-themes set-theme <name> --remove
|
|
|
48
58
|
```bash
|
|
49
59
|
colamd-themes color-systems [-j]
|
|
50
60
|
colamd-themes list [-d <dir>]
|
|
51
|
-
colamd-themes validate <file.css>
|
|
61
|
+
colamd-themes validate <file.css | file.md>
|
|
52
62
|
```
|
|
53
63
|
|
|
54
|
-
`validate` prints a **platform compat line** ("平台兼容") — it reports the installed `@bytechain.cn/colamd` version
|
|
64
|
+
`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
65
|
|
|
56
66
|
## Options
|
|
57
67
|
|
|
@@ -64,6 +74,7 @@ colamd-themes validate <file.css>
|
|
|
64
74
|
| `-d, --themes-dir` | Themes directory (default: `themes/`) |
|
|
65
75
|
| `-c, --color-system` | Force a color system |
|
|
66
76
|
| `-A, --auto-match` | Auto-match a color system from the extracted palette |
|
|
77
|
+
| `--ppt [style]` | Also emit PPT `--slide-*` tokens (2.7.13 slides); optional preset `serif` (default) / `sans` / `mono`. Off by default. A valueless `--ppt` keeps the preset auto-detected by the extractor (from-html templates) |
|
|
67
78
|
|
|
68
79
|
### Export options
|
|
69
80
|
|
|
@@ -139,7 +150,94 @@ Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
|
|
|
139
150
|
8. `buildExportHTML()` → standalone HTML with embedded CSS
|
|
140
151
|
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
152
|
|
|
142
|
-
## 2.7.
|
|
153
|
+
## Slide Layouts (ColaMD 2.7.13 幻灯片版式)
|
|
154
|
+
|
|
155
|
+
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.
|
|
156
|
+
|
|
157
|
+
### Directive syntax
|
|
158
|
+
|
|
159
|
+
```markdown
|
|
160
|
+
<!-- deck
|
|
161
|
+
logo: ./assets/logo.png
|
|
162
|
+
brand: 你的品牌
|
|
163
|
+
title: 报告标题
|
|
164
|
+
meta: 2026.11 · 汇报版
|
|
165
|
+
-->
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
<!-- slide: kpi
|
|
170
|
+
kicker: Executive Summary
|
|
171
|
+
label: 核心数据速览
|
|
172
|
+
chapter: Act I · 数据
|
|
173
|
+
-->
|
|
174
|
+
|
|
175
|
+
## 页标题
|
|
176
|
+
|
|
177
|
+
标题后的第一段自动成为导语。
|
|
178
|
+
|
|
179
|
+
- **数字** 说明
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
- `<!-- slide: 名字 … -->` 页头块:**仅页首生效**(该页第一个真实内容之前);第一行是版式名 `[a-z][a-z0-9-]*`,后续行是字段 `kicker / label / chapter`。单行 `<!-- slide: cover -->` 与 `<!-- slide-kicker: … -->` 旧写法兼容。
|
|
183
|
+
- 页角色由 Markdown 结构决定:一页第一个标题(h1/h2 同权)是页标题,标题后第一段是导语,标题前紧邻段落兜底当 kicker。
|
|
184
|
+
- `<!-- slide-css h1 { … } -->` 页内 CSS 微调(白名单清洗,拒 `position: absolute/fixed`、`z-index`、伪协议);`<!-- slide-js … -->` 页内脚本(放映沙箱执行,导出不执行)。
|
|
185
|
+
- deck 块配置每页 chrome:logo / brand / title / meta,文档顶部写一次。
|
|
186
|
+
|
|
187
|
+
### 11 built-in layouts
|
|
188
|
+
|
|
189
|
+
| 版式 | 内容约定 |
|
|
190
|
+
|---|---|
|
|
191
|
+
| `cover` | 首页 h1 主标题 + h2 副标题 + 首段导语 |
|
|
192
|
+
| `section` | 一个短标题 + 一句说明,大留白 |
|
|
193
|
+
| `agenda` | 有序列表 3-6 项 `**章名** 说明` |
|
|
194
|
+
| `kpi` | 无序列表 2-6 项 `**数字+单位** 说明` |
|
|
195
|
+
| `timeline` | 列表项带年份/日期 `**2019 年** 事件` |
|
|
196
|
+
| `steps` | 有序列表 3-5 项 `**步骤名** 说明` |
|
|
197
|
+
| `matrix` | 无序列表 3-8 项 `**名称** 说明` |
|
|
198
|
+
| `two-col` | 两个 h2 对半(左论点/右证据) |
|
|
199
|
+
| `figure` | 图片 / Mermaid / 表格为主体的页 |
|
|
200
|
+
| `quote` | 引用块为主体的页,引用后一行可作署名 |
|
|
201
|
+
| `closing` | 末页行动清单 |
|
|
202
|
+
|
|
203
|
+
未声明版式的页自动走默认文章版式;未知版式名无害降级。
|
|
204
|
+
|
|
205
|
+
### Markdown → PPT Markdown
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
colamd-themes to-slides <input.md> -o <output.md>
|
|
209
|
+
colamd-themes to-slides report.md --deck-brand "品牌" --deck-title "报告" --deck-meta "2026.11"
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
按内容结构自动分页并推断上述 11 种版式,生成 deck 块与页头块(kicker/chapter 随章节推进)。生成后自动跑指令契约校验。
|
|
213
|
+
|
|
214
|
+
### Slide rule validation
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
colamd-themes validate deck.md
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
- **SLIDES-01** (MUST_NOT):slide 页头块出现在页首内容之后(上游会降级为普通注释)
|
|
221
|
+
- **SLIDES-02** (MUST_NOT):版式名不符合 `[a-z][a-z0-9-]*`
|
|
222
|
+
- **SLIDES-03** (SHOULD):未知版式名(无害降级)
|
|
223
|
+
- **SLIDES-04/05** (MUST_NOT):页头块字段键 ∉ kicker/label/chapter、deck 键 ∉ logo/brand/title/meta
|
|
224
|
+
- **SLIDES-06** (MUST_NOT):slide-css 含 `position: absolute/fixed`、`z-index`、伪协议 URL
|
|
225
|
+
|
|
226
|
+
### PPT style tokens (--slide-*)
|
|
227
|
+
|
|
228
|
+
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:
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
colamd-themes from-url <URL> -n my-brand --ppt sans # presets: serif | sans | mono
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
- serif = 上游杂志衬线默认;sans = Notion 气质(无衬线、居中封面);mono = Writer 气质(等宽标题)。品牌层只派生 `--slide-title-font` / `--slide-mono` / `--slide-title-weight`,版式字号阶梯保持上游默认。
|
|
235
|
+
- **v0.6.1 全量版式令牌**:`from-html` 模板来源提供设计提示(`--sz-*` 字号阶梯 + template.json 的 mood/density/formality/scheme)时,生成 **24 个按页类型定制的令牌**——封面/章节/收页字号阶梯取自模板 display/body 比例,页标题 / KPI / 引言 / kicker / chrome / 页边距按气质(bold/quiet/tech)与密度调校;`--ppt` 不带值时信任按 display 字体自动判定的预设。无设计提示的主题保持仅品牌层输出(向后兼容)。
|
|
236
|
+
- 自定义主题 CSS 在 slides.css 之后加载,`:root` 同权重后到先赢;不要写 `body.theme-custom`(文档契约死选择器)。
|
|
237
|
+
- 手写主题里的幻灯片规则须遵守:**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 结尾。
|
|
238
|
+
- 平台需 ≥ 2.7.13 才消费这些令牌(compat 行「幻灯片版式」);旧平台下令牌惰性。导出的 HTML/PDF 仍为文档式排版,放映版式在 ColaMD 应用内查看。
|
|
239
|
+
|
|
240
|
+
## 2.7 Contract Constraints
|
|
143
241
|
|
|
144
242
|
- Variables live in `:root`; anything in `body.theme-*` is ignored
|
|
145
243
|
- 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-*`
|
|
@@ -152,6 +250,52 @@ Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
|
|
|
152
250
|
- Generated CSS ≤ 300 lines
|
|
153
251
|
- Font stacks must include CJK fallback and end with generic family
|
|
154
252
|
|
|
253
|
+
## Reference-Template Refinement (page-by-page replication)
|
|
254
|
+
|
|
255
|
+
Use when the task is to reproduce a multi-page PPT template
|
|
256
|
+
(`beautiful-html-templates/templates/<slug>/template.html`) as a ColaMD 2.7.13
|
|
257
|
+
slide theme (`themes/<slug>.css`) with strict fidelity. Full methodology:
|
|
258
|
+
`docs/slide-theme-replication.md`. Reference themes: `themes/biennale-yellow.css`
|
|
259
|
+
(header / token / section-1.6 structure) and `themes/pin-and-paper.css`
|
|
260
|
+
(page-background layer chain).
|
|
261
|
+
|
|
262
|
+
### Workflow
|
|
263
|
+
|
|
264
|
+
1. **Read the template**: `:root` palette + fonts, then every page section's
|
|
265
|
+
background / title / subtitle / body / object box (padding, radius, shadow).
|
|
266
|
+
2. **Map pages to layouts**: cover / section / agenda / kpi / timeline / steps /
|
|
267
|
+
matrix / two-col / figure / quote / closing. A mapping supplied by the user
|
|
268
|
+
always wins over your own inference; record it in the file header and §1.5.
|
|
269
|
+
3. **Convert**: 26px per em (presenting base `clamp(17px,1.35vw,26px)` @1920×1080);
|
|
270
|
+
template px ÷ 26, taking clamp() landing points at 1920. For inline children,
|
|
271
|
+
fix the li base size first, then divide by that scale.
|
|
272
|
+
4. **Write**: §1.5 `--slide-*` tokens (formula in every comment) → §1.6 scoped
|
|
273
|
+
per-layout rules (composite selectors, SLIDE-02 scopes) → §2/§3 mirrored
|
|
274
|
+
editor/export rules → §4 print.
|
|
275
|
+
5. **Validate**: `npx tsx src/cli.ts validate themes/<slug>.css` must report
|
|
276
|
+
contract pass + slide-layout support + zero SLIDE- / SLIDES- / CSS-03
|
|
277
|
+
findings. Paradigm errors are allowed only for identity items documented in
|
|
278
|
+
the file header.
|
|
279
|
+
|
|
280
|
+
### Fidelity checklist (walk every page)
|
|
281
|
+
|
|
282
|
+
- **Background**: swapped-background pages need the full 5-layer chain; ordinary
|
|
283
|
+
pages must not paint a page-level background.
|
|
284
|
+
- **Title**: family / weight / size / line-height / tracking / color / alignment /
|
|
285
|
+
max-width.
|
|
286
|
+
- **Subtitle & kicker**: size, tracking, transform, opacity.
|
|
287
|
+
- **Body**: li base scale + `.cm-md-strong` row title + `.cm-md-listmark`
|
|
288
|
+
number/date; redraw card borders instead of keeping capsule defaults.
|
|
289
|
+
- **Position**: page-level vertical centering, page padding, object-box width
|
|
290
|
+
(border-box, padding included), inter-row gaps.
|
|
291
|
+
|
|
292
|
+
### Batch runs
|
|
293
|
+
|
|
294
|
+
One theme = one file, so templates can be dispatched in parallel (max 5
|
|
295
|
+
concurrent sub-agents). After each batch verify the file's size/mtime actually
|
|
296
|
+
changed — an unchanged file means a lost run, so re-dispatch it. Run `validate`
|
|
297
|
+
once over every theme at the end.
|
|
298
|
+
|
|
155
299
|
## CSS Pitfall Quick Reference
|
|
156
300
|
|
|
157
301
|
> When adjusting themes, follow these rules strictly. Reference `themes/template.css` and the upstream examples in `ColaMD-extend/resources/templates/themes/`.
|
|
@@ -180,12 +324,40 @@ Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
|
|
|
180
324
|
|
|
181
325
|
**Pitfall:** Writing `themeVariables` or Mermaid `classDef` in the theme. **Correct:** override `--pele-*` on `:root`; the SVG reads them at render time.
|
|
182
326
|
|
|
327
|
+
### 7. Layout class and line-role class share one div
|
|
328
|
+
|
|
329
|
+
**Pitfall:** `.cm-md-slide-quote .cm-md-blockquote` (descendant form). **Correct:** `.cm-md-slide-quote.cm-md-blockquote` — the layout class is a line decoration stamped on the same div, so upstream descendant selectors miss in the editor DOM.
|
|
330
|
+
|
|
331
|
+
### 8. Page-level vertical centering
|
|
332
|
+
|
|
333
|
+
**Pitfall:** The template centers every page (`.slide` = flex column + `justify-content:center`), while upstream only centers cover / section / closing / two-col. **Correct:** single-column layouts get `display:flex; flex-direction:column; justify-content:safe center; min-height:92vh`. Card grids (kpi / matrix / steps / timeline) must keep inline-block flow, so use `flex-wrap:wrap` + `align-content:safe center`, cards `flex:0 0 auto`, every other line `flex:0 0 100%`; also `display:none` the page directive and zero the first line's top padding.
|
|
334
|
+
|
|
335
|
+
### 9. Per-item color rotation
|
|
336
|
+
|
|
337
|
+
**Pitfall:** Painting every card with the first card's color. **Correct:** target index N with `:nth-child(2 of .cm-md-slide-kpi.cm-md-li) .cm-md-strong` (Chrome 111+); older engines fall back to the base color.
|
|
338
|
+
|
|
339
|
+
### 10. No commas inside `:nth-child(... of ...)`
|
|
340
|
+
|
|
341
|
+
**Pitfall:** `:nth-child(1 of A, B)` — the validator splits the selector at the comma and flags the second half as unscoped (SLIDE-02). **Correct:** one selector per rule, e.g. `:nth-child(1 of .cm-md-slide-section.cm-md-li)`.
|
|
342
|
+
|
|
343
|
+
### 11. Object-box width is border-box
|
|
344
|
+
|
|
345
|
+
**Pitfall:** A template `max-width:750px` already includes its 56px padding; drawing the rows at `max-width:866px` makes the box 116px too wide. **Correct:** keep the template's outer width and subtract padding from the content width — never add.
|
|
346
|
+
|
|
347
|
+
### 12. Upstream `.cm-md-li` margins
|
|
348
|
+
|
|
349
|
+
**Pitfall:** Adding `padding-block` for list gaps while upstream keeps `margin:0.45em 0` turns an 18px gap into 29px. **Correct:** zero `margin-block` first; detect first/last rows with `:has(~ .cm-md-slide-x.cm-md-li)` (not `+`) so blank lines do not break detection.
|
|
350
|
+
|
|
351
|
+
### 13. Verify before inventing
|
|
352
|
+
|
|
353
|
+
**Pitfall:** Assuming a decorative or motion layer exists on a page. **Correct:** full-text search the template first; when it is absent, say so in the header's "not replicated" note instead of inventing a layout.
|
|
354
|
+
|
|
183
355
|
## Architecture
|
|
184
356
|
|
|
185
357
|
```
|
|
186
|
-
Source → Extractor → ThemeStyle → Color System + Pele + Validators → CSS (2.7.
|
|
358
|
+
Source → Extractor → ThemeStyle → Color System + Pele + Validators → CSS (2.7.13 contract)
|
|
187
359
|
|
|
188
360
|
Markdown → Puppeteer + ColaMD renderer → HTML / PDF
|
|
189
361
|
```
|
|
190
362
|
|
|
191
|
-
> Export runs the ColaMD 2.x library renderer (`@bytechain.cn/colamd@^2.7.
|
|
363
|
+
> 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.
|