From 9b6d65c9f13a660fe59e133d341243ada50608fb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 20 May 2026 19:00:38 +0000
Subject: [PATCH] docs: require running material-symbols-subset.sh when adding
 new icons

The bundled Material Symbols font ships only the codepoints referenced
from MaterialSymbols.kt. Without regenerating the subset, newly added
icons render as tofu at runtime. Document this as a mandatory step in
CLAUDE.md so agents pick it up automatically.
---
 .claude/CLAUDE.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index c81a08ec7..bb5ef6015 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -306,6 +306,29 @@ actual fun openExternalUrl(url: String) {
 }
 ```
 
+## Icons
+
+The Material Symbols font bundled at
+`commons/src/commonMain/composeResources/font/material_symbols_outlined.ttf`
+is a **subset** that only contains the glyphs referenced from
+`commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/icons/symbols/MaterialSymbols.kt`.
+
+**MANDATORY:** Whenever you add a new icon — i.e. introduce a
+`MaterialSymbol("\uXXXX")` codepoint that wasn't already referenced anywhere in
+`MaterialSymbols.kt` — you MUST regenerate the subset font by running:
+
+```bash
+./tools/material-symbols-subset/subset.sh
+```
+
+Commit the regenerated `material_symbols_outlined.ttf` alongside your
+`MaterialSymbols.kt` change. Without this step the new icon renders as tofu (□)
+at runtime because the glyph is not in the bundled font.
+
+Reusing a codepoint already present in `MaterialSymbols.kt` does NOT require
+regenerating. See `tools/material-symbols-subset/README.md` for details and
+prerequisites (`pip install fonttools brotli`).
+
 ## Code Formatting
 After completing any task that modifies Kotlin files, always run:
 ```