mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-12 23:01:23 +00:00

feat(markdown-html): add v2.10.0 foundation — orchestrator + design-system

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

2026-05-29 14:19:06 +00:00

2.9 KiB

Raw Permalink Blame History

description	argument-hint
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.	[--defaults \| --show \| --reset \| --set key=value \| --scope global\|project]

description

argument-hint

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.

/cs:design-system — Markdown-HTML design-system onboarding

Run the design-system wizard:

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

Default output directory (path; must be writable)
Brand primary HEX
Brand accent HEX (optional; auto-derives if blank)
Heading Google Font (12 safe defaults)
Body Google Font
Design style: editorial / technical / minimal / playful
Syntax-highlighting theme: light / dark / auto
TOC behavior: sticky-sidebar / collapsible-top / inline / none
Company / project name (optional, shows in footer)
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:

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.

2.9 KiB Raw Permalink Blame History