Skill125 repo starsupdated today

composing-html

Composes single-file HTML artifacts (PR review writeups, status reports, incident postmortems, slide decks, design systems, prototypes, flowcharts, module maps, feature explainers, kanban boards, prompt tuners) from a small JSON spec instead of hand-written HTML/CSS/JS. Use when the user asks to "compare options side-by-side", requests an HTML version of a report or review or deck, asks for a flowchart, status update, postmortem, design system reference, interactive prototype, custom editor — or explicitly says "HTML artifact", "single HTML file", "self-contained HTML". Skip for ad-hoc HTML snippets (forms, emails, embedded widgets) where there's no template fit.

View source Repository: claude-skills

Install in Claude Code

Copy

git clone --depth 1 https://github.com/oaustegard/claude-skills /tmp/composing-html && cp -r /tmp/composing-html/composing-html ~/.claude/skills/composing-html

Then start a new Claude Code session; the skill loads automatically.

Definition

SKILL.md

# composing-html

Produce single-file HTML artifacts without hand-writing the page chrome. The
composer supplies `<!DOCTYPE>`, `<head>`, inlined CSS, `base.js`, design
tokens, masthead, and colophon. You supply a title and the body content.

The product is the **chrome and inventory below** — primitives you can drop
into any artifact without re-deriving what a card, badge, or eyebrow looks
like. Templates are shortcuts on top of this, useful when the same artifact
shape repeats; see [Templates](#templates-shortcuts-for-repeat-structure)
near the end.

## Default workflow: freeform

`freeform` gives you the whole chrome with one content slot — `body_html` —
for the page body. Reach for it first. Reach for a template only when the
structure repeats across artifacts (see [Templates](#templates-shortcuts-for-repeat-structure)
near the end).

There are two ways to invoke it. **Use the `--set` flow for anything with a
substantial body** — it sidesteps the JSON-string escaping that bites
heredoc-style spec writing (newlines, quotes, `<`/`&` inside multi-line
HTML).

### Recommended: HTML in a file, metadata via `--set`

```
1. Write the body to a .html file directly (no JSON, no escaping).
2. python scripts/build.py build freeform \
       --set title='My Page' \
       --set subtitle='Optional subhead' \
       --set body_html=@body.html \
       --out artifact.html
```

`--set KEY=VALUE` assigns a literal string; `--set KEY=@FILE` loads the file
contents verbatim into that spec field. Repeat for any field. Works for
`body_html`, `extra_css`, `extra_js`, `eyebrow`, `page_class`, and the same
`*_html` fields in any other template (`summary_html`, `intro_html`,
`details_html`, …).

### Spec-file workflow (best for structured templates)

```
1. python scripts/build.py describe <template>     # required keys + skeleton
2. write spec.json
3. python scripts/build.py build <template> --spec spec.json --out artifact.html
```

For templates with typed slots (`pr_review.findings[]`, `slide_deck.slides[]`,
`status_report.metrics[]`), the spec file is the right shape — the template
reasons over the structure. For `freeform`, the spec is mostly a thin config
wrapper around one HTML string; the `--set` flow above is usually less
friction.

You can mix both: small `spec.json` for metadata, `--set body_html=@body.html`
for the heavy bit. `--set` overrides any matching field from `--spec`.

### Pitfall: don't inline multi-line HTML into a JSON heredoc

`cat > spec.json <<EOF { "body_html": "<multi\nline>\n..." } EOF` does not
produce valid JSON — JSON strings can't contain raw newlines or unescaped
quotes. Either:
- use `--set body_html=@body.html` (recommended), or
- assemble the spec in Python with `json.dump(spec, f)` so escaping is automatic.

## Inventory

Everything in this section is loaded into every artifact via inlined CSS and
`base.js`. Use these tokens and classes inside `body_html` (or any
template's `*_html` field) without re-declaring them.

### Color tokens

| Token | Hex | Use |
|---|---|---|
| `--ivory` | `#FAF9F5` | Page background |
| `--paper` | `#FFFFFF` | Card background |
| `--slate` | `#141413` | Headings, inverted background |
| `--clay` | `#D97757` | Brand accent (lines, primary actions) |
| `--clay-d` | `#B85C3E` | Hover/dark variant |
| `--oat` | `#E3DACC` | Soft contrast surface |
| `--olive` | `#788C5D` | Success, secondary accent |
| `--rust` | `#B04A3F` | Errors, destructive |
| `--moss` | `#4A6B3A` | Success text |
| `--g100` … `--g700` | grays | Surfaces, borders, body text |

Semantic aliases: `--ok`, `--warn`, `--err`, `--info`.

### Type stacks

- `--serif` — display headings (h1, h2, big numerics).
- `--sans` — body text (default).
- `--mono` — code, eyebrows, badges, captions.

### Geometry

`--radius-sm` (6px) · `--radius` (10px) · `--radius-lg` (16px) ·
`--border` · `--border-soft` · `--shadow-card` · `--shadow-pop`.

### Layout primitives

- `.page` — main column (1080px max). Variants: `.page--wide` (1280px),
  `.page--narrow` (720px). Set via the `page_class` spec key.
- `.masthead` — header strip with `.eyebrow` + `<h1>` + `.subtitle`
  (auto-rendered from `title`/`subtitle`/`eyebrow` unless `show_masthead`
  is false).
- `.grid .grid--2|3|4|auto` — responsive CSS grid.
- `.stack`, `.row` — vertical / horizontal flex.
- `.card`, `.card--soft`, `.card--elev` — content containers.
- `.rule` — `<hr>` underline below `<h2>`.
- `.colophon` — footer strip (auto-added by composer).

### Components

- **Eyebrow**: `<div class="eyebrow">SECTION</div>` — small all-caps label
  with a leading clay rule.
- **Badge**: `<span class="badge badge--ok|warn|err|info|clay">v1.0</span>`.
- **Kbd**: `<span class="kbd">⌘K</span>`.
- **Bullets**: `<ul class="bullets"><li>…</li></ul>` — clay dots.
- **Code**: inline `<code>` and block `<pre><code>`. Block code gets a
  `copy` button automatically via `base.js`.
- **Details**: native `<details><summary>…</summary>…</details>` styled.

### Tabs

```html
<div class="tabgroup">
  <div class="tabs">
    <button data-target="a">Tab A</button>
    <button data-target="b">Tab B</button>
  </div>
  <div class="tab-panel" data-id="a">…</div>
  <div class="tab-panel" data-id="b">…</div>
</div>
```

`base.js` wires this automatically and selects the first tab by default.

### Drag-to-reorder

```html
<div data-sortable="true">
  <div draggable="true">…</div>
  <div draggable="true">…</div>
</div>
```

Optional cross-zone drops: add `data-zone="<id>"` to each container.

### Live parameter bindings

```html
<input type="range" data-bind="size" min="0" max="100" value="50" data-format="number" data-unit="px">
<span data-out="size"></span>
<style>.box { width: var(--bind-size, 50px); }</style>
```

The CSS custom property `--bind-<name>` is updated on every input event,
and any `[data-out="<name>"]` element receives the formatted value.

## Output rules

Spend output tokens on **content**, not chrome:

1. **Never write `<html>`, `<head>`, `<style>`, `<