naive-icons 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 本文件记录 Naive Icons 的每个版本变更。版本号遵循语义化版本规范（SemVer）。
 
+## 1.5.0
+
+新增
+
+- 官方 Agent Skill：让 AI 编码助手能按语义检索图标、输出可直接粘贴的代码，并知道这套图标的设计规范
+- 一条命令装好，不用先装本库、不用挑 agent：
+
+  ```bash
+  npx skills add guokaigdg/naive-icons
+  ```
+
+  会先展示要装的内容再确认，并自动识别本机已装的 agent。
+  可选 Project（跟着仓库走，团队共享）或 Global（装到用户目录），加 `-g` 可跳过该选择。
+- Skill 自带全部 SVG 源码（收在 `scripts/icons.json` 一个文件里），装到哪都能出码，
+  不依赖项目里是否装了本库
+- 脚本只用 Python 标准库，skill 被装到任何位置都能跑
+- 新增 `scripts/build_skill_assets.py`，从 `svg/` 生成 skill 的 `catalog.md` 与
+  `icons.json`，并校验 `svg/`、`ICON_CATEGORY`、`ZH_NAMES` 三者一致
+
+修复
+
+- 补上 `index.ts` 对类型与色板的转发，`NAIVE_PALETTE`、`IconProps`、`IconName`、
+  `IconComponent`、`PaletteColor` 从包入口真正可用了。此前 `src/types.ts` 里都有定义，
+  但入口只导出 159 个图标组件，导致 README 里的
+  `import { NAIVE_PALETTE } from 'naive-icons'` 报运行时 `SyntaxError`、
+  `import type { IconProps } from 'naive-icons'` 报 `TS2305` / `TS2459`。
+  该问题自 1.0.0 起就存在
+- 两个生成器（`generate_icons.py` / `generate_icons_add.py`）的 `index.ts` 模板同步补上
+  转发，否则下次新增图标时会被全量重建冲掉
+
+## 1.4.0
+
+新增
+
+- 新增 25 个图标，图标总数增至 159
+  - 界面基础 +11：users、user-plus、more-vertical、check-square、shield、bell-off、sliders、grid、list、ban、badge-check
+  - 操作 +7：filter、sort、undo、redo、maximize、zoom-in、zoom-out
+  - 文件与媒体 +3：volume、volume-x、paperclip
+  - 通信 +2：send、inbox
+  - 导航方位 +1：arrow-up-right
+  - 交通工具 +1：scooter
+- 撤销 / 重做改为墨色长弧搭配橙色实心箭头的形态，两枚互为镜像，箭头水平朝外
+- 放大 / 缩小改用青色线框镜片加橙色大符号，与 search 的实心镜片彻底区分开
+
+改进
+
+- 重绘 refresh 为上下双弧的循环箭头，两段弧各占 120°，上下各留 100° 缺口，弧段与留白接近 1:2
+- external-link 的橙色箭头描边由 3.5 加粗到 4.0，小尺寸下更清晰
+- cart 从「交通工具」重新归入「日常物品」
+- 官网取色器与主题换色改为只替换墨色描边。图标自带的彩色描边（橙色箭头、黄色勾等）本来就是 naive 风格的一部分，此前会被一并刷成单色
+
+修复
+
+- 官网深色模式下首次加载时，hero 贴纸改用奶油色描边，不会因墨色与深色底糊在一起而看不见
+- hero 贴纸切换主题时只替换上一个主题色并在颜色未变时跳过，不再逐个重写 DOM
+- 移除图标详情弹窗的左右切换按钮与键盘 ← → 导航，连带删除 step / indexOfCurrent 等死代码
+- 扩充脚本重新生成 package.json 时会剥掉文件末尾的换行，导致凭空多出一行 diff，现已修复
+
 ## 1.3.0
 
 新增

package/README.md

@@ -21,14 +21,44 @@
   <img src="https://img.shields.io/badge/SVG-FFB13B?style=flat-square&logoColor=black" alt="SVG">
 </p>
 
-Each icon is drawn on a 48x48 grid with a 3.5 stroke, rounded line caps, and a unified retro palette — keeping the charming clumsiness and warmth of hand-drawn illustration. Some icons even feature a pair of dot eyes and a little smile, adding a touch of humanity to your interface.
+<p align="center">
+  <b>🤖 AI Agent Skill</b> — install it into Claude Code, Cursor, Codex and friends,<br/>
+  and they can pick icons by meaning, emit ready-to-paste code, and know the design rules.<br/>
+  <code>npx skills add guokaigdg/naive-icons</code> &nbsp;·&nbsp; <a href="#ai-agent-skill">See details &rarr;</a>
+</p>
+
+Each icon is drawn on a 48x48 grid with a 3.5 stroke, rounded line caps, and a retro palette — keeping the charming clumsiness and warmth of hand-drawn illustration. Some icons even feature a pair of dot eyes and a little smile, adding a touch of humanity to your interface.
 
 ## Features
 
 - Icons spanning 11 categories: interface, actions, media, navigation, animals, food, and more
 - Every icon ships as both an SVG source file and a React TSX component
-- Full TypeScript types: IconProps, IconName, IconCategory, NAIVE_PALETTE
-- Supports currentColor, so icons automatically follow the surrounding text color
+- Full TypeScript types: IconProps, IconName, IconComponent, NAIVE_PALETTE
+- Supports `currentColor` to follow the surrounding text color
+- Official Agent Skill: one command installs it into your AI coding agent, which can then pick icons by meaning and emit ready-to-paste code
+
+## AI Agent Skill
+
+Install it into your AI coding agent (Claude Code, Cursor, Codex, …) and it can pick icons by
+meaning, emit ready-to-paste code, and know this library's design rules.
+
+```bash
+npx skills add guokaigdg/naive-icons
+```
+
+You do not need to install the package first. **Start a new session** afterwards,
+then just ask:
+
+- "Give this login page a set of naive icons"
+- "Find an icon that means 'already read'"
+
+The skill bundles the full icon catalog, the design spec, usage patterns and every SVG source
+file, so the agent can generate code even when the package isn't installed in your project.
+Re-run the same command after upgrading the library to update it.
+
+> Installing the skill and using the components are separate things. You only need
+> `npm install naive-icons` from the Installation section below when you actually want to
+> `import { HomeIcon } from 'naive-icons'` in your own code.
 
 ## Installation
 
@@ -62,17 +92,19 @@ export function Example() {
 }
 ```
 
-Import per icon to further reduce bundle size:
+Tree-shaking works out of the box: the package is ESM and sets `sideEffects: false`, so a
+named import is all you need.
 
 ```tsx
-import HomeIcon from 'naive-icons/src/HomeIcon';
+import { HomeIcon, SearchIcon } from 'naive-icons';
 ```
 
-Use with currentColor so icons automatically inherit the parent text color:
+To follow the parent text color, pass `currentColor` explicitly — the default is ink `#2A2A2A`
+and is **not** inherited automatically:
 
 ```tsx
 <span style={{ color: '#264653' }}>
-  <HomeIcon size={20} />
+  <HomeIcon size={20} color="currentColor" />
   Home
 </span>
 ```
@@ -90,7 +122,7 @@ Every Naive Icon component extends the native `SVGProps<SVGSVGElement>`, so you
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | size | number \| string | 24 | Icon size, equal width and height. Overrides width and height when set |
-| color | string | currentColor | Stroke color |
+| color | string | `#2A2A2A` | Stroke color. Pass `currentColor` to follow the surrounding text color |
 | strokeWidth | number \| string | 3.5 | Stroke width, scaled to the 48x48 canvas |
 | fill | string | none | Fill color |
 | title | string | — | Accessibility title, rendered as an SVG title node |
@@ -152,7 +184,7 @@ Naive Icons follows four fixed rules. They should be respected when adding new i
 
 1. **Grid & bleed**: All graphics are drawn on a 48x48 canvas, keeping at least 3 units between the main body and the canvas edge.
 2. **Stroke**: A unified 3.5 width with round caps and joins, and no dashed lines.
-3. **Color**: Use only the 9 colors in the palette — no gradients, shadows, or semi-transparent overlays.
+3. **Color**: The 9 palette colors set the default tone; other solid colors are allowed when genuinely needed (e.g. brand colors) — no gradients, shadows, or semi-transparent overlays.
 4. **Personality**: Slight asymmetry is welcome; encourage dot eyes and a smile on living subjects to keep the hand-drawn clumsiness.
 
 ## Local Development

package/README.zh-CN.md

@@ -21,14 +21,41 @@
   <img src="https://img.shields.io/badge/SVG-FFB13B?style=flat-square&logoColor=black" alt="SVG">
 </p>
 
-每一个图标都建立在 48x48 的网格上，使用 3.5 的粗描边、圆角线帽与统一的复古调色板，并保留了手绘插画特有的笨拙感与温度——部分图标还带有一对小圆点眼睛和微笑，让界面多一点点人情味。
+<p align="center">
+  <b>🤖 AI Agent Skill</b> — 给 Claude Code / Cursor / Codex 等 AI 编码助手装一份，<br/>
+  它就能按语义帮你挑图标、生成可直接粘贴的代码，并且知道这套图标的设计规范。<br/>
+  <code>npx skills add guokaigdg/naive-icons</code> &nbsp;·&nbsp; <a href="#ai-agent-skill">看详情 &rarr;</a>
+</p>
+
+每一个图标都建立在 48x48 的网格上，使用 3.5 的粗描边、圆角线帽与复古调色板，并保留了手绘插画特有的笨拙感与温度——部分图标还带有一对小圆点眼睛和微笑，让界面多一点点人情味。
 
 ## 特性
 
 - 图标覆盖界面、操作、媒体、导航、动物、食物等 11 个分类
 - 每个图标同时提供 SVG 源文件与 React TSX 组件
-- 完整 TypeScript 类型：IconProps、IconName、IconCategory、NAIVE_PALETTE
-- 支持 currentColor，可跟随文字颜色自动变化
+- 完整 TypeScript 类型：IconProps、IconName、IconComponent、NAIVE_PALETTE
+- 支持 currentColor，传入后图标跟随文字颜色
+- 官方 Agent Skill：一条命令装到 AI 编码助手，按语义帮你挑图标并生成代码
+
+## AI Agent Skill
+
+给 AI 编码助手（Claude Code、Cursor、Codex 等）装一份，它就能按语义帮你挑图标、
+生成可直接粘贴的代码，并且知道这套图标的设计规范。
+
+```bash
+npx skills add guokaigdg/naive-icons
+```
+
+不用先装本库。装完**新开会话**，然后直接说：
+
+- 「用 naive 图标给这个登录页配一套图标」
+- 「找个表示『已读』的图标」
+
+Skill 自带完整图标目录、设计规范和用法，以及全部 SVG 源码，助手生成代码不依赖项目里
+是否装了本库。库升级后重跑同一条命令即可更新。
+
+> 装 skill 和用组件是两件事。要在代码里 `import { HomeIcon } from 'naive-icons'`，
+> 才需要下面「安装」里的 `npm install naive-icons`。
 
 ## 安装
 
@@ -62,17 +89,17 @@ export function Example() {
 }
 ```
 
-按需引入可以进一步减小打包体积：
+按需引入：包是 ESM 且标记了 `sideEffects: false`，用具名导入即可，打包器会自动 tree-shaking：
 
 ```tsx
-import HomeIcon from 'naive-icons/src/HomeIcon';
+import { HomeIcon, SearchIcon } from 'naive-icons';
 ```
 
-配合 currentColor 使用，图标会自动继承父级文字颜色：
+想跟随父级文字颜色，显式传 `currentColor`（默认是墨色 `#2A2A2A`，不会自动继承）：
 
 ```tsx
 <span style={{ color: '#264653' }}>
-  <HomeIcon size={20} />
+  <HomeIcon size={20} color="currentColor" />
   首页
 </span>
 ```
@@ -90,7 +117,7 @@ Naive Icons 的每个组件都继承原生 `SVGProps<SVGSVGElement>`，可以直
 | 属性 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | size | number \| string | 24 | 图标尺寸，宽高相等。传入后覆盖 width 与 height |
-| color | string | currentColor | 描边颜色 |
+| color | string | `#2A2A2A` | 描边颜色。传 `currentColor` 可跟随父级文字颜色 |
 | strokeWidth | number \| string | 3.5 | 描边宽度，按 48x48 画布比例缩放 |
 | fill | string | none | 填充色 |
 | title | string | — | 无障碍标题，渲染为 SVG title 节点 |
@@ -152,7 +179,7 @@ Naive Icons 遵循四条固定规则，新增图标时也应保持一致。
 
 1. **网格与出血**：全部图形绘制在 48x48 画布内，主体距离画布边缘至少保留 3 个单位。
 2. **描边**：统一 3.5 宽度，端点与转角均为 round，不使用虚线。
-3. **配色**：只使用调色板中的 9 个颜色，不使用渐变、阴影与半透明叠加。
+3. **配色**：以调色板的 9 色为默认基调，确有必要时可用其他实色（如品牌色），不使用渐变、阴影与半透明叠加。
 4. **性格**：允许线条轻微不对称，鼓励给有生命的图形加上圆点眼睛与微笑，保留手绘的笨拙感。
 
 ## 本地开发