/article-icons

name: article-icons
description: "Illustrate an article (Markdown, HTML, etc.) with animated-style icons from itshover.com/icons. Fetches icons as clean inline SVG and places them at section headings, key concepts, lists, and callouts. Triggers on: /article-icons, 配图, 给文章配图标, add icons to article, illustrate with icons."
user-invocable: true

Article Icons (itshover)

Add tasteful icons to an article using the [itshover](https://www.itshover.com/icons) icon set. itshover publishes 263 icons as shadcn registry components; this skill downloads them and converts each into a clean, static, inline **SVG** that drops straight into Markdown or HTML — no React, no `motion`, no build step.

Triggers

Use when the user wants to illustrate a document with icons:

• `/article-icons <file>`
• "给这篇文章配图标", "给文章配图", "add icons to this article", "illustrate with icons"

Inputs

• **Target file** — the article to illustrate (`.md`, `.html`, `.mdx`, ...). If not given, ask.
• **Style preferences** (optional) — color, size, where icons go. Otherwise use sensible defaults below.

The Tool

`scripts/fetch_icon.py` is the only moving part. It fetches an icon and prints static SVG to stdout.

# Get one icon (defaults: size 24, color currentColor, stroke-width 2)
python3 scripts/fetch_icon.py heart-icon

# Customize
python3 scripts/fetch_icon.py rocket-icon --size 32 --color "#d97757" --stroke-width 1.5

# Discover names (do this FIRST — names must match exactly)
python3 scripts/fetch_icon.py --list
python3 scripts/fetch_icon.py --search arrow
python3 scripts/fetch_icon.py --search brand

`scripts/icon_names.json` is a cached list of all 263 names for offline reference.

Most icon names end in `-icon` (e.g. `heart-icon`, `rocket-icon`, `database-icon`), and brands use `brand-<name>-icon` (e.g. `brand-anthropic-icon`). But the convention is **not** universal — real names include `shield-check`, `credit-card`, `down-chevron`, `apple-brand-logo`, `skull-emoji`. **Never guess a name. Always resolve it with `--search` first** — a wrong guess just wastes a 404.

Workflow

1. **Read the article.** Identify its structure: title, section headings (`#`/`##`/`<h1>`/`<h2>`), key concepts, list groups, callouts/warnings, and any tech/brand mentions (React, GitHub, AI tools...).

2. **Plan the icon map.** For each placement, choose a semantically matching icon. Match meaning, not just keywords — a "performance" section → `rocket-icon` or `zap-icon`; a "security" section → `shield-icon` or `lock-icon`; a warning callout → `alert-triangle-icon`. Prefer **one consistent icon family** (all outline, one color) so the article looks designed, not decorated. Resolve every name with `--search`.

3. **Confirm the plan** with the user before editing — show the heading→icon mapping. This is cheap and avoids reworking a whole document.

4. **Fetch and embed.** Run `fetch_icon.py` for each chosen icon (parallelize independent fetches) and inline the SVG at its placement. See embedding rules below.

5. **Verify.** Re-read the edited file; for HTML, open it / screenshot to confirm icons render and align. Report the mapping you applied.

Embedding Rules

**HTML** — inline the SVG directly. Wrap heading icons so they align with text:

<h2 style="display:flex;align-items:center;gap:.5rem;">
  <svg ...>...</svg> Performance
</h2>

**Markdown** — GitHub-flavored Markdown renders inline HTML, so embed the raw SVG. Keep it on one line and size it small (16–20px) for inline use, 24–28px beside headings:

## <svg ... width="22" height="22" ...>...</svg> Getting Started

If the target renderer strips inline SVG (some strict Markdown engines do), fall back to saving each SVG into an `assets/icons/` folder next to the article and referencing it: ``. Ask which the user prefers if unsure.

Defaults

• **Size:** 24px beside `h1`, 20–22px beside `h2`/`h3`, 16px inline in text.
• **Color:** `currentColor` so icons inherit text color. Override with `--color` only when the user wants accent colors.
• **Density:** one icon per heading + a few for genuinely key concepts. Do **not** icon every bullet or sentence — restraint reads as polish.
• **Alignment:** always `display:flex;align-items:center;gap:.4–.5rem` for heading icons in HTML.

Icon Selection Cheatsheet

These names are verified to exist, but the set changes — always reconfirm with `--search` before fetching.

| Theme | Real icon names | |-------|------| | intro / overview | `book-icon`, `home-icon`, `globe-icon`, `map-pin-icon` | | performance / speed | `rocket-icon`, `gauge-icon`, `clock-icon` | | security | `shield-check`, `lock-icon` | | data / charts | `database`-family via `--search`, `chart-bar-icon`, `chart-line-icon`, `chart-pie-icon`, `cloud-1-icon` | | settings / config | `gear-icon`, `sliders-horizontal-icon` | | warning / note | `triangle-alert-icon`, `info-circle-icon`, `filled-bell-icon` | | success / done | `checked-icon`, `double-check-icon`, `simple-checked-icon` | | ideas | `brain-circuit-icon`, `sparkles-icon`, `star-icon`, `bulb-svg` | | AI / brands | `brand-anthropic-icon`, `brand-gemini-icon`, ... (`--search brand`) | | navigation | `arrow-narrow-*-icon`, `down-chevron`, `right-chevron` |

Edge Cases

| Scenario | Handling | |----------|----------| | Icon name not found (404) | Run `--search <term>`; pick the closest real name. Never invent names. | | Icon won't convert (rare; ~2/263 use a JS map for paths) | Script prints a clear error. Pick an alternative icon with similar meaning. | | No network access | Cannot fetch SVGs; tell the user the skill needs network access to itshover.com. | | Markdown renderer strips inline SVG | Fall back to `assets/icons/*.svg` + image references. | | Article already has icons | Ask whether to replace, supplement, or skip those sections. | | Very long article | Confirm the mapping for the first few sections, then apply the same family consiste