@bytechain.cn/colamd-themes 0.3.0

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

@@ -0,0 +1,166 @@
+---
+id: colamd-themes
+name: ColaMD Themes
+description: >
+  Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes.
+  Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
+version: "1.0.0"
+icon: "\U0001F3A8"
+author: bytechain
+homepage: https://github.com/byteuser1977/ColaMD-themes
+user-invocable: true
+metadata:
+  openclaw:
+    os: [darwin, linux, win32]
+  clawdbot:
+    emoji: "\U0001F3A8"
+    requires:
+      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.
+
+## Prerequisites
+
+- Node.js ≥ 18
+- Project root: run `npm install && npm run build` before first use
+- Or run directly: `npx tsx src/cli.ts <command>`
+
+## Commands
+
+### Theme extraction
+
+```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
+
+`-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
+
+Config: `~/.colamd-themes/config.json`
+
+## Color Systems (15 schemes)
+
+| 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
+```
+
+## Rendering Pipeline
+
+Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
+
+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()`
+
+## v3.0 Paradigm Constraints
+
+- 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
+
+## Architecture
+
+```
+Source → Extractor → ThemeStyle → Color System + Mermaid Preset + Validators → CSS
+
+Markdown → Puppeteer + ColaMD Renderer → HTML / PDF
+```

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

@@ -0,0 +1,162 @@
+---
+name: colamd-themes
+version: "1.0.0"
+description: >
+  Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes.
+  Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+---
+
+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.
+
+## Prerequisites
+
+- Node.js ≥ 18
+- Project root: run `npm install && npm run build` before first use
+- Or run directly: `npx tsx src/cli.ts <command>`
+
+## Commands
+
+### Theme extraction
+
+```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
+
+`-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
+
+Config: `~/.colamd-themes/config.json`
+
+## Color Systems (15 schemes)
+
+| 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
+```
+
+## Rendering Pipeline
+
+Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
+
+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()`
+
+## v3.0 Paradigm Constraints
+
+- 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
+
+## Architecture
+
+```
+Source → Extractor → ThemeStyle → Color System + Mermaid Preset + Validators → CSS
+
+Markdown → Puppeteer + ColaMD Renderer → HTML / PDF
+```

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

@@ -0,0 +1,150 @@
+# ColaMD Themes Skill Instructions
+
+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.
+
+## Prerequisites
+
+- Node.js ≥ 18
+- Project root: run `npm install && npm run build` before first use
+- Or run directly: `npx tsx src/cli.ts <command>`
+
+## Commands
+
+### Theme extraction
+
+```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
+
+`-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
+
+Config: `~/.colamd-themes/config.json`
+
+## Color Systems (15 schemes)
+
+| 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
+```
+
+## Rendering Pipeline
+
+Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
+
+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()`
+
+## v3.0 Paradigm Constraints
+
+- 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
+
+## Architecture
+
+```
+Source → Extractor → ThemeStyle → Color System + Mermaid Preset + Validators → CSS
+
+Markdown → Puppeteer + ColaMD Renderer → HTML / PDF
+```

package/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+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]
+
+### Added
+- 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`
+
+### Changed
+- Package name migrated to scoped format: `@bytechain.cn/colamd-themes`
+- Optimized **Swiss Design** theme with improved typography and spacing
+- Fixed build script template file copy logic (`package.json` build command)
+
+### Removed
+- `.DS_Store` files from project directory
+
+---
+
+## [0.3.0] - 2026-06-01
+
+### Added
+- **Trae Blue Theme**: Modern blue color scheme optimized for developer documentation and technical writing
+- **Forest Ink Theme**: Dark forest-inspired theme with elegant ink-style aesthetics
+- **Absolute Path Support**: CLI now accepts absolute file paths for all input commands
+- **Theme Previews**: Added interactive HTML previews for colly and salvator-blog themes
+- **CSS Reference**: Included common CSS pitfalls and best practices documentation
+- **Short CLI Alias**: `cthemes` command added as shorthand for `colamd-themes`
+
+### Changed
+- **Package Name**: Migrated from `colamd-themes` to `@bytechain.cn/colamd-themes` (scoped package)
+- **Swiss Design Enhancement**: Refined Swiss Design theme with better contrast ratios and improved readability
+- **Build Process Fix**: Corrected template file copying logic in build script to ensure proper distribution
+
+### Removed
+- System files (`.DS_Store`) cleaned from repository
+
+---
+
+## [0.2.0] - 2026-05-25
+
+### Added
+- **v3.0 Seed Palette Paradigm**: Complete implementation of ColaMD's new design token system
+  - 15 predefined seed palettes across 5 families (Morandi, Macaron, Nordic, Vintage, Mint)
+  - Auto-derived semantic mapping from seed tokens via CSS custom properties
+  - Mermaid diagram presets (light/dark/elegant) with 20 core variables
+- **Academic Style Theme**: Specialized theme for academic paper formatting
+- **Three Base Themes**: Initial set of core themes (elegant, newsprint, light/dark)
+- **Theme Validation Engine**: WCAG 2.1 compliance checking with 15+ design constraint rules
+- **Color System Library**: Comprehensive color palette management utilities
+
+### Changed
+- **Extractor Refactoring**: Complete rewrite of URL, DOCX, and PDF extractors
+  - Improved CSS rule parsing via `css-tree`
+  - Enhanced specificity calculation for inline style resolution
+  - Multi-layer heuristic analysis for PDF metadata extraction
+- **Academic Paper Theme**: Restructured to follow v3.0 paradigm specifications
+- **Template Engine**: Handlebars-powered CSS generation with 6-section output structure
+
+### Fixed
+- Merge conflict resolution for `academic-paper.css` (adopted remote version)
+
+---
+
+## [0.1.0] - 2026-05-22
+
+### Added
+- **Initial Release**: Core ColaMD theme development toolkit
+- **CLI Interface**: Command-line tool for theme management and export operations
+- **Theme Extraction**:
+  - URL-based extractor with CSS parsing
+  - DOCX extractor using mammoth for Word document styles
+  - PDF extractor with typography metadata analysis
+  - Auto-detection of source type
+- **Export Functionality**:
+  - Markdown to HTML export with embedded theme CSS
+  - Markdown to PDF export via Puppeteer rendering
+  - Batch export support for multiple files/directories
+- **Theme Management**:
+  - Built-in theme registration system
+  - Custom theme import from CSS files
+  - Default theme configuration
+- **Core Utilities**:
+  - Color system with contrast ratio calculations
+  - Typography management
+  - Mermaid diagram integration
+  - KaTeX math rendering support
+
+---
+
+[Unreleased]: https://github.com/byteuser1977/ColaMD-themes/compare/v0.3.0...HEAD
+[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
+[0.1.0]: https://github.com/byteuser1977/ColaMD-themes/releases/tag/v0.1.0