AGENTS.md · git:20261022.29c97c2 · 2026-10-22 · sha256 9e540939867ae106
AGENTS.md git:20261022.29c97c2A
Immutable. This exact content never changes and is served at /api/v1/blob/9e540939867ae106.
# AGENTS.md
Guide for AI agents working in this repository.
## Overview
`@lobehub/icons` is a library of AI / LLM brand logos (models, providers, applications) shipped as React components, plus generated static SVG / PNG / WEBP / avatar packages and a React Native port. The docs site is <https://icons.lobehub.com>, built with `@lobehub/docs-kit` (`lobedocs`).
Key paths:
| Path | What |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `src/<Brand>/` | One folder per brand: `index.ts`, `style.ts`, `index.mdx`, `components/*.tsx` |
| `src/icons.ts` | Export list of every brand. The source of truth for which icons exist |
| `src/features/` | `ModelIcon`, `ProviderIcon`, `ProviderCombine`, `AgentIcon`, `IconAvatar`, `IconCombine`, mappings |
| `src/toc.json` | Generated icon catalog (`bun run build:toc`). Never edit by hand |
| `docs/`, `docs.config.ts` | Docs home, guide pages and site config |
| `packages/react-native/` | `@lobehub/icons-rn`, a separate copy of icons and mapping configs |
| `packages/static-{svg,png,webp,avatar}/` | Generated by CI. Never edit by hand |
| `scripts/` | toc, static, README and RN conversion workflows |
## Using Skills
Repo skills live in `.agents/skills/` (`.claude/skills` is a symlink to it). Read the `SKILL.md` before doing the matching task:
| Skill | Use when |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `add-icon-mapping` | Mapping a provider / model / agent id to an icon: `providerEnum.ts`, `providerConfig.tsx`, `modelConfig.ts`, `agentConfig.ts`, in both the main and RN package |
| `using-docs-kit` | Writing or fixing doc pages, demos, `docs.config.ts`, or debugging `lobedocs build` failures |
| `building-landing-home` | Changing the docs home page (`docs/home/home.tsx`, `@lobehub/ui/awesome` landing components) |
Tools that discover project skills load them automatically (e.g. Claude Code via `.claude/skills`). Otherwise, open the `SKILL.md` directly.
Two of the skills are generic and describe other repos too. Where a skill disagrees with this file or the code, trust the code. Known stale points in `add-icon-mapping`:
- `pnpm-lock.yaml` **is** tracked. Do not delete it.
- `tests/ModelIcon.test.tsx` exists and runs with the repo's `vitest.config.ts`.
`https://icons.lobehub.com/skills.md` and `https://icons.lobehub.com/llms.txt` are generated by `lobedocs build` for **downstream consumers** of the package. They are not instructions for working on this repo.
## Writing Docs
- **Brand pages**: `src/<Brand>/index.mdx` becomes `/components/<kebab-brand>` (`atomDirs: [{ dir: 'src' }]`). Frontmatter:
```mdx
---
title: Chutes # display name, also used as fullTitle in the toc
description: https://chutes.ai # the brand's official URL
category: Provider # Model | Provider | Application; becomes the toc group
---
```
Body: copy a sibling page with the same variants (e.g. `src/Decart/index.mdx`). Sections are `## Icons` (Mono and `.Color` side by side when a Color variant exists), `## Text`, `## Combine`, `## Brands` (only if Brand variants exist), `## Avatars`, `## Colors`. Each section has a live `<DocsPreview>` from `../components/DocsPreview` followed by a matching `tsx` code block. Colors use `<ColorPreview color={Brand.colorPrimary} />` from `../components/ColorPreview`. Import the library by package name: `import { Chutes } from '@lobehub/icons'`. The `alias` in `docs.config.ts` maps it to `src`.
- **Guide pages**: `docs/features/<name>.mdx` with `title`, `description`, `category: Features`. Demos live in `src/features/<Feature>/demos/*.tsx` (one default export each) and are imported with `?demo`, e.g. `import Demo from '../../src/features/ModelIcon/demos/index.tsx?demo'`, then rendered with `<Demo of={Demo} />`. A new guide must be added to `publicDocs` in `docs.config.ts` or it is not built. `docs/features/provder-icon.mdx` is the real (misspelled) filename and live URL. Do not rename it.
- **Conventions**: the page renders `title` as the H1, so start at `##`. Keep headings short and noun-style. Only `Demo` and `Api` are global; import everything else. No `:::` callouts. Full rules: `.agents/skills/using-docs-kit/SKILL.md`.
- **Preview / verify**: `bun run dev` (alias of `lobedocs dev`, restart after editing `docs.config.ts`). Before finishing doc changes, run `bun run docs:build`; it runs all docs validations.
- `README.md`: the brand table between the two `<!-- ICON LIST -->` markers is generated by `bun run sync:md`. Do not edit it by hand.
## Adding a New Icon
First check `src/` and `src/icons.ts`. If the brand already exists and only an id renders the fallback icon, this is a mapping task: use the `add-icon-mapping` skill.
1. **Prepare the SVG.** Use the official logo, cleaned up with path data only. Prefer `viewBox="0 0 24 24"` (other square viewBoxes exist, e.g. `0 0 64 64`) and make sure nothing is clipped. The online editor at <https://icons.lobehub.com/editor> (`docs/editor/index.mdx`) formats SVGs into component code. `bun run vectorizer` converts `temp/logo.png` into `temp/logo.svg`; it needs `VECTORIZE_URL` / `VECTORIZE_SECRET_ACCESS_KEY` in `.env`.
2. **Create `src/<Brand>/`** (PascalCase, matching the export name), copying the closest existing brand:
- `style.ts`: `TITLE`, `COLOR_PRIMARY` (optional `COLOR_GRADIENT`), `COMBINE_TEXT_MULTIPLE`, `COMBINE_SPACE_MULTIPLE`, `AVATAR_BACKGROUND`, `AVATAR_COLOR`, `AVATAR_ICON_MULTIPLE`.
- `components/Mono.tsx`: required. `IconType` + `memo`, `fill="currentColor"`, `<title>{TITLE}</title>`, spread `{...rest}`.
- Optional variants, only when the brand really has them: `Color`, `Text`, `TextCn`, `TextColor`, `Brand`, `BrandColor`, `Combine` (via `@/features/IconCombine`), `Avatar` (via `@/features/IconAvatar`), and `Inner` as a helper.
- Any `<linearGradient>` / `<mask>` / `<clipPath>` ids must come from `useFillId` / `useFillIds` (`@/hooks/useFillId`). Never hard-code ids. See `src/Sora/components/Color.tsx`.
- `index.ts`: attach variants to the Mono component and set `colorPrimary` / `title` (see `src/Chutes/index.ts`).
- `index.mdx`: see Writing Docs.
3. **Register** in `src/icons.ts`, alphabetically:
`export { default as Brand, type CompoundedIcon as BrandProps } from './Brand';`
`build:toc`, `build:static` and `sync:md` all discover icons from this file.
4. **Map ids (optional)**: if LobeHub should resolve a provider / model / agent id to it, follow `add-icon-mapping` and edit both `src/features/*` and `packages/react-native/src/features/*`.
5. **Regenerate the toc**: `bun run build:toc` updates `src/toc.json`. The `has*` flags come from which `components/*.tsx` exist, and the group comes from `category`. The pre-commit hook also runs it.
6. **React Native (usually a follow-up)**: `bun run auto-converter-web-icons-to-rn` converts new web icons into `packages/react-native/src/icons/` and syncs the RN configs (`scripts/rn-conversion/README.md`).
7. **Generated assets: leave them to CI.** On release, `.github/workflows/release.yml` runs `build:static` (renders `packages/static-*` with puppeteer) and `sync:md` (README icon list), then commits `✨ feat(auto): Auto build static icons`. Do not commit hand-made static files or README icon rows.
To render only some icons locally: `bun scripts/svgWorkflow/index.tsx --only Brand,Other` (same exporter, filtered). The release job runs it with `--since auto`: only brands changed since the last `Auto build static icons` commit are re-exported and removed brands are deleted, while changes to `scripts/svgWorkflow`, shared `src/` code, rendering dependencies or a missing baseline fall back to a full export (`--dry-run` prints the plan, the `full_static` dispatch input forces a full export).
On pull requests, `.github/workflows/pr-icon-preview.yml` renders the changed brands (`scripts/prPreviewWorkflow`) and `pr-icon-preview-comment.yml` posts them as a sticky comment with the convention issues; try it locally with `bun scripts/prPreviewWorkflow/index.tsx --base origin/master` and open `tmp/pr-preview/comment.md`.
8. **Check**: `bun run type-check`, `bun run lint`, `bun run test`, `bun scripts/check-svg-ids.tsx` (if you used gradients or ids), then view the page with `bun run dev` in light and dark mode at several sizes.
## Conventions & Checks
| Task | Command |
| --------------- | ------------------------------------------- |
| Install | `bun i` (what CI uses) |
| Docs dev server | `bun run dev` |
| Docs build | `bun run docs:build` |
| Lint (TS / TSX) | `bun run lint`, `bun run lint:style` |
| Lint (markdown) | `bun run lint:md` |
| Type-check | `bun run type-check` |
| Circular deps | `bun run lint:circular` |
| Tests | `bun run test` |
| Library build | `bun run build` (runs `build:toc` + tsdown) |
- **Commits**: gitmoji + Conventional Commits with a lowercase scope, enforced by commitlint (`@lobehub/lint`). Examples: `✨ feat: add Chutes icon`, `🐛 fix: use Meta icon for Muse Wonder models`, `📝 docs: update README`.
- **Pre-commit hook** (`.husky/pre-commit`): `build:toc` → `git add .` → `type-check` → `lint:circular` → `lint-staged` (prettier / remark / eslint / stylelint). Because it runs `git add .`, **every** unstaged change in the worktree goes into your commit. Commit from a clean tree and check `git show --stat HEAD` afterwards.
- Never use `--no-verify`. If the hook fails because `node_modules` is stale, reinstall dependencies and fix the cause; do not skip the hook.
- Do not hand-edit generated files: `src/toc.json`, `packages/static-*`, the README icon list, `packages/react-native/dist`.