sag-icons

状态感知的多色调 SVG 图标库

一个 Web Components 图标库，专门为"多色 + 状态感知" UI 场景设计——侧边栏导航、Tab 栏、激活态指示器。

📚 在线文档 · 📦 npm · 🐙 GitHub

这是什么

通用图标库（Lucide、IconPark、Tabler）面向"任意场景"，sag-icons 面向"多色 + 状态"。

我们做得有意的差异化，恰好是通用库不擅长的：

• 状态感知的多色调 — is-active 类切换颜色，CSS 自动接管。IconPark 的多色是静态的，需要自己加状态管理。
• CSS 变量驱动 — 6 个变量（--sag-icon-blue/cyan/green/amber/white/default）就能换肤，不需要 props 层层传色。
• 一个 Web Component 跨所有框架 — 不需要 react-lucide / vue-lucide 多包维护成本。
• 包体积小且结构简单 — 78 个图标 33KB 整包（gzip 6.75KB），按需 import 也支持。

我们不追求 1000+ 图标数量，我们追求"为正确的场景做对的事"。

安装

# npm
npm install @jujiuyey/sag-icons

# pnpm
pnpm add @jujiuyey/sag-icons

# yarn
yarn add @jujiuyey/sag-icons

快速开始

只需引入两样：主入口（注册 <sag-icon> 元素）+ CSS（驱动颜色状态）。

React

import '@jujiuyey/sag-icons';
import '@jujiuyey/sag-icons/css/svg-icon.css';

export default function Sidebar() {
  return (
    <nav>
      <sag-icon name="workbench" />
      <sag-icon name="settings" className="is-active" />
    </nav>
  );
}

Vue 3

<script setup>
import '@jujiuyey/sag-icons';
import '@jujiuyey/sag-icons/css/svg-icon.css';
</script>

<template>
  <nav>
    <sag-icon name="workbench" />
    <sag-icon name="settings" :class="{ 'is-active': isActive }" />
  </nav>
</template>

原生 HTML / 其他框架

<script type="module">
  import 'https://esm.sh/@jujiuyey/sag-icons';
  import 'https://esm.sh/@jujiuyey/sag-icons/css/svg-icon.css';
</script>

<sag-icon name="workbench"></sag-icon>
<sag-icon name="settings" class="is-active"></sag-icon>

完整文档与 React Router / Vue Router 集成示例：sag-icons.jujiuyey.com

状态切换

sag-icons 的核心特性。<sag-icon> 默认显示灰色，添加 is-active 类即激活为完整配色：

<sag-icon name="workbench"></sag-icon>                  <!-- 灰色 -->
<sag-icon name="workbench" class="is-active"></sag-icon> <!-- 彩色 -->

激活态由你控制。可以接到路由激活、:hover、状态机任意来源。

颜色定制

通过覆盖 6 个 CSS 变量实现换肤：

:root {
  --sag-icon-blue:   #3b82f6;
  --sag-icon-cyan:   #06b6d4;
  --sag-icon-green:  #22c55e;
  --sag-icon-amber:  #f59e0b;
  --sag-icon-white:  #ffffff;
  --sag-icon-default: #9ca3af;  /* 非激活灰色 */
}

无需 props、不需要 wrapper 组件，CSS 即真相。

图标列表

当前 78 个图标，分 7 个类别：

| 类别 | 数量 | 预览 | |------|------|------| | 导航 | 16 | 查看 | | 基础界面 | 10 | 查看 | | 文件 | 7 | 查看 | | 编辑操作 | 10 | 查看 | | 媒体 | 15 | 查看 | | 设备 | 12 | 查看 | | 状态反馈 | 8 | 查看 |

完整预览与每个图标的代码片段：sag-icons.jujiuyey.com/icons

我们的取舍

| 我们放弃 | 我们得到 | |---------|---------| | 1500+ 图标数量 | 风格聚焦、视觉一致 | | 4 主题切换（IconPark） | 多色调的深度 | | 按框架分包的"最佳实践" | 零学习成本 |

如果你需要"激活时变彩色、默认时变灰色"，sag-icons 是为此而生。

环境要求

• 现代浏览器（Chrome / Firefox / Safari / Edge 最新版）
• React 18+ / Vue 3+ / 任意支持自定义元素的框架
• TypeScript 4.5+（可选，但推荐获得 <sag-icon> JSX 类型补全）

相关链接

• 📚 在线文档
• 📦 npm 包
• 🐙 GitHub 仓库
• 📝 CHANGELOG

License

MIT

部署与发布

文档站通过 GitHub Actions 自动部署到 GitHub Pages，npm 包通过 tag 触发自动发布。CI 配置见：

• .github/workflows/docs.yml — push 到 main 自动部署文档
• .github/workflows/publish.yml — 打 v* tag 自动发 npm

首次部署与发布的详细操作见 桌面的部署教程 章节，或仓库的 wiki。