@bytechain.cn/colamd-themes 0.3.2 → 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,40 +18,4 @@ metadata:
       bins: [node, npm]
 ---
 
-## CSS Pitfall Quick Reference
 
-> When adjusting themes, follow these rules strictly. For each step, reference the corresponding pattern in `academic-paper.css`.
-
-### 1. Screen & Print Must Stay in Sync
-
-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`.
-
-### 2. Body Text First-Line Indent
-
-**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.
-
-### 3. Indent Exclusion (Do Not Pollute Lists / Tables / Diagrams)
-
-**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`.
-
-### 4. List Indentation (Hardest Pitfall)
-
-**Pitfall:** `padding-left` does not move the bullet/number; missing the `#editor .ProseMirror` editor selector; missing `li::before` and `li > p` inline conversion.
-
-**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`.
-
-### 5. Mermaid CJK Text Overflow
-
-**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).
-
-### 6. Mermaid classDef Does Not Inherit themeVariables
-
-**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
-
-```
-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
+---
+
+

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

@@ -2,40 +2,4 @@
 
 When the user asks to create, validate, export, or manage ColaMD themes, use the following CLI tool:
 
-## CSS Pitfall Quick Reference
 
-> When adjusting themes, follow these rules strictly. For each step, reference the corresponding pattern in `academic-paper.css`.
-
-### 1. Screen & Print Must Stay in Sync
-
-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`.
-
-### 2. Body Text First-Line Indent
-
-**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.
-
-### 3. Indent Exclusion (Do Not Pollute Lists / Tables / Diagrams)
-
-**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`.
-
-### 4. List Indentation (Hardest Pitfall)
-
-**Pitfall:** `padding-left` does not move the bullet/number; missing the `#editor .ProseMirror` editor selector; missing `li::before` and `li > p` inline conversion.
-
-**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`.
-
-### 5. Mermaid CJK Text Overflow
-
-**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).
-
-### 6. Mermaid classDef Does Not Inherit themeVariables
-
-**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
-
-```
-Source → Extractor → ThemeStyle → Color System + Mermaid Preset + Validators → CSS
-
-Markdown → Puppeteer + ColaMD Renderer → HTML / PDF
-```