mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-10-06 02:50:08 +00:00
8d1f2dec97
Operationalizes Shihipar's "Claude Code HTML output" essay (Medium, 2026): markdown collapses past ~100 lines for agent-generated artifacts; HTML restores density, clarity, shareability, and lightweight interaction. This foundation PR ships 2 of 5 planned skills: - markdown-html-orchestrator (context: fork): deterministic doctype classifier scoring filename hints + content signals across DOCUMENT / REVIEW / SLIDES; silent-routes above two-signal threshold; refuses inputs < 100 lines per Shihipar; refuses without design-system onboarding. 3 stdlib tools: doctype_classifier.py, route_explainer.py (the never-silently-chain enforcer + onboarding gate), and output_path_resolver.py (kebab slug + collision suffix). - design-system: one-time onboarding wizard (10 questions for brand primary/accent HEX + heading + body Google Fonts + editorial/technical/ minimal/playful style + default output dir + syntax theme + TOC behavior + optional logo/company). WCAG-AA-validated 12 CSS custom properties derived in HSL space; refuses to save if body-text or link contrast fails 4.5:1, or if the output dir is unwritable. Pattern lifted from research-ops/skills/clinical-research/scripts/ (onboard.py + config_loader.py shape) and marketing/landing/scripts/ (brand_palette_validator.py WCAG + HSL math). Precedence: project > global > defaults; MARKDOWN_HTML_NO_CONFIG=1 bypasses. Plus cs-markdown-html-orchestrator agent, 3 slash commands (/cs:markdown-html router, /cs:grill-markdown-html 5-question grill, /cs:design-system onboarding surface), 6 reference docs each citing 5-7 authoritative sources (Tufte, Shihipar, Bret Victor, Maggie Appleton, Bartosz Ciechanowski, Amelia Wattenberger; WCAG 2.2, Ellen Lupton, Adobe Spectrum, Sara Soueidan, Material Design 3), 1 JSON schema asset, domain README + CLAUDE.md. Converter sub-skills (md-document, md-review, md-slides) land in v2.10.1 follow-up PRs. All three will import design-system/scripts/config_loader.py for shared brand tokens. Repo-level updates: scripts/sync-codex-skills.py SKILL_DOMAINS adds markdown-html → documentation category; .claude-plugin/marketplace.json adds markdown-html-skills plugin entry (63 → 64 plugins, 16 → 17 domains); root CLAUDE.md gets nav-map row, structure-tree entry, and v2.10.0 release-notes block. Validation: - check_plugin_json.py → OK - sync-codex-skills.py --dry-run → 2 new symlinks, total 338 → 340 - skill_description_validator.py → PASS on both SKILL.md files - skill_review_checklist_runner.py → 5/6 PASS (under-100-lines advisory fires; same as research-ops orchestrator) - All 6 Python tools smoke-tested with --help and --sample - End-to-end onboarding round-trip works (--defaults, --set, --reset) - WCAG-fail hard refusal fires correctly on impossible color combos - Classifier on the repo's own CLAUDE.md correctly returns needs-clarification (15 vs 13 — document signals tie with slides signals because of multiple --- HRs); orchestrator asks rather than silently chains. Distinct from Anthropic's official Playground plugin (interactive prompt-tuning controls with sliders/knobs/prompt-copy-back) and from marketing/landing/ (landing-page generator from scratch). https://claude.ai/code/session_01BK2KoQot1U7J5oSosrCQdc
57 lines
2.9 KiB
Markdown
57 lines
2.9 KiB
Markdown
---
|
|
description: Run the one-time markdown-html design-system onboarding wizard. Captures brand primary/accent (HEX) + heading/body Google Fonts + design style (editorial/technical/minimal/playful) + default output directory + syntax theme + TOC behavior + optional logo/company. WCAG-AA validates body-text contrast; refuses if it fails. Stores at ~/.config/markdown-html/design-system.json (or project-scoped with --scope project). Every converter reads this config via config_loader.py before rendering.
|
|
argument-hint: "[--defaults | --show | --reset | --set key=value | --scope global|project]"
|
|
---
|
|
|
|
# /cs:design-system — Markdown-HTML design-system onboarding
|
|
|
|
Run the design-system wizard:
|
|
|
|
```bash
|
|
python3 markdown-html/skills/design-system/scripts/onboard.py $ARGUMENTS
|
|
```
|
|
|
|
## Modes
|
|
|
|
| Flag | Behavior |
|
|
|---|---|
|
|
| (no flag) | Interactive — walks 10 questions one at a time. Default. |
|
|
| `--defaults` | Zero-touch: writes built-in defaults (`#0A1628` navy + `#00D4AA` teal + Inter + technical + sticky TOC + `./markdown-html-out/`) without prompting. Useful for CI or first-test. |
|
|
| `--set key=value` | Non-interactive override (repeatable). Dotted keys supported: `brand.primary=#FF6B35`, `typography.heading_font=Lora`, `design_style=editorial`. |
|
|
| `--show` | Print the 10 questions + the current effective config (project > global > defaults). |
|
|
| `--reset` | Delete the saved config at the chosen scope. |
|
|
| `--scope project` | Save to `./.markdown-html/design-system.json` (per-repo override) instead of global `~/.config/markdown-html/design-system.json`. |
|
|
|
|
## The 10 questions
|
|
|
|
1. Default output directory (path; must be writable)
|
|
2. Brand primary HEX
|
|
3. Brand accent HEX (optional; auto-derives if blank)
|
|
4. Heading Google Font (12 safe defaults)
|
|
5. Body Google Font
|
|
6. Design style: editorial / technical / minimal / playful
|
|
7. Syntax-highlighting theme: light / dark / auto
|
|
8. TOC behavior: sticky-sidebar / collapsible-top / inline / none
|
|
9. Company / project name (optional, shows in footer)
|
|
10. Logo URL (optional, base64-embedded at render time)
|
|
|
|
## Hard refusals
|
|
|
|
- `default_output_dir` empty or unwritable → exit 3. Pick a path you control.
|
|
- WCAG AA body-text contrast fails (< 4.5:1) → exit 4. Pick a darker primary, blank `brand.bg`/`brand.text` to let derivation pick a passing pair, or override `brand.text` explicitly.
|
|
- WCAG link contrast walked iteratively; falls back to a passing color if accent on bg can't reach 4.5:1.
|
|
|
|
## After onboarding
|
|
|
|
Inspect the effective config:
|
|
|
|
```bash
|
|
python3 markdown-html/skills/design-system/scripts/config_loader.py --show
|
|
python3 markdown-html/skills/design-system/scripts/config_loader.py --status
|
|
```
|
|
|
|
Then convert markdown via `/cs:markdown-html <path>.md`.
|
|
|
|
## Bypass
|
|
|
|
`MARKDOWN_HTML_NO_CONFIG=1` skips saved config and returns DEFAULTS only. Useful for headless CI, ephemeral test containers, and evaluator loops. Never set it silently for an interactive user.
|