icons

用途

本技能用于在页面、按钮或 UI 元素中添加一致的 Lucide 图标，通过 <icon-wc> Web Component 实现统一、可访问的图标展示。核心要求是：始终使用 <icon-wc> 组件，绝不使用内联 SVG。

主要能力

统一图标尺寸，避免各页面图标大小不一
自动处理无障碍（a11y）
使用经过优化并缓存的 SVG 加载
颜色从 CSS 继承（使用 currentColor），不硬编码颜色
可配合任意图标集使用，如 Lucide、自定义图标等

何时使用

出现以下需求时使用本技能：图标按钮（关闭、菜单等）、导航图标、状态指示器（成功、错误、警告）、带图标的切换开关（主题、设置）、操作按钮（保存、删除、编辑）、社交分享图标，以及任何视觉指示或图标。

错误做法（不要这样）：

<!-- WRONG: Inline SVG -->
<button>
  <svg viewBox="0 0 24 24"><path d="M12 3v1m0 16v1..."/></svg>
</button>

正确做法：

<!-- CORRECT: icon-wc component -->
<button>
  <icon-wc name="sun" label="Light theme"></icon-wc>
</button>

快速上手

<!-- Basic usage -->
<icon-wc name="menu"></icon-wc>
<icon-wc name="arrow-right"></icon-wc>
<icon-wc name="check"></icon-wc>

<!-- With size -->
<icon-wc name="home" size="lg"></icon-wc>

<!-- With accessible label (for functional icons) -->
<button>
  <icon-wc name="x" label="Close"></icon-wc>
</button>

<!-- Custom icon set -->
<icon-wc name="logo" set="custom"></icon-wc>

目录结构

.assets/
├── js/
│   └── components/
│       └── x-icon/          # Icon Web Component
│           ├── icon-wc.js
│           └── x-icon-styles.js
└── icons/
    ├── lucide/              # Lucide icons (synced from npm)
    │   ├── index.json       # Icon manifest
    │   ├── menu.svg
    │   ├── x.svg
    │   └── ...              # ~1900 icons
    └── custom/              # Project-specific icons
        └── logo.svg

安装设置

运行 /scaffold-icons 在项目中设置图标，或手动执行：

# 1. Install lucide-static
npm install lucide-static --save-dev

# 2. Sync icons
npm run icons:sync

# 3. Copy icon-wc component
mkdir -p .assets/js/components/icon-wc
cp .claude/skills/icons/templates/icon-wc/*.js .assets/js/components/icon-wc/

# 4. Include in HTML
<script type="module" src="/.assets/js/components/icon-wc/icon-wc.js"></script>

<icon-wc> 组件属性

属性	说明	默认值
name	图标名（去掉 .svg 的文件名）	必填
set	图标集目录	"lucide"
size	尺寸预设：xs, sm, md, lg, xl, 2xl	"md"
label	功能性图标的无障碍标签	无
base-path	覆盖默认图标路径	/.assets/icons

尺寸参考

尺寸	对应大小
xs	1em（基准下 16px）
sm	1.25em（20px）
md	1.5em（24px）
lg	2em（32px）
xl	2.5em（40px）
2xl	3em（48px）

样式

图标通过 currentColor 继承描边颜色：

/* Change icon color */
.danger icon-wc {
  color: var(--color-error);
}

/* Custom sizing */
icon-wc.hero-icon {
  width: 4rem;
  height: 4rem;
}

同步图标

图标来自 lucide-static npm 包：

# Install package (one-time)
npm install lucide-static --save-dev

# Sync icons to .assets/icons/lucide/
npm run icons:sync

以下情况需要运行 icons:sync：初次项目设置、升级 lucide-static 版本、重新执行 npm install。

无障碍

装饰性图标（默认）：没有 label 的图标对屏幕阅读器隐藏。

<!-- Decorative - hidden from screen readers -->
<button>
  <icon-wc name="save"></icon-wc>
  Save Document
</button>

功能性图标：为纯图标按钮或链接添加 label。

<!-- Functional - announced to screen readers -->
<button aria-label="Close dialog">
  <icon-wc name="x" label="Close"></icon-wc>
</button>

使用准则

场景	模式
图标 + 可见文字	无需 label（装饰性）
纯图标按钮	添加 label 属性
状态指示器	添加描述状态的 label
纯装饰	无需 label

添加自定义图标

在 .assets/icons/custom/ 中创建 SVG 文件：

<!-- .assets/icons/custom/logo.svg -->
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
  <path d="M12 2L2 7l10 5 10-5-10-5z"/>
</svg>

配合 set="custom" 使用：

<icon-wc name="logo" set="custom"></icon-wc>

自定义图标要求：

SVG 格式并带 viewBox 属性
不设固定宽高（由组件处理尺寸）
描边/填充使用 currentColor 以继承颜色
保持文件体积小（可用 SVGO 优化）

替换图标集

使用其他图标库：

卸载：npm uninstall lucide-static
安装替代库：npm install [other-library]
更新 scripts/quality/sync-icons.js 源路径
运行 npm run icons:sync

或手动复制 SVG 到 .assets/icons/[set-name]/。

<icon-wc> 组件可与任何 SVG 图标库配合使用。

查找图标

Lucide：https://lucide.dev/icons
本地清单：.assets/icons/lucide/index.json

本地搜索：

grep -l "arrow" .assets/icons/lucide/*.svg | head -10

常用图标

用途	图标名
导航	menu, x, arrow-left, arrow-right
操作	plus, minus, edit, trash, save
状态	check, x, alert-circle, info
媒体	play, pause, volume-2, image
用户	user, users, settings, log-out
文件	file, folder, download, upload
社交	share, heart, star, message-circle

检查清单

使用图标时确认：

图标名与 .assets/icons/[set]/ 中的文件匹配
功能性图标带 label 属性
图标尺寸适合上下文
颜色从父级继承（使用 currentColor）
自定义图标存放在 .assets/icons/custom/

技能介绍

用途