@bytechain.cn/colamd-themes 0.3.1 → 0.5.0

package/.claude/skills/colamd-themes-preview.skill.md

@@ -0,0 +1,333 @@
+---
+name: colamd-themes-preview
+description: >-
+  Preview and showcase ColaMD themes with interactive HTML demos, batch
+  comparisons, and development server. Use when user wants to visualize a
+  theme's appearance across different Markdown elements or compare multiple
+  themes side-by-side.
+---
+
+# ColaMD Themes Preview — Visual Theme Showcase
+
+## Overview
+
+This skill complements `colamd-themes` by adding visual preview capabilities:
+
+- **Static HTML preview** — Generate a standalone HTML file showcasing a theme
+- **Batch comparison** — Compare multiple themes in one page with synchronized scrolling
+- **Dev server** — Hot-reload preview server for theme development
+- **Demo content** — Includes comprehensive Markdown examples (headings, lists, tables, code blocks, Mermaid diagrams, math, etc.)
+
+## When to Use
+
+- After generating a theme with `colamd-themes extract` → preview it before validation
+- When choosing between multiple extracted themes → batch compare
+- During theme fine-tuning → use dev server for instant feedback
+- Before sharing a theme → generate polished showcase page
+
+## Prerequisites
+
+- Node.js ≥ 18
+- ColaMD-themes project at: `/Volumes/DATA/data/develop/git/ColaMD-themes`
+- Theme CSS files available in `themes/` directory
+
+## Commands
+
+### Generate Static Preview for a Single Theme
+
+```bash
+colamd-themes-preview generate <theme.css> [options]
+# Output: themes-preview/<theme-name>-preview.html
+```
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `-c, --content <file.md>` | Custom Markdown content (default: built-in demo) |
+| `-o, --output <path>` | Output HTML file path |
+| `-t, --title <text>` | Page title |
+| `--embedded` | Embed theme CSS directly (single file) |
+| `--no-mermaid` | Skip Mermaid demo section |
+
+### Batch Compare Multiple Themes
+
+```bash
+colamd-themes-preview compare <theme1.css> <theme2.css> [theme3.css...] [options]
+# Output: themes-preview/comparison-<timestamp>.html
+```
+
+Features:
+- Themes displayed in vertical tabs
+- Synchronized scroll position
+- Common content rendered under each theme
+- Visual diff indicators (color swatches)
+
+### Start Development Preview Server
+
+```bash
+colamd-themes-preview serve [options]
+# Serves at http://localhost:3000
+```
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `-p, --port <number>` | Server port (default: 3000) |
+| `-w, --watch <dir>` | Watch directory for CSS changes |
+| `-t, --themes-dir <dir>` | Themes directory (default: `themes/`) |
+| `--open` | Open browser automatically |
+
+Auto-reload: When a watched CSS file changes, the page refreshes automatically.
+
+### Export Demo Content
+
+```bash
+colamd-themes-preview export-demo <output.md>
+# Generates comprehensive Markdown with all element types
+```
+
+### Audit Theme against Document Type
+
+```bash
+colamd-themes-preview audit <theme.css> [options]
+```
+
+Performs a comprehensive audit of the generated CSS against type-specific design constraints and prints a compliance score.
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `-t, --type <type>` | Document type: `document` (meeting minutes, reports), `design` (web page conversions), `ppt` (PDF from slides) |
+| `-s, --source <file>` | Source file (DOCX/PDF) to compare against (used for PPT type) |
+| `-f, --format <fmt>` | Report format: `text` (default), `json`, `html` |
+| `--strict` | Exit with non-zero code on ANY violation (default: only MUST/MUST_NOT failures) |
+
+The audit checks:
+
+- Color values against type expectations
+- Font stacks for appropriateness
+- Pele chart palette suitability (`--pele-*` derives from code block colors)
+- Print fidelity (2.7 exports the current window; `@media print` only needs `print-color-adjust`)
+- Contrast ratios and accessibility
+- Conformance to the 2.7 contract (`:root` vars, `.cm-md-*` selectors, no dead variables)
+
+Output includes overall score (0–100) and categorized issues (CRITICAL, WARNING, INFO).
+
+Example:
+
+```
+Audit: meeting-minutes.css (type: document)
+Overall score: 92/100
+
+CRITICAL:
+  (none)
+
+WARNINGS:
+  - Accent saturation 0.72 exceeds document-type max 0.6
+  - Consider a more muted blue for formal documents
+
+INFO:
+  - Chart palette: derived from `--pele-*`
+  - Font stack includes CJK fallbacks: Yes
+```
+
+## Built-in Demo Content
+
+The preview includes this sample Markdown structure:
+
+```
+# Heading 1
+## Heading 2
+### Heading 3
+
+Paragraph with **bold**, *italic*, `inline code`, [links](https://example.com), and ~~strikethrough~~.
+
+> Blockquote with *emphasized* text and a link.
+
+- Unordered list item 1
+- Unordered list item 2
+  - Nested item
+  - Another nested item
+
+1. Ordered list item 1
+2. Ordered list item 2
+   1. Nested ordered item
+
+- [ ] Task list item (unchecked)
+- [x] Task list item (checked)
+
+```python
+def hello():
+    print("Hello, ColaMD!")
+```
+
+| Header 1 | Header 2 | Header 3 |
+|----------|----------|----------|
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |
+
+---
+
+```mermaid
+graph TD
+    A[Start] --> B{Decision}
+    B --> C[Option 1]
+    B --> D[Option 2]
+```
+
+$$
+\int_{a}^{b} x^2 dx
+$$
+
+---
+
+[[toc]]
+```
+
+## HTML Preview Features
+
+Generated preview pages include:
+
+1. **Theme metadata bar** — name, color system, mermaid preset
+2. **Color palette swatches** — seed colors displayed as swatches
+3. **Typography samples** — heading and body font renders
+4. **Full Markdown rendering** — all ColaMD-supported elements
+5. **Print preview toggle** — switch to print stylesheet view
+6. **Mobile responsive toggle** — simulate mobile viewport
+7. **CSS source viewer** — collapsible panel to inspect the theme file
+8. **Download button** — export the theme CSS
+
+## Batch Comparison Layout
+
+Comparison page organizes themes horizontally (if < 4 themes) or in tabs:
+
+- **Color palette matrix** — side-by-side swatch comparison
+- **Shared scroll container** — all themes scroll together
+- **Highlight differences** — hover a theme to emphasize it
+- **Export all** — zip all themes + preview HTML
+
+## Development Server Workflow
+
+```bash
+# Start server with watch
+colamd-themes-preview serve -w themes/
+
+# In another terminal, edit your theme CSS
+# Browser auto-refreshes on save
+```
+
+The server serves:
+- `/` — theme selector + preview
+- `/preview/<theme-name>` — single theme preview
+- `/compare` — batch comparison (query: ?themes=a.css,b.css)
+- `/demo-content.md` — raw demo content
+
+## Integration with colamd-themes
+
+Typical workflow:
+
+1. Extract theme:
+   ```bash
+   colamd-themes extract source.docx --name my-theme --auto-match
+   ```
+
+2. Preview it:
+   ```bash
+   colamd-themes-preview generate themes/my-theme.css --embedded
+   ```
+
+3. Fine-tune seed colors manually in `themes/my-theme.css` (SECTION 1 only)
+
+4. Re-preview instantly with dev server:
+   ```bash
+   colamd-themes-preview serve -w themes/
+   ```
+
+5. Validate:
+   ```bash
+   colamd-themes validate themes/my-theme.css
+   ```
+
+6. (Optional) Compare with alternatives:
+   ```bash
+   colamd-themes-preview compare themes/*.css
+   ```
+
+7. Audit against document type expectations:
+   ```bash
+   colamd-themes-preview audit themes/my-theme.css --type document
+   ```
+
+## Code Audit Rules
+
+The `audit` command validates a theme against expectations for its document type. Rules are prioritized:
+
+- **MUST** / **MUST_NOT** — critical non-negotiable constraints (fail audit)
+- **SHOULD** / **SHOULD_NOT** — recommended best practices (warnings)
+- **INFO** — informational notes (no score impact)
+
+### Document Type Rules
+
+**Document** (meeting minutes, reports, proposals):
+
+- Surface: near-white (Luminance ≥ 0.95)
+- Ink: dark (Luminance ≤ 0.2 or hex `#000000`–`#222222`)
+- Accent: medium saturation (0.3 ≤ S ≤ 0.6), professional hues (blue, teal, burgundy)
+- Chart palette: muted `--pele-*` derived from code block tones
+- Font bodies: serif or clean sans-serif, include CJK fallbacks
+- Print styles: no mirrored color block needed; `@media print` only carries `print-color-adjust: exact`
+- Expectation: readability, print-friendliness, conservative palette
+
+**Design** (web page style conversions):
+
+- Surface: varies (light or dark)
+- Accent: high saturation (S ≥ 0.6), vibrant colors, possible gradients
+- Font families: modern sans-serif stack, may include display fonts
+- Chart palette: `--pele-*` tuned to the background luminance
+- Print styles: SHOULD preserve brand colors; if source has print styles, compare against them
+- Expectation: faithful reproduction of source website's visual identity
+
+**PPT** (PDF from presentation slides):
+
+- Must preserve original slide color scheme (extracted from source PDF)
+- Text colors must match original slide text colors within tolerance
+- Chart colors should follow slide accent palette (`--pele-accent`)
+- Font choices should reflect slide typography
+- Print styles: CRITICAL — 2.7 prints the current window, so screen rules apply as-is; verify `@media print` carries `print-color-adjust: exact`
+- Expectation: high fidelity to original slide design, including print output
+
+## Implementation Notes
+
+- Preview HTML uses a simple client-side renderer (marked.js or similar)
+- No additional build step required — copies template + injects theme CSS
+- Embedded mode inlines the entire CSS to avoid CORS issues when sharing
+- Dev server uses `chokidar` for file watching and `ws` for live reload WebSocket
+
+## File Structure
+
+```
+ColaMD-themes/
+├── .claude/skills/
+│   ├── colamd-themes.skill.md          (existing)
+│   └── colamd-themes-preview.skill.md  (this skill)
+├── src/
+│   ├── preview/
+│   │   ├── preview-server.ts           (dev server)
+│   │   ├── generate-html.ts            (static HTML generator)
+│   │   ├── demo-content.md             (built-in Markdown sample)
+│   │   └── template.html               (HTML skeleton)
+│   └── cli.ts                          (+ new subcommands)
+├── themes-preview/                     (output directory)
+└── package.json                        (adds preview deps)
+```
+
+## Future Enhancements
+
+- Screenshot automation (puppeteer) for documentation
+- Export to PDF with print styles applied
+- Share to ColaMD community gallery
+- AI-driven theme critique (color harmony, contrast feedback)
+- Theme package (.zip) with preview, demo, and license

package/.claude/skills/colamd-themes.skill.md

@@ -0,0 +1,10 @@
+---
+name: colamd-themes
+description: >
+  Generate, validate, export, and manage ColaMD 2.7.7 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.
+---
+
+

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

@@ -0,0 +1,14 @@
+---
+name: colamd-themes
+version: "1.0.0"
+description: >
+  Generate, validate, export, and manage ColaMD 2.7.7 contract CSS themes.
+  Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
+metadata:
+  dsh:
+    tags: [colamd, themes, css, markdown, export, pdf, html]
+prerequisites:
+  commands: [node, npm]
+---
+
+

package/.github/supported-topics.yml

@@ -0,0 +1,17 @@
+# GitHub Topics 支持列表
+# 此文件帮助 GitHub 在仓库设置页面自动建议相关 topics
+# 添加后需在 GitHub 仓库 Settings > General > Topics 中手动确认保存
+- dsh
+- deepseek-harness
+- colamd
+- themes
+- css
+- markdown
+- pdf
+- html
+- skill
+- ai-agent
+- agent-skill
+- theme-generator
+- markdown-export
+- colamd-themes

package/.hermes/skills/tools/colamd-themes/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: colamd-themes
+description: "Generate, validate, export, and manage ColaMD 2.7.7 contract CSS themes."
+version: 1.0.0
+author: bytechain
+license: MIT
+metadata:
+  hermes:
+    tags: [colamd, themes, css, markdown, export, pdf, html]
+prerequisites:
+  commands: [node, npm]
+---
+
+

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

@@ -2,7 +2,7 @@
 id: colamd-themes
 name: ColaMD Themes
 description: >
-  Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes.
+  Generate, validate, export, and manage ColaMD 2.7.7 contract CSS themes.
   Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
 version: "1.0.0"
 icon: "\U0001F3A8"
@@ -18,149 +18,4 @@ 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.
 
-## 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,17 @@
+---
+name: colamd-themes
+version: "1.0.0"
+description: >
+  Generate, validate, export, and manage ColaMD 2.7.7 contract 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
+---
+
+