kubai-icons README

The project's README from github.com/kubai087/kubai-icons. As one markdown file: README.md.

Kubai Icons

An agent skill that draws animated icons in one consistent style.
Plus 2,800+ open-source icons drawn with it, for React, Vue and the web.

Install the skill · Browse the icons · Use them in code · Docs

Sixteen icons opening one after another on hover: a folder opens, an envelope unseals, a calendar turns a page, a lock springs open, a gear turns

What's included

Part What you get
Agent skill The rules, engine and self-check that draw every icon in one hand. Give Claude Code, Codex or another coding agent a product, and it draws the icons that product needs.
Icon library 2,800+ icons: nearly 900 objects, plus badged and slashed "off" versions. For React, Vue, plain JavaScript, web components and static SVG. MIT licensed.
Website icons.kubai.design, in 16 languages. Search every icon by name, shape or meaning, recolor it, copy its code or a prompt for your agent, download it as SVG or PNG, and save a collection as a ZIP.

Install the skill

Copy this into your agent and send it:

Install the Kubai Icons skill for me:
clone https://github.com/kubai087/kubai-icons into your skills folder as kubai-icons
(~/.claude/skills in Claude Code, ~/.agents/skills in Codex;
if it's already there, pull the latest version instead),
make sure SKILL.md exists in that folder, and tell me when it's ready.

Restart your agent, and the skill is ready. An agent without skill support can read SKILL.md from the cloned folder and follow it.

[!TIP] The skill asks for careful geometry and several rounds of looking at its own screenshots, so use a capable model that can read images. It was developed and blind-tested with Claude Opus 5.5, which we recommend. Other models, such as GPT in Codex, can use the same skill. In Claude Code, run claude --model claude-opus-5-5.

Install it yourself

Clone the repository into your skills folder. In Codex, use ~/.agents/skills instead.

git clone https://github.com/kubai087/kubai-icons.git ~/.claude/skills/kubai-icons

Or download kubai-icons-v*.zip from the latest release and unzip it there:

unzip kubai-icons-v*.zip -d ~/.claude/skills/

The agent picks the skill up the next time it starts.

Publishing to a skill marketplace that asks for a version and display names in SKILL.md? Upload kubai-icons-v*-platform.zip from the same release. It carries those fields at the top of the frontmatter.

Ask for icons

Describe what you need in plain words. The skill triggers on requests about icons, so you don't need to name it.

The agent then:

  1. Reads the rules and writes one line per feature: an everyday object and what it does on hover ("a folder opens", "a lock springs open").
  2. Draws each icon after the closest existing one, reusing the engine.
  3. Runs the self-check beside existing icons, compares sizes, outlines, layers and colors, and repeats until every item on the checklist passes.

To start a set for your own product, the skill copies the engine, gallery and self-check into your project and works there.

Six icons on hover: an alarm clock rings, a notebook opens, a scan line sweeps a QR code, a door opens to an exit arrow, a calculator key presses, a compass needle settles north

Drawn by a fresh Claude session that had nothing but SKILL.md and PROMPT.md. Each blind test closes the gaps it finds in the rules.

Use the icons

Package For
kubai-icons-react React 18+ and Next.js, server rendering included
kubai-icons-vue Vue 3 and Nuxt
kubai-icons Any page: a framework-free API and the <kubai-icon> web component
kubai-icons-static Standalone SVG files for <img>, design tools, native apps and CDNs
npm i kubai-icons-react
import { Folder, CalendarCheck } from "kubai-icons-react";

// 24px, follows the text color
<Folder />

// Any CSS color, the soft look, a green badge
<CalendarCheck size={32} color="#22C55E" variant="soft" badgeColor="semantic" />

// Plays when the button is hovered
<button data-kubai-trigger>
  <Folder size={18} trigger="parent" /> Open
</button>

No build step? One script tag loads any icon on demand:

<script type="module" src="https://cdn.jsdelivr.net/npm/kubai-icons@0/dist/cdn/element.js"></script>
<kubai-icon name="folder-plus" size="32" color="#6366F1"></kubai-icon>

Find an icon and copy its code on the website. Guides for every package are in the documentation.

Building a native app in Go? Kubai Icons for MyGo is a community port for MyGo, maintained by yldm-tech rather than this project.

How an icon is built

Every icon is a back piece, optional white content and a front piece, like a folder holding a sheet of paper. Outlines sit outside the fill, so shapes keep their full size. Every gradient, outline and shadow derives from one accent color, so a single value repaints the whole icon. Each part has exactly two keyframes, rest and hover.

Eight icons moving through seven palettes: one color per icon, five clear tones, and black

The complete rules are in PROMPT.md.

Reference

What the skill ships
Part What it does for the model
PROMPT.md The rules, each one a hard requirement: canvas and keylines, layers, corners and outlines, light, color, marks and motion.
src/engine.js Color derivation, outside outlines, gradients, shadows, interpolation and palettes, already built. New icons reuse them instead of reinventing them.
src/icons.js 66 worked examples. Each new icon starts from the closest one in structure.
scripts/check.mjs A headless self-check: rest, hover, every moment in between, 24px, 28px and every palette, plus a list of findings against the rules that can be measured (scripts/measure.js).

index.html opens a local gallery of these 66 examples. The full library is on the website.

Export static SVG

This exports the skill's own icons, whose names and palettes are in Chinese. For the library, download from the website or use kubai-icons-static.

node scripts/export.mjs --only 文件夹,日历 --palette 薄荷 --out icons/
Option What it does
--palette 彩色 (default), 蓝灰, 青瓷, 薄荷, 薰衣草, 杏色 or 黑色.
--accent #hex Paints every icon in one accent color.
--state hover Exports the end of the hover instead of the rest pose.
--size 96 Width and height in pixels.
--pad 2.5 Room around the canvas, in icon units, so the shadow isn't cut off.
--out dir Where the files go; export/ by default.
Run the self-check

Needs Node.js 18 or later and Chrome. Everything runs headless.

node scripts/check.mjs --only 剪刀,地图 --with 文件夹,邮件,下载
Option What it does
--only Checks only these icons. Without it, the whole set.
--with Adds existing icons beside them for comparison.
--accent #F59E0B Paints every icon in one accent color, to check marks on light accents.
--scale 3 Renders every sheet at 3×, to look for seams.
--out dir Writes the screenshots somewhere other than check-out/.

Besides the screenshots it writes findings.md: each icon measured against the rules that can be measured, such as motion that stops dead or jumps, size and centring, line widths, thin gaps, outlines that peek out or meet in a spike, and edges with no outline. Each finding points at a likely problem to confirm on the screenshots.

CHROME overrides the browser path. The animations in this README come from node scripts/media.mjs, which also needs ffmpeg and img2webp.

Work on the library and website

Needs Node.js 20 or later; the contact sheets also need Chrome.

npm install
npm run build        # every package, from icons/ and badges/
npm run validate     # names, metadata and markup of every icon
npm test
node tools/check.mjs --only folder,mail --with download   # contact sheets in check-out/lib
npm run audit        # scores every icon against the rules, in check-out/audit
npm run site:dev     # the website

Each icon is one module in icons/; docs/authoring.md explains the format, and docs/review.md how icons are reviewed. The website is a static Next.js export in site/.

Contributing

See CONTRIBUTING.md and the code of conduct. Security issues go through SECURITY.md.

License

Part License In short
Icons (icons/, badges/) and the four packages MIT Use, change and redistribute them in any project, commercial or not.
The skill Kubai Icons License Source-available. See below.
Website (site/, tools/, tests/, docs/) All rights reserved You may read the source and run it to prepare a contribution, but not copy or host it.

Under the Kubai Icons License:

LICENSING.md lists which file falls under which license. The Kubai and Lumno names and logos are not licensed for reuse. The construction comes from the bookmark folder icon in Lumno.

kubai-icons (kubai087/kubai-icons)

Searching Database…

What is this?An agent skill that draws animated icons in one consistent style for Claude Code, Codex and other coding agents. It also ships a library of 2,800+ open-source animated icons for React, Vue and SVG, plus a website to browse them.
Is it an icon library or an AI skill?Both. The skill teaches a coding agent to draw new icons in the same style, and the library ships ready icons as packages for React, Vue, plain JavaScript and static SVG.
How do I install the skill?Clone the repository into your skills folder (~/.agents/skills in Codex), or unzip kubai-icons-v.zip from the latest release there. Then restart the agent, and it picks up the skill on start.
Which coding agents does it work with?It is built for Claude Code and Codex. Other coding agents can use it too: if an agent has no skill support, it can read SKILL.md from the cloned folder and follow it.
Does it need a specific model?Not strictly, but the skill relies on careful geometry and on checking its own screenshots, so the authors recommend Claude Opus 5.5 (claude --model claude-opus-5-5 in Claude Code). GPT in Codex can use the same skill too.
Can I use these icons in a commercial project?Yes. The icons and the four packages are MIT licensed, so you can use, change and redistribute them in any project, commercial or not. The skill is source-available under the Kubai Icons License: you can run it and share exact unmodified copies, but you cannot sell it or republish changed versions.
How do the icons animate?Each icon moves like its object: a folder opens, an envelope unseals, a calendar turns to the next day. Each part has just two keyframes, rest and hover, and hover, focus, a tap or your own state can play it.
Can I recolor the icons with CSS?Yes. Gradients, outlines and shadows all derive from one accent color through CSS, so icons follow currentColor and recolor without any script.
Why build it as a skill instead of just an icon set?The skill keeps every new icon consistent: it writes one line per feature, draws each icon after the closest existing example, and runs a self-check against the existing icons before finishing.
Can I make my own icon set for my product?Yes. The skill copies its engine, gallery and self-check into your project, and you draw new icons there in the same style.
Creator
kubai087
Size
11.1 MB
Stars
948
Age
15d
Commits · 90 Days