docs: require kebab-case icon names and drop upstream-only wiring from AGENTS

2026-08-28 11:05:31 +08:00 · 2026-07-30 17:21:08 -04:00
parent a1c7108fe6
commit 55ea1c2765
3 changed files with 5 additions and 3 deletions
@@ -12,14 +12,14 @@ Background: the IDE maintains Classic UI and New UI in parallel. Code branches w
 ## Golden rules

 1. **Always ship two SVGs** — one for the light theme (e.g. `addFile.svg`) and one for the dark theme with the `_dark` suffix (`addFile_dark.svg`). Geometry must be identical between them; only the palette swaps.
-   - **Tool-window icons ship as a quartet, not a pair.** When a tool window has both a 16×16 base (`name.svg` / `name_dark.svg`) and a 20×20 New-UI stripe variant (`name@20x20.svg` / `name@20x20_dark.svg`), they must share the same metaphor. The stripe is only one surface — the 16×16 base also appears in **Search Everywhere**, **Find Action**, context menus, the Services tool window, recent locations, and the View ▸ Tool Windows menu. Changing only the @20x20 leaves users seeing two different icons for the same tool window depending on where they encounter it. Always update all four files together (and the same applies to plugin-local icons like `toolWindowChat.svg` + `toolWindowChat@20x20.svg`).
+   - **Tool-window icons ship as a quartet, not a pair.** When a tool window has both a 16×16 base (`name.svg` / `name_dark.svg`) and a 20×20 New-UI stripe variant (`name@20x20.svg` / `name@20x20_dark.svg`), they must share the same metaphor. The stripe is only one surface — the 16×16 base also appears in **Search Everywhere**, **Find Action**, context menus, the Services tool window, recent locations, and the View ▸ Tool Windows menu. Changing only the @20x20 leaves users seeing two different icons for the same tool window depending on where they encounter it. Always update all four files together (and the same applies to plugin-local icons like `tool-window-chat.svg` + `tool-window-chat@20x20.svg`).
 2. **Only use colors from the canonical palette.** See [palette.md](./palette.md). Picking a one-off color breaks theming and contrast.
 3. **One canvas size per icon role.** See [Icon roles](#icon-roles). Do not invent new sizes or pad with empty space — IntelliJ scales the canvas as a single unit.
 4. **No raster, no gradients, no filters, no embedded fonts.** Path geometry only (`<path>`, `<rect>`, `<circle>`, `<line>`, `<polyline>`, `<polygon>`). Text must be converted to outlines.
 5. **Use `fill="none"` on the root `<svg>`** and set `fill` / `stroke` explicitly per shape — never rely on CSS or `currentColor`.
 6. **Strokes use `stroke-width="1"`, `stroke-linecap="round"`, `stroke-linejoin="round"`** (or `stroke-miterlimit="10"` for hard joins). Heavier strokes are reserved for hero glyphs inside a circle badge (e.g. status checkmarks) and use `stroke-width="1.5"` or `"2"`.
 7. **Pixel-grid align**: keep stroke axes on half-pixel centers (`x.5`) and fills on whole pixels so the icon stays crisp at 1× rendering.
-8. **File names use camelCase** (e.g. `arrowDownToLine.svg`, `bookOpenCheck.svg`, `toolWindowChat.svg`) matching the action/node ID and stay ASCII-only. This matches the naming convention used by all icons in `packages/kilo-jetbrains/frontend/src/main/resources/icons/`. See [PR #12713](https://github.com/Kilo-Org/kilocode/pull/12713) for the follow-up renaming all existing plugin icons to camelCase to conform with this rule.
+8. **File names match the naming convention of sibling icons in the target folder and stay ASCII-only.** Plugin-local Kilo icons in `packages/kilo-jetbrains/frontend/src/main/resources/icons/` use kebab-case (e.g. `arrow-down-to-line.svg`, `book-open-check.svg`, `tool-window-chat.svg`), matching every existing icon there. Upstream IntelliJ Platform icons use camelCase; when copying one from `$INTELLIJ_REPO`, keep its original name.

 ## Icon roles

@@ -176,3 +176,5 @@ Breakpoint marks read at a glance — a single solid fill in the status-error re
 ```

 `white` → `#5E4D33` inside the warning triangle. Apply the same swap whenever a light icon paints a glyph as `white` over a warm fill (`#FFAF0F`, `#E66D17`, etc.). For cool fills (`#3574F0`, `#208A3C`, `#DB3B4B`), the dark-theme glyph stays `white` because contrast is still sufficient.
+
+Note: the exclamation glyph here (the vertical bar + dot paths) is shared verbatim with the error badge in section 5 — upstream `warning.svg` / `warning_dark.svg` reuse the same optically centered `!` glyph, so between the light and dark warning variants only the fill color changes. This is the one case where reusing a sibling glyph unchanged is correct; the general rule still stands that a glyph must be re-balanced when its container centers it differently.
@@ -582,7 +582,7 @@ This section covers only the Kotlin/runtime integration side:
 - **Reuse platform icons**: browse at https://intellij-icons.jetbrains.design. Access via `AllIcons.*` constants.
 - Custom icons: SVG files in `resources/icons/`. Load via `IconLoader.getIcon("/icons/foo.svg", MyClass::class.java)`.
 - Organize in an `icons` package or a `*Icons` object with `@JvmField` on each constant.
- **Sizing, dark variants, and New UI support**: see the `icon-jetbrains` skill for the authoritative Icon roles table, canvas sizes, filename patterns, dark variant conventions, `expui/` placement, and `*IconMappings.json` wiring. Do not duplicate sizing or palette values here.
+- **Sizing, dark variants, and filename patterns**: see the `icon-jetbrains` skill for the authoritative Icon roles table, canvas sizes, filename patterns, and dark variant conventions. Do not duplicate sizing or palette values here.

 IntelliJ does not theme SVG icons with `currentColor`, CSS classes, CSS variables, `<style>` blocks, or inherited styles. `SVGLoader` patches icon colors by matching literal hex values in `fill` and `stroke` attributes against the active theme palette. Use hardcoded palette hex values in SVG assets and provide dark variants. This exception applies to icon asset files only; runtime Swing UI code must still derive colors from theme APIs.