Article Icons (itshover)
Add tasteful icons to an article using the itshover 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
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...).
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.
Confirm the plan with the user before editing — show the heading→icon mapping. This is cheap and avoids reworking a whole document.
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.
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 consistently throughout. |
Checklist
Before finishing:
1---2name: article-icons3description: 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.4---5
6# Article Icons (itshover)
7
8Add 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.
9
10## Triggers
11
12Use when the user wants to illustrate a document with icons:
13- `/article-icons <file>`
14- "给这篇文章配图标", "给文章配图", "add icons to this article", "illustrate with icons"
15
16## Inputs
17
18- **Target file** — the article to illustrate (`.md`, `.html`, `.mdx`, ...). If not given, ask.
19- **Style preferences** (optional) — color, size, where icons go. Otherwise use sensible defaults below.
20
21## The Tool
22
23`scripts/fetch_icon.py` is the only moving part. It fetches an icon and prints static SVG to stdout.
24
25```bash
26# Get one icon (defaults: size 24, color currentColor, stroke-width 2)
27python3 scripts/fetch_icon.py heart-icon
28
29# Customize
30python3 scripts/fetch_icon.py rocket-icon --size 32 --color "#d97757" --stroke-width 1.5
31
32# Discover names (do this FIRST — names must match exactly)
33python3 scripts/fetch_icon.py --list
34python3 scripts/fetch_icon.py --search arrow
35python3 scripts/fetch_icon.py --search brand
36```
37
38`scripts/icon_names.json` is a cached list of all 263 names for offline reference.
39
40Most 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.
41
42## Workflow
43
441. **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...).
45
462. **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`.
47
483. **Confirm the plan** with the user before editing — show the heading→icon mapping. This is cheap and avoids reworking a whole document.
49
504. **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.
51
525. **Verify.** Re-read the edited file; for HTML, open it / screenshot to confirm icons render and align. Report the mapping you applied.
53
54## Embedding Rules
55
56**HTML** — inline the SVG directly. Wrap heading icons so they align with text:
57
58```html
59<h2 style="display:flex;align-items:center;gap:.5rem;">
60 <svg ...>...</svg> Performance
61</h2>
62```
63
64**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:
65
66```markdown
67## <svg ... width="22" height="22" ...>...</svg> Getting Started
68```
69
70If 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.
71
72### Defaults
73- **Size:** 24px beside `h1`, 20–22px beside `h2`/`h3`, 16px inline in text.
74- **Color:** `currentColor` so icons inherit text color. Override with `--color` only when the user wants accent colors.
75- **Density:** one icon per heading + a few for genuinely key concepts. Do **not** icon every bullet or sentence — restraint reads as polish.
76- **Alignment:** always `display:flex;align-items:center;gap:.4–.5rem` for heading icons in HTML.
77
78## Icon Selection Cheatsheet
79
80These names are verified to exist, but the set changes — always reconfirm with `--search` before fetching.
81
82| Theme | Real icon names |
83|-------|------|
84| intro / overview | `book-icon`, `home-icon`, `globe-icon`, `map-pin-icon` |
85| performance / speed | `rocket-icon`, `gauge-icon`, `clock-icon` |
86| security | `shield-check`, `lock-icon` |
87| data / charts | `database`-family via `--search`, `chart-bar-icon`, `chart-line-icon`, `chart-pie-icon`, `cloud-1-icon` |
88| settings / config | `gear-icon`, `sliders-horizontal-icon` |
89| warning / note | `triangle-alert-icon`, `info-circle-icon`, `filled-bell-icon` |
90| success / done | `checked-icon`, `double-check-icon`, `simple-checked-icon` |
91| ideas | `brain-circuit-icon`, `sparkles-icon`, `star-icon`, `bulb-svg` |
92| AI / brands | `brand-anthropic-icon`, `brand-gemini-icon`, ... (`--search brand`) |
93| navigation | `arrow-narrow-*-icon`, `down-chevron`, `right-chevron` |
94
95## Edge Cases
96
97| Scenario | Handling |
98|----------|----------|
99| Icon name not found (404) | Run `--search <term>`; pick the closest real name. Never invent names. |
100| 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. |
101| No network access | Cannot fetch SVGs; tell the user the skill needs network access to itshover.com. |
102| Markdown renderer strips inline SVG | Fall back to `assets/icons/*.svg` + image references. |
103| Article already has icons | Ask whether to replace, supplement, or skip those sections. |
104| Very long article | Confirm the mapping for the first few sections, then apply the same family consistently throughout. |
105
106## Checklist
107
108Before finishing:
109- [ ] Every icon name was resolved with `--search`/`--list` (no guessed names)
110- [ ] One consistent icon family/color across the article
111- [ ] Icons placed at headings + genuinely key points, not everywhere
112- [ ] Heading icons vertically aligned with text (flex + gap)
113- [ ] Edited file re-read; HTML visually verified to render
114- [ ] Mapping summary reported to the user
smallnest