@bytechain.cn/colamd-themes 0.3.1 → 0.3.2

package/.openclaw/skills/colamd-themes/SKILL.md

@@ -18,144 +18,35 @@ metadata:
       bins: [node, npm]
 ---
 
-Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes. Extract formatting from URLs, DOCX, or PDF sources; export Markdown to standalone HTML/PDF with themes applied; batch export; manage theme configuration.
+## CSS Pitfall Quick Reference
 
-## Prerequisites
+> When adjusting themes, follow these rules strictly. For each step, reference the corresponding pattern in `academic-paper.css`.
 
-- Node.js ≥ 18
-- Project root: run `npm install && npm run build` before first use
-- Or run directly: `npx tsx src/cli.ts <command>`
+### 1. Screen & Print Must Stay in Sync
 
-## Commands
+Every rule in SECTION 5 must have a mirror copy in SECTION 6 `@media print`. Reference the `SECTION 5 / SECTION 6` correspondence in `academic-paper.css`.
 
-### Theme extraction
+### 2. Body Text First-Line Indent
 
-```bash
-colamd-themes from-url <URL> [options]
-colamd-themes from-docx <file> [options]
-colamd-themes from-pdf <file> [options]
-colamd-themes extract <source> [options]
-```
-
-### Export to HTML / PDF
-
-```bash
-colamd-themes export-html <input.md> -t <theme> -o <output.html>
-colamd-themes export-pdf  <input.md> -t <theme> -o <output.pdf>
-colamd-themes export <inputs...> --format html|pdf -t <theme> -d <dir>
-```
-
-### Theme management
-
-```bash
-colamd-themes set-theme <name> --default
-colamd-themes set-theme <name> --css <file>
-colamd-themes set-theme <name> --css <file> --default
-colamd-themes set-theme <name> --remove
-```
-
-### Inspection
-
-```bash
-colamd-themes color-systems [-j]
-colamd-themes mermaid-presets [-j]
-colamd-themes list [-d <dir>]
-colamd-themes validate <file.css>
-```
-
-## Options
-
-### Extract options
-
-| Flag | Description |
-|------|-------------|
-| `-n, --name` | Theme name |
-| `-o, --output` | Output CSS file path |
-| `-d, --themes-dir` | Themes directory (default: `themes/`) |
-| `-c, --color-system` | Force a color system |
-| `-m, --mermaid-preset` | Force a Mermaid preset (light/dark/elegant) |
-| `-A, --auto-match` | Auto-match color system and Mermaid preset |
-
-### Export options
-
-| Flag | Description |
-|------|-------------|
-| `-t, --theme` | Theme: built-in name, custom name, or `.css` file path |
-| `-o, --output` | Output file path |
-| `-d, --output-dir` | Output directory for batch export |
-| `--format` | Batch: `html` or `pdf`; PDF: `A4`, `Letter`, `A3` |
-
-## Theme Resolution
+**Pitfall:** `#write p` does not match. **Correct:** Reference `academic-paper.css` §5.3 directly — use `body.theme-custom p, body.theme-custom #write > p`, with `margin: 0` set beforehand.
 
-`-t, --theme` accepts:
-1. **Built-in**: `light`, `dark`, `elegant`, `newsprint`
-2. **Custom registered**: name set via `set-theme --css`
-3. **File path**: any `.css` file on disk
+### 3. Indent Exclusion (Do Not Pollute Lists / Tables / Diagrams)
 
-Config: `~/.colamd-themes/config.json`
+**Pitfall:** The `p` selector hits paragraphs inside all nested containers. **Correct:** Reference the exclusion block below `swiss-design.css` §5.2.1 — apply `text-indent: 0` uniformly to `li / li p / td p / th p / blockquote p / .mermaid-block p / figure p / pre p`.
 
-## Color Systems (15 schemes)
+### 4. List Indentation (Hardest Pitfall)
 
-| Family | Schemes |
-|--------|---------|
-| 莫兰迪 (Morandi) | misty-rose, sage-green, dusky-blue |
-| 马卡龙 (Macaron) | strawberry, mint, lavender |
-| 北欧 (Nordic) | fjord-blue, pine-green, cloud-grey |
-| 复古 (Vintage) | amber, burgundy, forest |
-| 薄荷绿 (Mint) | matcha, spearmint, seafoam |
-
-## Mermaid Presets
-
-`light` — cool accent on light bg | `dark` — dark bg | `elegant` — warm accent on light bg
-
-## Workflow Examples
-
-### Create theme from source
-
-```bash
-colamd-themes extract <source> --name "my-theme" --auto-match
-```
-
-### Export with theme
-
-```bash
-colamd-themes export-html doc.md -t elegant -o output.html
-colamd-themes export-pdf doc.md -t my-brand -o output.pdf
-```
-
-### Batch export
-
-```bash
-colamd-themes export docs/ --format pdf -t dark -d output/
-```
-
-### Validate theme
-
-```bash
-colamd-themes validate themes/my-theme.css
-```
+**Pitfall:** `padding-left` does not move the bullet/number; missing the `#editor .ProseMirror` editor selector; missing `li::before` and `li > p` inline conversion.
 
-## Rendering Pipeline
+**Correct:** Reference `academic-paper.css` §5.7 directly — copy its full selector structure (`#editor .ProseMirror > ul/ol` + `#write > ul/ol:first-of-type` + `li::before` + `#editor .ProseMirror li > p`). Use `margin-left: 2em` for indentation instead of `padding-left`. For Swiss style, keep `list-style-position: outside` and do NOT change to `none`.
 
-Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
+### 5. Mermaid CJK Text Overflow
 
-1. Local HTTP server serves renderer ESM bundle (avoids CORS)
-2. Puppeteer navigates to server page (same-origin)
-3. `createColaMDEditor({ editable: false })` initializes Milkdown editor
-4. `applyTheme(name, customCSS?)` sets theme
-5. `setMarkdown(content)` loads document
-6. `ensureAllPluginsRendered()` waits for mermaid/KaTeX
-7. `buildExportHTML()` → standalone HTML with embedded CSS
-8. For PDF: `emulateMediaType('screen')` + `page.pdf()`
+**Pitfall:** Multi-line `<br/>` nodes have incorrect width/height calculations. **Correct:** ≤ 2 lines per node + `fontSize: 14px` + simplify text (use `·` instead of `/`, remove redundant modifiers).
 
-## v3.0 Paradigm Constraints
+### 6. Mermaid classDef Does Not Inherit themeVariables
 
-- No bare hex colors in selectors — use `var(--seed-*)`
-- No bare font sizes — use `var(--font-*)`
-- No Mermaid SVG selectors (handled by built-in `variables.css`)
-- `!important` only in `@media print`
-- Generated CSS ≤ 300 lines
-- Font stacks must include CJK fallback and end with generic family
+**Pitfall:** Assuming `themeVariables` sets text color so you don't need to repeat it. **Correct:** `classDef` must explicitly declare all three properties: `fill / color / stroke`.
 
 ## Architecture
 

package/.trae/rules/colamd-themes.md

@@ -2,144 +2,35 @@
 
 When the user asks to create, validate, export, or manage ColaMD themes, use the following CLI tool:
 
-Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes. Extract formatting from URLs, DOCX, or PDF sources; export Markdown to standalone HTML/PDF with themes applied; batch export; manage theme configuration.
+## CSS Pitfall Quick Reference
 
-## Prerequisites
+> When adjusting themes, follow these rules strictly. For each step, reference the corresponding pattern in `academic-paper.css`.
 
-- Node.js ≥ 18
-- Project root: run `npm install && npm run build` before first use
-- Or run directly: `npx tsx src/cli.ts <command>`
+### 1. Screen & Print Must Stay in Sync
 
-## Commands
+Every rule in SECTION 5 must have a mirror copy in SECTION 6 `@media print`. Reference the `SECTION 5 / SECTION 6` correspondence in `academic-paper.css`.
 
-### Theme extraction
+### 2. Body Text First-Line Indent
 
-```bash
-colamd-themes from-url <URL> [options]
-colamd-themes from-docx <file> [options]
-colamd-themes from-pdf <file> [options]
-colamd-themes extract <source> [options]
-```
-
-### Export to HTML / PDF
-
-```bash
-colamd-themes export-html <input.md> -t <theme> -o <output.html>
-colamd-themes export-pdf  <input.md> -t <theme> -o <output.pdf>
-colamd-themes export <inputs...> --format html|pdf -t <theme> -d <dir>
-```
-
-### Theme management
-
-```bash
-colamd-themes set-theme <name> --default
-colamd-themes set-theme <name> --css <file>
-colamd-themes set-theme <name> --css <file> --default
-colamd-themes set-theme <name> --remove
-```
-
-### Inspection
-
-```bash
-colamd-themes color-systems [-j]
-colamd-themes mermaid-presets [-j]
-colamd-themes list [-d <dir>]
-colamd-themes validate <file.css>
-```
-
-## Options
-
-### Extract options
-
-| Flag | Description |
-|------|-------------|
-| `-n, --name` | Theme name |
-| `-o, --output` | Output CSS file path |
-| `-d, --themes-dir` | Themes directory (default: `themes/`) |
-| `-c, --color-system` | Force a color system |
-| `-m, --mermaid-preset` | Force a Mermaid preset (light/dark/elegant) |
-| `-A, --auto-match` | Auto-match color system and Mermaid preset |
-
-### Export options
-
-| Flag | Description |
-|------|-------------|
-| `-t, --theme` | Theme: built-in name, custom name, or `.css` file path |
-| `-o, --output` | Output file path |
-| `-d, --output-dir` | Output directory for batch export |
-| `--format` | Batch: `html` or `pdf`; PDF: `A4`, `Letter`, `A3` |
-
-## Theme Resolution
+**Pitfall:** `#write p` does not match. **Correct:** Reference `academic-paper.css` §5.3 directly — use `body.theme-custom p, body.theme-custom #write > p`, with `margin: 0` set beforehand.
 
-`-t, --theme` accepts:
-1. **Built-in**: `light`, `dark`, `elegant`, `newsprint`
-2. **Custom registered**: name set via `set-theme --css`
-3. **File path**: any `.css` file on disk
+### 3. Indent Exclusion (Do Not Pollute Lists / Tables / Diagrams)
 
-Config: `~/.colamd-themes/config.json`
+**Pitfall:** The `p` selector hits paragraphs inside all nested containers. **Correct:** Reference the exclusion block below `swiss-design.css` §5.2.1 — apply `text-indent: 0` uniformly to `li / li p / td p / th p / blockquote p / .mermaid-block p / figure p / pre p`.
 
-## Color Systems (15 schemes)
+### 4. List Indentation (Hardest Pitfall)
 
-| Family | Schemes |
-|--------|---------|
-| 莫兰迪 (Morandi) | misty-rose, sage-green, dusky-blue |
-| 马卡龙 (Macaron) | strawberry, mint, lavender |
-| 北欧 (Nordic) | fjord-blue, pine-green, cloud-grey |
-| 复古 (Vintage) | amber, burgundy, forest |
-| 薄荷绿 (Mint) | matcha, spearmint, seafoam |
-
-## Mermaid Presets
-
-`light` — cool accent on light bg | `dark` — dark bg | `elegant` — warm accent on light bg
-
-## Workflow Examples
-
-### Create theme from source
-
-```bash
-colamd-themes extract <source> --name "my-theme" --auto-match
-```
-
-### Export with theme
-
-```bash
-colamd-themes export-html doc.md -t elegant -o output.html
-colamd-themes export-pdf doc.md -t my-brand -o output.pdf
-```
-
-### Batch export
-
-```bash
-colamd-themes export docs/ --format pdf -t dark -d output/
-```
-
-### Validate theme
-
-```bash
-colamd-themes validate themes/my-theme.css
-```
+**Pitfall:** `padding-left` does not move the bullet/number; missing the `#editor .ProseMirror` editor selector; missing `li::before` and `li > p` inline conversion.
 
-## Rendering Pipeline
+**Correct:** Reference `academic-paper.css` §5.7 directly — copy its full selector structure (`#editor .ProseMirror > ul/ol` + `#write > ul/ol:first-of-type` + `li::before` + `#editor .ProseMirror li > p`). Use `margin-left: 2em` for indentation instead of `padding-left`. For Swiss style, keep `list-style-position: outside` and do NOT change to `none`.
 
-Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
+### 5. Mermaid CJK Text Overflow
 
-1. Local HTTP server serves renderer ESM bundle (avoids CORS)
-2. Puppeteer navigates to server page (same-origin)
-3. `createColaMDEditor({ editable: false })` initializes Milkdown editor
-4. `applyTheme(name, customCSS?)` sets theme
-5. `setMarkdown(content)` loads document
-6. `ensureAllPluginsRendered()` waits for mermaid/KaTeX
-7. `buildExportHTML()` → standalone HTML with embedded CSS
-8. For PDF: `emulateMediaType('screen')` + `page.pdf()`
+**Pitfall:** Multi-line `<br/>` nodes have incorrect width/height calculations. **Correct:** ≤ 2 lines per node + `fontSize: 14px` + simplify text (use `·` instead of `/`, remove redundant modifiers).
 
-## v3.0 Paradigm Constraints
+### 6. Mermaid classDef Does Not Inherit themeVariables
 
-- No bare hex colors in selectors — use `var(--seed-*)`
-- No bare font sizes — use `var(--font-*)`
-- No Mermaid SVG selectors (handled by built-in `variables.css`)
-- `!important` only in `@media print`
-- Generated CSS ≤ 300 lines
-- Font stacks must include CJK fallback and end with generic family
+**Pitfall:** Assuming `themeVariables` sets text color so you don't need to repeat it. **Correct:** `classDef` must explicitly declare all three properties: `fill / color / stroke`.
 
 ## Architecture
 

package/CHANGELOG.md

@@ -5,14 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.2] - 2026-05-29
 
 ### Added
+- **CSS Pitfall Quick Reference**: Comprehensive 6-topic guide for theme authoring in AI agent skills, covering screen/print sync, body text indent, indent exclusion, list indentation, Mermaid CJK text overflow, and Mermaid classDef inheritance rules
 - New theme: **Trae Blue** — modern blue-themed design for technical documentation
 - New theme: **Forest Ink** — nature-inspired dark green palette with ink aesthetics
 - Support for absolute path input in CLI commands
 - Two new theme preview HTML files (colly-preview, salvator-blog-preview)
-- CSS pitfall reference documentation
 - Short CLI alias `cthemes` as alternative to `colamd-themes`
 - Unified error handling system with structured error codes (`CLIError` + `ErrorCode`)
 - Shared utility functions for consistent file path resolution (`cli-utils.ts`)
@@ -233,7 +233,8 @@ User Input → Validation Layer → Processing Layer
 
 ---
 
-[Unreleased]: https://github.com/byteuser1977/ColaMD-themes/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/byteuser1977/ColaMD-themes/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/byteuser1977/ColaMD-themes/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/byteuser1977/ColaMD-themes/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/byteuser1977/ColaMD-themes/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/byteuser1977/ColaMD-themes/compare/v0.1.0...v0.2.0

package/README.md

@@ -31,7 +31,7 @@ A theme development & export toolkit for [ColaMD](https://github.com/cola-md/col
 - **Color System Library** — 15 predefined seed palettes across 5 families (Morandi, Macaron, Nordic, Vintage, Mint)
 - **Mermaid Presets** — 3 presets (light/dark/elegant) with 20 core variables, auto-selected by luminance and accent warmth
 
-### Security & Performance (v0.3.1+)
+### Security & Performance (v0.3.2+)
 
 - **SSRF Protection** — URL extractor validates against protocol whitelist and blocks private network access to prevent Server-Side Request Forgery attacks
 - **Input Validation** — CSS files validated for extension, size limit (1MB max), and content validity to prevent OOM attacks

package/README_CN.md

@@ -31,7 +31,7 @@
 - **色彩系统库** — 5 大色系 15 套预定义种子色板（莫兰迪、马卡龙、北欧、复古、薄荷绿）
 - **Mermaid 预设** — 3 套预设（light/dark/elegant），20 个核心变量，根据明度和色相自动选择
 
-### 安全与性能 (v0.3.1+)
+### 安全与性能 (v0.3.2+)
 
 - **SSRF 防护** — URL 提取器通过协议白名单验证并阻止私有网络访问，防止服务器端请求伪造攻击
 - **输入验证** — CSS 文件经过扩展名、大小限制（最大 1MB）和内容有效性验证，防止 OOM 攻击

package/RELEASENOTE.md

@@ -1,5 +1,29 @@
 # Release Notes
 
+## Version 0.3.2 (2026-05-29) — Theme Authoring Guide 📝
+
+> **AI agent skill enhancement**: Added comprehensive CSS pitfall quick reference for reliable theme generation.
+
+### 📝 AI Agent Skill Update
+
+**CSS Pitfall Quick Reference**
+- Added 6-topic theme authoring guide to all AI agent skill definitions:
+  1. **Screen & Print Sync** — every SECTION 5 rule must mirror in SECTION 6 `@media print`
+  2. **Body Text First-Line Indent** — correct selector chain: `body.theme-custom p, body.theme-custom #write > p`
+  3. **Indent Exclusion** — prevent indent pollution in lists, tables, mermaid blocks, blockquotes, and figures
+  4. **List Indentation** — use `margin-left: 2em` instead of `padding-left`; include `#editor .ProseMirror` selectors
+  5. **Mermaid CJK Text Overflow** — ≤ 2 lines per node, `fontSize: 14px`, simplified text
+  6. **Mermaid classDef Inheritance** — must explicitly declare `fill / color / stroke`
+- References `academic-paper.css` and `swiss-design.css` as canonical examples
+- Skill files affected: `.claude/skills/`, `.opencode/skills/`, `.openclaw/skills/`, `.hermes/skills/`, `.trae/rules/`
+
+### 🔧 Changes
+
+- Consolidated all unreleased changes from v0.3.1 into this patch release
+- Updated CHANGELOG and version links for the 0.3.2 release
+
+---
+
 ## Version 0.3.1 (2026-06-01) — Security & Stability Patch 🔒
 
 > **Important**: This release contains critical security fixes and important stability improvements.