# 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 , built with `@lobehub/docs-kit` (`lobedocs`). Key paths: | Path | What | | ---------------------------------------- | -------------------------------------------------------------------------------------------------- | | `src//` | 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//index.mdx` becomes `/components/` (`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 `` from `../components/DocsPreview` followed by a matching `tsx` code block. Colors use `` 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/.mdx` with `title`, `description`, `category: Features`. Demos live in `src/features//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 ``. 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 `` 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 (`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//`** (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}`, 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 `` / `` / `` 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`.