Icon maintenance

This page explains how icons are organized and maintained in this repository.

Files

Each icon is made of two source files:

icons/<icon-name>.svg
icons/<icon-name>.json

• .svg stores the icon shape.
• .json stores stable category IDs, Chinese default metadata, tags, and required English i18n.en metadata.

Related files:

• categories/*.json: category keys, Chinese titles, and English titles.
• docs/: generated documentation pages, search data, category pages, and icon detail pages.

Generic icons, business icons, and illustrations all use kebab-case file names.

Business-specific icons live in business-icons/<color-mode>/*.svg. The first-level folder must be outlined, filled, or multicolor, and it controls the cleanup and package-generation behavior. Each SVG needs same-name metadata JSON. Color-mode display names live in business-icons/<color-mode>/index.json, while business-icons/index.json and business-icons/metadata/index.json are generated; URL-based remote lookup snapshots are copied into docs/public/metadata during docs builds. See Business icons.

Illustrations live in illustration-icons/<category>/*.svg; the first-level folder is the category, and unclear assets should use other. They do not go through color conversion or size cleanup, and generated components default to width="100%" and height="auto". Each SVG needs same-name metadata JSON, while illustration-icons/index.json and illustration-icons/metadata/index.json are generated; URL-based remote lookup snapshots are copied into docs/public/metadata during docs builds. Package subpaths use @ycloud-web/icons-*/illustration, while static assets use @ycloud-web/icons-static/illustration-icons/<category>/<name>.svg.

Icon Metadata

YCloud Icons is Chinese-first at the source-data level:

• name is the Simplified Chinese icon name.
• tags are Simplified Chinese search tags.
• use-cases are Simplified Chinese usage phrases. Use an empty array when none are known.
• categories are stable category slugs, not display text.
• i18n.en.name, i18n.en.tags, and i18n.en.use-cases are required for English docs and English search. Category translations are maintained in categories/*.json.

Example:

{
  "$schema": "../icon.schema.json",
  "use-cases": [],
  "name": "Simplified Chinese icon name",
  "tags": ["Simplified Chinese tag"],
  "categories": ["arrows", "navigation"],
  "i18n": {
    "en": {
      "name": "circle arrow up",
      "tags": ["arrow", "up", "circle"],
      "use-cases": []
    }
  }
}

Add an icon

1. Add icons/<icon-name>.svg.
2. Add icons/<icon-name>.json.
3. Reuse existing category slugs from categories/*.json, unless the change explicitly adds a new category.
4. Run validation.

If the SVG comes from a design tool, optimize it first:

pnpm optimize

Delete an icon

Delete both files:

icons/<icon-name>.svg
icons/<icon-name>.json

Then check whether any alias, deprecation migration, or documentation example still references the icon.

Update an icon

• Shape only: update icons/<icon-name>.svg.
• Metadata only: update icons/<icon-name>.json.
• Rename: rename both .svg and .json, update examples if needed, and add aliases when appropriate.

Add or update a category

Categories are defined in categories/*.json.

{
  "$schema": "../category.schema.json",
  "title": "Simplified Chinese category title",
  "i18n": {
    "en": {
      "title": "Navigation & Places"
    }
  }
}

Rules:

• title is the Simplified Chinese display title.
• i18n.en.title is the English display title.
• icon must point to an existing icon.
• Icon metadata may only reference category slugs that already exist or are added in the same change.

Validation

For generic icon additions, removals, or updates, run at least:

pnpm checkIcons
pnpm lint:json
pnpm lint:svg:icons
pnpm docs:build:no-og

For business icons and illustrations, run their index generator, asset metadata generator, and family-specific SVG validator. See Business icons and Illustrations for the exact commands.

If the change affects package exports or runtime behavior, also run the related package build, for example:

pnpm --filter @ycloud-web/icons-react build
pnpm --filter @ycloud-web/icons-vue build